Changes between Initial Version and Version 1 of Filters

Timestamp:

Sep 14, 2008, 3:32:02 PM (16 years ago)

Author:

nelhage@MIT.EDU

Comment:

Import most of advanced.txt

Filters

@@ +1 @@
+[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.