mod_macro.xml revision 8e4f67d801eed8da80a5765df00e8da90cf17f3a
f545d156561c08020a67f9640c51454c2df4fb57fabien<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
f545d156561c08020a67f9640c51454c2df4fb57fabien<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
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.
f545d156561c08020a67f9640c51454c2df4fb57fabien<description>This module provides usage of macros within apache runtime configuration files</description>
f545d156561c08020a67f9640c51454c2df4fb57fabien <p>This modules provides macros within apache runtime configuration files.
f545d156561c08020a67f9640c51454c2df4fb57fabien These macros 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>
f545d156561c08020a67f9640c51454c2df4fb57fabien Definition of a macro:
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> macro definition within a <Macro> section, following
f545d156561c08020a67f9640c51454c2df4fb57fabien the apache style.</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> user defined names for the macro and its parameters.</li>
f545d156561c08020a67f9640c51454c2df4fb57fabien <li> macro names are case-insensitive, like apache 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 Use of a macro:
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 Removal of a macro definition:
f545d156561c08020a67f9640c51454c2df4fb57fabien<Macro DirGroup $dir $group>
f545d156561c08020a67f9640c51454c2df4fb57fabien <Directory $dir>
f545d156561c08020a67f9640c51454c2df4fb57fabien require group $group
f545d156561c08020a67f9640c51454c2df4fb57fabien </Directory>
f545d156561c08020a67f9640c51454c2df4fb57fabien</Macro>
f545d156561c08020a67f9640c51454c2df4fb57fabienUndefMacro DirGroup
f545d156561c08020a67f9640c51454c2df4fb57fabien </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 order deny,allow
f545d156561c08020a67f9640c51454c2df4fb57fabien deny from all
f545d156561c08020a67f9640c51454c2df4fb57fabien</Macro>
f545d156561c08020a67f9640c51454c2df4fb57fabien<Macro RestrictedAccessPolicy $ipnumbers>
f545d156561c08020a67f9640c51454c2df4fb57fabien order deny,allow
f545d156561c08020a67f9640c51454c2df4fb57fabien deny from all
f545d156561c08020a67f9640c51454c2df4fb57fabien allow from $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>
f545d156561c08020a67f9640c51454c2df4fb57fabien <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>
f545d156561c08020a67f9640c51454c2df4fb57fabienUse LocalAccessPolicy
f545d156561c08020a67f9640c51454c2df4fb57fabienUse RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"
f545d156561c08020a67f9640c51454c2df4fb57fabien </highlight>
f545d156561c08020a67f9640c51454c2df4fb57fabienorder deny,allow
f545d156561c08020a67f9640c51454c2df4fb57fabiendeny from all
f545d156561c08020a67f9640c51454c2df4fb57fabienorder deny,allow
f545d156561c08020a67f9640c51454c2df4fb57fabiendeny from all
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>