From 4d752d13462ba034cf0050032f90090f37e64974 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Mon, 13 Nov 2006 16:18:35 +0000 Subject: update git-svn-id: file:///svnroot/mailfromd/trunk@881 7a8a7f39-df28-0410-adc6-e0d955640f24 --- ChangeLog | 7 ++ NEWS | 12 +- README-alpha | 3 +- doc/mailfromd.texi | 359 ++++++++++++++++++++++++++++++++++++++++------------- 4 files changed, 294 insertions(+), 87 deletions(-) diff --git a/ChangeLog b/ChangeLog index 4b5e77f0..817fca75 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2006-11-13 Sergey Poznyakoff + + * NEWS: Update + * README-alpha: Update + * doc/mailfromd.texi: Update + * src/bi_vars.m4 (numrcpt): Removed + 2006-11-12 Sergey Poznyakoff * NEWS: Update diff --git a/NEWS b/NEWS index 674a8578..2cea82f2 100644 --- a/NEWS +++ b/NEWS @@ -45,10 +45,12 @@ declarations is supported as well. Automatic variables are defined within the function or handler. Their scope of visibility ends with the terminating `done' statement. -Automatic variables are defined and referenced the same way as global -ones. To declare the variable as automatic, use `TYPE NAME' +Automatic variables are declared and referenced the same way as global +ones. To declare a variable as automatic, use `TYPE NAME' notation. Variable declarations can be intermixed with executable -statements. The following example defines two automatic variables for +statements. + +The following example defines two automatic variables for the function `foo': func foo() @@ -59,6 +61,10 @@ do See the documentation for the detailed description and examples. +** The legacy function numrcpt() has been withdrawn + +Use %rcpt_count instead. + * Fuller SMTP timeout control In order to more fully control SMTP transactions, new timeout value diff --git a/README-alpha b/README-alpha index 98bab7e9..6f0be359 100644 --- a/README-alpha +++ b/README-alpha @@ -45,7 +45,8 @@ once. Packaged alpha versions do not need bootstrapping. 2. Populate the source tree with the necessary files from Gnulib. Run: - gnulib-tool --import argp obstack snprintf strtok_r fprintftime + gnulib-tool --import argp obstack snprintf strtok_r fprintftime \ + regex malloc realloc (make sure gnulib-tool is in your path or supply its full file name). diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi index 0427810f..159e2927 100644 --- a/doc/mailfromd.texi +++ b/doc/mailfromd.texi @@ -126,7 +126,8 @@ Filter Script Language * Data Types:: * Literals:: Literals or atoms. * Here Documents:: -* Variables and Macros:: +* Sendmail Macros:: +* Variables:: * Back references:: * Handlers:: * Functions:: Functions. @@ -178,6 +179,7 @@ Statements * Actions:: Actions control the handling of the mail. * Assignments:: +* Next:: @c Return statement:: @c Conditionals @c Exception handlers @@ -1283,23 +1285,40 @@ handler and than use this variable value in the other handler. This brings us to the concept of variables in @command{mailfromd} scripts. @cindex Variables, introduced - A variable is defined using @code{set} statement, as shown below: +@cindex variable declaration + A variable is declared using the following syntax: @smallexample -set @var{variable} @var{value} +@var{type} @var{name} @end smallexample @noindent -where @var{variable} is the variable name and @var{value} is the value -to be assigned to it. To get the value of a variable, the following -notation is used: @code{%@var{variable}}. The @code{set} statement -can occur within handler declarations as well as outside of them. -There are two kinds of @command{Mailfromd} variables: @dfn{global +where where @var{variable} is the variable name and @var{type} is +@samp{string} if the variable is to hold a string value and +@samp{number} if it is supposed to have a numeric value. + +@cindex variable assignment +@cindex assignment to variable + A variable is assigned a value using @code{set} statement, as shown +below: + +@smallexample +set @var{name} @var{value} +@end smallexample + +@noindent +where @var{value} is the value to be assigned to it. + + To get the value of a variable, the following notation is used: +@code{%@var{name}}. The @code{set} statement can occur within handler +declarations as well as outside of them. + + There are two kinds of @command{Mailfromd} variables: @dfn{global variables}, that are visible to all handlers and functions, and @dfn{automatic variables}, that are available only within the handler or function where they are declared. For our purpose we need a global -variable (@FIXME-pxref{variable types}, for the detailed description -of both kinds of variables). +variable (@xref{Variables, Variable classes}, for the detailed description +of both kinds of variables). The following example illustrates the approach that allows to use the helo domain name in any handler: @@ -2161,7 +2180,8 @@ amount of white-space characters (i.e. spaces, tabulations or newlines). * Data Types:: * Literals:: Literals or atoms. * Here Documents:: -* Variables and Macros:: +* Sendmail Macros:: +* Variables:: * Back references:: * Handlers:: * Functions:: Functions. @@ -2699,10 +2719,10 @@ value is @var{ooo}. @cindex Macro expansion Macro expansion and variable interpretation occur at runtime. During these phases all Sendmail macros and @command{mailfromd} variables, -referenced in the string, are replaced by their actual values. -@xref{Variables and Macros}, for the description of macro and variable -referencing syntax. For example, if the Sendmail macro @code{$f} -has the value @samp{postmaster@@gnu.org.ua} and the variable +referenced in the string, are replaced by their actual values +@xref{Sendmail Macros}, and @xref{Variables}, for the description of +macro and variable referencing syntax. For example, if the Sendmail +macro @code{$f} has the value @samp{postmaster@@gnu.org.ua} and the variable @code{last_ip} has the value @samp{127.0.0.1}, then the string@footnote{Implementation note: actually, the references are not interpreted within the string, instead, each such string is split at compilation time into a series of concatenated atoms. Thus, @@ -2867,13 +2887,10 @@ TEXT Here-documents are particularly useful with @code{reject} actions (@pxref{reject}. -@node Variables and Macros -@section Variables and Macros +@node Sendmail Macros +@section Sendmail Macros @UNREVISED{} - There are two kinds of variable entities in @command{mailfromd} -scripts: @command{Sendmail} macros and proper variables. - @cindex Macros, referencing @cindex Sendmail macros, referencing Sendmail macros are referenced exactly the same way they are in @@ -2891,13 +2908,73 @@ Configuration}). Attempt to reference a not exported macro will result in raising an unhandled exception at the run time (@pxref{Exceptions}). +@node Variables +@section Variables +@UNREVISED{} +@cindex Variables, defined + Variables represent regions of memory used to hold variable data. +These memory regions are identified by @dfn{variable names}. A +variable name must begin with a letter or underscore and must consist +of letters, digits and underscores. + + Each variable is associated with its @dfn{lexical scope}, i.e. the +part of source code where it can be used. Depenging on the scope we +discern two main classes of variables: global and automatic ones. + + @dfn{Global variables} have indefinite lexical scope, so they may +be referred to anywhere in the program. @dfn{Automatic or local +variables} are visible only within the given function or handler. + + The two variable classes occupy separate @dfn{namespaces}, so that an +automatic variable can have the same name as an existing global one. +In this case this variable is said to @dfn{shadow} its global +counterpart. All references to such a name will refer to the automatic +variable until the end of its scope is reached, where the global one +becomes visible again. + +@cindex variables, declaring +@cindex variable declarations + A variable is @dfn{declared} using the following syntax: + +@smallexample +@var{type} @var{name} +@end smallexample + +@noindent +where @var{name} is the variable name and @var{type} is the type of +the data it is supposed to hold. It is @samp{string} for string +variables and @samp{number} for numeric ones. + + If a variable declaration occurs within a function +(@pxref{Functions,User-defined}) or handler (@pxref{Handlers}), it +declares an automatic variable, local to this function or handler. +Otherwise, it declares a globale variable. + +@cindex variable, assigning a value +@cindex variable assignment + A variable is assigned a value using @code{set} statement: + +@smallexample +set @var{name} @var{expr} +@end smallexample + +@noindent +where @var{name} is the variable name and @var{expr} is a +@command{mailfromd} expression (@pxref{Expressions}). The effect of +this statement is that the @var{expr} is evaluated and the value it +yields is assigned to the variable @var{name}. + + It is not an error to assign a value to a variable that is not +declared. In this case the assignement first declares a @emph{global} +variable having the type of @var{expr} and then assigns a value to it. +This is called @dfn{implicit variable declaration}. This feature is +available for compatibility with previous versions and should not be +relied upon, as it may disappear in the future versions. + @cindex Variables, referencing - Variables are referenced using the notation @samp{%@var{name}}, -where @var{name} is the variable name. Variable names must begin with -a letter or underscore and must consist of letters, digits and -underscores. Variables are not declared, they spring into existence -when they are assigned a value using @code{set} statement. All -@command{mailfromd} variables are global. + Variables are referenced using the notation @samp{%@var{name}}. The +variable being referenced must have been declared earlier (either +explicitly or implicitly). @anchor{predefined variables} @cindex Predefined variables @@ -3659,7 +3736,7 @@ invoked. @cindex @code{func} statement, function definition @smallexample @group -func @var{name} (@var{param-types}) returns @var{data-type} +func @var{name} (@var{param-decl}) returns @var{data-type} do @var{function-body} done @@ -3667,18 +3744,31 @@ done @end smallexample @noindent -@var{name} is the name of the function to define, @var{param-types} is -a comma-separated list of @var{parameter types} and @var{data-type} -specifies the type of the value the function returns. Data types are -represented by single letters: @samp{s} meaning @samp{string} and -@samp{n} meaning @samp{numeric}. For example, the following code -defines the function @var{foo} that takes two string parameters -and returns a numeric value: +@var{name} is the name of the function to define, @var{param-decl} is +a comma-separated list of parameter declarations. The syntax of the +latter is the same as that of variable declarations (@pxref{Variables, +Variable declarations}), i.e.: @smallexample -func samedomain(s,s) returns n +@var{type} @var{name} +@end smallexample + +@noindent +declares the parameter @var{name} having the type @var{type}. The +@var{type} is @code{string} or @code{number}. + + For example, the following declares a function @samp{sum}, that takes +two numeric arguments and returns a numeric value: + +@smallexample +func sum(number x, number y) returns number @end smallexample + Parameters are referenced in the @var{function-body} by their name, +using the syntax for variable references: @code{%@var{name}}. The +value of a parameter can be altered using @code{set} statement, the +same way as for variables. + @cindex return statement, defined The @var{function-body} is any list of valid @command{mailfromd} statements. In addition to the statements discussed below @@ -3690,12 +3780,114 @@ return statement is return @var{value} @end smallexample -@cindex function arguments, accessing -@cindex accessing function arguments - The function can access its actual arguments using the notation -@code{$@var{n}}, where @var{n} is the ordinal number of the argument. -Arguments are counted from left to right. The first argument is -@code{$1}. + As an example of this, consider the following code snippet that +defines the function @samp{sum} to return a sum of its two arguments: + +@smallexample +@group +func sum(number x, number y) returns number +do + return %x + %y +done +@end group +@end smallexample + +@cindex Procedures +@cindex Function returning void +@cindex Void functions + The @code{returns} part in the function declaration is optional. A +declaration lacking it defines a @dfn{procedure}, or @dfn{void +function}, i.e. a function that is not supposed to return any value. +Such functions cannot be used in expressions, instead they should be +used in statement context (@pxref{Statements}). The following example +shows a function that emits a customized temporary failure notice: + +@smallexample +@group +func stdtf() +do + tempfail 451 4.3.5 "Try again later" +done +@end group +@end smallexample + +@cindex Automatic variables +@cindex Local variables + A variable declared within a function becomes a local variable to +this function. Its lexical scope ends with the terminating +@code{done} statement. + + Parameters, local variables and global variables are using +separate namespaces, so a parameter name can coincide with the name of +a global, in which case a parameter is said to @dfn{shadow} the +global. All references to its name will refer to the parameter, +until the end of its scope is reached, where the global one +becomes visible again. Consider the following example: + +@smallexample +@group +number x + +func foo(string x) +do + echo "foo: %x" +done + +prog envfrom +do + set x "Global" + foo("Local") + echo %x +done +@end group +@end smallexample + +@noindent + Running @command{mailfromd --test} with this configuration will +display: + +@smallexample +@cartouche +foo: Local +Global +@end cartouche +@end smallexample + +@smallformat + For compatibility with previous versions, @command{mailfromd} also +supports the @dfn{legacy} format of function declarations: + +@smallexample +func @var{name} (@var{param-types}) returns @var{rettype} +@end smallexample + +@noindent +Here, @var{param-types} is a comma-separated list of parameter types. +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. + +@cindex positional parameters, in functions + The variables declared this way are called @dfn{positional +parameters}. The function can access its actual arguments using the notation +@code{$@var{n}}, where @var{n} is the ordinal number of the +argument@footnote{Well, to tell you the truth, you can access named +arguments using positional notation as well. But such a mixing of +styles is not recommended.}. Arguments are counted from left to +right. The first argument is @code{$1}. + + Using this syntax, the above definition of sum whould look like: + +@smallexample +@group +func sum(n, n) returns n +do + return $1 + $2 +done +@end group +@end smallexample + +@end smallformat @menu * Some Useful Functions:: @@ -3760,7 +3952,7 @@ do return "\4.\3.\2.\1" fi return %ip -done +done @end group @end smallexample @end deftypefn @@ -3784,13 +3976,13 @@ strip_domain_part("puszcza.gnu.org.ua", 0) @result{} "gnu.org.ua" func strip_domain_part(string domain, number n) returns string do - if %n = 0 - return domainpart %domain - elif domainpart(%domain) matches '.*((\.[^.]+)@{' $2 '@})' - return substring(\1, 1, -1) - else - return %domain - fi + if %n = 0 + return domainpart %domain + elif domainpart(%domain) matches '.*((\.[^.]+)@{' $2 '@})' + return substring(\1, 1, -1) + else + return %domain + fi done @end group @end smallexample @@ -3824,11 +4016,11 @@ do number ip4 set ip1 \1 - set ip2 \2 - set ip3 \3 - set ip4 \4 + set ip2 \2 + set ip3 \3 + set ip4 \4 else - return %ip + return %ip fi number x @@ -3836,37 +4028,37 @@ do switch %n do case 1: - set x %ip1 + %delta - if %x > 255 - set x 255 - elif %x < 0 - set x 0 - fi + set x %ip1 + %delta + if %x > 255 + set x 255 + elif %x < 0 + set x 0 + fi return %x "." %ip2 "." %ip3 "." %ip4 case 2: - set x %ip2 + %delta - if %x > 255 - set x 255 - elif %x < 0 - set x 0 - fi - return %ip1 "." %x "." %ip3 "." %ip4 + set x %ip2 + %delta + if %x > 255 + set x 255 + elif %x < 0 + set x 0 + fi + return %ip1 "." %x "." %ip3 "." %ip4 case 3: - set x %ip3 + %delta - if %x > 255 - set x 255 - elif %x < 0 - set x 0 - fi - return %ip1 "." %ip2 "." %x "." %ip4 + set x %ip3 + %delta + if %x > 255 + set x 255 + elif %x < 0 + set x 0 + fi + return %ip1 "." %ip2 "." %x "." %ip4 case 4: - set x %ip4 + %delta - if %x > 255 - set x 255 - elif %x < 0 - set x 0 - fi - return %ip1 "." %ip2 "." %ip3 "." %x + set x %ip4 + %delta + if %x > 255 + set x 255 + elif %x < 0 + set x 0 + fi + return %ip1 "." %ip2 "." %ip3 "." %x done done @end smallexample @@ -5279,9 +5471,9 @@ words: @item func @item if @item matches -@item matches @item next -@item not +@item not +@item number @item on @item or @item prog @@ -5290,7 +5482,8 @@ words: @item replace @item return @item returns -@item set +@item set +@item string @item switch @item tempfail @item when -- cgit v1.2.1