umpf.man

   1 NAME
   2 umpf - universal mail processing filter
   3
   4 SYNOPSIS
   5 umpf [-c config_file] [-m default_mailbox]
   6
   7 DESCRIPTION
   8
   9 Umpf is a program that reads an e-mail from stdin and according to
  10 the config file decides, what to do with it. It is possible to forward the
  11 e-mail, filter it through external program and, of course, deliver it to the
  12 local mailbox.  IMAP support is planned, but not ready yet.
  13
  14 OPTIONS
  15
  16 -c file
  17 Set an alternative location of the config file.
  18
  19 -m file
  20 Set an alternative location of the default mailbox.
  21
  22 CONFIGURATION
  23
  24 The program reads a config file (default location is ~/.umpf) and according
  25 to the rules provided it decides, what to do with it. If no rule is matched,
  26 or some action fails, or the config file cannot be parsed, e-mail is
  27 delivered to the default mailbox (default location is /var/mail/login,
  28 program needs setgid to be able to use it).
  29
  30 VARIABLES
  31
  32 Variables can be specified in the config file. Their identifiers must start
  33 with the letter $. Variables have three types that are distinguisghed
  34 according to the case of the identifiers. Upper case identifiers are reserved
  35 for automatic variables like message size, it is possible to modify them but
  36 it is not encouraged. Variables with identifiers starting with an upper-case
  37 letter but mixed case otherwise correspond to values of e-mail headers,
  38 assigning to them will change the headers. Variables with identifiers
  39 starting with a lower case letter are intended for general use. Otherwise,
  40 variable identifiers are case-insensitive, ie. $abc refers to the same
  41 variable as $aBc, but not the same as $Abc and all of these variables differ from $ABC.
  42
  43 AUTOMATIC VARIABLES
  44
  45 Config file recognizes these automatic variables:
  46 $MAIL_LEN refers to the length of the e-mail, including headers
  47 $LAST_EXIT_CODE refers to the exit code of last external program executed (actions filter or pipe can be used to do it)
  48 $LAST_OUTPUT refers to the output of last external program executed by action pipe
  49
  50 COMMANDS
  51 A command is either an action specification or an assignment. All the
  52 commands must with semicolon. Commands can be grouped in blocks bounded by
  53 braces.
  54
  55 ASSIGNMENTS
  56 Assignment is specified in a following way:
  57 Lvalue = Rvalue;
  58 Lvalue is a variable identifier. Rvalue can be variable, a constant (constant
  59 must be given in double quotes) or an expression consisting of variables,
  60 constants and binary operations .,+, -, * and /. Operation . stands for
  61 string contatenations, the rest of them are arithmetic operations. Doing
  62 arithemtic operations makes sense only on integers. Precedence of the operations can be specified using parenthesis.
  63
  64 ACTIONS
  65 Actions are specified with an arrow operator. Plain
  66 -> ;
  67 means "deliver the e-mail to the default mailbox and exit".
  68 -> expression ;
  69 means "deliver the e-mail the mailbox specified behind arrow and exit"
  70 -> pipe expression ;
  71 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.
  72 -> filter expression ;
  73 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.
  74 -> discard ;
  75 means just "discard the email and exit".
  76 -> mail expression ;
  77 means "forward the e-mail to the address specifed behind the mail keyword and exit"
  78
  79 If action fails, the e-mail is delivered to the default mailbox.
  80
  81 Some of the actions (delivery or forwarding an e-mail) can have keyword copy in front of the arrow, ie.
  82 copy -> "mailbox";
  83 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.
  84
  85 CONDITIONS
  86
  87 Conditional execution of commands can be specified in a following way:
  88
  89 if (condition) { ... }
  90 or
  91 if (condtion) { ... } else { ... }
  92
  93 where condition can be a constant, a variable or an expression consisting of
  94 following operations:
  95 & is binary boolean and
  96 | is binary boolean or
  97 ^ is binary boolean xor
  98 ! is unary boolean not
  99
 100 A variable or a constant has a boolean value 0, if its value is either "" or "0" and 1 otherwise.
 101
 102 Expressions can be compared using following binary relations.
 103
 104 String comparisons:
 105 ~~ means "matches" (left operand should be string, right one can be a perl compatible regular expression)
 106 !~ means "does not match"
 107
 108 Integer comparisons (does not make sense on strings):
 109 == means "is equal to"
 110 != means "is not equal to"
 111 < means "is lesser than"
 112 > means "is greater than"
 113 <= means "is lesser or equal than"
 114 >= means "is greater or equal than"
 115
 116 COMMENTS
 117 All the text behind a hash character up to the end of the line is ignored.
 118
 119 BUGS
 120 Aer prsenet.
 121
 122 TODO
 123 IMAP support.
 124
 125 AUTHOR
 126 Anicka <anicka@anicka.net>