The Ant Task

Description

If you need the FMPP Ant task in a project xml (build.xml), use the taskdef core task:

<taskdef name="fmpp" classname="fmpp.tools.AntTask" />

Then you can use the <fmpp ...> task further down. You may remember the 4th step of Quick Tour. This is an Ant equivalent:

<project name="FMPP test" default="build">
    <taskdef name="fmpp" classname="fmpp.tools.AntTask" />
    
    <target name="build">
        <fmpp
              sourceRoot="src" outputRoot="out"
              data="tdd(data/style.tdd), birds:csv(data/birds.csv)"
        />
    </target>
</project>

Almost all parameters of the Ant task correspond to the FMPP settings. If the setting value is of scalar type (as string, boolean, number) then just enter the value simply with Ant-ish syntax, not with TDD syntax. If the setting value is of more tricky type, as hash or sequence, then use TDD syntax for it. For hash settings the value is hash mode TDD, and for sequence setting it is sequence mode TDD, so the brackets should be omitted, as with data above.

The configuration base for the setting values given with Ant parameters is the Ant project base directory. That is, if you enter sourceRoot="src", then src is interpreted relatively to the project base directory.

There is no parameter that directly corresponds to the sources setting. The sources are chosen with nested <fileset>-style parameters and nested elements (as include and exclude). However, if you use the outputFile setting, you can't use <fileset>-style stuff, and sources will be specified with the sourceFile parameter.

Alternatively, the data, localData, borders, modes, turns, xmlRenderings, outputFormatsByPath and freemarkerLinks settings can be specified with nested elements instead of parameters. For example, this is equivalent with the above example:

<project name="FMPP test" default="build">
    <taskdef name="fmpp" classname="fmpp.tools.AntTask" />
    
    <target name="build">
        <fmpp sourceRoot="src" outputRoot="out">
            <data>
                 tdd(data/style.tdd)
                 birds: csv(data/birds.csv)
            </data>
        </fmpp>
    </target>
</project>

This can be useful, if the setting value is long. The content of the element can be a CDATA section, which is useful if the setting value contains HTML or XML fragments. Unlike with attributes, Ant property interpolations (${foo}) in the text are not expanded, unless you force that with the expandProperties attribute of the element (<data expandProperties="yes">...).

About the support and interpretation of FMPP settings:

• The values of settings ignoreCvsFiles, ignoreSvnFiles and ignoreTemporaryFiles are always set to false, and there is no Ant task parameter for them. This is so that they don't interfere with Ant's standard defaultExcludes parameter.
• Settings echoFormat, printStackTrace, snip and columns are ignored, and there is no Ant task parameter for them.
• The quiet setting implements only grades true and false. reallyQuiet is the same as true.
• All logging related settings are supported.

To access the Ant properties and other Ant specific data in the templates, you can use data loaders such as antProperty(), antProperties(), antProject() and antTask(). Read the chapter about data loaders for more details.

Parameters

The FMPP task accepts the following parameters:

• All FMPP settings except sources, ignoreCvsFiles, ignoreSvnFiles, ignoreTemporaryFiles, echoFormat, printStackTrace, snip and columns. If the setting value is of scalar type (as string, boolean, number) then just enter the value simply with Ant-ish syntax, not with TDD syntax. If the setting value is of more tricky type, as hash or sequence, then use TDD syntax for it. For hash settings the value is hash mode TDD, and for sequence setting it is sequence mode TDD, so the brackets should be omitted. The configuration base for the setting values is the Ant project base directory.
• To follow the Ant conventions, srcdir and destdir attribute names can be optionally used instead of sourceRoot and outputRoot attribute names. These are just alias names.
• Configuration file handling:
  • configuration: Loads a configuration file. The setting values given with the parameters has higher precedence.
  • configurationBase: Emulates that configurationBase meta setting is present in configuration file with the given value.
  • inheritConfiguration: Emulates that inheritConfiguration meta setting is present in configuration file with the given value.
