From: Anicka Bernathova Date: Wed, 22 Jul 2009 14:14:46 +0000 (+0200) Subject: umpf.1 done X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=4a7b9ef7cccc634e5078ed7540a83cc99ea05bae;p=umpf.git umpf.1 done --- diff --git a/umpf.1 b/umpf.1 new file mode 100644 index 0000000..e696e6e --- /dev/null +++ b/umpf.1 @@ -0,0 +1,200 @@ +.TH "umpf" 1 +.SH NAME +umpf \- universal mail processing filter +.SH SYNOPSIS +.B umpf +[-c config_file] [-m default_mailbox] +.SH 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. +.SH OPTIONS +.TP +.B \-c "\|file\^" +Set an alternative location of the config file. +.TP +.B \-m "\|file\^" +Set an alternative location of the default mailbox. +.SH CONFIGURATION +The program reads a config file (default location is +.I ~/.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 +.I /var/mail/login +, program needs setgid to be able to use it). +.SS VARIABLES +Variables can be specified in the config file. Their identifiers must start +with the letter +.B "$" +, 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. +.SS AUTOMATIC VARIABLES +Config file recognizes these automatic variables: +.TP +.B $MAIL_LEN +refers to the length of the e-mail, including headers +.TP +.B $LAST_EXIT_CODE +refers to the exit code of last external program executed (actions filter or +pipe can be used to do it) +.TP +.B $LAST_OUTPUT +refers to the output of last external program executed by action pipe +.SS 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. +.SS ASSIGNMENTS +Assignment is specified in a following way: +.P +.B Lvalue = Rvalue ; +.P +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 +.B . +, +.B + +, +.B - +, +.B * +and +.B / +, operation +.B . +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 parentheses. +.SS ACTIONS +Actions are specified with an arrow operator. Plain +.TP +.B -> ; +means "deliver the e-mail to the default mailbox and exit". +.TP +.B -> expression ; +means "deliver the e-mail the mailbox specified behind arrow and exit" +.TP +.B -> pipe expression ; +means "pipe the e-mail to the external program specified behind pipe +keyword". Output of the program is stored in +.B $LAST_OUTPUT +variable, its exit code is stored in +.B $LAST_EXIT_CODE +variable. +.TP +.B -> filter expression +means "pipe the e-mail to the external program and replace it with output of the program". All the headers variables, +.B $MAIL_LEN +and +.B $LAST_EXIT_CODE +are set accordingly. +.TP +.B -> discard ; +means just "discard the email and exit". +.TP +.B -> mail expression ; +means "forward the e-mail to the address specifed behind the mail keyword and exit" +.TP -1 +If action fails, the e-mail is delivered to the default mailbox. +.P +Some of the actions (delivery or forwarding an e-mail) can have keyword copy +in front of the arrow, ie. +.P +.B copy -> "mailbox"; +.P +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. +.SS CONDITIONS +Conditional execution of commands can be specified in a following way: +.P +.B if (condition) { ... } +.P +.B if (condtion) { ... } else { ... } +.P +.B if (condition) { ... } else if { ... } [ else { ... } ] +.P +where the condition can be a constant, a variable or an expression consisting +of following operations: +.TP +.B & +is binary boolean and +.TP +.B | +is binary boolean or +.TP +.B ^ +is binary boolean xor +.TP +.B ! +is unary boolean not +.TP -1 +A variable or a constant has a boolean value 0, if its value is either "" or +"0" and 1 otherwise. +.P +Expressions can be compared using following binary relations. +.P +String comparisons: +.P +.TP +.B ~~ +means "matches" (left operand should be string, right one can be a perl compatible regular expression) +.TP +.B !~ +means "does not match" +.TP -1 +Integer comparisons (does not make sense on strings): +.TP +.B == +means "is equal to" +.TP +.B != +means "is not equal to" +.TP +.B < +means "is lesser than" +.TP +.B > +means "is greater than" +.TP +.B <= +means "is lesser or equal than" +.TP +.B >= +means "is greater or equal than" +.TP -1 +Parentheses can be used to specify a precedence. Boolean operations have greater priority than relation operations. +.SS COMMENTS +All the text behind a hash character up to the end of the line is ignored. +.SH EXIT STATUS +.TP +.B 0 +Success +.TP +.B 1 +Failure +.TP +.B EX_TEMPFAIL +Temporary OS failure +.SH BUGS +Aer prsenet. +.SH TODO +IMAP support. +.SH AUTHOR +Anicka +.SH RESOURCES +Current version of the program can be downloaded at +.B http://www.anicka.net/umpf +.SH COPYING +The program can be used according to the terms of GPL, version 2. diff --git a/umpf.man b/umpf.man deleted file mode 100644 index c214596..0000000 --- a/umpf.man +++ /dev/null @@ -1,126 +0,0 @@ -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