readme

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

break
=====
  Usage:
	break

	Sets the BREAK flag. If all config files have been read and the BREAK
	flag is set, no SMS will be sent.

        To abort the SMS sending depending on some mail content, use the abort
	keyword within an if/endif section.

unbreak
=======
  Usage:
	unbreak

	Clears the BREAK flag. See 'break'.

exit
=====
  Usage:
	exit: <exit code>

	Sets the BREAK flag and sets what return code mail2sms should return
        to the invoking process/shell. If all config files have been read and
        the BREAK flag is set, no SMS will be sent.

        Note that this keyword can also be used within IF/ENDIF sections and
        if so, it will be treated as a ABORT keyword with an added exitcode
        specifier.

------------------------------------------------------------------------------
  2.5 Conditional Actions and Variables
------------------------------------------------------------------------------

 These actions can be put on root-level, within begin-end sections or within
if-endif section. When set within if/endif sections, they take effect at first
when that IF expression matches.

 All these keywords take advantage of the log string in case there is one set
before the actual keyword. The logging will take place when the action is
performed.


abort
=====
  Usage:
	abort: <message>

	The abort keyword aborts the sms creation immediately. This keyword
	can't be used on root-level, abort MUST be put within an if/endif
	section. The message will simply be logged.

config
======
  Usage:
	config: <file name>

	Reads the specified config file if the previous 'if' regex matches.

create
======
  Usage:
	create: <filename>

	Creates the file if it isn't already created.

delete
======
  Usage:
	delete: <filename>

	Deletes the specified file.

exit  (see the upper section for full details)
====

maxparts
========
  Usage:
	maxparts: <num>

        This specifies the maximum number of output parts that mail2sms is
	allowed to generate. Default is 1. Each part is maximum 'outsize'
	bytes long.

multipart
=========
  Usage:
        multipart: <format>

        Specifies how to deal with multipart prefixes or suffixes. If the
	message is sent in more than one part, this string is used to define
	the prefix or suffix to include in every single part. If this format
	starts with a dash (-) the rest of the string will be used as a
	suffix, otherwise it will be a prefix.

        The format string has two "variables" that will be replaced with the
	numbers that goes for each part and message:

                $index     starts at 1 and is increased for every part
                $numparts  the amount of parts that this message uses 

        Other characters that can be used in the string are:

                \t         Tab character
                \n         Newline character
                \r         Carriage return character

output
======
  Usage:
	output: <output>

	Specifies what to output and in what order. Available variables are:

          $from         The name or the email of the sender
          $fromaddress  The email address of the sender
          $to           The name or the email of the receiver
          $toaddress    The email address of the receiver
          $subject      The subject field
          $body         The body of the mail

        Other characters that can be used in the string are:

        \t              Tab character
        \n              Newline character
        \r              Carriage return character

	Default output string is "F: $from S: $subject B: $body". Note that
        as much as possible of all variables will be output. I.e if the first
        variable used is very big, no other output will be shown.

outsize
=======
  Usage:
	outsize: <number of bytes>

	Specifies the maximum size of the output message. Default is 160.
	There is at max 'maxparts' parts of this size sent.

system
======
  Usage:
	system: <command line>

	Runs the specified shell command line.

phone
port
progargs
program
server
=======
  Usage:
	<keyword> : <value>

	These keywords all set the variable with the same name as the keyword.
	The variable can be used in the 'run' string to specify what command
	line to use when passing the SMS to a client program.

run
===
  Usage:
	run : <command line to run>

	This command line is a string with the possibility to insert different
	variables. All non-variable characters are inserted as specified. The
	'output' string will be passed to the program on its stdin.

	There is no default run string. If no string is specified, no program
	will be run by mail2sms.

	Available variables are:

	Name		Contains
	----		--------
	$message	The entire SMS message.
	$phone		What has been specified with the phone keyword.
	$port		What has been specified with the port keyword.
	$progargs	What has been specified with the progargs keyword.
	$program	What has been specified with the program keyword.
	$server		What has been specified with the server keyword.

