Views
Tool interface guidelines
From MCRL2
This page describes the guidelines for the interfaces of tools.
To ease adherence to these guidelines, it is mandatory to use the mCRL2 command line interface library.
Contents |
Command line interface
The command line interface of each tool should adhere to the following guidelines.
Options
Options can be provided in the following two forms:
- a long form (mandatory): '--option', where option is a string of the form '[a-z][a-z0-9\-]*';
- a short form (strongly recommended): '-o', where o is a character of the form '[a-zA-Z0-9]'.
Furthermore, the options should adhere to the following:
- Options may take arguments, either mandatory or optionally:
- the mandatory argument of an option must be accepted as '--option=ARG' for long forms and as '-oARG' or '-o␣ARG' for short forms, where ␣ stands for one or more whitespace characters.
- the optional argument of an option must be accepted as '--option=ARG' for long forms and as '-oARG' for short forms.
- Short forms of options may be concatenated, where the last option in the chain may take an argument. For instance, given options '-o' and '-p' where the latter takes an argument 'ARG', the chain '-opARG' is valid (but '-pARGo' is not).
- Users should not be allowed to specify an option more than once.
- Every tool should provide the following standard options:
-q, --quiet do not display warning messages
-v, --verbose display short intermediate messages
-d, --debug display detailed intermediate messages
-h, --help display help information
--version display version information
- Every tool that utilises rewriting should additionally provide the following option:
-rNAME, --rewriter=NAME use rewrite strategy NAME:
'jitty' for jitty rewriting (default),
'jittyp' for jitty rewriting with prover,
'jittyc' for compiled jitty rewriting,
'inner' for innermost rewriting,
'innerp' for innermost rewriting with prover, or
'innerc' for compiled innermost rewriting,
Input and output files
Some tools require input and/or output files; these include transformation and conversion tools (but not GUI tools). The most important input file and the most important output file (if any) should be accepted as optional command line arguments, in the following way:
- the first argument is treated as the input file, the second argument is treated as the output file (if present);
- when the input file is not supplied, input is read from stdin;
- when the output file is not supplied, output is written to stdout.
It is only allowed to deviate from these rules if it is technically infeasible to read from stdin or write to stdout.
Furthermore, the following features are not allowed:
- designate the input file without its extension, e.g.
- wrong: mcrl22lps abp
- right: mcrl22lps abp.mcrl2
- option '-' to indicate input should be read from stdin, e.g.
- wrong: ... | lpsrewr - abp.rewr.lps
- right: ... | lpsrewr > abp.rewr.lps
Exit codes
The command line interface should have an exit code of 0 upon successful termination, and non-zero upon unsuccessful termination. Success here means that during executing of the tool, no errors have occurred.
Handling interface errors
When parsing the command line, errors may be encountered, for instance due to an invalid number of arguments, unrecognised options or illegal arguments to options. When such errors are encountered the following actions should be taken, depending on whether the tool has a GUI or not:
A tool that does not have a GUI should print the following message to stderr :
TOOL: ERROR_MSG Try `TOOL --help' for more information.
where:
- TOOL stands for the name of the tool that the user called, i.e. argv[0];
- ERROR_MSG stands for the error message corresponding to the first error that is encountered when parsing the command line.
After that, the tool should terminate with exit code 1.
A tool that has a GUI should show an error message dialog containing the error message corresponding to the first error that is encountered when parsing the command line.
Exceptions
It is not allowed for tools to pass unhandled exceptions to the operating system.
Graphical user interface
Every tool that has a graphical user interface tool should provide a help menu containing the following menu items:
- Contents: a link to the tool user manual;
- About: a message dialog containing the tool version information
Use of the mcrl2::utilities::wx::tool class takes care of both by default. This class must be used for all wxWidgets tools to get the correct command line interface behaviour.
Exceptions
It is not allowed for tools to pass unhandled exceptions to the operating system.
Help and version information
Tool help and version information should adhere to the following guidelines.
Help information
Help information should be provided by the command line option -h, --help.
It basically is a condensed version of the tool user manual in plain text with a maximum width of 80 characters. It should consist of the following elements (in that order):
- Synopsis: the line
Usage: TOOL [OPTION]... ARGS
- where:
- TOOL stands for the name of the tool that the user called, i.e. argv[0];
- ARGS stands for the arguments the tool can take, where optional arguments are typeset in square brackets '[' and ']'.
- Short description on the workings of the tool, including the effects on the arguments (not the options).
- Options: a list of all non-standard command line options. The list should be sorted alphabetically on short option, or long option when there is no short option. It should be formatted as follows:
Options:
-o, --option description of the option
-oFOO, --option=FOO description of the option and the possible values of
mandatory argument FOO
-o[FOO], --option[=FOO] description of the option and the possible values of
optional argument FOO, including an indication of
the default value
--ridiculously-long-option
description of the option
Below the list of all non-standard options, the list of standard options should be printed as a separate paragraph, formatted as follows:
Standard options:
-q, --quiet do not display warning messages
-v, --verbose display short intermediate messages
-d, --debug display detailed intermediate messages
-h, --help display help information
--version display version information
- Known issues (if any): a paragraph containing a short description of known issues, formatted as follows:
Known issues: Short description of the issue.
- Reporting bugs: a paragraph consisting of the single line
Report bugs at <http://www.mcrl2.org/issuetracker>.
- See also: a paragraph consisting of the single line
See also the manual at <http://www.mcrl2.org/wiki/index.php/TOOL>.
where TOOL stands for the official name of the tool.
Version information
Version information should be provided by:
- the command line option --version;
- the About menu item.
It should contain the following text:
TOOL_NAME mCRL2 toolset MCRL2_VERSION (revision MCRL2_REVISION) Copyright (C) MCRL2_COPYRIGHT_YEAR Technische Universiteit Eindhoven. This is free software. You may redistribute copies of it under the terms of the Boost Software License <http://www.boost.org/LICENSE_1_0.txt>. There is NO WARRANTY, to the extent permitted by law. Written by TOOL_AUTHOR.
where:
- TOOL_NAME stands for the official name of the tool;
- MCRL2_VERSION stands for the toolset version;
- MCRL2_REVISION stands for the toolset revision;
- MCRL2_COPYRIGHT_YEAR stands for the toolset copyright year;
- TOOL_AUTHOR stands for the author(s) of the tool.
Copyright © 2005-2012 Technische Universiteit Eindhoven.
