P18 Internationalizing Preprocessor

Documentation

Previous  Next  .  Contents
 		About  .  Documentation  .  License   .  Download

Configuration

The configuration file syntax is defined through an XML DTD. The main reason for that is that I was lazy defining a more user-friendly configuration language and writing a parser for it. It is likely that there will be a nicer configuration language by the time of the 1.0 release. If that happens, the XML format will still be supported, of course.

Here is the XML DTD specifying the configuration file syntax: 
<!ELEMENT p18cfg (input* define* undef* macro* option*)>
<!ELEMENT input (define* undef* macro* option* files*)>
<!ATTLIST input
        name            CDATA           #IMPLIED
        path            CDATA           #REQUIRED
>
<!ELEMENT define EMPTY>
<!ATTLIST define
        name            CDATA           #REQUIRED
        value           CDATA           #REQUIRED
>
<!ELEMENT undef EMPTY>
<!ATTLIST undef
        name            CDATA           #REQUIRED
        var-only        (yes|no)        "no"
>
<!ELEMENT macro (parameter)* (#PCDATA)>
<!ATTLIST macro
        name            CDATA           #REQUIRED
>
<!ELEMENT parameter EMPTY>
<!ATTLIST parameter
        name            CDATA           #REQUIRED
        default         CDATA           #IMPLIED
        vararg          (yes|no)        "no"
>
<!ELEMENT option EMPTY>
<!ATTLIST option
        name            CDATA           #REQUIRED
        value           CDATA           #IMPLIED
>
<!ELEMENT files (#PCDATA)>

Input Objects

A configuration file may list a number of input objects. An input object is represented by the <input> element. An input object encapsulates a set of files and associates these files with a symbolic name. The <input> element takes the following parameters:
name
  The symbolic name associated with the input object. If this parameter is omitted, it defaults to the last component of the path parameter.
path
  The path to the base directory of the input object. All input filenames and filename patterns are interpreted relative to this directory.
All variables, macros, and options defined within the <input> element are local to the input object and take precedence over variables, macros, and options defined globally (i.e. outside an <input> element).

In an <input> element, the files (and file patterns) for all files represented by the input object are specified through one or more <files> elements. The contents of all <files> elements are interpreted as whitespace-separated lists of input file patterns. These patterns are glob-style patterns (i.e. the patterns may include the wildcard characters known from the UNIX command shell).

Setting Options

Options can be set using the <option> element. An <option> element may appear inside of an <input> element (where it defines an option local to the input object), and on the top level (where it defines a global option). A complete list of supported options is given in the section Configuration Options.

The <option> element takes the following parameters:
name
  The name of the option.
value
  The value bound to the option name.
If the specified option is already set, the value defined in the <option> element replaces the value bound to the option.

Defining Variables

Variables (and macros) can be defined using the <define> element. A <define> element may appear inside of an <input> element (where the variable definition takes effect only for the files specified in the input object), and on the top level (where the variable definition takes effect for all input files). The <define> element takes the following parameters:
name
  The name of the variable/macro.
value
  The value bound to the named variable/macro.
If the specified variable/macro is already defined, the value specified in the <define> element replaces the value bound to the variable/macro.

Defining Macros

Macros (and variables) can be defined using the <macro> element. Actually, defining a macro using the <macro> element is equivalent to defining the macro (and all its default parameters) using a series of <define> elements (see section Concept for details). In contrast to the <define> element, the <macro> element sets the value of the macro through the elements content. The parameters taken by the macro are specified inside the <macro> element, using a series of <parameter> elements (see below).

The <macro> elements takes the following parameters:
name
  The name of the macro/variable.
The value bound to the macro/variable is specified through the elements content.

The <parameter> element may appear inside the <macro> element, to specify the parameters taken by the macro. The <parameters> element takes the following parameters:
name
  The name of the parameter. When the macro is expanded, the argument passed for that parameter is available through a variable with the specified name.
default
  The default value for the parameter. If the macro is invoked with less arguments than defined parameters, the omitted arguments are replaced by the specified default values.
vararg
  Valid values for this parameter are "yes" and "no" (the default is "no"). The value "yes" indicates that extra arguments passed to the macro should be combined to a single argument. Only the last parameter specified may be a vararg-parameter.

Undefining Variables and Macros

The element <undef> may be used to undefine a variable or macro. The <undef> element may appear inside of an <input> element (where it takes effect only for the files specified in the input object), or at the top level (where it takes effect for all input files).

The <undef> element takes the following parameters:
name
  The name of the variable/macro to be undefined.
var-only
  Valid values for this parameter are "yes" and "no" (the default is "no"). The value "yes" indicates that only the variable with the specified name should be undefined. The default is to undefine all associated variables (i.e. macro definitions and default parameters).

Configuration Options

The following options are recognized.
output-path
  The base path for the output files. When the preprocessor is run, the output files are generated relative to this directory, using the filenames derived from the <files> element in the input object. Note that this may actually mean that files are created in a subdirectory of the specified output path.
create-directories
  If this option is set to a string representing TRUE, the directory hierarchy for the output files is created if it does not exit. The default is to issue an error message if an output directory does not exit.
language
  The output language. The default value is "*", which means that the messages will not be translated. Note that if this option is specified, the value takes precedence over an output language specified on the command line (which is equivalent to a global option). It is probably better not to specify this option in a configuration file.
config-status
  Specify the location of the projects "config.status" file (assuming the project uses GNU autoconf). All variables defined in the specified "config.status" file are defined as preprocessor variables.
database
  Specify the translation database file. This option is recognized only as a global option.
Note: The translation database file is read on startup, i.e. this option has no effect if the configuration file is read through a config command. The option only works if the configuration file is specified on the invocation command line.

Note: When specifying options, be careful to double-check that the option names are correct. P18 will silently ignore options it does not know. This may change for the 1.0 release.

Examples

Here's the configuration file I use for creating this manual: 
<p18cfg>

<option name="create-directories" value="true"/>
<option name="config-status" value="../config.status"/>

<input name="doc" path="./html.in">
  <option name="output-path" value="./html"/>
  <files>*.html</files>
</input>

</p18cfg>

Although it is possible to define variables and macros in the configuration file, it is probably better to define macros and variables through an include file (i.e. a file that is read by the source files using an ##include directive). However, here's a more complex example of a configuration file defining some variables and macros: 
<p18cfg>

<option name="create-directories" value="true"/>

<define name="PACKAGE" value="FOO-Wizard"/>
<define name="VERSION" value="1.0"/>

<input name="webapp" path="./php.in">
  <option name="output-path" value="./php"/>
  <files>
    *.php
    *.inc
    *.html
  </files>
  <define name="ENABLE_FEATURE_A" value="1"/>
  <define name="ENABLE_FEATURE_B" value="1"/>
  <undef name="ENABLE_FEATURE_C"/>
</input>

<macro name="FEATURE">
<parameter name="feature"/>
## if ENABLE_@feature@
</macro>
<macro name="FEATURE_END">
## endif
</macro>

</p18cfg>

Previous  Next  .  Contents
 		About  .  Documentation  .  License   .  Download