Tool Description Library (TDL)

Introduction

This library offers a unified api to export tool description formats like CTD or CWL.

The current CLIs of OpenMS and SeqAn3 are very different. Using the same command-line parsing library is currently (2022) not feasible for these projects. While OpenMS already has support for CTD, both are missing support for CWL.

The idea is to replace the CTD exporter of OpenMS with the TDL implementation and integrate TDL into SeqAn3.

As a next step, TDL will gain support for CWL. With (hopefully) minimal code adjustments, this will give OpenMS- and SeqAn3-based tools easy access to CWL tool description support.

Usage (C++20)

At the core of TDL is the ToolInfo structure. It consists of three values:

struct ToolInfo {
    MetaInfo                metaInfo{};
    Node::Children          params{};
    std::vector<CLIMapping> cliMapping{};
};

Where ToolInfo carries

• metadata about the tool
• a tree of parameters struct Node
• a tree of mappings from parameters to CLI prefixes

The Node class is defined as:

struct Node {
    using Children = std::vector<Node>;
    using Value    = std::variant<BoolValue, // just a single bool value
                               IntValue,  // single int, double or string value
                               DoubleValue,
                               StringValue,
                               IntValueList, // list of int, double or string values
                               DoubleValueList,
                               StringValueList,
                               Children>; // not a value, but a node with children

    std::string           name{};            //!< Name of the entry.
    std::string           description{};     //!< Entry description.
    std::set<std::string> tags{};            //!< List of tags, e.g.: advanced parameter tag.
    Value                 value{Children{}}; //!< Current value of this entry
};

A CWL file is generated by calling convertToCWL

auto toolInfo = ToolInfo {
    ...
};
auto cwlAsString = convertToCWL(toolInfo);
std::cout << cwlAsString;

Examples

• Detailed Example
• Complete Example

Special Cases

CTD

• String values with tags {"input", "file"}, {"output", "file"} or {"output", "prefix"} are exported as CTD-typed values input-file, output-file or output-prefix. The list valid of string values is interpreted as supported_formats.
• Lists of string values with tags {"input", "file"} or {"output", "file"} are exported as CTD-typed values input-file or output-file. The list valid of string values is interpreted as supported_formats.

CWL

The following tags and tag combinations have a special meaning:

• {"file"}: If used with tdl::StringValue, it is a single input file. If used with tdl::StringValueList, it represents a list of input files.
• {"directory"}: Same as the tag file but for directories.
• {"file", "output"}: A single or a list of input files (depending on tdl::StringValue or tdl::StringValueList).
• {"directory", "output"}: Same as {"file", "directory"} but for directories.
• {"prefixed", "output"}: A partial path that is used as a prefix. If used with tdl::StringValue, only a single file will be created. If used with tdl::StringValueList, it signals that multiple files might be created.
• {"basecommand"}: If used with tdl::Node::Children, the value will be appended to the list of base-commands, e.g.: build of raptor build ....