summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org.ua>2010-06-24 08:55:00 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2010-06-24 08:55:47 (GMT)
commitc0e1d8a2cfa7dce23c0f3366de392dda2de4ce77 (patch) (side-by-side diff)
treed669d55dd2d79174612e97e1d15ae42d080db518
parent663f14592440156d4aab94eaf850d7bcbad52048 (diff)
downloadsmap-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.
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--doc/ex-meta1.texi10
-rw-r--r--doc/smap.texi349
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

Return to:

Send suggestions and report system problems to the System administrator.