source: doc/advanced.txt @ 601733d

barnowl_perlaimdebianowlrelease-1.4release-1.5release-1.6release-1.7release-1.8release-1.9
Last change on this file since 601733d was c82b055, checked in by Erik Nygren <nygren@mit.edu>, 17 years ago
Updated intro.txt and advanced.txt documents (still in progress).
  • Property mode set to 100644
File size: 7.3 KB
Line 
1                     ========================
2                     Owl Advanced Users Guide
3                     ========================
4
5
6=========================
7Section X: COMMAND ALISES
8=========================
9
10[see Section 4 in intro.txt, which may want to be moved here]
11
12=======================
13Section X: KEY BINDINGS
14=======================
15
16[see Section 4 in intro.txt, which may want to be moved here]
17
18=========================
19Section X: CUSTOM FILTERS
20=========================
21
22For example, the following
23command will create a filter called 'mail' that maches any messages
24sent to the zephyr class 'mail':
25
26     filter mail class ^mail$
27
28The first argument after the filter command specifies the name of the
29filter to be created.  The text after that indicates that matching
30messages must have the zephyr class "mail".  For help understanding
31the '^' and '$' characters, consult a reference on regular
32expressions.  Note that all pattern matching in Owl is
33case-insensitive.
34
35The message fields that can be used in a filter command include:
36
37     sender        message sender
38     recipient     message recipient
39     class         zephyr class name
40     instance      zephyr instance name
41     opcode        zephyr opcode
42     realm         zephyr realm
43     body          message body
44     type          message type ('zephyr', 'aim', 'admin')
45     direction     either 'in' 'out' or 'none'\n"
46     login         either 'login' 'logout' or 'none'\n"
47
48You can also use the operators 'and' 'or' and 'not' as well as the
49values 'true' and 'false'.  Parentheses can be used to group
50expressions, though there must be spaces present before and after all
51parenthesis.  For example:
52
53   filter myfilt ( class ^foo$ ) or ( class ^quux$ and instance ^bar$ )
54
55If you define a filter using a filter name that already exists, it
56will overwrite the existing filter.  This can be a useful way to
57override the built-in filters.
58
59
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>".
68
69Subroutines created with the names below will be executed at the
70specified times:
71
72    subroutine name    properties
73    ---------------    ----------
74    owl::startup()     run when owl first starts
75    owl::shutdown()    run when owl exits
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.
79    owl::receive_msg() run when a message is received, and after
80                       it has been added to the message list
81
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.
Note: See TracBrowser for help on using the repository browser.