• Ant <fileset>-style attributes (see the Ant documentation for more details). Used for specifing the value of the sources setting:
  • dir: The directory that the patterns are relative to. If this attribute is omitted, then the FMPP source root will be used as the base. Note that regardless of the value of this attribute, all source files must be inside the source root.
  • casesensitive: Sets case sensitivity of the file names. (Same as the FMPP setting)
  • defaultexcludes: Indicates whether default excludes should be used or not ("yes" or "no"); default excludes are used when omitted.
  • excludes: comma- or space-separated list of patterns of files that must be excluded; no files (except default excludes) are excluded when omitted.
  • excludesfile: the name of a file; each line of this file is taken to be an exclude pattern.
  • followsymlinks: Shall symbolic links be followed? Defaults to true.
  • includes: Comma- or space-separated list of patterns of files that must be included; all files are included when omitted. Note that be default all files of the source root directory are included.
  • includesfile: The name of a file; each line of this file is taken to be an include pattern.
• sourceFile: It can be used only if the outputFile setting is specified. It specifies the value of the sources setting, as a simple string (not a comma separated list) that specifies the path of a single file. <fileset>-style attributes/elements will be ignored.
• antTaskFailOnError: Specifies if the Ant task should fail if there were errors during the execution of the processing session. Defaults to true. It has nothing to do with the stopOnError setting. If this parameter is true, the Ant task will fail if there were any failed file processing during the processing session, even if it was skipped because stopOnError was true (so the session wasn't aborted). If this parameter is false, then the Ant task will be successful regardless of the failed file processings or other errors during the processing session, even if the processing session was aborted. But, it never suppresses errors occurred during the initialization of the FMPP engine (i.e. errors occurred before the processing session could be stated).

Either the configuration parameter, or sourceRoot+outputRoot parameters, or sourceFile+outputFile parameters are required. All other parameters are optional. When you use configuration, any Ant task parameters can become optional, when the value of the coressponding settings are given in the configuration file.

Attention! When you specify the sources setting in a configuration file, its value will be added to the set of files and directories that the Ant task itself selects, which is, following the Ant tradition, by default all files and directories inside the source root. Thus, usually you will want to exclude all files in the Ant task, so only those specified in the configuration file will remain:

<fmpp configuration="config-with-sources-setting.fmpp" excludes="**/*" />

Nested elements

The FMPP task accepts the following nested elements:

• Elements for attribute substitution: Using these elements is the same as if you were use the attributes (parameters) with the same name, and with the same value as the nested text (or CDATA section) of the elements. Ant property values (${foo}) are not expanded by default, but you can override this with a expandProperties="yes" attribute. Note that you either give a certain setting with attribute, or with element, but not both.
  • data
  • localData
  • borders
  • modes
  • turns
  • xmlRenderings
  • outputFormatsByPath
  • freemarkerLinks
• <fileset>-style elements (see the Ant documentation for more details):
  • patternset
  • include: Note that be default all files inside the source root directory are included.
  • exclude
  • includesfile
  • excludesfile

Examples

Run processing session with the settings stored in <projectBaseDir>/config.fmpp (or fmpp.cfg):

<fmpp configuration="." />

As the previous, but override outputEncoding:

<fmpp configuration="." outputEncoding="UTF-8" />

Processes all files in src/www and stores the output in build/www:

<fmpp sourceRoot="src/www" outputRoot="build/www" />

Same as the previous, but processes files with extension ftl only:

<fmpp
    sourceRoot="src/www" outputRoot="build/www"
    includes="**/*.ftl"
/>

Same as the previous:

<fmpp sourceRoot="src/www" outputRoot="build/www">
    <include name="**/*.ftl" />
</fmpp>

Run processing session with the settings stored in <projectBaseDir>/src/wwwconfig.fmpp, but process files with extension ftl only:

<fmpp configuration="src/wwwconfig.fmpp" includes="**/*.ftl" />

Processes a single file:

<fmpp sourceFile="src/test.txt" outputFile="build/test.txt" />

Exposes Ant properties foo, bar and baaz for the templates:

<fmpp sourceRoot="src/www" outputRoot="build/www"
        data="antProperties(foo, bar, baaz)"
/>

Just to show something more complex...:

<fmpp sourceRoot="src/www" outputRoot="build/www"
        replaceExtension="ftl, html"
        modes="copy(**/*.html, **/*.htm)"
>
    <borders><![CDATA[
        border('<#escape x as x?html>', '</#escape>', **/*.ftl)
    ]]></borders>
    <data>
        bgColor: white
        fgColor: black
        antProps: antProperties()
    </data>
</fmpp>