@page title="The Command-line Tool" keywords="command-line tool"> <@sect title="Basic usage" anchor="cmdln_basics">
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 <@c><@r><source-root>@r>/foo/bar.txt@c> will be <@c><@r><output-root>@r>/foo/bar.txt@c>. If <@c>/home/me/sample-project/src@c> is the source root and <@c>/home/me/sample-project/out@c> is the output root, then you issue:
<@prg>fmpp -S /home/me/sample-project/src -O /home/me/sample-project/out@prg>It's possible to tell FMPP to process only certain files and/or directories of the source root directory:
<@prg>fmpp -S /home/me/sample-project/src -O /home/me/sample-project/out index.html foo/bar.txt somedir@prg>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 <@c>-o@c> option. It's the <@c>-o@c> option is what triggers single file mode.
<@prg>fmpp /home/me/file-to-process.txt -o /home/me/processed-file.txt@prg>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 <@c>-S@c> and <@c>-O@c> 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 <@c>config.fmpp@c> with this content:
<@prg> sourceRoot: src outputRoot: out logFile: fmpp.log modes: [ ignore(tmp/), copy(**/*.dwg, bin/) ] data: { contact: me@example.com clients: csv(data/clients.csv) } @prg>then use it as:
<@prg>fmpp -C /home/me/sample-project/config.fmpp@prg>or since <@c>config.fmpp@c> is the default configuration file name, you can simply issue:
<@prg>fmpp -C /home/me/sample-project@prg>or if you are in the same directory as <@c>config.fmpp@c> then just issue:
<@prg>fmpp@prg>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:
<@prg>fmpp -C /home/me/sample-project/config.fmpp -O other/destination@prg>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!
@sect> <@sect title="Command-line argument syntax primer" anchor="cmdln_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 <@a href="#fmpp_cmdline">skip to the next section@a>.
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:
<@prg>test -f t 1.txt 2.txt@prg>as the executable name is <@c>test@>, and the list of arguments is:
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:
<@prg>test -f t -D "x:1, y:2"@prg>Here, the list of arguments will be:
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 (<@c>'@c>) instead of quotation marks. In Windows/DOS shell you can use quotation marks (<@c>"@c>) only.
You have to quote the argument if you use characters that are reserved by the shell for other purposes. For example <@c>>@> and <@c>|@> is reserved in most shells. <@c>&@>, <@c>;@> and <@c>(@> is reserved in sh. Also, if you use an UN*X shell, sometimes you need to quote arguments that contain <@c>*@c>, <@c>?@c> or <@c>~@c>, 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:
<@prg>test -D"x:1, y:2"@prg>will be interpreted as:
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:
<@prg>test -D"x:'red led', y:2"@prg>or (will not work in Windows/DOS shell!):
<@prg>test -D'x:"red led", y:2'@prg> @sect> <@sect title="FMPP command-line argument syntax" anchor="fmpp_cmdline">The FMPP command-line tool uses similar argument syntax to usual UN*X command-line tools, such as <@c>ls@>. UN*X users should be able to use the tool even without reading this section.
This is a possible FMPP command-line:
<@prg>fmpp -C mycfg.fmpp -q --case-sensitive products index.html@prg>The FMPP command-line tool interprets command-line arguments as either:
An option always starts with dash (<@c>-@c>), or with double dash. (<@c>--@c>), followed by the name of the option (e.g. <@c>q@c>, <@c>C@c>, <@c>case-sensitive@c>). If the option requires parameter, then it is followed by the parameter to the option (as <@c>mycfg.fmpp@c> in <@c>-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 <@c>-q@c> and <@c>--quiet@c>). Short form options can be grouped together, for example you can write
<@c>-qxs@c>
instead of
<@c>-q -x -s@c>
Some options require a parameter. To demonstrate the syntactical rules with examples, here are the valid ways to give <@c>cp852@c> as parameter to option <@c>-E@c> alias <@c>--source-encoding@c>:
I didn't show the combinations like <@c>-E="cp852"@c>, as the usage of quotation marks is shell dependent. See <@a href="#cmdln_syntax_primer">the section about using the command-line@a> 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>-c@c> and <@c>-C@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:
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, <@c>--@> followed by no option name, to indicate that all subsequent arguments are non-options:
<@prg> fmpp -Cmycfg.fmpp -- -this-is-a-non-option @prg> @sect> <@sect title="Invoking the command-line tool">The command-line tool can be invoked with the <@c>fmpp@c> shell script (<@fmppPath path="bin/fmpp" /> or <@fmppPath path="bin/fmpp.bat" />), assuming you have <@a href="installing.html#commandLineTool">installed it@a> 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 <@c>-h@c> it just prints help.)
@sect> <@sect title="Specifying settings in the command-line">Most command-line options specify <@a href="settings.html">FMPP settings@a>. The option name is the name of the setting, but with lower case dashed form (as <@c>source-root@c>) instead of the usual mixed case form (as <@c>sourceRoot@c>). The value of the setting is given as the parameter of the option. The <@a href="configfile.html#configurationBase">configuration base@a> for the values is the current working directory (i.e. the directory you are in).
Example: Runs a processing session with <@s>sourceRoot@s> set to <@c>src@c> and <@s>outputRoot@s> set to <@c>out@c> (so this will process all files in the <@c>src@c> directory, and store the output in the <@c>out@c> directory):
<@prg>fmpp --source-root src --output-root out@prg>For the most frequently used settings there is short option name too. For example, this is equivalent with the previous example:
<@prg>fmpp -S src -O out@prg>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 <@a href="tdd.html#modes">hash mode TDD@a>, and for sequence setting it is sequence mode TDD, so the brackets should be omitted. For example:
<@prg>fmpp -S src -O out -D "online:false, tdd(data/style.tdd)" --replaceExtensions "ftl, html"@prg>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 <@s>quiet@s>) are specified with parameterless options:
Command-line option | Meaning | |
---|---|---|
Setting name | Value | |
<@c>-s@c>, <@c>--stop-on-error@c> | <@s>stopOnError@s> | <@c>true@c> |
<@c>-c@c>, <@c>--continue-on-error@c> | <@s>stopOnError@s> | <@c>false@c> |
<@c>--case-sensitive@c> | <@s>caseSensitive@s> | <@c>true@c> |
<@c>--ignore-case@c> | <@s>caseSensitive@s> | <@c>false@c> |
<@c>--ignore-cvs-files@c> | <@s>ignoreCvsFiles@s> | <@c>true@c> |
<@c>--dont-ignore-cvs-files@c> | <@s>ignoreCvsFiles@s> | <@c>false@c> |
<@c>--ignore-svn-files@c> | <@s>ignoreSvnFiles@s> | <@c>true@c> |
<@c>--dont-ignore-svn-files@c> | <@s>ignoreSvnFiles@s> | <@c>false@c> |
<@c>--ignore-temporary-files@c> | <@s>ignoreTemporaryFiles@s> | <@c>true@c> |
<@c>--dont-ignore-temporary-files@c> | <@s>ignoreTemporaryFiles@s> | <@c>false@c> |
<@c>--print-stack-trace@c> | <@s>printStackTrace@s> | <@c>true@c> |
<@c>--dont-print-stack-trace@c> | <@s>printStackTrace@s> | <@c>false@c> |
<@c>-x@c>, <@c>--expert@c> | <@s>expert@s> | <@c>true@c> |
<@c>--not-expert@c> | <@s>expert@s> | <@c>false@c> |
<@c>--append-log-file@c> | <@s>appendLogFile@s> | <@c>true@c> |
<@c>--dont-append-log-file@c> | <@s>appendLogFile@s> | <@c>false@c> |
<@c>-q@c>, <@c>--quiet@c> | <@s>quiet@s> | <@c>true@c> |
<@c>-v@c>, <@c>--verbose@c> | <@s>quiet@s> | <@c>false@c> |
<@c>-Q@c>, <@c>--really-quiet@c> | <@s>quiet@s> | <@c>reallyQuiet@c> |
Example:
<@prg>fmpp -S src -O out --dont-ignore-cvs-files -cqx@prg>where the last few options mean: <@s>ignoreCvsFiles@s> is <@c>false@c>, <@s>stopOnError@s> is <@c>false@c>, <@s>quiet@s> is <@c>true@c>, <@s>expert@s> is <@c>true@c>.
The value of the <@s>sources@s> setting can be given as the non-option arguments to the tool. For example, to process only files <@c>index.html@c> and directory <@c>products@c> of the source root:
<@prg>fmpp -S src -O out index.html products@prg>Notes for Windows users:
With option <@c>--configuration@c> or <@c>-C@c> you can load a configuration file. As you may know it <@a href="configfile.html">from the chapter about configuration files@a>, it is enough to give the directory of the configuration file, if the file uses one of the standard names. Example:
<@prg>fmpp -C works/project1@prg>If you don't use option <@c>--configuration@c>/<@c>-C@c>, <@c>fmpp@c> 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 <@c>--configuration@c>/<@c>-C@c> with <@c>none@c> parameter (as <@c>-C none@c>).
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 <@s>data@s> specified in the configuration file, or if variable <@c>online@c> was already created there then replace its value:
<@prg>fmpp -C works/project1 -D online:true@prg>Options <@c>configurationBase@c> and <@c>inheritConfiguration@c> can be used to emulate that settings <@s>configurationBase@s> and <@s>inheritConfiguration@s> are present with the given value in the configuration file.
@sect> <@sect title="Global options" anchor="fmpprc">The default of some settings that can't influence the output files can be set in a configuration file called <@c>.fmpprc@c>. This file is searched in these directories, in this order:
Only the first <@c>.fmpprc@c> found will be loaded.
The settings you can set in the <@c>.fmpprc@c> are:
All <@a href="settings.html#logging">logging related settings@a> are supported.
All recommended <@s>echoFormat@s>-s are supported, but <@c>verbose@c> is the same as <@c>normal@c>. It depends on the terminal implementation you use, but <@c>terse@c> echo format can substantially speed up the processing session if you have many files.
All <@s>quiet@s> values are supported.
@sect> <@sect title="List of all options">The complete list of command-line options with brief description is included further below in the output of <@c>fmpp -h@c>. Almost all options correspond to FMPP settings; see the <@a href="settings.html">complete descriptions of FMPP settings here@a>.
${pp.loadData('eval', ' StringWriter sw = new StringWriter(); PrintWriter pw = new PrintWriter(sw); r = fmpp.tools.CommandLine.execute( new String[]{"-h", "--columns", "110"}, pw, new PrintWriter(fmpp.util.NullWriter.INSTANCE)); if (r != 0) { throw new Exception("CommandLine.execute exited with code " + r); } pw.close(); return sw.toString(); ')}@sect> @page>