From 64061fd8e5c4dc99e04bd2605251989c2613fc96 Mon Sep 17 00:00:00 2001 From: Anicka Bernathova Date: Wed, 22 Jul 2009 15:08:00 +0200 Subject: [PATCH] started writing docs --- umpf.man | 126 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 umpf.man diff --git a/umpf.man b/umpf.man new file mode 100644 index 0000000..c214596 --- /dev/null +++ b/umpf.man @@ -0,0 +1,126 @@ +NAME +umpf - universal mail processing filter + +SYNOPSIS +umpf [-c config_file] [-m default_mailbox] + +DESCRIPTION + +Umpf is a program that reads an e-mail from stdin and according to +the config file decides, what to do with it. It is possible to forward the +e-mail, filter it through external program and, of course, deliver it to the +local mailbox. IMAP support is planned, but not ready yet. + +OPTIONS + +-c file +Set an alternative location of the config file. + +-m file +Set an alternative location of the default mailbox. + +CONFIGURATION + +The program reads a config file (default location is ~/.umpf) and according +to the rules provided it decides, what to do with it. If no rule is matched, +or some action fails, or the config file cannot be parsed, e-mail is +delivered to the default mailbox (default location is /var/mail/login, +program needs setgid to be able to use it). + +VARIABLES + +Variables can be specified in the config file. Their identifiers must start +with the letter $. Variables have three types that are distinguisghed +according to the case of the identifiers. Upper case identifiers are reserved +for automatic variables like message size, it is possible to modify them but +it is not encouraged. Variables with identifiers starting with an upper-case +letter but mixed case otherwise correspond to values of e-mail headers, +assigning to them will change the headers. Variables with identifiers +starting with a lower case letter are intended for general use. Otherwise, +variable identifiers are case-insensitive, ie. $abc refers to the same +variable as $aBc, but not the same as $Abc and all of these variables differ from $ABC. + +AUTOMATIC VARIABLES + +Config file recognizes these automatic variables: +$MAIL_LEN refers to the length of the e-mail, including headers +$LAST_EXIT_CODE refers to the exit code of last external program executed (actions filter or pipe can be used to do it) +$LAST_OUTPUT refers to the output of last external program executed by action pipe + +COMMANDS +A command is either an action specification or an assignment. All the +commands must with semicolon. Commands can be grouped in blocks bounded by +braces. + +ASSIGNMENTS +Assignment is specified in a following way: +Lvalue = Rvalue; +Lvalue is a variable identifier. Rvalue can be variable, a constant (constant +must be given in double quotes) or an expression consisting of variables, +constants and binary operations .,+, -, * and /. Operation . stands for +string contatenations, the rest of them are arithmetic operations. Doing +arithemtic operations makes sense only on integers. Precedence of the operations can be specified using parenthesis. + +ACTIONS +Actions are specified with an arrow operator. Plain +-> ; +means "deliver the e-mail to the default mailbox and exit". +-> expression ; +means "deliver the e-mail the mailbox specified behind arrow and exit" +-> pipe expression ; +means "pipe the e-mail to the external program specified behind pipe keyword". Output of the program is stored in $LAST_OUTPUT variable, its exit code is stored in $LAST_EXIT_CODE variable. +-> filter expression ; +means "pipe the e-mail to the external program and replace it with output of the program". All the headers variables, $MAIL_LEN and $LAST_EXIT_CODE are set accordingly. +-> discard ; +means just "discard the email and exit". +-> mail expression ; +means "forward the e-mail to the address specifed behind the mail keyword and exit" + +If action fails, the e-mail is delivered to the default mailbox. + +Some of the actions (delivery or forwarding an e-mail) can have keyword copy in front of the arrow, ie. +copy -> "mailbox"; +When copy is specified, the program does not exit after doing an action but continues reading the rules. It also does not deliver to default mailbox if action fails. + +CONDITIONS + +Conditional execution of commands can be specified in a following way: + +if (condition) { ... } +or +if (condtion) { ... } else { ... } + +where condition can be a constant, a variable or an expression consisting of +following operations: +& is binary boolean and +| is binary boolean or +^ is binary boolean xor +! is unary boolean not + +A variable or a constant has a boolean value 0, if its value is either "" or "0" and 1 otherwise. + +Expressions can be compared using following binary relations. + +String comparisons: +~~ means "matches" (left operand should be string, right one can be a perl compatible regular expression) +!~ means "does not match" + +Integer comparisons (does not make sense on strings): +== means "is equal to" +!= means "is not equal to" +< means "is lesser than" +> means "is greater than" +<= means "is lesser or equal than" +>= means "is greater or equal than" + +COMMENTS +All the text behind a hash character up to the end of the line is ignored. + +BUGS +Aer prsenet. + +TODO +IMAP support. + +AUTHOR +Anicka -- 2.39.2