ToolHandler Class Reference

Registry of TOPP tools and their TOPPAS categories. More...

#include <OpenMS/APPLICATIONS/ToolHandler.h>

Static Public Member Functions
static ToolListType	getTOPPToolList ()
	List every TOPP tool enabled in this build, keyed by tool name.
static const ToolListType &	getTOPPToolListRef ()
	The registry of getTOPPToolList without copying it.
static StringList	getTypes (const std::string &toolname)
	Return the alternative "types" / sub-commands a tool supports, or an empty list if it has none.
static std::string	getCategory (const std::string &toolname)
	Return the category string of a tool.
static std::string	getToolRegistryPath ()
	Resolved file-system path of the tool registry directory (root of the .tsv search).

Static Private Member Functions
static ToolListType	loadRegistry_ ()
static StringList	getToolRegistryFiles_ ()

Detailed Description

Registry of TOPP tools and their TOPPAS categories.

The registry is data, not code: it is assembled from the tab-separated .tsv files under ToolHandler::getToolRegistryPath ([OpenMS share]/TOOLS plus an OS-specific subdirectory, .../LINUX on Mac and Linux and .../WINDOWS on Windows). The search path can be augmented through the OPENMS_TOOL_REGISTRY_PATH environment variable (OPENMS_TTD_INTERNAL_PATH, its name in earlier releases, is still read as well). A directory that the search reaches twice contributes its files once.

An entry carries only what the registry is for – the tool's name and the category TOPPAS groups it under, plus the tool's -type sub-modes where it has any:

# <tool name> <TOPPAS category>
FileConverter File Converter

Everything else about a tool (its description, parameters, valid formats, citations) is self-described by its binary through -write_ctd, so a tool does not have to be built from the same source tree, or even the same repository, as the library: installing its binary and a .tsv naming it is enough to register it.

OpenMS' own tools are registered by share/OpenMS/TOOLS/OpenMS.tsv, which the build generates from the openms_topp_tool() declarations in src/topp/executables.cmake (see cmake/topp_tool_macros.cmake). That file is therefore never edited by hand and lists exactly the tools the build produced, so a tool that a build option did not build is not registered either. A build tree that was never installed has no share/OpenMS/TOOLS of its own; there the generated file is read from the build tree.

Used by TOPPAS for the visual workflow editor's tool palette and by the TOPP runtime to look up tools and their categories.

Note

The assembled registry is parsed once per process and cached, so the repeated lookups OpenMS::TOPPBase makes during start-up cost one map lookup each.

Member Function Documentation

getCategory()

static std::string getCategory ( const std::string &  toolname )

static

Return the category string of a tool.

Parameters

[in]

toolname

Name of the TOPP tool to query.

Returns

Category string (e.g. "Quantitation") or an empty string if toolname is unknown.

getToolRegistryFiles_()

static StringList getToolRegistryFiles_ ( )

staticprivate

Enumerate the .tsv files to read: everything under getToolRegistryPath (and its OS-specific subdirectory), or under the build tree's generated registry when this build was never installed, plus the directories the environment variables add. A directory the search reaches more than once contributes its files once.

getToolRegistryPath()

static std::string getToolRegistryPath ( )

static

Resolved file-system path of the tool registry directory (root of the .tsv search).

Returns

File::getOpenMSDataPath() + "/TOOLS".

getTOPPToolList()

static ToolListType getTOPPToolList ( )

static

List every TOPP tool enabled in this build, keyed by tool name.

Assembled from the .tsv files under getToolRegistryPath (a name collision between two of them throws Exception::InvalidValue, naming both files). Each value carries the tool's category string (e.g. "Quantitation", "File Converter") used by TOPPAS for grouping. Every .tsv of the directory is read, so a tool of another repository is listed as soon as its file is installed there.

Prefer getTOPPToolListRef when a copy is not needed.

Returns

Map toolname -> Internal::ToolDescription for every tool enabled in this build.

Referenced by TOPPASBase::createTOPPToolsTreeWidget().

getTOPPToolListRef()

static const ToolListType & getTOPPToolListRef ( )

static

The registry of getTOPPToolList without copying it.

Same content as getTOPPToolList, served from the process-wide cache. Use this for membership tests and lookups; the reference stays valid for the lifetime of the process.

Returns

Reference to the cached map toolname -> Internal::ToolDescription.

Referenced by INIUpdater::getNewToolName().

getTypes()

static StringList getTypes ( const std::string &  toolname )

static

Return the alternative "types" / sub-commands a tool supports, or an empty list if it has none.

Most tools have a single behaviour; a small number expose multiple sub-modes via -type (e.g. FeatureFinderCentroided vs. FeatureFinderIsotopeWavelet sharing infrastructure).

Parameters

[in]

toolname

Name of the TOPP tool to query.

Returns

Type names (may be empty); empty also when the tool is unknown, so that a tool which is not in the registry can still write its CTD/CWL description.

Referenced by TOPPASBase::createTOPPToolsTreeWidget().

loadRegistry_()

static ToolListType loadRegistry_ ( )

staticprivate

Parse every file of getToolRegistryFiles_ into the registry map. Throws Exception::InvalidValue when two files register the same tool name.