52 lines
2.4 KiB
Text
52 lines
2.4 KiB
Text
This directory contains the source of some command-line tools that
|
|
expose some of Spot's algorithms to Unix users.
|
|
|
|
Man pages are generated from the --help output of each tool,
|
|
supplemented by any text in the man/*.x files. Usually the extra text
|
|
contains either some bibliographical references, some formal
|
|
definitions or some examples that are too long for --help. Having a
|
|
few short examples at the end of --help is good.
|
|
|
|
This directory also builds some non-installed binaries, like spot-x,
|
|
whose purpose is just to generate a man-page with the same format as
|
|
the other man pages (this includes keeping the version number
|
|
up-to-date).
|
|
|
|
There is also a script called 'options.py' that summerizes how the
|
|
different short options are used among the tools.
|
|
|
|
Routines that are shared by multiple command-line tools are stored in
|
|
files called common_*.{cc,hh}.
|
|
|
|
|
|
Recommendations when adding new tools or features:
|
|
--------------------------------------------------
|
|
|
|
- Tools should be designed to work on multiple inputs (e.g., read
|
|
different outputs from multiple files, and accept many inputs from
|
|
the same file, including stdin). They should also all be designed
|
|
to produce several outputs, usually one per input. This way they
|
|
can be piped one onto the other easily.
|
|
|
|
- When naming an option, seek inspiration from the POSIX standard, or
|
|
from GNU extensions. For instance ltlfilt and autfilt both have a
|
|
-v option to invert the filter; this is inspired from grep's -v
|
|
option. The long version of this option (--invert-match) is also
|
|
the same as in grep.
|
|
|
|
- When adding a new option, implement only the --long-option by
|
|
default. Do not add a short version unless
|
|
(1) you are sure it will be frequently used interactively
|
|
(if it is only used in scripts, then a long option is enough)
|
|
(2) this option can be shared by multiple tools.
|
|
|
|
- As much as possible, use the same option names across tools. Use
|
|
the script options.py in this directory to check what short options
|
|
are used. It's OK if the same short option correspond to different
|
|
long names in the various tools, as long as the intent is similar.
|
|
For instance -n has different long options depending on the tool:
|
|
autfilt -n N means --max-count=N
|
|
randltl -n N means --formulas=N
|
|
randaut -n N means --automata=N
|
|
but in all cases, the intent is to specify the number of items
|
|
to output.
|