source: doc/advanced.txt @ f183917

                     ========================
                     Owl Advanced Users Guide
                     ========================


=========================
Section X: COMMAND ALISES
=========================

[see Section 4 in intro.txt, which may want to be moved here]

=======================
Section X: KEY BINDINGS
=======================

[see Section 4 in intro.txt, which may want to be moved here]

=========================
Section X: CUSTOM FILTERS
=========================

For example, the following
command will create a filter called 'mail' that maches any messages
sent to the zephyr class 'mail':

     filter mail class ^mail$

The first argument after the filter command specifies the name of the
filter to be created.  The text after that indicates that matching
messages must have the zephyr class "mail".  For help understanding
the '^' and '$' characters, consult a reference on regular
expressions.  Note that all pattern matching in Owl is
case-insensitive.

The message fields that can be used in a filter command include:

     sender        message sender
     recipient     message recipient
     class         zephyr class name
     instance      zephyr instance name
     opcode        zephyr opcode
     realm         zephyr realm
     body          message body
     type          message type ('zephyr', 'aim', 'admin')
     direction     either 'in' 'out' or 'none'\n"
     login         either 'login' 'logout' or 'none'\n" 

You can also use the operators 'and' 'or' and 'not' as well as the
values 'true' and 'false'.  Parentheses can be used to group
expressions, though there must be spaces present before and after all
parenthesis.  For example:

   filter myfilt ( class ^foo$ ) or ( class ^quux$ and instance ^bar$ )

If you define a filter using a filter name that already exists, it
will overwrite the existing filter.  This can be a useful way to
override the built-in filters.


=========================================
Section 6: THE PERL EXTENSION CONFIG FILE
=========================================

*** WARNING: This interface is still evolving and may change over time ***

The ~/.owlconf file is interpreted by the perl interpreter. 
You may specify an alternate file by running owl with "owl -c <configfile>".

Subroutines created with the names below will be executed at the
specified times:

    subroutine name    properties
    ---------------    ----------
    owl::startup()     run when owl first starts
    owl::shutdown()    run when owl exits
    owl::format_msg()  run to format messages when using the perl style.
                       The return value is used to display the message on the
                       screen. 
    owl::receive_msg() run when a message is received, and after
                       it has been added to the message list

It is possible to call back into owl and execute owl commands
from within these functions.  This is particularly useful
in owl::startup for setting up your initial owl environment.
If you wish to execute an owl command use the function owl::command().  i.e.

     owl::command('set zsigproc "/mit/kretch/bin/getzsig foo"');

will set the owl variable zsigproc to 
the value "/mit/kretch/bin/getzsig foo".
Note that you will need to watch out for perl quoting issues.
[It may be worth talking about them a little here...]

Both owl::format_msg and owl::receive_msg are passed perl owl::Message
objects which have methods for accessing the attributes of the message.  

(Caveat: Note that these owl::Message objects are currently only
         snapshots of the message contents that are created as needed.  As
         such, there could be multiple owl::Message objects for the same owl
         message.  Use the msgid if you want to uniquely identify individual
         messages.)

All owl::Message objects contain the following methods:

    type      - returns the type of the message ("zephyr", "aim", "admin")
    direction - returns "in" or "out" for incoming or outgoing messages
    time      - returns a string of the time when the message showed up
    id        - returns a unique id for the message
    body      - returns the body text of the message
    sender    - returns the sender of the message
    recipient - returns the recipient of the message
    login     - returns either "login", "logout", or "none"
    is_login  - returns true if this is a login message
    is_logout - returns true if this is a logout message
    is_loginout - returns true if this is a login or logout message
    is_incoming - returns true if this is an incoming message
    is_outgoing - returns true if this is an outgoing message
    is_deleted  - returns true if this message is marked for deletion
    is_<type>   - returns true if the message is of type <type> (eg, is_zephyr)
    delete      - marks the message for deletion
    undelete    - unmarks the message from deletion
    pretty_sender - returns a cleaned up version of the sender

The following owl::Message methods are only applicable to
various message types:

    header      - returns the admin message header line  (admin)
    is_personal - returns true if this is a personal message (aim,zephyr)
    is_private  - returns true if this was a private message (zephyr)
    login_tty   - returns the login tty for login messages (zephyr)
    login_host  - returns the login host for login messages (zephyr)
    zwriteline  - returns the zwrite command line for outgoing zephyrs (zephyr)
    zsig        - returns the zsig (zephyr)
    is_ping     - returns true if this was a zephyr ping (zephyr)
    is_mail     - returns true if this was a new mail notification (zephyr)
    class       - returns the zephyr class (zephyr)
    instance    - returns the zephyr instance (zephyr)
    realm       - returns the zephyr realm (zephyr)
    opcode      - returns the zephyr opcode (zephyr)
    hostname    - returns the zephyr sender's hostname (zephyr)
    fields      - returns the zephyr fields as a perl list (zephyr)
    auth        - returns whether this zephyr was authentic (zephyr)

An example formatting function that formats messages so that they only
list the direction, sender, and time would be:

    sub owl::format_msg {
        my ($m) = @_;    # assigns the message object passed
                         # to this function to $m
        return sprintf "[direction=%s] from sender %s at %s\n",
                       $m->direction,
                       $m->sender,
                       $m->time;
    }

In the above, $m is the owl::Message object and 
its methods are called with $m->METHODNAME.

An example receiver function that tags all zephyr pings for 
deletion would be:

    sub owl::receive_msg {
        my ($m) = @_;    # assigns the message object passed
                         # to this function to $m
        if ($m->is_zephyr and $m->is_ping) {
           $m->delete();
        }
    }


=================
Section X: STYLES
=================





========================================
Section 7: PERL COMMANDS FROM WITHIN OWL
========================================

Perl code may be executed from within owl with:

  perl <perlcode>

If you use pperl instead of perl, the return value
of the perl command will be displayed in a pop-up window.
This is particularly useful within key bindings 
and aliases.  For example:

  alias finger pperl $x=owl::getcurmsg()->hostname; `finger \@$x`;

Will cause the "finger" command to be used to finger at the host
where the current message came from.  You can then bind this 
to the "f" key with:

   bindkey recv f command finger

See the section above for detailss of commands and functions
that are available from within the perl interpreter.