mod_macro.xml revision b4ddd0004bc04c857001f9f5e4600f3957054a32
530eba85dbd41b8a0fa5255d3648d1440199a661slive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding Licensed to the Apache Software Foundation (ASF) under one or more
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding contributor license agreements. See the NOTICE file distributed with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding this work for additional information regarding copyright ownership.
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding The ASF licenses this file to You under the Apache License, Version 2.0
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding (the "License"); you may not use this file except in compliance with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding the License. You may obtain a copy of the License at
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Unless required by applicable law or agreed to in writing, software
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd distributed under the License is distributed on an "AS IS" BASIS,
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd See the License for the specific language governing permissions and
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd limitations under the License.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<description>This module provides usage of macros within apache runtime configuration files</description>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <p>This modules provides macros within apache runtime configuration files.
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna These macros have parameters. They are expanded when used (parameters are
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna substituted by their values given as an argument), and the result is
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna processed normally.</p>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> macro definition within a <Macro> section, following
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna the apache style.</li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> user defined names for the macro and its parameters.</li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> macro names are case-insensitive, like apache directives.</li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> macro parameters must have distinct names.</li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> macro definitions can be nested... (but what for?)</li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> warn about macro parameter names which prefix one another.</li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> warn if a parameter is not prefixed by any of '<code>$%@</code>'
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna (good practice).</li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> the available prefixes help deal with interactions with other
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna directives such as <directive module="core">Define</directive>.</li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> tip: it may be useful to define a macro parameter with surrounding
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna braces, say <code>${foo}</code> so that the name can appear with
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna surrounding characters such as <code>bla${foo}bla</code>.</li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> warns if sections are not properly nested within a macro.
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna (if it is detected so).</li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> the lexical scope of macro parameters is restricted to the macro text,
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna it is not forwarded to includes for instance.</li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> arbitrary contents in macros.
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <p>It means you can put perl sections or whatever you like in a macro.
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna No assumption is made about the lexical structure (quotes, spaces or
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna whatever) within the macro contents but to expect a set of
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> number of arguments must match the definition.</li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> all occurences of macro parameters are substituted by their values.</li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> in case of conflicts, the longest parameter name is chosen.</li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <li> macro expansion recursion is detected and stopped (error).</li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <li> on errors, try to describe precisely where the error occured.</li>
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess <li> <code>$</code> and <code>%</code>-prefixed parameters are not
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive escaped.</li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <li> <code>@</code>-prefixed parameters are escaped in quotes.</li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<Macro DirGroup $dir $group>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <Directory $dir>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive require group $group
fb77c505254b6e9c925e23e734463e87574f8f40kess </Directory>
fb77c505254b6e9c925e23e734463e87574f8f40kess</Macro>
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveUndefMacro DirGroup
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</highlight>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<!-- Macro -->
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<description>Define a configuration file macro</description>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<Macro <var>name</var> [<var>par1</var> .. <var>parN</var>]>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive... </Macro></syntax>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<contextlist>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</contextlist>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>The <directive>Macro</directive> directive controls the definition of
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive a macro within the server runtime configuration files.
fb77c505254b6e9c925e23e734463e87574f8f40kess The first argument is the name of the macro.
6b64034fa2a644ba291c484c0c01c7df5b8d982ckess Other arguments are parameters to the macro. It is good practice to prefix
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive parameter names with any of '<code>$%@</code>', and not macro names
bc4b55ec8f31569d606d5680d50189a355bcd7a6rbowen with such characters.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<Macro LocalAccessPolicy>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive order deny,allow
fb77c505254b6e9c925e23e734463e87574f8f40kess deny from all
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</Macro>
fb77c505254b6e9c925e23e734463e87574f8f40kess<Macro RestrictedAccessPolicy $ipnumbers>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive order deny,allow
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd deny from all
130d299c4b2b15be45532a176604c71fdc7bea5bnd allow from $ipnumbers
130d299c4b2b15be45532a176604c71fdc7bea5bnd</Macro>
130d299c4b2b15be45532a176604c71fdc7bea5bnd </highlight>
130d299c4b2b15be45532a176604c71fdc7bea5bnd</directivesynopsis>
130d299c4b2b15be45532a176604c71fdc7bea5bnd<!-- Use -->
130d299c4b2b15be45532a176604c71fdc7bea5bnd<directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<syntax>Use <var>name</var> [<var>value1</var> ... <var>valueN</var>]
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<contextlist>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd</contextlist>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>The <directive>Use</directive> directive controls the use of a macro.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive The specified macro is expanded. It must be given the same number of
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive arguments than in the macro definition. The provided values are
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess associated to their corresponding initial parameters and are substituted
003f0c9fda6664daf5092a0e42f65ede20098153slive before processing.</p>
6b64034fa2a644ba291c484c0c01c7df5b8d982ckessUse LocalAccessPolicy
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cndUse RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd </highlight>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>is equivalent, with the macros defined above, to:</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveorder deny,allow
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivedeny from all
130d299c4b2b15be45532a176604c71fdc7bea5bndorder deny,allow
130d299c4b2b15be45532a176604c71fdc7bea5bnddeny from all
130d299c4b2b15be45532a176604c71fdc7bea5bnd </highlight>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<!-- UndefMacro -->
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<contextlist>
530eba85dbd41b8a0fa5255d3648d1440199a661slive</contextlist>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>The <directive>UndefMacro</directive> directive undefines a macro
003f0c9fda6664daf5092a0e42f65ede20098153slive which has been defined before hand.</p>
843a03fe0b138a4c1f64cb90a014e9417ac30691fieldingUndefMacro LocalAccessPolicy
843a03fe0b138a4c1f64cb90a014e9417ac30691fieldingUndefMacro RestrictedAccessPolicy
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding </highlight>
a8ce9095d102e43fecb81093a132b90b9a227f78kess</directivesynopsis>
684f2a9a422185adda0692a1203c5ad6687fc5c5nd</modulesynopsis>