patplex: Add reparse action.

[ashd.git] / doc / patplex.doc

diff --git a/doc/patplex.doc b/doc/patplex.doc
index dbe8e96..a9ebe69 100644 (file)
--- a/doc/patplex.doc
+++ b/doc/patplex.doc
@@ -35,20 +35,24 @@ CONFIGURATION
 
 In addition to the 'CONFIGFILE' specified on the command-line,
 *patplex* also attempts to find and read a global configuration file
 
 In addition to the 'CONFIGFILE' specified on the command-line,
 *patplex* also attempts to find and read a global configuration file

-called `patplex.rc`, unless the *-N* option is given. It looks in all
-directories named by the *PATH* environment variable, appended with
-`../etc`. For example, then, if *PATH* is
-`/usr/local/bin:/bin:/usr/bin`, the directories `/usr/local/etc`,
-`/etc` and `/usr/etc` are searched for `patplex.rc`, in that
-order. Only the first file found is used, should there exist several.
+called `patplex.rc`, unless the *-N* option is given. It looks in
+`$HOME/.ashd/etc`, and then in all directories named by the *PATH*
+environment variable, appended with `../etc/ashd`. For example, then,
+if *PATH* is `/usr/local/bin:/bin:/usr/bin`, the directories
+`$HOME/.ashd/etc`, `/usr/local/etc/ashd`, `/etc/ashd` and
+`/usr/etc/ashd` are searched for `patplex.rc`, in that order. Only the
+first file found is used, should there exist several. If the given
+'CONFIGFILE' contains any slashes, it is opened by that exact
+name. Otherwise, it is searched for in the same manner as the global
+configuration file.

 
 Should the global and the given configuration files conflict, the
 directives from the given file take precedence.
 
 The configuration files follow the same general format as for
 
 Should the global and the given configuration files conflict, the
 directives from the given file take precedence.
 
 The configuration files follow the same general format as for

-*dirplex*(1), though the recognized stanzas differ. The *child* and
-*fchild* stanzas are also shared with *dirplex*(1), so see its manpage
-for a description thereof.
+*dirplex*(1), though the recognized stanzas differ. The *child*,
+*fchild* and *include* stanzas are also shared with *dirplex*(1), so
+see its manpage for a description thereof.

 
 *patplex* recognizes the *match* stanza, which takes no arguments, but
 must contain at least one follow-up line to specify match rules. All
 
 *patplex* recognizes the *match* stanza, which takes no arguments, but
 must contain at least one follow-up line to specify match rules. All


@@ -63,14 +67,15 @@ rules are recognized:
        matched case-independently. If the *match* stanza as a whole
        matches and contains no *restpat* line (as described below),
        the rest string of the request is replaced by the remainder of
        matched case-independently. If the *match* stanza as a whole
        matches and contains no *restpat* line (as described below),
        the rest string of the request is replaced by the remainder of

-       the rest string after the portion that was matched by 'REGEX'.
+       the rest string after the portion that was matched by
+       'REGEX'. See also URL UNQUOTING, below.

 
 *url* 'REGEX' 'FLAGS'::
 
        'REGEX' must be an extended regular expression. The rule is
        considered to match if 'REGEX' matches the raw URL of the
        request. If 'FLAGS' contain the character `i`, 'REGEX' is
 
 *url* 'REGEX' 'FLAGS'::
 
        'REGEX' must be an extended regular expression. The rule is
        considered to match if 'REGEX' matches the raw URL of the
        request. If 'FLAGS' contain the character `i`, 'REGEX' is

-       matched case-independently.
+       matched case-independently. See also URL UNQUOTING, below.

 
 *method* 'REGEX' 'FLAGS'::
 
 
 *method* 'REGEX' 'FLAGS'::
 


@@ -87,28 +92,70 @@ rules are recognized:
        'HEADER', the rule never matches. If 'FLAGS' contain the
        character `i`, 'REGEX' is matched case-independently.
 
        'HEADER', the rule never matches. If 'FLAGS' contain the
        character `i`, 'REGEX' is matched case-independently.
 

