The Command-line Tool
The Command-line Tool |
| |
| ||
| ||
| ||
| ||
| ||
Page contents
|
|
|
|
|
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:
| | | |
|
| | |
| | |
as the executable name is test, and the list of arguments is:
-f
t
1.txt
2.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:
| | | |
|
| | |
| | |
Here, the list of arguments will be:
-f
t
-D
x: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:
| | | |
|
| | |
| | |
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:
| | | |
|
| | |
| | |
or (will not work in Windows/DOS shell!):
| | | |
|
| | |
| | |
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:
| | | |
|
| | |
| | |
The FMPP command-line tool interprets command-line arguments as either:
-q, --case-sensitive and -C mycfg.fmpp
products and index.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 -E require 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.html
products index.html -C mycfg.fmpp -q
products -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:
| | | |
|
| | |
| | |
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.)
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):
| | | |
|
| | |
| | |
For the most frequently used settings there is short option name too. For example, this is equivalent with the previous example:
| | | |
|
| | |
| | |
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:
| | | |
|
| | |
| | |
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
|
--snip
| snip
| true
|
--dont-snip
| snip
| 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:
| | | |
|
| | |
| | |
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:
| | | |
|
| | |
| | |
Notes for Windows users:
/) instead of backslash (\) anywhere.* and ? in paths (except in settings that explicitly want path patterns, e.g. modes)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:
| | | |
|
| | |
| | |
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:
| | | |
|
| | |
| | |
Options configurationBase and inheritConfiguration can be used to emulate that settings configurationBase and inheritConfiguration are present with the given value in the configuration file.
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:
HOME environment variable.FMPP_HOME environment 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:
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.
These are the settings that are not (directly) for specifying FMPP settings:
-C, --configuration-h, --help--long-help--version--print-localesThis is what FMPP prints with -h:
Typical usages:
fmpp -C configfile
fmpp -S sourcedir -O outputdir
fmpp sourcefile -o outputfile
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.
--append-log-file If the log file already exists, it will
be continuted, instead of restarting
it.
--borders=<SEQ> The list of TDD function calls that
choose header and footer for
templates, e.g.:
-M 'border("<#escape x as x?html>",
"</#escape>", *.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. Defaults to 80.
--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 template
will see. <TDD> is the Textual Data
Definition, e.g.:
-D "properties(style.properties),
onLine:true"
Note that paths like
"style.properties" are relatve 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-snip Don't snip (--8<--) long messages.
--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 value of the option
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-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
precednece.
-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 Prints long help.
-M, --modes=<SEQ> The list of TDD function calls that
choose the file processing mode, e.g.:
-M "ignore(**/tmp/), execute(**/*.htm,
**/*.html), copy(**/*)"
--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".
--print-locales Prints the locale codes that Java
platform knows.
-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.
--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 Snip (--8<--) long messages. This is the
default.
--tag-syntax=<WHAT> Sets the tag syntax for templates that
doesn't start with the ftl directive.
Possible values are: angleBracket,
squareBracket, autoDetect. The default
depends on the FreeMarker version. 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 used to show time.
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 of the above command-line options directly correspond to FMPP settings.
The detailed description of the FMPP settings is in the FMPP Manual.
|
|
|
|
|
|
||
  |
