fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe<?xml version="1.0"?>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe<?xml-stylesheet type="text/xsl" href="/style/manual.fr.xsl"?>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe<modulesynopsis metafile="mod_macro.xml.meta">

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe

f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung<name>mod_macro</name>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe<description>Ce module permet d'utiliser des macros dans les fichiers

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowede configuration Apache.</description>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe<status>Base</status>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe<sourcefile>mod_macro.c</sourcefile>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe<identifier>macro_module</identifier>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe<summary>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe <p>Ce module permet de d&eacute;finir et d'utiliser des macros dans les fichiers

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe de configuration Apache. Ces macros peuvent avoir des param&egrave;tres qui sont

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe expans&eacute;s &agrave; l'utilisation (les param&egrave;tres sont remplac&eacute;s par la valeur

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe pass&eacute;e en argument), et le r&eacute;sultat de la substitution est trait&eacute;

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf normalement.</p>

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf</summary>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe<section id="features"><title>Caract&eacute;ristiques</title>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <p>D&eacute;finition d'une macro :</p>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe <ul>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe <li> dans une section &lt;Macro&gt; au style conforme &agrave; la

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe syntaxe des fichiers de configuration Apache.</li>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe <li> l'utilisateur choisit le nom de la macro et de ses param&egrave;tres.</li>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe <li> les noms de macro sont insensibles &agrave; la casse, comme les directives Apache.</li>

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <li> les noms de param&egrave;tres sont par contre sensibles &agrave; la casse.</li>

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <li> les param&egrave;tres d'une macro doivent avoir des noms distincts.</li>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe <li> il y a une erreur si un param&egrave;tre a un nom vide.</li>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe <li> la red&eacute;finition d'une macro g&eacute;n&egrave;re un avertissement.</li>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe <li> des d&eacute;finitions de macros peuvent &ecirc;tre imbriqu&eacute;es les unes dans les autres... (mais dans quel but ?)</li>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe <li> les param&egrave;tres inutilis&eacute;s g&eacute;n&egrave;rent un avertissement.</li>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe <li> les noms de param&egrave;tre en pr&eacute;fixe les uns des autres g&eacute;n&egrave;rent un avertissement.</li>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe <li> les noms de param&egrave;tre non pr&eacute;fix&eacute;s par un des caract&egrave;res '<code>$%@</code>' g&eacute;n&egrave;rent un

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe avertissement pour encourager cette bonne pratique.</li>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe <li> les diff&eacute;rents pr&eacute;fixes propos&eacute;s permettent de g&eacute;rer les interactions

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe avec d'autres directives comme <directive module="core">Define</directive>.</li>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe <li> un conseil : il peut &ecirc;tre utile d'ajouter des accolades autour du nom d'un

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe param&egrave;tre, par exemple <code>${foo}</code>, de mani&egrave;re &agrave; ce que le

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe param&egrave;tre puisse &ecirc;tre utilis&eacute; entour&eacute; de caract&egrave;res,

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe par exemple <code>bla${foo}bla</code>.</li>

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe <li> g&eacute;n&egrave;re un avertissement si le contenu de la macro est vide.</li>

f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung <li> g&eacute;n&egrave;re un avertissement si le syst&egrave;me d&eacute;tecte que les sections &agrave; l'int&eacute;rieur

fc32fe886201ffcf1ca557bdf7d34a7468ab3374wrowe d'une macro ne sont pas correctement imbriqu&eacute;es.</li>

5effc8b39fae5cd169d17f342bfc265705840014rbowen <li> la port&eacute;e lexicale des param&egrave;tres d'une macro est restreinte au texte

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd de la macro elle-m&ecirc;me... en particulier elle n'est pas propag&eacute;e aux inclusions.</li>

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd <li> il n'y a pas de contrainte sur le contenu d'une macro.

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd <p>Cela signifie que vous pouvez mettre une section perl ou n'importe

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd quoi d'autre dans une macro. Il n'y a pas d'autre contrainte sur la

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd structure lexicale et syntaxique de la macro (guillemets, espaces...)

a329941afa602684be21fa85a54f2639e91763f8pquerna que d'attendre une s&eacute;quence de ligne avec &eacute;ventuellement des

continuations.</p></li>

</ul>

<p>Utilisation d'une macro:</p>

<ul>

<li> le nombre d'arguments doit &ecirc;tre coh&eacute;rent avec la d&eacute;finition.</li>

<li> toutes les occurences des param&egrave;tres sont substitu&eacute;es par leur valeur.</li>

<li> en cas de conflit, le nom le plus long est choisi.</li>

<li> une r&eacute;cursion dans l'expansion d'une macro est d&eacute;tect&eacute;e et interrompue avec envoi d'un message d'erreur.</li>

<li> si un argument vide est d&eacute;tect&eacute;, un avertissement est g&eacute;n&eacute;r&eacute;.</li>

<li> le syst&egrave;me s'efforce de g&eacute;n&eacute;rer une description pr&eacute;cise de la localisation des erreurs.</li>