+*all*::
+
+       The rule always matches.
+

 *default*::
 
 *default*::
 

-       Matches if and only if no *match* stanza without a *default*
-       rule has matched.
+       Convenient shorthand for an *all* line followed by *priority
+       -10* (see below).

 
 In addition to the rules, a *match* stanza must contain exactly one
 
 In addition to the rules, a *match* stanza must contain exactly one

-follow-up line specifying the action to take if it mathces. Currently,
-only the *handler* action is recognized:
+follow-up line specifying the action to take if it matches. The
+following actions are supported:

 
 *handler* 'HANDLER'::
 
        'HANDLER' must be a named handler as declared by a *child* or
        *fchild* stanza, to which the request is passed.
 
 
 *handler* 'HANDLER'::
 
        'HANDLER' must be a named handler as declared by a *child* or
        *fchild* stanza, to which the request is passed.
 

-Additionally, a *match* stanza may contain a *restpat* line:
+*reparse*::
+
+       Apply any side-effects as required by the match stanza (such
+       as rest-string or header modifications), and then retry the
+       matching of the request. During the rematching, the stanza
+       containing the *reparse* action will be disabled. Multiple
+       *reparse* stanzas may be used recursively.
+
+Additionally, a *match* stanza may contain any of the following,
+optional lines:
+
+*priority* 'INTEGER'::
+
+       Specifies the priority for the match stanza. In case more than
+       one stanza match a request, the one with the highest priority
+       is used. In case more than one stanza with the same highest
+       priority match a request, it is unspecified which will be
+       used. Match stanzas without a priority specification will
+       default to priority 0. Either positive or negative priorities
+       may be specified.
+
+*order* 'INTEGER'::
+
+       A synonym for *priority*. Use whichever you like the best.
+
+*set* 'HEADER' 'VALUE'::
+
+       If the *match* stanza as a whole matches, the named HTTP
+       'HEADER' in the request is set to 'VALUE' before passing the
+       request on to the specified handler. A *match* stanza may
+       contain any number of *set* lines.
+
+*xset* 'HEADER' 'VALUE'::
+
+       *xset* does exactly the same thing as *set*, except that
+         'HEADER' is automatically prepended with the `X-Ash-`
+         prefix. The intention is only to make configuration files
+         look nicer in this very common case.

 
 *restpat* 'TEMPLATE'::
 
        If the *match* stanza as a whole matches, 'TEMPLATE' is
        expanded and installed as the rest string of the request
        before it is passed to the specified handler. In 'TEMPLATE',
 
 *restpat* 'TEMPLATE'::
 
        If the *match* stanza as a whole matches, 'TEMPLATE' is
        expanded and installed as the rest string of the request
        before it is passed to the specified handler. In 'TEMPLATE',

-       the following parameters are recognized and expanded.
+       the following parameters are recognized and expanded. At most
+       one *restpat* line may be given per *match* stanza.

 
 *$0* ... *$9*::
 
 
 *$0* ... *$9*::
 


@@ -135,6 +182,20 @@ Additionally, a *match* stanza may contain a *restpat* line:
 If no *match* stanza matches, a 404 response is returned to the
 client.
 
 If no *match* stanza matches, a 404 response is returned to the
 client.
 

+URL UNQUOTING
+-------------
+
+If the 'FLAGS' of a *point* or *url* rule contain the character `q`,
+then the rule's pattern will be matched against a copy of the input
+string where URL percent-escapes have been decoded so that, for
+example, the regular expression `^~` will match an input string that
+begins with either `~`, `%7E` or `%7e`.
+
+Even if such percent-escapes were decoded, however, the original
+version of the string will be used for any *restpat* expansion,
+regardlessly of whether the escapes were unquoted inside or outside
+the matched part of the string.
+

 SIGNALS
 -------
 
 SIGNALS
 -------