Command Line Guidelines
The purpose of this document is to provide guidelines for developing Trainz-related command-line utilities with the intention of creating a standardised, easy-to-use command set and reliable machine-parsing of tool output.
Contents |
Invoking the Tool
Paths and the working directory
Trainz executables generally require access to the Trainz Asset Database. On start-up, the tool will attempt to open the TAD relative to the executable’s binary location. This means that the tool is intrinsically linked to a single Trainz installation, and that the tool cannot be moved relative to the Trainz installation location. The Trainz installation can be safely moved as a whole without breaking the relative mapping.
The working directory in which the tool is executed should be within the Trainz installation. If no specific working directory is required, the tool should be started with the main Trainz program directory as its working directory.
Command syntax
Where a tool is capable of performing multiple functions, the first parameter to the tool determines which function the tool shall perform. This ‘command’ parameter is case insensitive, and is formed from English alphabet characters and the hyphen (‘-‘) character only. No other parameters (eg. options) may be present prior to the command parameter.
If the command parameter is not recognised, the tool shall report an error and no command will be performed. Additionally, if a syntax error is detected while parsing parameters, the tool shall report an error and no command will be performed.
If a tool which accepts parameters is executed with no parameters, a help screen will be output to stdout detailing the usage of the tool. The help screen is not expected to comply with the guidelines for machine-parseable output described in this document.
Where a tool accepts a command parameter, the following commands shall be implemented:
- "help" – The tool shall respond by displaying the help screen as described above.
- "version" – The tool shall respond by display the tool name and build version in a machine-parseable fashion.
- "echo" – The tool shall respond by outputting a diagnostic line echoing any further command parameters. This is intended for use in synchronising batch command output.
Shell quoting
Command shells (and some system functions which execute shell commands) reserve certain symbols for special interpretation prior to passing the text as parameters to the tool. Because this is performed by the shell itself, the exact functionality of this is not possible in a generic manner, however some common functionality exists between many popular shells and some common pitfalls are described here.
Information given elsewhere in this document and within the tool-specific documentation and inline help refers to the format that the tool expects after any command-shell text processing occurs. Where example usages are given, the examples will be quoted in a way that is easily readable and relevant to the more popular shells.
Where a single parameter contains whitespace or any unusual characters, that parameter will generally require quoting so that the shell does not break it into multiple parameters, or perform text processing. Quoting rules vary between shells, but for many strings, simply wrapping the literal text within double quotes (") is sufficient. It is good practice to quote every filepath parameter.
KUID parameters also contain several unusual characters. Many shells will treat angle brackets (‘<’ and ‘>’) as pipe commands. It is advisable to properly quote all KUID parameters.
Where a parameter includes a quote symbol in its literal text, some shell-specific escaping may be necessary when quoting the parameter. Techniques for this are beyond the scope of this document to describe.
KUID parameters
In order to support legacy content, a number of invalid KUID encodings are accepted by the Trainz config.txt parser. These encodings should not be used, as they are not supported and may not work as expected. The valid encodings for KUID values are:
- <KUID:123:456> for standard KUIDs.
- <KUID2:123:456:7> for versioned KUIDs.
Items of note:
- The surrounding angle braces form a mandatory part of the KUID encoding.
- The ‘2’ in ‘KUID2’ is mandatory if a version field is to be included.
- Colons are required between each field of the KUID.
- Spaces and other extra characters are not permitted within a KUID.
Versions between 0 and 127 inclusive are valid. Version 0 of a KUID2 represents an identical value to the same KUID without version encoding.
Path parameters
Parameters representing file or folder paths may be specified as either fully qualified (absolute) paths, or as relative paths. Relative paths are parsed relative to the working directory in which the tool started execution. (Internally, the tools will generally change the working directory to the Trainz program directory, however this shall not affect the way in which relative paths are parsed.)
Paths should be valid for the operating system in use. In general, it is safest to use forward slashes ‘/’ for path separators except where the operating system mandates a backwards slash ‘\’ (eg. for windows network names or drive names.)
Paths shall be encoded in the native text codepage of the host OS, not UTF-8 (unless that is what the OS uses natively.)
Batch mode
As the TAD connection process currently requires one or more seconds of CPU time, it is expected that Trainz tools will launch too slowly for large numbers of repeated calls to be viable. With this in mind, tools which can reasonably expect to be called repeatedly should implement "batch mode". Where implemented, batch mode should follow the implementation described here.
When the caller wishes to use batch mode, the tool is launched without a command, but instead will have as its only parameter a filepath prefixed by the ‘@’ character. The tool will consider this an instruction to load from the specified filepath as a UTF-8 encoded text file containing a series of instruction lines.
The tool will execute each line from the batch file in sequence as a new command. The first word of each line should be the command for the tool to run, subsequent words form the parameter. The tool will implement basic quoting support to allow for the specification of filepaths containing with spaces, etc.
Empty lines will be silently ignored and will not cause the display of the help text. Syntax or execution errors will cause the line in question to fail as per normal, however the batch file as a whole will continue to be executed.
Return value
Tools shall return a zero exit code if all operations were performed successfully. Tools shall return a non-zero exit code if one or more operations failed for any reason.
Logging
Success, error, warning, and diagnostic messages will be logged to stdout as detailed below. No additional logging will be performed, and no logfiles will be generated by the tool.
Standard Output
All output from the program will be provided in a minimal machine-parseable format. It is intended that both users and programs may execute tools and parse the results, thus the results must be meaningful but not overly verbose.
All output messages from a tool will be written to stdout. The stderr mechanism does not provide significant benefits to this implementation and may make synchronisation more difficult.
Line prompts
Each line of output shall begin with a prompt character. The prompt determines the meaning of the line from the perspective of an automated parser. If an unknown prompt is output, the line should be ignored by automated parsers. Valid prompts are as follows:
- ‘+’ Lines starting with the plus symbol are the result of a successful command execution. There may be more than one success line per command execution.
- ‘-’ Lines starting with the minus symbol are the result of a failed command execution. There may be more than one failure line per command execution.
- ‘!’ Lines starting with the exclamation symbol are warnings related to a command execution (whether the execution is successful or failed.)
- ‘:’ Lines starting with the colon symbol are diagnostic or comment lines, and should not be machine parsed.
String data
Since string quoting may be awkward to parse (both for humans and programmers) it is considered preferable to avoid the need where possible. To this end, literal string output shall be returned at the end of an output line after all other relevant information. Where possible, quoting and escaping of the string text will be avoided. The location of the first character of the string within the output line shall be clearly defined.
Literal string data shall be parsed as UTF-8 encoded text, regardless of the OS conventions for strings.
Consistency
All output messages should follow a consistent format, as detailed in the tool-specific documentation or inline help. When new versions of tools are released, existing fields may be upgraded to contain new values, however new fields shall not be added within existing command output.
It is feasible that new fields could be safely added to the end of existing command output, as long as the command output did not contain string data (as that must be at the end of the line.) Addition of new fields to the end of an existing data line is acceptable given that the format and order of existing fields is maintained. Fields are separated by one or more space characters, unless otherwise specified.
Where further output is required that can not be fit into an existing design, a new command should be added to the tool and the old command left untouched. Generally, commands should perform very specific function such that significant extension is not necessary.
