From: Rich Bowen Date: Tue, 18 May 2010 22:55:44 +0000 (+0000) Subject: Rephrasing of RewriteMap intro. X-Git-Tag: 2.3.6~111 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f493564be35a4379f8d849e12f499814a8565732;p=apache Rephrasing of RewriteMap intro. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@945944 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/rewrite/rewritemap.html.en b/docs/manual/rewrite/rewritemap.html.en index 3b9d0fa9e0..7da69d414d 100644 --- a/docs/manual/rewrite/rewritemap.html.en +++ b/docs/manual/rewrite/rewritemap.html.en @@ -21,14 +21,17 @@

Available Languages:  en 

+

This document supplements the mod_rewrite reference documentation. It describes the use of the RewriteMap directive, and provides examples of each of the various RewriteMap types.

+
Note that many of these examples won't work unchanged in your particular server configuration, so it's important that you understand them, rather than merely cutting and pasting the examples into your configuration.
+
  • prg: External Rewriting Program
  • dbd or fastdbd: SQL Query
  • Summary
    • -

    See also

    +

    See also

    top

    Introduction

    -

    The RewriteMap directive defines a - Rewriting Map which can be used inside rule - substitution strings by the mapping-functions to - insert/substitute fields through a key lookup. The source of - this lookup can be of various types.

    -

    The MapName is - the name of the map and will be used to specify a - mapping-function for the substitution strings of a rewriting - rule via one of the following constructs:

    + +

    + The RewriteMap directive + defines an external function which can be called in the context of + RewriteRule or + RewriteCond directives to + perform rewriting that is too complicated, or too specialized to be + performed just by regular expressions. The source of this lookup can + be any of the types listed in the sections below, and enumerated in + the RewriteMap reference + documentation.

    + +

    The syntax of the RewriteMap directive is as + follows:

    + +

    +RewriteMap MapName MapType:MapSource +

    + +

    The MapName is an + arbitray name that you assign to the map, and which you will use in + directives later on. Arguments are passed to the map via the + following syntax:

    +

    - ${ - MapName - : - LookupKey - } -
    - ${ - MapName - : - LookupKey - | - DefaultValue - } + ${ MapName : LookupKey + }
    ${ MapName : + LookupKey | DefaultValue }

    +

    When such a construct occurs, the map MapName is consulted and the key LookupKey is looked-up. If the key is found, the map-function construct is substituted by SubstValue. If the key is not found then it is substituted by DefaultValue or by the empty string if no DefaultValue was specified.

    +

    For example, you might define a RewriteMap as:

    @@ -85,8 +95,9 @@ configuration.

    RewriteRule ^/ex/(.*) ${examplemap:$1}

    -

    The following combinations for MapType and - MapSource can be used:

    + +

    The sections that follow describe the various MapTypes that +may be used, and give examples of each.

    top

    txt: Plain text maps

    @@ -190,29 +201,30 @@ $ httxt2dbm -i mapfile.txt -o mapfile.map
    top
    -

    prg: External Rewriting Program

    - MapType: prg, MapSource: Unix filesystem - path to valid regular file -

    Here the source is a program, not a map file. To - create it you can use a language of your choice, but - the result has to be an executable program (either - object-code or a script with the magic cookie trick - '#!/path/to/interpreter' as the first - line).

    This program is started once, when the Apache httpd server - is started, and then communicates with the rewriting engine - via its stdin and stdout - file-handles. For each map-function lookup it will - receive the key to lookup as a newline-terminated string - on stdin. It then has to give back the - looked-up value as a newline-terminated string on - stdout or the four-character string - ``NULL'' if it fails (i.e., there - is no corresponding value for the given key).

    This feature utilizes the rewrite-map mutex, - which is required for reliable communication with the program. - The mutex mechanism and lock file can be configured with the - Mutex directive.

    External rewriting programs are not started if they're defined in a - context that does not have RewriteEngine set to - on

    . +

    prg: External Rewriting Program

    + +

    MapType: prg, MapSource: Unix filesystem path to valid regular file

    + +

    Here the source is a program, not a map file. To +create it you can use a language of your choice, but +the result has to be an executable program (either +object-code or a script with the magic cookie trick +'#!/path/to/interpreter' as the first +line).

    This program is started once, when the Apache httpd server +is started, and then communicates with the rewriting engine +via its stdin and stdout +file-handles. For each map-function lookup it will +receive the key to lookup as a newline-terminated string +on stdin. It then has to give back the +looked-up value as a newline-terminated string on +stdout or the four-character string +``NULL'' if it fails (i.e., there +is no corresponding value for the given key).

    This feature utilizes the rewrite-map mutex, +which is required for reliable communication with the program. +The mutex mechanism and lock file can be configured with the +Mutex directive.

    External rewriting programs are not started if they're defined in a +context that does not have RewriteEngine set to +on

    .

    A trivial program which will implement a 1:1 map (i.e., key == value) could be:

    diff --git a/docs/manual/rewrite/rewritemap.xml b/docs/manual/rewrite/rewritemap.xml
index 0ef432f502..f7f532bb2a 100644
--- a/docs/manual/rewrite/rewritemap.xml
+++ b/docs/manual/rewrite/rewritemap.xml
@@ -22,58 +22,68 @@
   Rewrite
   Using RewriteMap
   
