aboutsummaryrefslogtreecommitdiff
path: root/doc/mailfromd.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/mailfromd.texi')
-rw-r--r--doc/mailfromd.texi359
1 files changed, 276 insertions, 83 deletions
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

Return to:

Send suggestions and report system problems to the System administrator.