Improve docs.

* doc/mailfromd.texi, NEWS: Document `getopt' and run (script)
mode. 
* mfd/lex.l: Octal characters can contain 1 to 3 octal characters.
* mfd/bi_getopt.m4: Allow to specify long options (without short
option equivalents) that take arguments.
* mfd/main.c (options): Document optional argument to the `--run'
option.


git-svn-id: file:///svnroot/mailfromd/trunk@1722 7a8a7f39-df28-0410-adc6-e0d955640f24

1 files changed, 331 insertions, 0 deletions

diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi
index ea42e42d..0a0edbe0 100644
--- a/doc/mailfromd.texi
+++ b/doc/mailfromd.texi
@@ -168,6 +168,7 @@ Tutorial
 * Examining mail contents::
 * Databases::
 * Testing Filter Scripts::
+* Run Mode::
 * Logging and Debugging::
 * Runtime errors::
 * Cautions::
@@ -178,6 +179,10 @@ Databases
 * Basic Database Operations::
 * Database Maintenance::
 
+Run Mode
+
+* getopt::      Parsing Command Line Arguments.
+
 Mail Filtering Language
 
 * Comments::                    Usual and pragmatic comments.
@@ -1465,6 +1470,7 @@ interaction with the Mail Transport Agent.
 * Examining mail contents::
 * Databases::
 * Testing Filter Scripts::
+* Run Mode::
 * Logging and Debugging::
 * Runtime errors::
 * Cautions::
@@ -3015,6 +3021,322 @@ its standard input and sends answers to the standard output.  The
 with it.  For the detailed description of the program and the ways to
 use it, @xref{mtasim}.
 