<li> les valeurs des param&egrave;tres pr&eacute;fix&eacute;es par <code>$</code> et <code>%</code> ne sont pas &eacute;chapp&eacute;es.</li>

<li> les valeurs des param&egrave;tres pr&eacute;fix&eacute;es par <code>@</code> sont &eacute;chapp&eacute;es par des guillemets.</li>

</ul>

<p>Suppression de la d&eacute;finition d'une macro :</p>

<ul>

<li> la macro supprim&eacute;e doit avoir &eacute;t&eacute; d&eacute;finie auparavant.</li>

</ul>

<highlight language="config">

&lt;Macro DirGroup $dir $group&gt;

&lt;Directory $dir&gt;

require group $group

&lt;/Directory&gt;

&lt;/Macro&gt;

Use DirGroup /www/apache/private private

Use DirGroup /www/apache/server admin

UndefMacro DirGroup

</highlight>

</section>

<section id="examples"><title>Exemples</title>

<p>Un exemple typique d'utilisation de <module>mod_macro</module> est la

cr&eacute;ation dynamique de serveurs virtuels.</p>

<highlight language="config">

## D&eacute;finition d'une macro VHost pour les configurations r&eacute;p&eacute;titives

&lt;Macro VHost $host $port $dir&gt;

Listen $port

&lt;VirtualHost *:$port&gt;

ServerName $host

DocumentRoot $dir

&lt;Directory $dir&gt;

# directives propres au r&eacute;pertoire $dir ...

&lt;/Directory&gt;

# restriction d'acc&egrave;s au sous-r&eacute;pertoire intranet.

&lt;Directory $dir/intranet&gt;

Require ip 10.0.0.0/8

&lt;/Directory&gt;

&lt;/VirtualHost&gt;

&lt;/Macro&gt;

## Utilisation de la macro VHost avec diff&eacute;rents arguments.

Use VHost www.apache.org 80 /vhosts/apache/htdocs

Use VHost example.org 8080 /vhosts/example/htdocs

Use VHost www.example.fr 1234 /vhosts/example.fr/htdocs

</highlight>

</section>

<directivesynopsis type="section">

<name>Macro</name>

<description>D&eacute;finition d'une macro dans un fichier de configuration</description>

<syntax>

&lt;Macro <var>nom</var> [<var>par1</var> .. <var>parN</var>]&gt;

... &lt;/Macro&gt;</syntax>

<contextlist>

<context>server config</context>

<context>virtual host</context>

<context>directory</context>

</contextlist>

<usage>

<p>La directive <directive>Macro</directive> permet de d&eacute;finir une macro

dans un fichier de configuration Apache. Le premier argument est le nom

de la macro, et les arguments suivants sont les param&egrave;tres. Il

est de bon aloi de pr&eacute;fixer les noms des param&egrave;tres d'une macro

avec un caract&egrave;re parmi '<code>$%@</code>', et d'&eacute;viter d'en faire

de m&ecirc;me avec les noms de macros.

</p>

<highlight language="config">

&lt;Macro LocalAccessPolicy&gt;

Require ip 10.2.16.0/24

&lt;/Macro&gt;

&lt;Macro RestrictedAccessPolicy $ipnumbers&gt;

Require ip $ipnumbers

&lt;/Macro&gt;

</highlight>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>Use</name>

<description>Utilisation d'une macro</description>

<syntax>Use <var>nom</var> [<var>valeur1</var> ... <var>valeurN</var>]

</syntax>

<contextlist>

<context>server config</context>

<context>virtual host</context>

<context>directory</context>

</contextlist>

<usage>

<p> La directive <directive>Use</directive> permet d'utiliser une macro.

La macro consid&eacute;r&eacute;e est expans&eacute;e. Son nombre d'arguments doit &ecirc;tre &eacute;gal au

nombre de param&egrave;tres pr&eacute;cis&eacute;s dans sa d&eacute;finition. Les valeurs pass&eacute;es en

argument sont attribu&eacute;es aux param&egrave;tres correspondants et

substitu&eacute;es avant l'interpr&eacute;tation du texte de la macro.</p>

<highlight language="config">

Use LocalAccessPolicy

...

Use RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"

</highlight>

<p>est &eacute;quivalent, avec les macros d&eacute;finies ci-dessus &agrave; :</p>

<highlight language="config">

Require ip 10.2.16.0/24

...

Require ip 192.54.172.0/24 192.54.148.0/24

</highlight>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>undefMacro</name>

<description>Supprime une macro</description>

<syntax>UndefMacro <var>nom</var></syntax>

<contextlist>

<context>server config</context>

<context>virtual host</context>

<context>directory</context>

</contextlist>

<usage>

<p>La directive <directive>UndefMacro</directive> annule la d&eacute;finition

d'une macro qui doit avoir &eacute;t&eacute; d&eacute;finie auparavant.</p>

<highlight language="config">

UndefMacro LocalAccessPolicy

UndefMacro RestrictedAccessPolicy

</highlight>

</usage>

</directivesynopsis>

</modulesynopsis>