readme

邮件发送后向相应手机发送短信

                               _ _ ____                    
               _ __ ___   __ _(_) |___ \ ___ _ __ ___  ___ 
              | '_ ` _ \ / _` | | | __) / __| '_ ` _ \/ __|
              | | | | | | (_| | | |/ __/\__ \ | | | | \__ \
              |_| |_| |_|\__,_|_|_|_____|___/_| |_| |_|___/

Project: mail2sms
Version: 1.3.x
Date:    February 12, 2001
Author:  Daniel Stenberg <[e-mail]>
Web:     http://www.contactor.se/~dast/mail2sms/

==============================================================================
  Description
==============================================================================

  mail2sms reads a (MIME) mail and converts it to a short message. It offers
search and replace, conditional rules, conditional search and replace etc to
create a custom output. It can optionally pipe its output into a specified
program.

  mail2sms is entirely FREE. See the LEGAL file for details.

			      Table Of Contents
			      =================

	1. Usage

	2. Config File Format
	  In General
	  2.1 General Keywords
	  2.2 Search/Replace, Conditional Search/Replace
	  2.3 Conditional Config File Sections
	  2.4 Stop/Allow Message Forwarding
	  2.5 Conditional Actions and Variables
	  2.6 Logfile and Include

	3. mail2sms internals

==============================================================================
				   1. Usage
==============================================================================

	mail2sms [options] < mail

 mail2sms reads the config file /usr/local/mail2sms/config first and then
 $HOME/.mail2sms by default.

 Available options:

 -c [file]  specifies what config file to read. It can be used repeatedly.
 -d         switch on debug messages in the log file
 -I [dir]   adds a directory to the include path.
 -l [file]  log everything to the specified file, this overrides 'logfile'
            entries on the config file
 -n         prevents reading the default config files
 -o         makes mail2sms write the sms message to stdout when completed (and
            not invoke any sub-command).
 -p         sets the $phone variable (see the run command)
 -q         shuts off all logging
 -v         prints version number and quits

==============================================================================
			    2. Config File Format
==============================================================================

Each line should be in the format:

	<keyword> [ : <value> ]

Values are either written plainly and whitespaces left and right of the words
are cut off, or within quotes ("). If the value is quoted, you must escape
quotes to be able to have them in the string, as in: " \" ".

Lines beginning with '#' are treated as comments.

Basically, there are two kinds of keywords. The first is the one read and
dealt with in real-time when read from the config file, they may also build
strings that define output format, specify command to run etc.. The other type
is the keywords that build a tree of regular expressions with accompanying
actions. Those actions might be performed when the regexes match contents of
the input mail. It is important to understand the difference.

------------------------------------------------------------------------------
  2.1 General Keywords
------------------------------------------------------------------------------

options
=======
  Usage:
	options: <options>

	(may be specified as o:)

	Options are single words separated with spaces or commas. The options
	control the following search/replace or if operation. Available
	options are:

	 1perline (previously: "noloop")
	   - only one replace per line
	 once
	   - only one replace per mail
	 subject (*)
	   - replace in subject
	 from (*)
	   - replace in from (the name or if not available, the email address)
         fromaddress (*)
           - replace in from address (the email address)
	 to (*)
	   - replace in to (the name or if not available, the email address)
         toaddress (*)
           - replace in the to field (the email address)
	 body (*)
	   - replace in body
	 fullbody (*)
	   - replace in the full body, as one large buffer without newlines
         header (*)
	   - search/replace in header! Must be specifily specified, if not
	     specified no searching will be done in headers.
	 nocase
	   - case insensitive search. Only the letters A-Z will be treated
	     case insensitively.
	 prio <1-5>
	   - lower prio value makes the regex be done before higher values.
	     Default prio is 3.

	(*) = when one or more of these are used, the search/replace or if
	      is only valid for the specified parts.

log
===
  Usage:
	log: <message>

	This is a message that will be added to the log file when the action
	specified after this is performed. 'log' is used by search, if,
	not, begin and many other keywords.

------------------------------------------------------------------------------
 2.2 Search/Replace, Conditional Search/Replace
------------------------------------------------------------------------------
search
======
  Usage:
	search: <search regex>

	(may be specified as s:) The search regex is a full posix egrep style
	regex. Must be used BEFORE the replace command.

        This regex may in fact match many times, not just one.

replace
=======
  Usage:
	replace: <replacement>

	(may be specified as r:) Replace is the replacement for the
	search. \<num> can be used to insert "registers" from the search. Must
	be used AFTER a search command. This must also be the last line in a
	search/replace action.

        One search/replace pair may be used many times if the search pattern
        is general enough.

if
==
  Usage:
	if: <trigging regex>

	Starts a conditional sub-section. This sub-section that MUST be ended
	with an 'endif' keyword, is an ordinary sequence of config items that
	won't be considered until the if-regex has first matched once. Once
	the if-regex has matched, all the sub-sections' expressions (like
	search/replace within this sub-section) are all moved to the "normal"
	list and are then treated just as normal items.

	You can control the if-regex with the 'options' keyword. The 'log'
	keyword is also used.

	You can "append" actions to this keyword by using one or more of the
	following keywords within the if/endif block:

                abort, outsize, create, delete, system, config, run, program,
                progargs, output, phone, server, port, multipart, maxparts

        When you use these keywords within an if/endif block, they will all
        take effect the first time the IF regex matches (and only then).

        Do not confuse the IF keyword with BEGIN. The IF/ENDIF is for
        conditions against mail content like if you want different behaviour
	for different kinds of mails. BEGIN/END is used for making parts of
	the config file conditional.

	You MUST end this sub-section with 'endif'

endif
=====
  Usage:
	endif

	Closes a conditional sub-section previously started with the 'if'
	keyword.

not
===
  Usage:
	not: <regex>

	This keyword can only be used within an if-endif section, or after a
	'replace' keyword. Each time this keyword is used, it adds a regex to
	the list on the the preceeding regex keyword (i.e search/replace, or
	if) that must NOT match for the regex to match. 'not' can be used any
	number of times.

	You may specify a separate 'log' line for the NOT expression. The
	'not' expression will always be tried on the exact same context that
	the previous regex-expression just matched.

	Example, if the subject includes Daniel but NOT Stenberg, add a
	special search/replace rule:

		options: subject
		if: Daniel
		Not: Stenberg
			search: Daniel
			replace: Fake-Danman
		endif

	Make a search/replace like the above without the if:

		options: subject
		search: Daniel
		replace: Fake-Danman
		not: Stenberg

------------------------------------------------------------------------------
 2.3 Conditional Config File Sections
------------------------------------------------------------------------------
 These keywords control what parts of a config file that is read.

when
whennot
=======
  Usage:
	when: <expression>
	whennot: <expression>

	If the given when expression matches current conditions, it sets the
	condition flag. 

        If a whennot expression matches current conditions it clears the
        condition flag.

	You can also reverse the expression by prefixing it with !.

	NOTE: a 'when' command only defines what sections to read from the
	config file.

	The condition flag controls whether a following sub-section shall be
	parsed or skipped. If the condition flag is set, the section is
	parsed, otherwise it is skipped!

	A sub section is specified within 'begin', 'else' and 'end'
	keywords. The condition flag is always undefined after a begin, end
	or else.

	Default state of the condition flag is undefined, and the first when
	command will set it.

	    The EXPRESSION may involve:

	     day <sequence 1 - 31>
		Day of the month.
	     hour <sequence 0 - 23 or 0000 - 2359>
		Note that the size of the numbers are used to figure out which
		of these formats to use. 0-23 means full hours, 0-26 would
		mean from 00:00 to 00:26>
	     min <sequence 0000 - 2359>
		Note that this is hour+minutes and not plain minutes
	     wday <sequence 1 - 7>
		Day of the week. 1 is Monday, 7 is Sunday.
	     month <sequence 1 - 12>
		Month of the year. 1 is January, 12 is December.
	     year <sequence 1998 - 2038>
		Year number. Only full 4-digit years are supported.
	     file <filename>
		TRUE if the file is present
	     always
		Always set TRUE
	     never
		Always set FALSE

	    Sequences can be specified as:

		1-4,2,9-4,3 (no whitespace)

	    Filename is a filename without whitespace.

	    You can combine the different parts of an expression to a combined
	    expression as in:

		day 1-3 hour 8-14 wday 1,3,6

	    The file keyword makes the operation dependent on the presense of
	    a named file:

		when: file /etc/passwd

	    ... requires that named file to be there for the program to
	    continue.

	    Expressions are read top to bottom.

	    You can mix when and whennot keywords to make complex expressions.

	Example, make a special search expression friday the 13th 1999:

		# place condition
		when: year 1999
		when: day 13 wday 5
		begin
		  # start sub section
	   	  options: nocase
		  search: .*
		  replace: friday the 13th!
		end
begin
=====
  Usage:
	begin

	Starts a config file sub section. If the condition flag is set or
	undefined, this section will be parsed. If the condition flag is
	cleared, this section will be skipped all the way to the following end
	(or else) keyword (not counting sub sections within this section). You
	MUST end a sub section with a corresponding 'end'.

        It is important to remember that begin/end keywords only change what
        to read in the config file. The section's "condition flag" is set by
        conditions found when reading the config. The begin/end section can
        *NEVER* depend on particular mail contents, since the config file is
        scanned long before any mail content is known. To make conditional
        actions depending on mail content, see the IF keyword.

	If 'log' was used for this keyword, it will be logged together with
	the condition flag status.

	You can use '{' instead of 'begin'.

end
===
  Usage:
	end

	Ends a sub section. See 'begin' and 'when' for more details. This
	shall not be used without a preceeding 'begin' or 'else' keyword.

	You can NOT have the 'end' keyword of section appear in another file
	than the one with the initiating 'begin'.

	You can use '}' instead of 'end'.

else
====
  Usage:
	special

	This must be preceeded with a begin keyword and an end keyword should
	end this section. This keyword ends a section and if the previous one
	was parsed, the one following this won't be and vice verse.

	You can NOT have the 'else' keyword of section appear in another file
	than the one with the initiating 'begin'.

	'else' shall not be used without a preceeding 'begin' keyword.

------------------------------------------------------------------------------
  2.4 Stop/Allow Message Forwarding
------------------------------------------------------------------------------
 These commands are taken care of when the config file is read, and the
decision whether to continue or not will be taken before the mail is read at
all.