mod_macro.xml revision 3b35091b9c1ae36ee3d0e64ebbfdba58062290ff
f545d156561c08020a67f9640c51454c2df4fb57fabien<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
f545d156561c08020a67f9640c51454c2df4fb57fabien<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
b4ddd0004bc04c857001f9f5e4600f3957054a32nd<!-- $LastChangedRevision$ -->
f545d156561c08020a67f9640c51454c2df4fb57fabien Licensed to the Apache Software Foundation (ASF) under one or more
f545d156561c08020a67f9640c51454c2df4fb57fabien contributor license agreements. See the NOTICE file distributed with
f545d156561c08020a67f9640c51454c2df4fb57fabien this work for additional information regarding copyright ownership.
f545d156561c08020a67f9640c51454c2df4fb57fabien The ASF licenses this file to You under the Apache License, Version 2.0
f545d156561c08020a67f9640c51454c2df4fb57fabien (the "License"); you may not use this file except in compliance with
f545d156561c08020a67f9640c51454c2df4fb57fabien the License. You may obtain a copy of the License at
f545d156561c08020a67f9640c51454c2df4fb57fabien Unless required by applicable law or agreed to in writing, software
f545d156561c08020a67f9640c51454c2df4fb57fabien distributed under the License is distributed on an "AS IS" BASIS,
f545d156561c08020a67f9640c51454c2df4fb57fabien WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
f545d156561c08020a67f9640c51454c2df4fb57fabien See the License for the specific language governing permissions and
f545d156561c08020a67f9640c51454c2df4fb57fabien limitations under the License.
f3d0c7823381704cd2977a45cdc490515bda49b6rbowen<description>Provides macros within apache httpd runtime configuration files</description>
6cdc7c6af490803d64ba77e244bc9fcfb4989600rbowen <p>This modules provides macros within apache httpd runtime configuration files.
f3d0c7823381704cd2977a45cdc490515bda49b6rbowen These macros may have parameters. They are expanded when used (parameters are
f545d156561c08020a67f9640c51454c2df4fb57fabien substituted by their values given as an argument), and the result is
f545d156561c08020a67f9640c51454c2df4fb57fabien processed normally.</p>
f3d0c7823381704cd2977a45cdc490515bda49b6rbowen <li> macro definition within a <directive type="section">Macro</directive> section, following
6cdc7c6af490803d64ba77e244bc9fcfb4989600rbowen the httpd configuration style.</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> user defined names for the macro and its parameters.</li>
6cdc7c6af490803d64ba77e244bc9fcfb4989600rbowen <li> macro names are case-insensitive, like httpd directives.</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> macro definitions can be nested... (but what for?)</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> warn about macro parameter names which prefix one another.</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> warn if a parameter is not prefixed by any of '<code>$%@</code>'
f545d156561c08020a67f9640c51454c2df4fb57fabien (good practice).</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> the available prefixes help deal with interactions with other
f545d156561c08020a67f9640c51454c2df4fb57fabien directives such as <directive module="core">Define</directive>.</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> tip: it may be useful to define a macro parameter with surrounding
f545d156561c08020a67f9640c51454c2df4fb57fabien braces, say <code>${foo}</code> so that the name can appear with
f545d156561c08020a67f9640c51454c2df4fb57fabien surrounding characters such as <code>bla${foo}bla</code>.</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> warns if sections are not properly nested within a macro.
f545d156561c08020a67f9640c51454c2df4fb57fabien (if it is detected so).</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> the lexical scope of macro parameters is restricted to the macro text,
f545d156561c08020a67f9640c51454c2df4fb57fabien it is not forwarded to includes for instance.</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> arbitrary contents in macros.
f545d156561c08020a67f9640c51454c2df4fb57fabien <p>It means you can put perl sections or whatever you like in a macro.
f545d156561c08020a67f9640c51454c2df4fb57fabien No assumption is made about the lexical structure (quotes, spaces or
f545d156561c08020a67f9640c51454c2df4fb57fabien whatever) within the macro contents but to expect a set of
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> number of arguments must match the definition.</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> all occurences of macro parameters are substituted by their values.</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> in case of conflicts, the longest parameter name is chosen.</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> macro expansion recursion is detected and stopped (error).</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> on errors, try to describe precisely where the error occured.</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> <code>$</code> and <code>%</code>-prefixed parameters are not
f545d156561c08020a67f9640c51454c2df4fb57fabien escaped.</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> <code>@</code>-prefixed parameters are escaped in quotes.</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien<Macro DirGroup $dir $group>
f545d156561c08020a67f9640c51454c2df4fb57fabien <Directory $dir>
f545d156561c08020a67f9640c51454c2df4fb57fabien require group $group
f545d156561c08020a67f9640c51454c2df4fb57fabien </Directory>
f545d156561c08020a67f9640c51454c2df4fb57fabien</Macro>
f545d156561c08020a67f9640c51454c2df4fb57fabienUndefMacro DirGroup
9546947d8f7082fb4b70e1659feb5460502b73e4rbowen</highlight>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen<p>A common usage of <module>mod_macro</module> is for the creation of
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowendynamically-generated virtual hosts.</p>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen## Define a VHost Macro for repetitive configurations
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen<Macro VHost $host $port $dir>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen Listen $port
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen <VirtualHost *:$port>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen ServerName $host
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen DocumentRoot $dir
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen <Directory $dir>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen # do something here...
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen </Directory>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen # limit access to intranet subdir.
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen order deny,allow
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen deny from all
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen allow from 10.0.0.0/8
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen </Directory>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen </VirtualHost>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen</Macro>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen## Use of VHost with different arguments.
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowenUse VHost www.example.fr 1234 /vhosts/example.fr/htdocs
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen</highlight>
f545d156561c08020a67f9640c51454c2df4fb57fabien<!-- Macro -->
f545d156561c08020a67f9640c51454c2df4fb57fabien<description>Define a configuration file macro</description>
f545d156561c08020a67f9640c51454c2df4fb57fabien<Macro <var>name</var> [<var>par1</var> .. <var>parN</var>]>
f545d156561c08020a67f9640c51454c2df4fb57fabien... </Macro></syntax>
f545d156561c08020a67f9640c51454c2df4fb57fabien<contextlist>
f545d156561c08020a67f9640c51454c2df4fb57fabien</contextlist>
f545d156561c08020a67f9640c51454c2df4fb57fabien <p>The <directive>Macro</directive> directive controls the definition of
f545d156561c08020a67f9640c51454c2df4fb57fabien a macro within the server runtime configuration files.
f545d156561c08020a67f9640c51454c2df4fb57fabien The first argument is the name of the macro.
f545d156561c08020a67f9640c51454c2df4fb57fabien Other arguments are parameters to the macro. It is good practice to prefix
f545d156561c08020a67f9640c51454c2df4fb57fabien parameter names with any of '<code>$%@</code>', and not macro names
f545d156561c08020a67f9640c51454c2df4fb57fabien with such characters.
f545d156561c08020a67f9640c51454c2df4fb57fabien<Macro LocalAccessPolicy>
f545d156561c08020a67f9640c51454c2df4fb57fabien</Macro>
f545d156561c08020a67f9640c51454c2df4fb57fabien<Macro RestrictedAccessPolicy $ipnumbers>
fe89484abca7439b98b250ee9091da29089c2bdarbowen Require ip $ipnumbers
f545d156561c08020a67f9640c51454c2df4fb57fabien</Macro>
f545d156561c08020a67f9640c51454c2df4fb57fabien </highlight>
f545d156561c08020a67f9640c51454c2df4fb57fabien</directivesynopsis>
f545d156561c08020a67f9640c51454c2df4fb57fabien<!-- Use -->
f545d156561c08020a67f9640c51454c2df4fb57fabien<directivesynopsis>
f545d156561c08020a67f9640c51454c2df4fb57fabien<syntax>Use <var>name</var> [<var>value1</var> ... <var>valueN</var>]
f545d156561c08020a67f9640c51454c2df4fb57fabien<contextlist>
f545d156561c08020a67f9640c51454c2df4fb57fabien</contextlist>
9546947d8f7082fb4b70e1659feb5460502b73e4rbowen <p>The <directive>Use</directive> directive controls the use of a macro.
f545d156561c08020a67f9640c51454c2df4fb57fabien The specified macro is expanded. It must be given the same number of
f545d156561c08020a67f9640c51454c2df4fb57fabien arguments than in the macro definition. The provided values are
f545d156561c08020a67f9640c51454c2df4fb57fabien associated to their corresponding initial parameters and are substituted
f545d156561c08020a67f9640c51454c2df4fb57fabien before processing.</p>
f3d0c7823381704cd2977a45cdc490515bda49b6rbowenUse LocalAccessPolicy
f3d0c7823381704cd2977a45cdc490515bda49b6rbowenUse RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"
f545d156561c08020a67f9640c51454c2df4fb57fabien </highlight>
f545d156561c08020a67f9640c51454c2df4fb57fabien </highlight>
f545d156561c08020a67f9640c51454c2df4fb57fabien</directivesynopsis>
f545d156561c08020a67f9640c51454c2df4fb57fabien<!-- UndefMacro -->
f545d156561c08020a67f9640c51454c2df4fb57fabien<directivesynopsis>
f545d156561c08020a67f9640c51454c2df4fb57fabien<contextlist>
f545d156561c08020a67f9640c51454c2df4fb57fabien</contextlist>
f545d156561c08020a67f9640c51454c2df4fb57fabien <p>The <directive>UndefMacro</directive> directive undefines a macro
f545d156561c08020a67f9640c51454c2df4fb57fabien which has been defined before hand.</p>
f545d156561c08020a67f9640c51454c2df4fb57fabienUndefMacro LocalAccessPolicy
f545d156561c08020a67f9640c51454c2df4fb57fabienUndefMacro RestrictedAccessPolicy
f545d156561c08020a67f9640c51454c2df4fb57fabien </highlight>
f545d156561c08020a67f9640c51454c2df4fb57fabien</directivesynopsis>
f545d156561c08020a67f9640c51454c2df4fb57fabien</modulesynopsis>