diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2010-06-24 11:55:00 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2010-06-24 11:55:47 +0300 |
commit | c0e1d8a2cfa7dce23c0f3366de392dda2de4ce77 (patch) | |
tree | d669d55dd2d79174612e97e1d15ae42d080db518 | |
parent | 663f14592440156d4aab94eaf850d7bcbad52048 (diff) | |
download | smap-c0e1d8a2cfa7dce23c0f3366de392dda2de4ce77.tar.gz smap-c0e1d8a2cfa7dce23c0f3366de392dda2de4ce77.tar.bz2 |
Update the docs.
* doc/smap.texi: Document transformations and sed module. Provide
a placeholder for mysql documentation.
* doc/ex-meta1.texi: Update.
-rw-r--r-- | doc/ex-meta1.texi | 10 | ||||
-rw-r--r-- | doc/smap.texi | 349 |
2 files changed, 335 insertions, 24 deletions
diff --git a/doc/ex-meta1.texi b/doc/ex-meta1.texi index 1cf02ac..e558008 100644 --- a/doc/ex-meta1.texi +++ b/doc/ex-meta1.texi @@ -4,11 +4,11 @@ @c ******************************************************************* @cindex MeTA1 In this appendix we will show how to use the @samp{mailutils} -module (@pxref{mailutils module}) to configure local user and alias maps for -@acronym{MeTA1}. For this purpose, we will assume that the actual -data is stored in two tables in a @acronym{MySQL} database. The two -maps will be served by two separate databases, each of which uses a -separate configuration file. +module (@pxref{mailutils,mailutils module}) to configure local user +and alias maps for @acronym{MeTA1}. For this purpose, we will assume +that the actual data is stored in two tables in a @acronym{MySQL} +database. The two maps will be served by two separate databases, each +of which uses a separate configuration file. @menu * userdb-meta1:: Configure local_user_map. diff --git a/doc/smap.texi b/doc/smap.texi index 14c3cc0..0ff480c 100644 --- a/doc/smap.texi +++ b/doc/smap.texi @@ -103,15 +103,18 @@ The Socket Map Server * loadable modules:: Loadable Modules. * databases:: Databases. * dispatch rules:: Query Dispatch Rules. +* transformations:: Rules May Transform Input Queries. * exit codes:: Smapd Exit Codes. Modules Shipped with Smap -* echo module:: -* mailutils module:: -* guile module:: +* echo:: +* mailutils:: +* guile:: +* mysql:: +* sed:: -The @samp{mailutils} Module +Mailutils * expansion:: Variable Expansion * load-mailutils:: Loading Sequence @@ -119,7 +122,7 @@ The @samp{mailutils} Module * auth:: Mailutils Auth Mode * mbq:: Mailutils MBQ Mode -The @samp{guile} Module +Guile * Virtual Functions:: * Guile Output Ports:: @@ -127,6 +130,13 @@ The @samp{guile} Module * Guile API:: @c * Guile Example Module:: +Sed + +* sed module:: +* sed database:: +* s-expressions:: +* sed lookups:: + Socket map client * Single Query Mode:: @@ -252,6 +262,10 @@ A @dfn{database} is an intermediate logical entity associated with a particular module. The database provides actual configuration for the module. Several different databases may be associated with the same module, thereby creating several instances of the same lookup driver. + +If the underlying module allows for such use, a database may also be +used to modify input map name and/or key value, before passing them on +to another database. @end table The relationships before these parts are shown in the figure below: @@ -381,6 +395,7 @@ $ smapd --lint --config ./mysmapd.conf * loadable modules:: Loadable Modules. * databases:: Databases. * dispatch rules:: Query Dispatch Rules. +* transformations:: Rules May Transform Input Queries. * exit codes:: Smapd Exit Codes. @end menu @@ -880,7 +895,7 @@ initialization function. They are module-specific. To illustrate this, let's consider the @samp{echo} module, which replies to any request with a constant string supplied to it as arguments -(@pxref{echo module}). The following example configures two instances +(@pxref{echo,echo module}). The following example configures two instances of this module: @example @@ -904,9 +919,14 @@ and a target part. The rules are joined in a list. When applied to a particular query, this list is scanned from top down. The conditions of each rule are evaluated using the query as their argument. If all conditions return @samp{True}, then the target part of this rule -indicates the database to dispatch this query to. If the list is -exhausted and no matching rule was found, @command{smapd} sends back -the default @samp{NOTFOUND} reply. +is applied. The target part may either @dfn{transform} the map +name and/or key value (a @dfn{transformation rule}), or indicate a +database to dispatch this query to (a @dfn{destination rule}). After +applying a transformation rule, the scanning resumes at +the next rule. Destination rules end the processing. + +If the list is exhausted without having found a matching destination +rule, @command{smapd} sends back the default @samp{NOTFOUND} reply. @kwindex map Consider for example the following rule: @@ -1007,6 +1027,53 @@ dispatch default database nomap will match any rule and dispatch it to a database named @samp{nomap}. The @samp{default} condition cannot be combined with other conditions. +@node transformations +@section Transformations +@dfn{Transformations} are special rules that modify the key or map +value. Syntax of transformation rules is: + +@example +dispatch @var{cond-list} transform @var{key-or-map} @var{dbname} +@end example + +@noindent +where @var{cond-list} is a condition list, as described in the +previous section, @var{key-or-map} is @samp{key} if the transformation +is applied to the key value and @samp{map} if it is applied to +the map name, and @var{dbname} is the name of a database that +handles the transformation. For example: + +@example +dispatch key like <*> transform key dequote +@end example + +This rule applies the @samp{dequote} database to any key that is +enclosed in angle brackets. It is supposed that the @samp{dequote} +database removes the brackets. It may be implemented using the +the @samp{sed} module (@pxref{sed,sed module}), as follows. + +@example +module sed sed +database dequote sed extended 's/<(.*)>/\1/g' +@end example + +The transform rules can be chained, as in the example below: + +@example +@group +# @r{This database removes domain part from its argument}. +database localpart sed 's/@@.*$//' + +# @r{Dispatch rules:} +dispatch key like <*> transform key dequote +dispatch key like *@@* transform key localpart +dispatch default database getpwnam +@end group +@end example + +As a result, the @samp{getpwnam} database will get the local part of +the original key (which may be supplied in the form of an email address). + @node exit codes @section Smapd Exit Codes @cindex exit codes @@ -1511,6 +1578,12 @@ regular expressions. @end table @end deffn +@deffn {Condition} key op string +@samp{True} if the key value (@pxref{Protocol,key}) +matches @var{string}. The @var{op} argument has the +same meaning as for @code{map} above. +@end deffn + @deffn {Condition} not cond Reverts the value returned by @var{cond}, which is one of the conditions described above. For example: @@ -1546,13 +1619,15 @@ and per-database (@pxref{databases}) levels. in detail in the following sections. @menu -* echo module:: -* mailutils module:: -* guile module:: +* echo:: +* mailutils:: +* guile:: +* mysql:: +* sed:: @end menu -@node echo module -@section The @samp{echo} Module +@node echo +@section Echo @kwindex echo The echo module is the simplest of all modules. It sends back a static reply string, no matter what the query was. This module is @@ -1582,8 +1657,8 @@ dispatch rule: dispatch default database default @end example -@node mailutils module -@section The @samp{mailutils} Module +@node mailutils +@section Mailutils @kwindex mailutils This module uses GNU Mailutils (@uref{http://www.gnu.org/software/mailutils}) and provides two main @@ -1880,8 +1955,8 @@ violating its quota. Notice, that this mode requires superuser privileges. -@node guile module -@section The @samp{guile} Module +@node guile +@section Guile @cindex guile module @dfn{Guile} is an acronym for @dfn{GNU's Ubiquitous Intelligent Language for Extensions}. It provides a Scheme interpreter conforming @@ -2010,6 +2085,10 @@ Close the database. @kwindex query @item query Handle a socket map query + +@kwindex xform +@item xform +Handle a transformation request (@pxref{transformations}). @end table For example, the following is a valid virtual function table: @@ -2122,7 +2201,8 @@ The following example function returns a complete virtual function table: (cons "done" db-done) (cons "open" db-open) (cons "close" db-close) - (cons "query" db-query))) + (cons "query" db-query) + (cons "xform" db-xform))) @end group @end lisp @@ -2214,6 +2294,237 @@ the current output port, e.g.: @end lisp @end deffn +@deffn {Guile Callback} xform-db dbh arg . rest +Virtual Table: @code{(cons "xform" xform-db)}@* +Transform the argument @var{arg}. Arguments @var{dbh} and +@var{rest} have the same meaning as in @ref{query-db}. + +Returns transformed value or @samp{#f} if no transformation applies. +This callback may be used to alter map or key values using +@samp{guile} module (@pxref{transformations}). The following example +function removes optional domain part from its argument: + +@example +@group +(define (smap-xform handle arg . rest) + (let ((arg-parts (string-split arg #\@@))) + (if (null? (cdr arg-parts)) + #f + (car arg-parts)))) +@end group +@end example + +The following snippet from the @file{smapd.conf} file shows how to +apply it: + +@example +@group +database localpart guile init-script=local.scm + +dispatch key like *@@* transform key localpart +@end group +@end example +@end deffn + +@node mysql +@section Mysql +@cindex mysql module +FIXME + +@node sed +@section Sed +@cindex sed module + The @samp{sed} module applies sed-like @dfn{s-expressions} to strings +to modify them. It is designed mainly for use in transformation rules +(@pxref{transformations}). + +@menu +* sed module:: +* sed database:: +* s-expressions:: +* sed lookups:: +@end menu + +@node sed module +@subsection Loading sed module +@cindex sed, loading the module +@example +module sed sed [@var{args}] +@end example + +The following arguments may be given in the statement above: + +@table @option +@item icase +Use case-insensitive expressions. + +@itemx noicase +Use case-sensitive expressions. This is the default. + +@item extended +Use extended regular expressions. This is the default. + +@item noextended +Use basic regular expressions. +@end table + +Although @code{sed} module is designed for transformations in the +first place, it may also be used as a conventional lookup database +(@pxref{sed lookups}). The following options modify its behavior in +this mode: + +@table @option +@kwindex positive-reply +@item positive-reply=@var{str} +Use @var{str} for positive replies. + +@kwindex negative-reply +@item negative-reply=@var{str} +Use @var{str} for negative replies. + +@kwindex onerror-reply +@item onerror-reply=@var{str} +Reply with @var{str} if an error occurred. +@end table + +@node sed database +@subsection Defining Sed Databases +@cindex sed databases +@cindex database, sed + The definition of a sed databases requires a single argument: the +@dfn{s-expression} to be applied. For example: + +@example +database dequote sed 's/<(.*)>/\1/g' +@end example + + Be sure to properly quote the expression, especially if it contains +backreferences. It is preferable to use single quotes, to avoid +duplicating each backslash in the expression, as shown in the example +below. If the expression itself contains single quote, you may either +use double-quotes to quote the entire expression: + +@example +database foo sed "s/'utf8'(.*)/u8_\\1/" +@end example + +@noindent +or use escaped single quotes outside of quoted expression (a technique +familiar for shell programmers): + +@example +database foo sed 's/'\''utf8'\''(.*)/u8_\1/' +@end example + + All options valid for module initialization (@pxref{sed module}) may +also be used in database declarations. When used so, they take +precedence over module initialization options. For example, the +following database definition uses basic case-insensitive regular +expressions: + +@example +database bar sed noextended noicase 's/test(\([^)]\))/\1/g' +@end example + +@node s-expressions +@subsection S-expressions +@cindex s-expression +The transformation expression is a @command{sed}-like +replace expression of the form: + +@smallexample +s/@var{regexp}/@var{replace}/[@var{flags}] +@end smallexample + +@noindent +where @var{regexp} is a @dfn{regular expression}, @var{replace} is a +replacement for each part of the input that matches @var{regexp}. Both +@var{regexp} and @var{replace} are described in detail in +@ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}. + +As in @command{sed}, you can give several replace expressions, +separated by a semicolon. + +Supported @var{flags} are: + +@table @samp +@cindex g, @option{transform} flag +@item g +Apply the replacement to @emph{all} matches to the @var{regexp}, not +just the first. + +@cindex i, @option{transform} flag +@item i +Use case-insensitive matching + +@cindex x, @option{transform} flag +@item x +@var{regexp} is an @dfn{extended regular expression} (@pxref{Extended +regexps, Extended regular expressions, Extended regular expressions, +sed, GNU sed}). + +@item @var{number} +Only replace the @var{number}th match of the @var{regexp}. + +Note: the @acronym{POSIX} standard does not specify what should happen +when you mix the @samp{g} and @var{number} modifiers. The +@command{sed} module follows the GNU @command{sed} implementation in +this regard, so the interaction is defined to be: ignore matches +before the @var{number}th, and then match and replace all matches from +the @var{number}th on. +@end table + +Any delimiter can be used in lieue of @samp{/}, the only requirement being +that it be used consistently throughout the expression. For example, +the following two expressions are equivalent: + +@smallexample +@group +s/one/two/ +s,one,two, +@end group +@end smallexample + + Changing delimiters is often useful when the @var{regex} contains +slashes. For instance, it is more convenient to write @code{s,/,-,} than +@code{s/\//-/}. + +@node sed lookups +@subsection Using Sed for Lookups +@cindex sed, using for lookups + The @command{sed} module is designed primarily for argument +transformation. Nevertheless, it may also be used to define simple +look-up databases. When used in a @code{database} clause of a +dispatch rule, the module behaves as follows. The s-expression is +applied to the key. If the result differs from the input key, the +@samp{positive-reply} is returned. It the result is the same as the +input key, @samp{negative-reply} is returned. If some error occurred, +@samp{onerror-reply} is returned. The reply strings may be +supplied as arguments to the database definition or to the module +loading statement. The following variables are expanded within these +strings: + +@table @samp +@item map +The map name. + +@item key +The key value. + +@item xform +Transformed key value. This variable is not defined for +@samp{onerror-reply}. +@end table + + Default replies are: + +@multitable @columnfractions 0.4 0.6 +@headitem Reply @tab Value +@item positive-reply @tab @samp{OK $@{xform@}} +@item negative-reply @tab @samp{NOTFOUND} +@item onerror-reply @tab @samp{NOTFOUND} +@end multitable + @node smapc @chapter Socket map client @cindex smapc, socket client utility |