filter
======
  Usage:
        filter : <filter instruction>

        The filter can only be used conditionally. It cannot be set on the
        root-level. A filter is set on a section on a line-by-line basis. When
        the filter is switched on, it is in use until it is again switched
        off. The filter instruction that is written on the right side should
        be in this format:

                <name> <status> [lines <num>] [exclude/include]

        'name' is the filter name. Currently 'ignore' is the only available
        supported filter. 'ignore' effectively cuts off the lines in the
        filtered section. Note that the theory here is that you should be able
        to switch on and off different filters independently. As soon as there
        is more filters available that is.

        'status' is either "on" or "off". Setting a filter to "on" means it
        takes effect, it gets in use. Switched "off" a filter means that the
        filter is turned off and things go back to normal (non-filtered).

        'lines <num>' (for 'on' entries only) sets the filter to remain valid
        for a certain number of lines, the matching one counted. This makes
        the filter to automatically get switched off after this amount of lines
        have been sent through the filter.

        'exclude' in the line means that the matching line in itself should
        not be considered as part of the filtered section. Exclude it from the
        section.

        'include' is the opposite of 'exclude'. It is the default behaviour
        and it makes the matching line of a filter expression to be included
        in the filter section.

------------------------------------------------------------------------------
  2.6 Logfile and Include
------------------------------------------------------------------------------
 These can only be made conditional within begin/end sections.

logfile
=======
  Usage:
	logfile: <filename>

	Logs all messages to the specified logfile instead of stderr.

showlog
=======
  Usage:
	showlog: <what to include>

	Sets what kinds of log messages to include in the logfile. The format
	for the control string is:

		<[+/-]LOGTYPE1>, <[+/-]LOGTYPE2>

	Available log types are: ALL, INFO, BREAK, ERROR, DEBUG, WARNING,
	ABORT, IF, SEARCH, NOT, DELETE, CREATE, SYSTEM, CONFIG, REGEX, ACTION

	A few examples explain this best:

	To see all log entries:

		showlog: +all

	To see all except the DELETE ones:

		showlog: +all, -delete

	To see the default set but not the WARNING ones:

		showlog: -warning

	To disable if, search and not:

		showlog: -if,search,not

	Switch off everything:

		showlog: -all

	NOTE: the -d command line flag enables "ALL" (including DEBUG). Normal
	defaults are "+ALL,-DEBUG".

path
====
  Usage:
	path: <directory name without trailing slash>

	Adds the specified directory to the include path. The include path is
	a list of directories that mail2sms will search through for the
	specified file when include is used. By default, no directory is in
	the include path.

include
=======
  Usage:
	include: <file>

	Makes that specified conf file get read.

==============================================================================
			    3. mail2sms Internals
==============================================================================

 The Regex Loop
 --------------
  When traversing the config files, mail2sms creates a linked list of regex
nodes. One node is added for each IF or SEARCH/REPLACE.

 Each regex node may have sub-list (that themselves are actal regex nodes)
that if the main node matches, are moved into the main list. They're not taken
into account until they're in the main list.

 Each sublist node may itself have subnodes of course, which can make it
pretty advanced.

 Each regex node may also have a list of not-matches. If any of the entries in
the not-list matches, the main node is considered not a match. An attempt to
draw this situation looks like:

 Search/Replace #1
        |
        |
     If #2 ----- Subsearch/replace #1 - Subsearch/replace #2 - ...
       	|
        |
 Search/Replace #3
        | \__                             
        |    \__                          
        |        Not #1  - Not #2 - ...
        |
 Search/Replace #4
        |
       ...

 The list is built when the config files are read. mail2sms then goes through
the input mail and for each line of the mail it does the following:

We start at the beginning with the highest prio; number 1.

  1. If the node isn't of this prio, get the next. If we reach the end of the
     list, increase the prio to check for and restart the list. If the prio
     to check for reaches max, end the loop.

  2. Check if the condition is dependent on what kind of input (header, from,
     subject, etc). If it isn't supposed to replace/match the current type,
     loop.

  3. Make sure that we haven't looped this too many times.

  4. Check if the regex matches. Otherwise, loop.

  5. Make sure we haven't found exactly this match too many times.

  6. Check the type of the regex.

    6.1 If it is an 'IF':

	o Check that it hasn't already been "done".

	o Check the not-list. If any of them matches, treat this as a
	  non-match.

        o Perform all the actions that were specified within this if/endif
          block.

	o Move the sublist to the "main list".

    6.2 If it is a 'SEARCH/REPLACE', perform the replace.

  7. Reset to start-of-list at prio 1.

  8. Loop

 Order Of Tests
 --------------

 First all headers are read.

 Each header is first tested as a 'header' and then secondly, if it is a known
 header (like To:, From: etc) it is tested as that kind of header.

 When all headers are done the body gets read.

 Each line of the body is tested as 'body', one line at a time. This goes on
 until mail2sms has collected a body-"buffer" that is ten times the size of
 the output text (by default that means 10*160 bytes). It then tests the whole
 body-buffer as 'fullbody'.

 In each of these many tests, the low prio tests are performed before the high
 prio tests.  But this order described here is important to understand since
 the prio system only changes importance within the same test.