[Much of this documentation is cloned from `doc/advanced.txt` in the `owl` repository]

BarnOwl supports an expressive filter language that can be used to
describe sets of messages. This language is used both for coloring
messages and for selectively viewing subsets of your messages.

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 POSIX regular
expressions, such as `man 7 regex` or an
[http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html online version].
Note that all pattern matching in Barnowl 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"

The `info` command (bound to `i` by default) includes a list of “Owl
Message Attributes”; Any attribute listed in this area can also be
matched on by a filter.

A filter can refer to other filters using the `filter` command:

{{{   filter somefilt filter foo or filter bar}}}

Would match anything in either the `foo` or `bar` filters. Recursive
filters are explicitly disallowed.

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.

== Built-in special filters ==

 all::
   Matches all messages
 none::
   Matches no messages
 personal::
   “personal” messages, messages sent privately to you.
 login::
   Login/Logout notifications
 auto::
   Messages generated by automated programs
 out::
   Messages sent from you to another user
 aim::
   AIM messages
 zephyr::
   Zephyr messages
 trash::
   "Trash" messages
 ping::
   Zephyr pings
 reply-lockout    Messages for which the reply commands should not work


The `trash` filter is used for the `delete trash` command (bound to
`T`). That command will mark as deleted (but not expunge) all messages
in the `trash` filter. By default, this filter matches messages
on `-c mail`, admin messages, pings, and login notifications.

The `reply-lockout` filter can be used to prevent you from
accidentally replying to classes you do not want to ever send to. By
default it includes class `mail` and class `noc`, both of which are
used for automatic notifications but which users generally never send
to themselves.