Command Line Interface

General Arguments

  • --help prints the usage with all available arguments

  • --version prints the version

  • --license prints the license

Subcommands

Dim supports different subcommands:

dim <subcommand> <parameters>

All available subcommands with the additional parameters are described below.

check

This checks all input files if they are valid, e.g. if the refs can be resolved.

-i FILENAME, --input FILENAME

-i specifies a requirements file or config file.

Usually requirements are loaded via a config file which specifies the category and the originator for the requirements. If a requirements file is loaded directly, the category is set to unspecified and the originator to an empty string.

Example:

dim check -i project/reqs/config.dim

-a FILENAME, --attributes FILENAME

-a specifies a custom attributes file.

An attributes files is usually specified in the config file. Loading a requirements file with custom attributes directly would lead to an error. To avoid that, the attributes file can also be specified on the command line.

If the config file has a reference to custom attributes AND an attributes file is specified using this command line parameter, then attributes from both references are taken into consideration. If the same attribute is present in both files, the attributes loaded from config file will be prioritized.

If a single requirements file without this parameter is loaded, then Dim searches for a file named attributes.dim recursively, starting from location of the requirements file till the root directory is reached. If such a file is found, then the custom attributes are loaded from that file.

--allow-missing

When loading only a part of the requirements files, references may not be resolvable, which would lead to an error. To suppress them, use --allow-missing. This is only for developing purposes. An official export must be done without this parameter.

While formatting, this parameter is automatically set.

--no-check-enclosed

When Dim contains enclosed files, it checks for the presence of those files. A missing file leads to an error. To skip the enclosed files check, use --no-check-enclosed.

--silent

When this option is set, Dim will not print any info logs on the screen. Errors and warnings will still be printed to inform the user what went wrong during the operations.

format

This subcommand formats requirements files. Dim sets the allow-missing parameter automatically when formatting the documents, which means Dim will not warn about missing references.

format implicitly executes the consistency check. All check parameters can also be used for format.

All existing YAML comments are removed during formatting.

--output-format FORMAT

  • in-place: By default, requirements files are changed in-place.

  • extra: To create extra files next to the original files (with the ending .formatted) use this output format.

  • check-only: Checks the files without changing them. If the formatting is not correct, Dim exists with an exit code != 0.

  • stdout: This is to support the inline formatting in IDEs. Any IDE which works with STDIN and STDOUT can use this flag to support code formatting within the IDE.

More details about stdout:

It is assumed that the requirements file is valid. As binary input is read from STDIN, this output format skips the check for enclosed files and refs. The formatted output will be sent to STDOUT, from where the IDE is supposed to read.

When output format is set to stdout, Dim automatically sets the following parameters:

  • allow-missing

  • no-check-enclosed

  • silent

Config files are not supported.

The following example shows how to use this feature with Vim, assuming that the vim-autoformat plugin is already installed:

  • First, add this to the .vimrc file:

    let g:formatdef_dimtool = '"dim format --output-format stdout"'
let g:formatters_dim = ['dimtool']

  • After the file has been loaded into Vim, format the file like this:

    :Autoformat dim

export

Requirements can be exported to different formats. The output can be made available to other tools or third-parties.

export implicitly executes the consistency check. All check parameters can also be used for export.

-o FOLDER --output FOLDER

Specifies the output folder. Every document with its enclosed files will be exported to a subfolder. If the folders do not exist, they will be created. Existing files will be overwritten.

-f FORMAT --format FORMAT

FORMAT can be rst, csv and json.

csv can be used for e.g. exporting to other requirements tools.
rst output is input for a Sphinx documentation build which can create HTML pages.

--filter FILTER

The output can be filtered with quite natural conditions, e.g.

# filter entries which are requirements and have CAN in the text.
--filter "type == requirement && text =~ /CAN/"

stats

This prints some nice stats about requirements, per owner/originator, per document, etc.

stats implicitly executes the consistency check. All check parameters can also be used for stats.