+@node Run Mode
+@section Run Mode
+@cindex run mode
+  Mailfromd provides a special option that allows to run arbitrary
+@acronym{MFL} scripts.  This is an experimental feature, intended for
+future use of @acronym{MFL} as a scripting language.
+
+@xopindex{run, described}
+@cindex main, MFL function
+  When given the @option{--run} command line option,
+@command{mailfromd} loads the script given in its command line and
+executes a function called @samp{main}. 
+
+The function main must be declared as:
+
+@smallexample
+func main(...) returns number
+@end smallexample
+
+Mailfromd passes all command line arguments that follow the script
+name as arguments to that function.  When the function returns, its
+return value is used by @command{mailfromd} as exit code.
+
+As an example, suppose the file @file{script.mf} contains the
+following:
+
+@smallexample
+func main (...)
+  returns number
+do
+  loop for number i 1,
+       while %i <= $#,
+       set i %i + 1
+  do
+    echo "arg %i=" $(%i)
+  done
+done
+@end smallexample
+
+This function prints all its arguments (@xref{variable number of
+arguments}, for a detailed description of functions with variable
+number of aruments).  Now running:
+
+@smallexample
+$ mailfromd --run script.mf 1 file dest
+@end smallexample
+
+@noindent
+displays the following:
+
+@smallexample
+@cartouche
+arg 1=1
+arg 2=file
+arg 3=dest
+@end cartouche
+@end smallexample
+
+Note, that @acronym{MFL} does not have a direct equivalent of
+shell's @code{$0} argument.  If your function needs to know the name
+of the script that is being executed, use @code{__file__} built-in
+constant instead (@pxref{Built-in constants, __file__}.
+
+You may name your start function with any name other than the default
+@samp{main}.  In this case, give its name as an argument to the
+@option{--run} option.  This argument is optional, therefore it must
+be separated from the option by an equals sign (with no whitespace
+from either side).  For example, given the command line below,
+@command{mailfromd} will load file @file{script.mf} and execute the
+function named @samp{start}:
+
+@smallexample
+$ mailfromd --run=start script.mf
+@end smallexample
+
+@menu
+* getopt::      Parsing Command Line Arguments.
+@end menu
+
+@node getopt
+@subsection Parsing Command Line Arguments
+@cindex command line arguments, parsing in MFL
+@cindex scripting, parsing command line arguments
+@cindex parsing command line arguments
+
+A special function is provided to break (parse) options in command
+lines, and to check for legal options.  It uses the GNU getopt
+routines (@pxref{Getopt, getopt, , libc, The GNU C Library
+Reference Manual}).
+
+@deftypefn {Built-in Function} string getopt (number @var{argc}, @
+  pointer @var{argv}, ...)
+The @command{getopt} function parses the command line arguments, as
+supplied by @var{argc} and @var{argv}.  The @var{argc} argument is the
+argument count, and @var{argv} is an opaque data structure,
+representing the array of arguments@footnote{When @acronym{MFL} has
+array data type, the second argument will change to array of
+strings.}.  The operator @code{vaptr} (@pxref{vaptr}) is
+provided to initialize this argument.
+
+An argument that starts with @samp{-} (and is not exactly @samp{-} or
+@samp{--}), is an option element.  An argument that starts with a
+@samp{-} is called @dfn{short} or @dfn{traditional} option. The
+characters of this element, except for the initial @samp{-} are option
+characters.  Each option character represents a separate option.  An
+argument that starts with @samp{--} is called @dfn{long} or @dfn{GNU}
+option.  The characters of this element, except for the initial
+@samp{--} form the @dfn{option name}.
+
+Options may have arguments.  The argument to a short option is
+supplied immediately after the option character, or as the next word
+in command line.  E.g., if option @option{-f} takes a mandatory
+argument, then it may be given either as @option{-farg} or as
+@option{-f arg}.  The argument to a long option is either given
+immediately after it and separated from the option name by an equals
+sign (as @option{--file=arg}), or is given as the next word in the
+command line (e.g. @option{--file arg}).
+
+If the option argument is optional, i.e. it may not necessarily be
+given, then only the first form is used (i.e. either @option{-farg} or
+@option{--file=arg}.
+
+The @samp{--} command line argument ends the option list.  Any
+arguments following it are not considered options, even if they begin
+with a dash.
+
+If @code{getopt} is called repeatedly, it returns successively each of
+the option characters from each of the option elements (for short
+options) and each option name (for long options).  In this case, the
+actual arguments are supplied only to the first invocation.
+Subsequent calls must be given two nulls as arguments.  Such
+invocation instructs @code{getopt} to use the values saved on the
+previous invocation.
+
+When the function finds another option, it returns its character or name
+updating the external variable @code{optind} (see below) so that the
+next call to @code{getopt} can resume the scan with the following
+option.
+
+When there are no more options left, or a @samp{--} argument is
+encountered, @code{getopt} returns an empty string.  Then
+@code{optind} gives the index in @var{argv} of the first element that
+is not an option.
+
+The legitimate options and their characteristics are supplied in
+additional arguments to @code{getopt}.  Each such argument is a string
+consisting of two parts, separated by a vertical bar (@samp{|}).  Any
+one of these parts is optional, but at least one of them must be
+present.  The first part specifies short option character.  If it is
+followed by a colon, this character takes mandatory argument.  If it
+is followed by two colons, this character takes an optional argument.
+If only the first part is present, the @samp{|} separator may be
+omitted.  Examples:
+
+@table @asis
+@item "c"
+@itemx "c|"
+Short option @option{-c}.
+
+@item "f:"
+@itemx "f:|"
+Short option @option{-f}, taking a mandatory argument.
+
+@item "f::"
+@itemx "f::|"
+Short option @option{-f}, taking an optional argument.
+@end table
+
+If the verical bar is present and is followed by any characters, these
+characters specify the name of a long option, synonymous to the short
+one, specified by the first part.  Any mandatory or optional arguments
+to the short option remain mandatory or optional for the corresponding
+long option.  Examples:
+
+@table @asis
+@item "f:|file"
+Short option @option{-f}, or long option @option{--file}, requiring an
+argument.
+
+@item "f::|file"
+Short option @option{-f}, or long option @option{--file}, taking an
+optional argument.
+@end table
+
+In any of the above cases, if this option appears in the command line,
+@command{getopt} returns its short option character.
+
+To define a long option without a short equivalent, begin it with a
+bar, e.g.:
+
+@table @asis
+@item "|help"
+@end table
+
+If this option is to take an argument, this is specified using the
+mechanism described above, except that the short option character
+is replaced with a minus sign.  For example:
+
+@table @asis
+@item "-:|output"
+Long option @option{--output}, which takes a mandatory argument.
+
+@item "-::|output"
+Long option @option{--output}, which takes an optional argument.
+@end table
+
+@vrindex optarg
+If an option is returned that has an argument in the command line,
+@code{getopt} stores this argument in the variable @code{optarg}.
+
+@vrindex optind
+After each invocation, @code{getopt} sets the variable @code{optind}
+to the index of the next @var{argv} element to be parsed.  Thus,
+when the list of options is exhausted and the function returned an
+empty string, @code{optind} contains the index of the the first
+element that is not an option.
+
+@vrindex optopt
+When @code{getopt} encounters an option that is not described in its
+arguments or if it detects a missing option argument it prints an
+error message using @command{mailfromd} logging facilities, stores
+the offending option in the variable @code{optopt}, and returns @samp{?}.   
+
+@vrindex opterr
+If printing error message is not desired (e.g. the application is going
+to take care of error messaging), it can be disabled by setting the
+variable @code{opterr} to @samp{0}.
+
+@cindex controlling argument, getopt
+The third argument to @code{getopt}, called @dfn{controlling argument},
+may be used to control the behavior of the function.  If it is a
+colon, it disables printing the error message for unrecognized options
+and missing option arguments (as setting @code{opterr} to @samp{0}
+does).  In this case @code{getopt} returns @samp{:}, instead of
+@samp{?} to indicate missing option argument.
+
+If the controlling argument is a plus sign, or the environment
+variable @env{POSIXLY_CORRECT} is set, then option processing stops as
+soon as a non-option argument is encountered.  By default, if options
+and non optional arguments are intermixed in @var{argv}, @code{getopt}
+permutes them so that the options go first, followed by non-optional
+arguments.
+
+If the controlling argument is @samp{-}, then each non-option
+element in @var{argv} is handled as if it were the argument of
+an option with character code 1 (@samp{"\001"}, in @acronym{MFL}
+notation.  This can used by programs that are written to expect options and
+other @var{argv}-elements in any order and that care about the
+ordering of the two.
+
+Any other value of the controlling argument is handled as an option
+definiton.
+@end deftypefn
+
+@anchor{vaptr}
+@cindex vaptr
+The special language construct is provided to supply the second
+argument (@var{argv}) to @code{getopt} and similar functions:
+
+@smallexample
+vaptr(@var{arg})
+@end smallexample
+
+@noindent
+where @var{argv} is a positional parameter, from which to start the
+array of @var{argv}.  For example:
+
+@smallexample
+func main(...)
+  returns number
+do
+  set rc getopt($#, vaptr($1), "|help")
+  ...
+@end smallexample
+
+Here, @code{vaptr($1)} constructs the @var{argv} array from all the
+arguments, supplied to the function @code{main}.
+
+To illustrate the use of @code{getopt} function, let's suppose you
+write a script that takes the following options:
+
+@table @option
+@item -f @var{file}
+@itemx --file=@var{file}
+
+@item --output[=@var{dir}]
+
+@item --help
+@end table
+
+Then, the corresponding @code{getopt} invocation will be:
+
+@smallexample
+func main(...)
+  returns number
+do
+  loop for string rc getopt($#, vaptr($1),
+                            "f:|file", "-::|output", "h|help"),
+       while %rc != "",
+       set rc getopt(0, 0)
+  do
+    switch %rc
+    do
+      case "f":
+        set file %optarg
+      case "output"
+        set %output 1
+        set %output_dir %optarg
+      case "h"
+        help()
+      default:
+        return 1
+    done
+    ...
+@end smallexample
+    
 @node Logging and Debugging
 @section Logging and Debugging
 
@@ -8595,6 +8917,7 @@ optional argument for which no actual parameter was supplied, results
 in an undefined value, so be sure to check whether a parameter is
 passed before dereferencing it.
 
+@anchor{variable number of arguments}
 @cindex variable number of arguments
   A function can also take variable number of arguments.  This is
 indicated by the use of ellipsis as the last abstract argument.  The
@@ -8776,6 +9099,7 @@ The following abbreviations can be used: @samp{s} for @code{string}
 and @samp{n} for numeric.  The same holds true for @var{rettype} as
 well.
 
+@anchor{positional parameter}
 @cindex positional parameters, in functions
   The parameters declared this way are called @dfn{positional
 parameters}.  The function can access its actual arguments using the notation
@@ -11004,6 +11328,7 @@ words:
 @item switch   
 @item tempfail
 @item throw
+@item vaptr
 @item when
 @item while
 @end itemize
@@ -11392,6 +11717,12 @@ This option implies @option{--stderr} (@pxref{--stderr}).
 
 @xref{Basic Database Operations}.
 
+@opsummary{run}
+@item --run[=@var{start}]
+Load the script named in the command line and execute the function
+named @var{start}, or @samp{main}, if @var{start} is not given.
+@xref{Run Mode}, for a detailed description of this feature.
+
 @opsummary{show-defaults}
 @item --show-defaults
 Show compilation defaults. @xref{Databases}.