+
     
    This document supplements the mod_rewrite 
 reference documentation. It describes
 the use of the RewriteMap directive,
 and provides examples of each of the various RewriteMap types.
    
+
     Note that many of these examples won't work unchanged in your
 particular server configuration, so it's important that you understand
 them, rather than merely cutting and pasting the examples into your
 configuration.
+
       
-   Module documentation 
-   mod_rewrite introduction 
-   Redirection and remapping 
-   Controlling access 
-   Virtual hosts 
-   Proxying 
-   Advanced techniques and tricks 
-   When not to use mod_rewrite 
+  Module documentation
+  mod_rewrite introduction
+  Redirection and remapping
+  Controlling access
+  Virtual hosts
+  Proxying
+  Advanced techniques and tricks
+  When not to use mod_rewrite
 
   
    
     Introduction
-    
    The RewriteMap directive defines a
-      Rewriting Map which can be used inside rule
-      substitution strings by the mapping-functions to
-      insert/substitute fields through a key lookup. The source of
-      this lookup can be of various types.
    
-    
    The MapName is
-      the name of the map and will be used to specify a
-      mapping-function for the substitution strings of a rewriting
-      rule via one of the following constructs:
    
+
+   
    
+   The RewriteMap directive
+   defines an external function which can be called in the context of
+   RewriteRule or
+   RewriteCond directives to
+   perform rewriting that is too complicated, or too specialized to be
+   performed just by regular expressions. The source of this lookup can
+   be any of the types listed in the sections below, and enumerated in
+   the RewriteMap reference
+   documentation.
    
+
+   
    The syntax of the RewriteMap directive is as
+   follows:
    
+
+
+RewriteMap MapName MapType:MapSource
+
+    
+    
    The MapName is an
+    arbitray name that you assign to the map, and which you will use in
+    directives later on. Arguments are passed to the map via the
+    following syntax:
    
+
     
    
       
-        ${
-        MapName
-        :
-        LookupKey
-        }
-        
    
-        ${
-        MapName
-        :
-        LookupKey
-        |
-        DefaultValue
-        }
+        ${ MapName : LookupKey
+        } 
     ${ MapName :
+        LookupKey | DefaultValue }
           
     
    
+
     
    When such a construct occurs, the map MapName is
       consulted and the key LookupKey is looked-up. If the
       key is found, the map-function construct is substituted by
       SubstValue. If the key is not found then it is
       substituted by DefaultValue or by the empty string
       if no DefaultValue was specified.
    
+
     
    For example, you might define a
       RewriteMap as:
    
     
@@ -84,9 +94,11 @@ configuration.
     
       RewriteRule ^/ex/(.*) ${examplemap:$1}
       
-    
    The following combinations for MapType and
-      MapSource can be used:
    
+
+
    The sections that follow describe the various MapTypes that
+may be used, and give examples of each.
    
   
    
+
   
    
     txt: Plain text maps
     
    MapType: txt, MapSource: Unix filesystem
@@ -190,29 +202,30 @@ $ httxt2dbm -i mapfile.txt -o mapfile.map
             special characters.
     
   
    
-  
    prg: External Rewriting Program
    
-           MapType: prg, MapSource: Unix filesystem
-          path to valid regular file
-          
    Here the source is a program, not a map file. To
-          create it you can use a language of your choice, but
-          the result has to be an executable program (either
-          object-code or a script with the magic cookie trick
-          '#!/path/to/interpreter' as the first
-          line).
    This program is started once, when the Apache httpd server
-          is started, and then communicates with the rewriting engine
-          via its stdin and stdout
-          file-handles. For each map-function lookup it will
-          receive the key to lookup as a newline-terminated string
-          on stdin. It then has to give back the
-          looked-up value as a newline-terminated string on
-          stdout or the four-character string
-          ``NULL'' if it fails (i.e., there
-          is no corresponding value for the given key).
    This feature utilizes the rewrite-map mutex,
-          which is required for reliable communication with the program.
-          The mutex mechanism and lock file can be configured with the
-          Mutex directive.
    External rewriting programs are not started if they're defined in a
-          context that does not have RewriteEngine set to
-          on
    .
+  
    prg: External Rewriting Program
+  
+
    MapType: prg, MapSource: Unix filesystem path to valid regular file 
    
+
+
    Here the source is a program, not a map file. To
+create it you can use a language of your choice, but
+the result has to be an executable program (either
+object-code or a script with the magic cookie trick
+'#!/path/to/interpreter' as the first
+line).
    This program is started once, when the Apache httpd server
+is started, and then communicates with the rewriting engine
+via its stdin and stdout
+file-handles. For each map-function lookup it will
+receive the key to lookup as a newline-terminated string
+on stdin. It then has to give back the
+looked-up value as a newline-terminated string on
+stdout or the four-character string
+``NULL'' if it fails (i.e., there
+is no corresponding value for the given key).
    This feature utilizes the rewrite-map mutex,
+which is required for reliable communication with the program.
+The mutex mechanism and lock file can be configured with the
+Mutex directive.
    External rewriting programs are not started if they're defined in a
+context that does not have RewriteEngine set to
+on
    .
 
           
    A trivial program which will implement a 1:1 map (i.e.,
           key == value) could be: