P18 Internationalizing Preprocessor

Documentation

Previous  Next  .  Contents
About  .  Documentation  .  License   .  Download

Commands

The P18 preprocessor can be controlled using a simple command language. When invoked with no arguments, P18 starts in command mode, i.e. it acts as a simple command interpreter. Commands may also be specified using the -f commandline option, causing P18 to read commands from the specified file (see Invocation).

The command interpreter recognizes the following commands:

Command   Description
exit   Terminate the command interpreter, passing an optional exit status to the caller.
quit   Terminate the command interpreter.
option   Set/get a P18 configuration option.
config   Read a P18 configuration file (see Configuration).
define   Define a P18 variable/macro.
undef   Un-define a P18 variable/macro.
source   Read P18 commands from a file.
run   Run the preprocessor.
locate   Locate messages in input files.
scan   Scan input files for new messages.
db   Edit the translation database.

All lines with a hash mark ("#") as the first non-whitespace character are ignored. Empty lines are also ignored.

Arguments passed to the commands are delimited by whitespace characters. If an argument includes whitespace characters, it must be quoted. There are two flavours of quoting:

Single character quoting and string quoting can be mixed.

All option arguments passed to the commands start with a single hyphen. All option arguments (if any) must preceed all non-option arguments. The end of the option arguments may be signaled using a double hyphen, this is useful if a non-option argument starts with a hyphen. Terminating the list of option arguments with a double hyphen works for all commands, even those that don't take any option arguments.

exit

Synopsis:
exit [exit-code]

Description:
Terminate the P18 command interpreter. It is possible to specify an exit status code using the optional parameter exit-code. The exit code is interpreted as an integer number and passed to the libc `exit()' function. Special values for exit-code are "SUCCESS" or "EXIT_SUCCESS" for successful termination and "FAIL", "FAILURE", or "EXIT_FAILURE" for unsuccessful termination. If no exit code is specified, the command assumes successful termination.

quit

Synopsis:
quit

Description:
Terminate the P18 command interpreter.

option

Synopsis:
(a) option name [value]
(b) option ! name
(c) option

Description:
Manage options. For variants (a) and (b), name may specify a global option or a per-input option. To specify a per-input option, prefix the option name with the input name and a dot. For example foo.bar selects the option "bar" of the input "foo".

Use variant (a) to set the option to the specified value. If the value parameter is omitted, the option is set to an empty string (which is interpreted as TRUE for boolean options).

Use variant (b) to un-set an option.

Varant (c) lists all defined options and values.

config

Synopsis:
config filename

Description:
Read the configuration file filename. The configuration file syntax is specified in section Configuration.

define

Synopsis:
define [name [value]]

Description:
Define the variable/macro name to the specified value. If you want to define the variable/macro only for a single input, prefix the name of the variable/macro with the name of the input and a dot, example:

define foo.bar X

This defines the variable/macro "bar" for the input "foo". If value is omitted, the variable is defined to an empty string. If the command is called without arguments, a lists of all defined variables is printed.

undef

Synopsis:
undef [!] name

Description:
Undefine the variable/macro name. The command removes all definitions associated with name (i.e. name and all variables with the prefix "name$"). If the first parameter passed to the command is an exclamation mark, the command removes only the variable name, leaving the associated variables there.

If you want to remove a variable defined only for a single input, use the name of the input and a dot as a prefix.

source

Synopsis:
source filename

Description:
Process the commands from the file filename as if they were typed on the command prompt.

run

Synopsis:
run [input-list]

Description:
Run the preprocessor on the specified list of input folders. The input folders are specified as a whitespace separated list of input names. If the command is invoked without arguments, all specified input folders are processed.

If input files and/or folders were specified on the P18 invocation commandline, these files are available through an input object name ARGS.

locate

Synopsis:
locate [options] [input-list]

Description:
List all appearances of messages matching the specified pattern or message ID in the specified list of inputs. If the input-list is empty, all configured inputs are scanned.

Options:
-p pattern
  Locate messages matching the specified regular expression pattern.
-i id
  Locate messages with the specified message ID. It is possible to specify muliple message IDs.
-l language
  Locate messages of the specified language language.
-t type
  Locate messages of the specified type type.
-o output-file
  Specify an output file for the report. The default is the standard output.
-a
  Approximate matching for message IDs. Note that the -a flag has no effect on regex-matching.

scan

Synopsis:
scan [options] [input-list]

Description:
Scan all specified inputs for new messages. If the specified input list is empty, all configured inputs are scanned. If approximate matching is specified (-a option), all unknown messages are compared to all known messages using a fuzz-factor determined from the length of the message string. If the new message string is similar to an existing message, a warning is given. If the new message is not similar to an existing message, it is added to the temporary message set. Note that unless the -x option is specified, the current translation database is not modified by the command.

Options:
-l language
  Specify the language to scan for. It is an error of no language is specified.
-a
  Perform approximate matching. This is expensive but may be useful for locating typos.
-c commands-file
  Specify a filename for a commands file. The commands file contains a list of P18 commands for adding the new messages to the message database. The commands from the commands file may then by executed using the "source" command.
-x
  Executive scan. All messages found are inserted into the translation dictionary.
-o output-file
  Specify a filename for the diagnostic output messages of the command. The default is the standard output.
-q
  Quiet operation.

db

Synopsis:
db command [options]

Description:
This command is the general translation database management command. It offers a list of subcommands. The following subcommands are recognized:
Command   Description
db read   Read the translation database from a specified file.
db write   Write the translation database to a specified file.
db clear   Clear the contents of the database.
db new   Add a new message to the database (create a new message set).
db export   Write a translation file.
db import   Import a translation file.

db read

Synopsis:
db read [options] filename

Description:
Read the translation database from the specified file. If the current translation table is not empty, the translations from the specified file are merged into the translation table.

Options:
-c
  Clear the local database before reading the new database.
-m
  Merge the specified database filename into the local database. The database ID of the specified database is ignored.

db write

Synopsis:
db write filename

Description:
Write the translation database to the specified file.

db clear

Synopsis:
db clear

Description:
Clear the translation database.

db new

Synopsis:
db new [options] message

Description:
Insert a new message into the translation database. The new message is not associated with an existing message set, i.e. the new message is not the translation of a message already known. If no unique ID for the new message set is specified (and the -n option is not given), the command will create a unique ID for the new message set.

Options:
-l language
  Specify the language of the new message. This option is required.
-n
  Do not create a unique ID for the new message set.
-u unique-id
  Specify the unique ID for the new message set.
-t type
  Specify the message type of the new message. The default is "TEXT".

db export

Synopsis:
db export [options] filename

Description:
Export a translation file. A translation file may be used to create a translation from one language to another. The translation file is written to the file filename. The command selects all message sets from the current translation database, where at least one of the specified languages is present. Of these message sets, only those are exported where at least one of the specified languages is missing. You can force the export of all selected message sets by specifying the -a option.

Options:
-l language
  Specify a language that should be exported. Multiple languages may be specified.
-L language-list
  Specify a comma-separated list of languages. Specifying muliple languages in a list is equivalent to specifying these languages using muliple -l options.
-k language
  Specify an extra language that should be exported. Extra languages appear in the exported message sets, but have no effect on the decision which message sets are exported. The -k option is typically used to specify localized variants of languages specified through the -l or -L options. Multiple extra languages may be specified.
-K language-list
  Specify a comma-separated list of extra languages. Specifying muliple extra languages in a list is equivalent to specifying these languages using muliple -k options.
-a
  Export all selected message sets, i.e. all message sets where at least one of the specified languages is present.
-f
  Forced export, i.e. message characters that can't be encoded using the translation file encoding are not treated as errors.
-e encoding
  Specify the translation file encoding. The encoding is specified using a well-known name for the encoding (e.g. Latin 1 may be specified as ``ISO-8859-1'' or ``IBM819'' or simply ``Latin1'' or ``l1''), character case is insignificant. The specified encoding has to be a roughly ASCII compatible encoding (i.e. use the ASCII character repertoire). The default is ISO-8859-1.
-t type
  Specify a type restriction. If this option is specified, a message set is exported only if a message message belonging to one of the specified languages or extra languages is of the specified type.

db import

Synopsis:
db import [options] filename

Description:
Import a translation file. The translations in the specify file are merged into the current translation database.

Options:
-s
  Strict import. If a message in the translation file has a counterpart in the current translation database, the messages have to match.
-f
  Forced import. If a message in the translation file differs from its counterpart in the current database, the message in the current database is replaced and an info message is issued.
-q
  Quiet operation. When used in combination with the -f option, info messages about replaced messages are suppressed.


Previous  Next  .  Contents
About  .  Documentation  .  License   .  Download