Changeset c82b055


Ignore:
Timestamp:
Jul 26, 2003, 1:36:36 PM (21 years ago)
Author:
Erik Nygren <nygren@mit.edu>
Branches:
master, barnowl_perlaim, debian, owl, release-1.10, release-1.4, release-1.5, release-1.6, release-1.7, release-1.8, release-1.9
Children:
87c6ef1
Parents:
a7a42b9
Message:
Updated intro.txt and advanced.txt documents (still in progress).
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • ChangeLog

    r282ec9b rc82b055  
    44        Make sure that a newline is always at the end of messages
    55                returned by perl style formatting functions.
    6         Add owl::login to legacy variables populated for format_msg.
     6        Add owl::login and owl::auth to legacy variables populated for format_msg.
     7        Additions to intro.txt and advanced.txt documents.  (Still in progress.)
    78
    892.0.8-pre-2
  • doc/advanced.txt

    r675ce49 rc82b055  
    55
    66=========================
    7 Section X: CUSTOM FILTERS
    8 =========================
    9 
    10 
    11 ==========================
    12 Section X: THE CONFIG FILE
    13 ==========================
     7Section X: COMMAND ALISES
     8=========================
     9
     10[see Section 4 in intro.txt, which may want to be moved here]
    1411
    1512=======================
     
    1714=======================
    1815
    19 
    20 =========================
    21 Section X: COMMAND ALISES
    22 =========================
    23 
    24 
    25 =================
    26 Section X: STYLES
    27 =================
    28 
    29 
    30 - - - - - - - - - - - - - - - - - - - - - - - - - - -
    31 
     16[see Section 4 in intro.txt, which may want to be moved here]
     17
     18=========================
     19Section X: CUSTOM FILTERS
     20=========================
    3221
    3322For example, the following
     
    6958
    7059
    71 ==========================
    72 Section 6: THE CONFIG FILE
    73 ==========================
    74 
    75 *** WARNING: This interface may change substantially in the near future ***
    76 
    77 This file is interpreted by the perl interpreter.
    78 If you wish to execute an owl command use the
    79 function owl::command().  i.e.
    80 
    81      owl::command("set zsigproc \"/mit/kretch/bin/getzsig foo\"");
    82 
    83 will set the owl variable zsigproc.  Note that commands will currently
    84 be executed in order after the called configuration subroutine exits.
     60=========================================
     61Section 6: THE PERL EXTENSION CONFIG FILE
     62=========================================
     63
     64*** WARNING: This interface is still evolving and may change over time ***
     65
     66The ~/.owlconf file is interpreted by the perl interpreter.
     67You may specify an alternate file by running owl with "owl -c <configfile>".
    8568
    8669Subroutines created with the names below will be executed at the
     
    9174    owl::startup()     run when owl first starts
    9275    owl::shutdown()    run when owl exits
    93     owl::format_msg()  run when a new message arrives, the return
    94                           value is used to display the message on the
    95                           screen
     76    owl::format_msg()  run to format messages when using the perl style.
     77                       The return value is used to display the message on the
     78                       screen.
    9679    owl::receive_msg() run when a message is received, and after
    9780                       it has been added to the message list
    9881
    99 
    100 The following variables will be set each time a message is recevied:
    101 
    102     $owl::class, $owl::instance, $owl::recipient,
    103     $owl::sender, $owl::opcode, $owl::zsig,
    104     $owl::msg, $owl::time, $owl::host, @owl::fields, $owl::id
    105 
    106 The "appendtosepbar" variable may be set in owl::format_msg()
    107 to set text to be appended to sepbar that separates the received
    108 message list from the edit window.
     82It is possible to call back into owl and execute owl commands
     83from within these functions.  This is particularly useful
     84in owl::startup for setting up your initial owl environment.
     85If you wish to execute an owl command use the function owl::command().  i.e.
     86
     87     owl::command('set zsigproc "/mit/kretch/bin/getzsig foo"');
     88
     89will set the owl variable zsigproc to
     90the value "/mit/kretch/bin/getzsig foo".
     91Note that you will need to watch out for perl quoting issues.
     92[It may be worth talking about them a little here...]
     93
     94Both owl::format_msg and owl::receive_msg are passed perl owl::Message
     95objects which have methods for accessing the attributes of the message. 
     96
     97(Caveat: Note that these owl::Message objects are currently only
     98         snapshots of the message contents that are created as needed.  As
     99         such, there could be multiple owl::Message objects for the same owl
     100         message.  Use the msgid if you want to uniquely identify individual
     101         messages.)
     102
     103All owl::Message objects contain the following methods:
     104
     105    type      - returns the type of the message ("zephyr", "aim", "admin")
     106    direction - returns "in" or "out" for incoming or outgoing messages
     107    time      - returns a string of the time when the message showed up
     108    id        - returns a unique id for the message
     109    body      - returns the body text of the message
     110    sender    - returns the sender of the message
     111    recipient - returns the recipient of the message
     112    login     - returns either "login", "logout", or "none"
     113    is_login  - returns true if this is a login message
     114    is_logout - returns true if this is a logout message
     115    is_loginout - returns true if this is a login or logout message
     116    is_incoming - returns true if this is an incoming message
     117    is_outgoing - returns true if this is an outgoing message
     118    is_deleted  - returns true if this message is marked for deletion
     119    is_<type>   - returns true if the message is of type <type> (eg, is_zephyr)
     120    delete      - marks the message for deletion
     121    undelete    - unmarks the message from deletion
     122    pretty_sender - returns a cleaned up version of the sender
     123
     124The following owl::Message methods are only applicable to
     125various message types:
     126
     127    header      - returns the admin message header line  (admin)
     128    is_personal - returns true if this is a personal message (aim,zephyr)
     129    is_private  - returns true if this was a private message (zephyr)
     130    login_tty   - returns the login tty for login messages (zephyr)
     131    login_host  - returns the login host for login messages (zephyr)
     132    zwriteline  - returns the zwrite command line for outgoing zephyrs (zephyr)
     133    zsig        - returns the zsig (zephyr)
     134    is_ping     - returns true if this was a zephyr ping (zephyr)
     135    is_mail     - returns true if this was a new mail notification (zephyr)
     136    class       - returns the zephyr class (zephyr)
     137    instance    - returns the zephyr instance (zephyr)
     138    realm       - returns the zephyr realm (zephyr)
     139    opcode      - returns the zephyr opcode (zephyr)
     140    hostname    - returns the zephyr sender's hostname (zephyr)
     141    fields      - returns the zephyr fields as a perl list (zephyr)
     142    auth        - returns whether this zephyr was authentic (zephyr)
     143
     144An example formatting function that formats messages so that they only
     145list the direction, sender, and time would be:
     146
     147    sub owl::format_msg {
     148        my ($m) = @_;    # assigns the message object passed
     149                         # to this function to $m
     150        return sprintf "[direction=%s] from sender %s at %s\n",
     151                       $m->direction,
     152                       $m->sender,
     153                       $m->time;
     154    }
     155
     156In the above, $m is the owl::Message object and
     157its methods are called with $m->METHODNAME.
     158
     159An example receiver function that tags all zephyr pings for
     160deletion would be:
     161
     162    sub owl::receive_msg {
     163        my ($m) = @_;    # assigns the message object passed
     164                         # to this function to $m
     165        if ($m->is_zephyr and $m->is_ping) {
     166           $m->delete();
     167        }
     168    }
     169
     170
     171=================
     172Section X: STYLES
     173=================
     174
     175
     176
     177
     178
     179========================================
     180Section 7: PERL COMMANDS FROM WITHIN OWL
     181========================================
     182
     183Perl code may be executed from within owl with:
     184
     185  perl <perlcode>
     186
     187If you use pperl instead of perl, the return value
     188of the perl command will be displayed in a pop-up window.
     189This is particularly useful within key bindings
     190and aliases.  For example:
     191
     192  alias finger pperl $x=owl::getcurmsg()->hostname; `finger \@$x`;
     193
     194Will cause the "finger" command to be used to finger at the host
     195where the current message came from.  You can then bind this
     196to the "f" key with:
     197
     198   bindkey recv f command finger
     199
     200See the section above for detailss of commands and functions
     201that are available from within the perl interpreter.
  • doc/intro.txt

    r675ce49 rc82b055  
    336336     owl::command("set zsigproc \"/mit/kretch/bin/getzsig foo\"");
    337337
    338 will set the owl variable zsigproc.  Note that commands will currently
    339 be executed in order after the called configuration subroutine exits.
     338will set the owl variable zsigproc. 
    340339
    341340Subroutines created with the names below will be executed at the
     
    346345    owl::startup()     run when owl first starts
    347346    owl::shutdown()    run when owl exits
    348     owl::format_msg()  run when a new message arrives, the return
    349                           value is used to display the message on the
    350                           screen
     347    owl::format_msg()  run to format messages when using the perl style.
     348                       The return value is used to display the message on the
     349                       screen.
    351350    owl::receive_msg() run when a message is received, and after
    352351                       it has been added to the message list
    353352
    354 
    355 The following variables will be set each time a message is recevied:
    356 
    357     $owl::class, $owl::instance, $owl::recipient,
    358     $owl::sender, $owl::opcode, $owl::zsig,
    359     $owl::msg, $owl::time, $owl::host, @owl::fields, $owl::id
     353Both owl::format_msg and owl::receive_msg are passed
     354perl owl::Message objects which contain attributes of the message.
     355Please see the advanced.txt file for further documentation
     356of the Perl extension API.
    360357
    361358The "appendtosepbar" variable may be set in owl::format_msg()
     
    368365==========================================
    369366
     367Aliases
     368-------
     369
     370Command aliases allow users to create shortcuts
     371for commonly used commands.  Aliases can be created wit
     372the alias command:
     373
     374    alias NAME VALUE
     375
     376For example:
     377
     378    alias zw zwrite
     379
     380Will make "zw" an alias for the zwrite command.  As such, "zw aphacker"
     381will be expanded to "zwrite aphacker".  If the value of an
     382alias is multiple words, use of the alias will result in the alias
     383command name being replaced by the sequence of words.
     384Any arguments following the alias name will be appended
     385after the expanded alias value.  For example:
     386
     387   alias vs view -s
     388
     389will result in "vs standard" being expanded to "view -s standard".
     390There is not yet any way to allow an alias to take arguments
     391that will be inserted in the middle of the expansion.
     392
     393
     394Separating Commands
     395-------------------
     396
     397Multiple commands can be grouped together with parentheses
     398and then separated by semicolons.  For example:
     399
     400   ( smartnarrow ; delete view ; expunge ; view all )
     401
     402Will result in the four commands being executed
     403in sequence.  This is particularly useful with key bindings
     404and coommands.  For example:
     405
     406   alias sn-delete ( smartnarrow ; delete view )
     407
     408will create an "sn-delete" alias that will smartnarrow
     409to a view and them mark the view for deletion.
     410
     411Using "show commands" will list all existing aliases.
     412
     413
     414Key Bindings
     415------------
     416
     417New key bindings may be created with the "bindkey" command.  Each key
     418binding is associated with a particular keymap which is applicable in
     419a particular context/situation.  When the key associated with a
     420binding is pressed in the right context, it will result in an owl
     421command being run.  The syntax is:
     422
     423   bindkey <keymap> <keyseq> command <command>
     424
     425For example:
     426
     427   bindkey recv C-k command delete
     428
     429will bind Control-k to the delete command, but only in the
     430recv window context.
     431
     432Some keymaps inherit their bindings from more
     433general keymaps.  The valid keymaps are:
     434
     435  - global            - owl-wide defaults (apply everywhere)
     436    |-edit            - all text editing and command windows
     437    |  |-editmulti    - multi-line text editing windows
     438    |  |-editline     - single-line editing and command windows
     439    |  |-editresponse - single-line responses to questions
     440    |-popless         - scrolling pop-up windows
     441    |-recv            - the main message list window
     442                        where received messages are displayed
     443
     444The existing key bindings can be shown with "show keymaps".
     445The use of "show commands" will list all available commands.
     446Note that not all commands may be used in all contexts.
     447
     448Key sequences may be surrounded by quotes and include
     449a sequence of keys that must be pressed in order
     450to execute the command.  For example:
     451
     452   bindkey recv "C-s v" command view -s vt
     453
     454will result in "Control-s" followed by "v" in the recv window
     455causing the command "view -s vt" to be run.
     456
     457
    370458
    371459==============================
Note: See TracChangeset for help on using the changeset viewer.