Basic usage
FMPP can work in two modes: as a recursive directory processor, or as single file processor.
When you're using it as recursive directory processor, it needs a source root directory and an output root directory. It processes all files inside the source root (including the files in its subdirectories), and writes the processed files into the output root directory with similar path as in the source root (that is, the output of <source-root>/foo/bar.txt will be <output-root>/foo/bar.txt. If /home/me/sample-project/src is the source root and /home/me/sample-project/out is the output root, then you issue:
fmpp -S /home/me/sample-project/src -O /home/me/sample-project/out
It's possible to tell FMPP to process only certain files and/or directories of the source root directory:
fmpp -S /home/me/sample-project/src -O /home/me/sample-project/out index.html foo/bar.txt somedir
Note that these paths are interpreted relatively to the source root directory, not to the current working directory.
When you use FMPP as single file processor, you specify a single input file, and then an output file with the -o option. It's the -o option is what triggers single file mode.
fmpp /home/me/file-to-process.txt -o /home/me/processed-file.txt
In single file mode, the source root and output root directory defaults to the directory of source and output files respectively. (It has significance for example if the source file wants to include another file), but you can override them with the -S and -O switches. The source file and output file path is always interpreted relatively to the current working directory.
It's often more convenient and manageable to use a project configuration file instead of entering everything as command-line arguments. For example, create file config.fmpp with this content:
sourceRoot: src
outputRoot: out
logFile: fmpp.log
modes: [ ignore(tmp/), copy(**/*.dwg, bin/) ]
data: {
contact: me@example.com
clients: csv(data/clients.csv)
}
then use it as:
fmpp -C /home/me/sample-project/config.fmpp
or since config.fmpp is the default configuration file name, you can simply issue:
fmpp -C /home/me/sample-project
or if you are in the same directory as config.fmpp then just issue:
fmpp
Note that paths in the configuration file are resolved relatively to the configuration file's directory, so it doesn't mater where do you invoke it from. Also note that you can override the settings stored in the configuration file with the command line:
fmpp -C /home/me/sample-project/config.fmpp -O other/destination
Much of what should be known about FMPP is not specific to its command line interface, so look around in the Table of Contents for more information!
Command-line argument syntax primer
This section is for users who are not too familiar with using the command-line. No FMPP specific information can be found here, so you may skip to the next section.
The exact command-line syntax depends on what shell do you use (sh, csh, DOS shell, etc.), because the shell is responsible to split the command-line to an executable name and a list of arguments. FMPP just gets the list from the shell.
Most shells will parse this command-line:
test -f t 1.txt 2.txt
as the executable name is test, and the list of arguments is:
-ft1.txt2.txt
As you may guess, the arguments are delimited by the spaces. If you want to put spaces into the value of arguments, in most shells you should use quotation marks:
test -f t -D "x:1, y:2"
Here, the list of arguments will be:
-ft-Dx:1, y:2
The shell has removed the quotation marks. Thus, command-line tools like FMPP will not know that there were quotation marks, as they just gets the above list from the shell.
With shells as sh, you can use apostrophe-quotes (') instead of quotation marks. In Windows/DOS shell you can use quotation marks (") only.
You have to quote the argument if you use characters that are reserved by the shell for other purposes. For example > and | is reserved in most shells. &, ; and ( is reserved in sh. Also, if you use an UN*X shell, sometimes you need to quote arguments that contain *, ? or ~, because otherwise the shell interprets the argument as a path, and replaces that with the list of matching files.
Most shells understand partially quoted arguments. For example:
test -D"x:1, y:2"
will be interpreted as:
-Dx:1, y:2
A tricky situation is when you want to use quotation marks in an argument value. To prevent this situations use apostrophe-quotes instead of plain quotes and vice versa. For example:
test -D"x:'red led', y:2"
or (will not work in Windows/DOS shell!):
test -D'x:"red led", y:2'
FMPP command-line argument syntax
The FMPP command-line tool uses similar argument syntax to usual UN*X command-line tools, such as ls. UN*X users should be able to use the tool even without reading this section.
This is a possible FMPP command-line:
fmpp -C mycfg.fmpp -q --case-sensitive products index.html
The FMPP command-line tool interprets command-line arguments as either:
- Option, as
-q,--case-sensitiveand-C mycfg.fmpp - Non-option, as
productsandindex.html
An option always starts with dash (-), or with double dash. (--), followed by the name of the option (e.g. q, C, case-sensitive). If the option requires parameter, then it is followed by the parameter to the option (as mycfg.fmpp in -C mycfg.fmpp), which counts as the part of the option, not as non-option.
If the option uses single dash, then the name of the option is exactly 1 character long; this is called short form. If the option uses double dash, then the name can be arbitrary long; this is called long form. All options have long form, and many options have both long and short form versions, which are equivalent (for example -q and --quiet). Short form options can be grouped together, for example you can write-qxs
instead of -q -x -s
Some options require a parameter. To demonstrate the syntactical rules with examples, here are the valid ways to give cp852 as parameter to option -E alias --source-encoding:
-E cp852: here the parameter was the next argument after the option-Ecp852: here I have utilized that a short option name is always 1 character long, and thus, since-Erequire parameter, the rest of this argument will be interpreted as the parameter of the option. (Note, that because if this, grouping (as-qxs) will not work if an option in the group, other than the very last option, requires parameter.) The next argument of the command-line will not be interpreted as parameter to-E.-E=cp852: This is similar to the latest, but the option name and parameter value is separated with=--source-encoding cp852--source-encoding=cp852
I didn't show the combinations like -E="cp852", as the usage of quotation marks is shell dependent. See the section about using the command-line for more information.
The order in which options occur in the command-line argument list is not significant.
Options are case sensitive. This means that -c and -C are not the same.
Any argument that does not start with dash and is not directly after an option that needs parameter, is a non-option. In FMPP, non-options are used to list the name of the files or directories that you want to process; see more about this later. The position of a non-option in the argument list relatively to the options is not significant. That is, these command-line argument lists are equivalent:
-C mycfg.fmpp -q products index.htmlproducts index.html -C mycfg.fmpp -qproducts -C mycfg.fmpp index.html -q
Sometimes it happens that a non-option should start with dash (for example, because the name of the file you want to refer to starts with dash). In this case you can use a special character sequence, -- followed by no option name, to indicate that all subsequent arguments are non-options:
fmpp -Cmycfg.fmpp -- -this-is-a-non-option
Invoking the command-line tool
The command-line tool can be invoked with the fmpp shell script (<FMPP>/bin/fmpp or <FMPP>/bin/fmpp.bat), assuming you have installed it properly.
When you invoke this tool, it will immediately run a processing session, with the settings you have set with its arguments (see later how), and then terminates. (With some command-line options, however, it will do something else, as with -h it just prints help.)
Specifying settings in the command-line
Most command-line options specify FMPP settings. The option name is the name of the setting, but with lower case dashed form (as source-root) instead of the usual mixed case form (as sourceRoot). The value of the setting is given as the parameter of the option. The configuration base for the values is the current working directory (i.e. the directory you are in).
Example: Runs a processing session with sourceRoot set to src and outputRoot set to out (so this will process all files in the src directory, and store the output in the out directory):
fmpp --source-root src --output-root out
For the most frequently used settings there is short option name too. For example, this is equivalent with the previous example:
fmpp -S src -O out
If the setting value is of scalar type (as string, boolean, number) then just enter the value simply as is, not with TDD syntax. If the setting value is of more tricky type, as hash or sequence, then you use TDD syntax for it. For hash settings the value is a hash mode TDD, and for sequence setting it is sequence mode TDD, so the brackets should be omitted. For example:
fmpp -S src -O out -D "online:false, tdd(data/style.tdd)" --replaceExtensions "ftl, html"
Note that the quotation marks were needed only for the command-line parser of the shell (see earlier on this page), so they are not visible for FMPP.
Boolean settings (and quiet) are specified with parameterless options:
| Command-line option | Meaning | |
|---|---|---|
| Setting name | Value | |
-s, --stop-on-error
| stopOnError
| true
|
-c, --continue-on-error
| stopOnError
| false
|
--case-sensitive
| caseSensitive
| true
|
--ignore-case
| caseSensitive
| false
|
--ignore-cvs-files
| ignoreCvsFiles
| true
|
--dont-ignore-cvs-files
| ignoreCvsFiles
| false
|
--ignore-svn-files
| ignoreSvnFiles
| true
|
--dont-ignore-svn-files
| ignoreSvnFiles
| false
|
--ignore-temporary-files
| ignoreTemporaryFiles
| true
|
--dont-ignore-temporary-files
| ignoreTemporaryFiles
| false
|
--print-stack-trace
| printStackTrace
| true
|
--dont-print-stack-trace
| printStackTrace
| false
|
-x, --expert
| expert
| true
|
--not-expert
| expert
| false
|
--append-log-file
| appendLogFile
| true
|
--dont-append-log-file
| appendLogFile
| false
|
-q, --quiet
| quiet
| true
|
-v, --verbose
| quiet
| false
|
-Q, --really-quiet
| quiet
| reallyQuiet
|
Example:
fmpp -S src -O out --dont-ignore-cvs-files -cqx
where the last few options mean: ignoreCvsFiles is false, stopOnError is false, quiet is true, expert is true.
The value of the sources setting can be given as the non-option arguments to the tool. For example, to process only files index.html and directory products of the source root:
fmpp -S src -O out index.html products
Notes for Windows users:
- In paths you can optionally use slash (
/) instead of backslash (\) anywhere. - You can't use
*and?in paths (except in settings that explicitly want path patterns, e.g.modes)
Using configuration files
With option --configuration or -C you can load a configuration file. As you may know it from the chapter about configuration files, it is enough to give the directory of the configuration file, if the file uses one of the standard names. Example:
fmpp -C works/project1
If you don't use option --configuration/-C, fmpp will look for a configuration file in the current working directory, and if it finds one with standard name, it will load that automatically. To prevent this, use --configuration/-C with none parameter (as -C none).
Settings loaded from the configuration file have lower priority than settings given as command-line arguments. For example, here you add an extra variable to the data specified in the configuration file, or if variable online was already created there then replace its value:
fmpp -C works/project1 -D online:true
Options configurationBase and inheritConfiguration can be used to emulate that settings configurationBase and inheritConfiguration are present with the given value in the configuration file.
Global options
The default of some settings that can't influence the output files can be set in a configuration file called .fmpprc. This file is searched in these directories, in this order:
- In your home directory.
- On Windows, in the directory pointed by the
HOMEenvironment variable. - In the directory pointed by the
FMPP_HOMEenvironment variable. This is usually automatically set to the directory where you have installed FMPP.
Only the first .fmpprc found will be loaded.
The settings you can set in the .fmpprc are:
appendLogFilecolumnsechoFormatprintStackTracequietsnip: Deprecated, now just an inverted alias ofprintStackTrace
Supported front-end dependent settings
All logging related settings are supported.
All recommended echoFormat-s are supported, but verbose is the same as normal. It depends on the terminal implementation you use, but terse echo format can substantially speed up the processing session if you have many files.
All quiet values are supported.
List of all options
The complete list of command-line options with brief description is included further below in the output of fmpp -h.
Almost all options correspond to FMPP settings; see the complete descriptions of FMPP settings here.
Typical usages:
fmpp -C configfile
fmpp -S sourcedir -O outputdir
fmpp sourcefile -o outputfile
For more examples: http://fmpp.sourceforge.net/commandline.html
Options:
-A, --locale=<LOC> The locale (as ar_SA). Use the special value "host" (-A host) if the default
locale of the host machine should be used. The default value of the option
is en_US.
--always-create-directories Create output subdirectory even if it will remain empty. Defaults to false.
--append-log-file If the log file already exists, it will be continued, instead of restarting
it.
--boolean-format=<FORMAT> The boolean format used to show boolean values, like "Yes,No". Not
"true,false"; use ${myBool?c} for that. The default is error on ${myBool}.
--borders=<SEQ> The list of TDD function calls that choose header and footer for templates,
e.g.:
-M 'border("<#import "/lib/utils.ftlh" as u><@u.myLayout>",
"</@u.myLayout>", *.htm, *.html), header("<#include \"/css.ftl\">",
*.css)'
-c, --continue-on-error Skip to the next file on failed file processing (and log the error: see -L)
-C, --configuration=<FILE> Load settings from a configuration file. Settings given with command-line
options have higher priority (note that some settings are merged, rather
than overridden). Be default fmpp will use ./config.fmpp or ./fmpp.cfg if
that exists. Use value "none" (-C none) to prevent this.
--case-sensitive Upper- and lower-case letters are considered as different characters when
comparing or matching paths.
--columns=<COLS> The number of columns on the console screen. Use when auto-detection gives
bad result.
--configuration-base=<DIR> The directory used as base to resolve relative paths in the configuration
file. It defaults to the directory of the configuration file.
-D, --data=<TDD> Creates shared data that all templates will see. <TDD> is the Textual Data
Definition, e.g.:
-D "properties(style.properties), onLine:true"
Note that paths like "style.properties" are relative to the data root
directory.
--data-root=<DIR> Sets the root directory of data files. The reserved value "source" means
that the data root is the same as the source root. The default value is
"source".
--date-format=<FORMAT> The format used to show date (year+month+day) values. The default is locale
dependent.
--datetime-format=<FORMAT> The format used to show date-time values. The default is locale dependent.
--dont-append-log-file If the log file already exists, it will be restarted. This is the default.
--dont-ignore-cvs-files Don't ignore CVS files in the source root directory.
--dont-ignore-svn-files Don't ignore SVN files in the source root directory.
--dont-ignore-temporary-files Don't ignore well-known temporary files in the source root directory.
--dont-map-common-extensions-to-output-formats Opposite of --map-common-extensions-to-output-formats.
--dont-print-stack-trace Don't print stack trace on error, just cause chain. This is the default.
--dont-remove-freemarker-extensions Opposite of --remove-freemarker-extensions.
--dont-snip Deprecated; alias of printStackTrace.
--dont-validate-xml Sets that XML files will not be validated by default. This is the default.
-E, --source-encoding=<ENC> The encoding of textual sources (templates). Use the special value "host"
(-E host) if the default encoding of the host machine should be used. The
default is "ISO-8859-1".
-F, --echo-format=<FORMAT> The format used for displaying the progress. <FORMAT> is n[ormal], t[erse]
or q[uiet] (or v[erbose], which is the same as normal). The default is
normal.
--freemarker-incompatible-improvements=<VER> Enables the FreeMarker fixes/improvements that aren't 100%
backward compatible, and were implemented in FreeMarker version <VER>. In
older projects using the highest available 2.3.x is usually a good
compromise, but check FreeMarker documentation. New projects should use
the maximum (in this installation "2.3.28". The default depends on the
recommended-defaults setting; usually you just set that, and not directly
this setting.
--freemarker-links=<MAP> The map of FreeMarker links (external includes).
-h, --help Prints help on options.
--ignore-case Upper- and lower-case letters are considered as the same characters when
comparing or matching paths. This is the default.
--ignore-cvs-files Ignore CVS files in the source root directory. This is the default.
--ignore-svn-files Ignore SVN files in the source root directory. This is the default.
--ignore-temporary-files Ignore well-known temporary files (e.g. **/?*~) in the source root
directory. This is the default.
--inherit-configuration=<FILE> Inherits options from a configuration file. The options in the primary
configuration file (-C) has higher precedence.
--interpolation-syntax=<WHAT> Sets the interpolation syntax of the templates. Possible values are:
legacy (like ${exp} or #{exp}), dollar (${exp} only), squareBracket (like
[=exp]). The default is legacy.
-L, --log-file=<FILE> Sets the log file. Use "none" (-L none) to disable logging. The default is
"none".
--local-data=<SEQ> Creates data that is visible only for certain templates. This is a list of
case(...) and layer() function calls.
--long-help Deprecated; same as -h
-M, --modes=<SEQ> The list of TDD function calls that choose the file processing mode, e.g.:
-M "ignore(**/tmp/), execute(**/*.htm, **/*.html), copy(**/*)"
--map-common-extensions-to-output-formats Should templates with common file extensions ("html", "htm",
"xml", etc.) be mapped to an output format (auto-escaping). Has lower
priority than --output-formats-by-path. Enabled by default if
--recommended-defaults is at least 0.9.16.
--not-expert Disables expert mode. This is the default.
--number-format=<FORMAT> The number format used to show numerical values. The default is
0.############
-o, --output-file=<FILE> The output file. This switches FMPP to single-file mode.
-O, --output-root=<DIR> Sets the root directory of output files.
--object-wrapper=<BSH> Specifies the ObjectWrapper to use with a BeanShell expression that must
evaluate to an object that extends BeansWrapper. The default value is a
BeansWrapper instance with simpleMapWrapper set to true.
--output-encoding=<ENC> The encoding of template output. Use the special value "source" if the
encoding of the template file should be used. Use the special value "host"
if the default encoding of the host machine should be used. The default is
"source".
--output-format=<NAME> Sets the output format (auto-escaping) of templates, like "HTML", "XML",
"RTF", etc. By default "unspecified". The --output-formats-by-path and
--map-common-extensions-to-output-formats option overrides this for
matching paths.
--output-formats-by-path=<SEQ> List of case(...)-s that choose the template output format
(auto-escaping), e.g.:
--output-formats="case(**/*.xsl, **/*.wsdl, XML), case(**/*.htm*, HTML)"
By default empty.
--print-locales Prints the locale codes that Java platform knows.
--print-stack-trace Print stack trace on error.
-q, --quiet Don't write to the stdout, unless the command-line arguments are wrong.
Print warning and error messages to the stderr.
-Q, --really-quiet As -q, but doesn't even write to the stderr.
-R, --remove-extensions=<SEQ> These extensions will be removed from the output file name. <SEQ> contains
the extensions without the dot.
--recommended-defaults=<VER> Use the setting value defaults recommended as of FMPP version <VER>. When
you start a new project, set this to the current FMPP version (0.9.16). In
older projects changing this setting can break things (check
documentation). The default is 0.9.15, because this setting was added in
0.9.16.
--remove-freemarker-extensions Remove "ftl", "ftlh", and "ftlx" file extensions from the output file
name. (This is applied last among the settings that tranform the output
file name.) Enabled by default if --recommended-defaults is at least
0.9.16.
--remove-postfixes=<SEQ> If the source file name without the extension ends with a string in the
<SEQ>, then that string will be removed from the output file name.
--replace-extensions=<SEQ> Replaces the extensions with another exensions. The list contains the old
and new extensions alternately; old1, new1, old2, new2, etc. The
extensions in the <SEQ> do not contain the dot.
-s, --stop-on-error Terminate fmpp on failed file processing. This is the default behaviour. Use
-c to override this.
-S, --source-root=<DIR> Sets the root directory of source files. In bulk-mode it defaults to the
current working directory.
--snip Deprecated; alias of dont-printStackTrace.
--sql-date-and-time-time-zone=<ZONE> Sets a different time zone for java.sql.Date and java.sql.Time
only.
--tag-syntax=<WHAT> Sets the tag syntax of the templates that doesn't start with the ftl
directive. Possible values are: angleBracket (like <#ftl>), squareBracket
(like [#ftl]), autoDetect. The default is angleBracket. The recommended
value is autoDetect.
--time-format=<FORMAT> The format used to show time values. The default is locale dependent.
--time-zone=<ZONE> Sets the time zone in which date/time/date-time values are shown. The
default is the time zone of the host machine. Example: GMT+02
--turns=<SEQ> The list of turn(...)-s that choose the turns of processings, e.g.:
--turns "turn(2, **/*_t2.*, ), turn(3, **/*_t3.*, **/*.toc)"
By default all files will be procesed in the first turn.
-U, --skip-unchanged=<WHAT> Skip <WHAT> files if the source was not modified after the output file was
last modified. <WHAT> can be "all", "none" or "static"
--url-escaping-charset=<ENC> The charset used for URL escaping. Use the special value "output" if the
encoding of the output file should be used. The default is "output".
-v, --verbose The opposite of -Q: prints everything to the stdout. This is the default.
--validate-xml Sets that XML files will be validated by default.
--version Prints version information.
-x, --expert Expert mode.
--xml-catalog-files=<SEQ> Sets the catalog files used for XML entity resolution. Catalog based
resolution is enabled if and only if this settings is specified.
--xml-catalog-prefer=<WHAT> Sets if catalog file based XML entity resolution prefers public or system
identifiers. Valid values are: public, system, globalDefault. Defaults to
public.
--xml-renderings=<SEQ> Sets the sequence of XML renderings. Each item is hash, that stores the
options of an XML rendering configuration.
--xpath-engine=<NAME> Sets the XPath engine to be used. Legal values are: dontSet, default, jaxen,
xalan, and any adapter class name.
Most options above directly correspond to FMPP settings. See their full descriptions here:
http://fmpp.sourceforge.net/settings.html
