This class holds the keywords and their documentation. More...

#include <Keywords.h>

Classes
struct	component

struct	keyInfo

struct	KeyType
	This class lets me pass keyword types easily. More...

Public Types
enum class	argType { scalar =1 , vector =1<<2 , matrix =1<<3 , grid =1<<4 }

enum class	componentType { scalar =1 , vector =1<<2 , matrix =1<<3 , grid =1<<4 , atoms =1<<5 , atom =1<<6 }

Public Member Functions
	Keywords ()
	Constructor.

void	add (const Keywords &keys)
	append the data from another Keywords object (only keywords, reserved keywords and components)

void	add (std::string_view keytype, std::string_view key, std::string_view defaultValue, std::string_view docstring)
	Add a new compulsory keyword (t must equal compulsory) with name k, default value def and description d.

void	add (std::string_view keytype, std::string_view key, std::string_view docstring)
	Add a new keyword of type t with name k and description d.

void	addActionNameSuffix (const std::string &suffix)
	Add a suffix to the list of possible action name suffixes.

void	addDOI (const std::string &doi)
	Add a DOI to the list in the manual page for this action.

void	addFlag (std::string_view key, bool defaultValue, std::string_view docstring)
	Add a falg with name k that is by default on if def is true and off if def is false. d should provide a description of the flag.

void	addInputKeyword (const std::string &keyType, const std::string &key, argType dataType, const std::string &defaultValue, const std::string &docstring)
	Create the documentation for a keyword that reads arguments.

void	addInputKeyword (const std::string &keyType, const std::string &key, argType dataType, const std::string &docstring)
	Create the documentation for a keyword that reads arguments.

void	addInputKeyword (const std::string &keyType, const std::string &key, const std::string &dataType, const std::string &defaultValue, const std::string &docstring)
	Create the documentation for a keyword that reads arguments.

void	addInputKeyword (const std::string &keyType, const std::string &key, const std::string &dataType, const std::string &docstring)
	Create the documentation for a keyword that reads arguments.

void	addOutputComponent (const std::string &name, const std::string &key, componentType type, const std::string &descr)
	Add a potential component which can be output by this particular action.

void	addOutputComponent (const std::string &name, const std::string &key, const std::string &descr)
	Add a potential component which can be output by this particular action.

void	addOutputComponent (const std::string &name, const std::string &key, const std::string &type, const std::string &descr)

bool	checkArgumentType (const std::size_t &rank, const bool &hasderiv) const
	Check the documentation of the argument types.

bool	componentHasCorrectType (const std::string &name, const std::size_t &rank, const bool &hasderiv) const
	Check that type for component has been documented correctly.

void	destroyData ()
	Clear everything from the keywords object.

bool	exists (std::string_view k) const
	Check if there is a keyword with name k.

std::vector< std::string >	getArgumentKeys () const

std::string	getArgumentType (const std::string &name) const
	Get the valid types that can be used as argument for this keyword.

bool	getDefaultValue (const std::string &key, std::string &def) const
	Get the value of the default for the keyword named key.

std::string	getDisplayName () const
	Return the name of the action that has this set of keywords.

const std::vector< std::string > &	getDOIList () const
	Get the list of DOI.

std::string	getHelpString () const
	Get the help string.

const std::vector< std::string > &	getKeys () const
	Get the ordered list of active keywords (not the reserved ones)

std::string	getKeyword (const unsigned i) const
	Return the ith keyword.

std::string	getKeywordDescription (const std::string &name) const
	Get the description of a particular keyword.

std::string	getKeywordDocs (const std::string &key) const
	Get the documentation for a particular keyword.

std::string	getLinkedActions (const std::string &key) const
	Get any actions that are linked to this keyword.

bool	getLogicalDefault (const std::string &key, bool &def) const
	find out whether flag key is on or off by default.

const std::vector< std::string > &	getNeededKeywords () const
	Get the list of keywords that are needed by this action.

std::string	getOutputComponentDescription (const std::string &name) const
	Get the description of the named component.

std::string	getOutputComponentFlag (const std::string &name) const
	Get the flag that forces thie named component to be calculated.

const std::vector< std::string > &	getOutputComponents () const
	Get the full ordered list of output components.

std::string	getOutputComponentType (const std::string &name) const
	Get the type for the named output component.

std::string	getReplacementAction () const
	Get the action that should be used to replace this one if action has been deprecated.

std::string	getStyle (const std::string &k) const
	Get the type for the keyword with string k.

std::string	getTooltip (const std::string &name) const
	Get the description of a particular keyword.

bool	isActionNeeded (std::string_view name) const
	Check if the requested action is in the list of the needed actions.

bool	isActionSuffixed (std::string_view name, std::string_view basename) const
	checks that name is is a composition of basename and one of the possible suffixes

void	isAnalysis ()

void	isDriver ()

void	linkActionInDocs (const std::string &k, const std::string &action)
	Create a link to this action in the documentation for it.

void	needsAction (const std::string &name)
	Note that another actions is required to create this shortcut.

bool	numbered (const std::string &k) const
	Check if numbered keywords are allowed for this action.

bool	outputComponentExists (const std::string &name) const
	Has a component with this name been added?

void	print (FILE *out) const
	Print the documentation to a file (use by PLUMED::CLTool::readCommandLineArgs)

void	print (Log &log) const
	Print the documentation to the log file (used by PLMD::Action::error)

void	print_html () const
	Print an html version of the documentation.

void	print_spelling () const
	Print a file containing the list of keywords for a particular action (used for spell checking)

void	print_template (const std::string &actionname, bool include_optional) const
	Print the template version for the documentation.

void	print_vim () const
	Print keywords in form readable by vim.

void	remove (const std::string &k)
	Remove the keyword with name k.

void	removeOutputComponent (const std::string &name)
	Remove a component that can be output by this particular action.

void	reserve (std::string_view keytype, std::string_view key, std::string_view docstring)
	Reserve a keyword.

bool	reserved (std::string_view k) const
	Check the keyword k has been reserved.

void	reserveFlag (const std::string &key, bool defaultValue, const std::string &docstring)
	Reserve a flag.

void	reset_style (const std::string &k, const std::string &style)
	Change part of the style of a keyword.

void	setComponentsIntroduction (const std::string &instr)
	Set the text that introduces how the components for this action are introduced.

void	setDeprecated (const std::string &name)
	Note that this action has been deprecated.

void	setDisplayName (const std::string &name)
	Set the display name.

void	setValueDescription (componentType type, const std::string &descr)

void	setValueDescription (const std::string &type, const std::string &descr)
	Add the description of the value.

unsigned	size () const
	Return the number of defined keywords.

bool	style (const std::string &k, const std::string &t) const
	Check if the keyword with name k has style t.

void	use (std::string_view k)
	Use one of the reserved keywords.

Private Member Functions
void	addOrReserve (std::string_view keytype, std::string_view key, std::string_view docstring, bool reserve)
	Add o reserve a new keyword (internal tool)

void	print_html_item (const std::string &) const
	Print the documentation for the named keyword in html.

Private Attributes
std::vector< std::string >	actionNameSuffixes
	List of suffixes that can be used with this action.

std::vector< std::string >	cnames
	The names of all the possible components for an action, in order of their (first) declaration.

std::map< std::string, component, std::less< void > >	components

std::string	cstring
	The string that should be printed out to describe how the components work for this particular action.

std::vector< std::string >	doilist
	List of doi's that should appear in the manual.

bool	isaction =true
	Is this an action or driver (this bool affects what style==atoms does in print)

bool	isatoms =true
	This allows us to overwrite the behavior of the atoms type in analysis actions.

std::vector< std::string >	keys
	The names of the allowed keywords, in order of declaration.

std::map< std::string, keyInfo, std::less< void > >	keywords
	Stores the keywords along with their settings.

std::vector< std::string >	neededActions
	The list of actions that are needed by this action.

std::string	replaceaction ="none"
	The action to use in place of this deprecated action.

std::vector< std::string >	reserved_keys
	The names of the reserved keywords, in order of declaration.

std::string	thisactname
	The name of the action that has this set of keywords.

Detailed Description

This class holds the keywords and their documentation.

Member Enumeration Documentation

◆ argType

enum class PLMD::Keywords::argType

strong

Enumerator
scalar
vector
matrix
grid

◆ componentType

enum class PLMD::Keywords::componentType

strong

Enumerator
scalar
vector
matrix
grid
atoms
atom

Constructor & Destructor Documentation

◆ Keywords()

PLMD::Keywords::Keywords ( )

inline

Constructor.

Member Function Documentation

◆ add() [1/3]

void PLMD::Keywords::add ( const Keywords & keys )

append the data from another Keywords object (only keywords, reserved keywords and components)

◆ add() [2/3]

void PLMD::Keywords::add	(	std::string_view	keytype,
		std::string_view	key,
		std::string_view	defaultValue,
		std::string_view	docstring )

Add a new compulsory keyword (t must equal compulsory) with name k, default value def and description d.

◆ add() [3/3]

void PLMD::Keywords::add	(	std::string_view	keytype,
		std::string_view	key,
		std::string_view	docstring )

Add a new keyword of type t with name k and description d.

◆ addActionNameSuffix()

void PLMD::Keywords::addActionNameSuffix ( const std::string & suffix )

Add a suffix to the list of possible action name suffixes.

◆ addDOI()

void PLMD::Keywords::addDOI ( const std::string & doi )

Add a DOI to the list in the manual page for this action.

◆ addFlag()

void PLMD::Keywords::addFlag	(	std::string_view	key,
		bool	defaultValue,
		std::string_view	docstring )

Add a falg with name k that is by default on if def is true and off if def is false. d should provide a description of the flag.

◆ addInputKeyword() [1/4]

void PLMD::Keywords::addInputKeyword	(	const std::string &	keyType,
		const std::string &	key,
		argType	dataType,
		const std::string &	defaultValue,
		const std::string &	docstring )

Create the documentation for a keyword that reads arguments.

◆ addInputKeyword() [2/4]

void PLMD::Keywords::addInputKeyword	(	const std::string &	keyType,
		const std::string &	key,
		argType	dataType,
		const std::string &	docstring )

Create the documentation for a keyword that reads arguments.

◆ addInputKeyword() [3/4]

void PLMD::Keywords::addInputKeyword	(	const std::string &	keyType,
		const std::string &	key,
		const std::string &	dataType,
		const std::string &	defaultValue,
		const std::string &	docstring )

Create the documentation for a keyword that reads arguments.

Todo: prepend[[deprecated("Please specify the data type for the argument from scalar/vector/matrix/grid with the Keywords::argType enum")]]

◆ addInputKeyword() [4/4]

void PLMD::Keywords::addInputKeyword	(	const std::string &	keyType,
		const std::string &	key,
		const std::string &	dataType,
		const std::string &	docstring )

Create the documentation for a keyword that reads arguments.

Todo: prepend [[deprecated("Please specify the data type for the argument from scalar/vector/matrix/grid with the Keywords::argType enum")]]

◆ addOrReserve()

void PLMD::Keywords::addOrReserve	(	std::string_view	keytype,
		std::string_view	key,
		std::string_view	docstring,
		bool	reserve )

private

Add o reserve a new keyword (internal tool)

◆ addOutputComponent() [1/3]

void PLMD::Keywords::addOutputComponent	(	const std::string &	name,
		const std::string &	key,
		componentType	type,
		const std::string &	descr )

Add a potential component which can be output by this particular action.

◆ addOutputComponent() [2/3]

void PLMD::Keywords::addOutputComponent	(	const std::string &	name,
		const std::string &	key,
		const std::string &	descr )

Add a potential component which can be output by this particular action.

◆ addOutputComponent() [3/3]

void PLMD::Keywords::addOutputComponent	(	const std::string &	name,
		const std::string &	key,
		const std::string &	type,
		const std::string &	descr )

Todo: prepend[[deprecated("Please specify the data type for the argument from scalar/vector/matrix/grid with the Keywords::argType enum")]]

◆ checkArgumentType()

bool PLMD::Keywords::checkArgumentType	(	const std::size_t &	rank,
		const bool &	hasderiv ) const

Check the documentation of the argument types.

◆ componentHasCorrectType()

bool PLMD::Keywords::componentHasCorrectType	(	const std::string &	name,
		const std::size_t &	rank,
		const bool &	hasderiv ) const

Check that type for component has been documented correctly.

◆ destroyData()

void PLMD::Keywords::destroyData ( )

Clear everything from the keywords object.

Not actually needed if your Keywords object is going out of scope.

◆ exists()

bool PLMD::Keywords::exists ( std::string_view k ) const

Check if there is a keyword with name k.

◆ getArgumentKeys()

std::vector< std::string > PLMD::Keywords::getArgumentKeys ( ) const

◆ getArgumentType()

std::string PLMD::Keywords::getArgumentType ( const std::string & name ) const

Get the valid types that can be used as argument for this keyword.

◆ getDefaultValue()

bool PLMD::Keywords::getDefaultValue	(	const std::string &	key,
		std::string &	def ) const

Get the value of the default for the keyword named key.

◆ getDisplayName()

std::string PLMD::Keywords::getDisplayName ( ) const

Return the name of the action that has this set of keywords.

◆ getDOIList()

const std::vector< std::string > & PLMD::Keywords::getDOIList ( ) const

Get the list of DOI.

◆ getHelpString()

std::string PLMD::Keywords::getHelpString ( ) const

Get the help string.

◆ getKeys()

const std::vector< std::string > & PLMD::Keywords::getKeys ( ) const

inline

Get the ordered list of active keywords (not the reserved ones)

◆ getKeyword()

std::string PLMD::Keywords::getKeyword ( const unsigned i ) const

Return the ith keyword.

◆ getKeywordDescription()

std::string PLMD::Keywords::getKeywordDescription ( const std::string & name ) const

Get the description of a particular keyword.

◆ getKeywordDocs()

std::string PLMD::Keywords::getKeywordDocs ( const std::string & key ) const

Get the documentation for a particular keyword.

◆ getLinkedActions()

std::string PLMD::Keywords::getLinkedActions ( const std::string & key ) const

Get any actions that are linked to this keyword.

◆ getLogicalDefault()

bool PLMD::Keywords::getLogicalDefault	(	const std::string &	key,
		bool &	def ) const

find out whether flag key is on or off by default.

◆ getNeededKeywords()

const std::vector< std::string > & PLMD::Keywords::getNeededKeywords ( ) const

Get the list of keywords that are needed by this action.

◆ getOutputComponentDescription()

std::string PLMD::Keywords::getOutputComponentDescription ( const std::string & name ) const

Get the description of the named component.

◆ getOutputComponentFlag()

std::string PLMD::Keywords::getOutputComponentFlag ( const std::string & name ) const

Get the flag that forces thie named component to be calculated.

◆ getOutputComponents()

const std::vector< std::string > & PLMD::Keywords::getOutputComponents ( ) const

inline

Get the full ordered list of output components.

◆ getOutputComponentType()

std::string PLMD::Keywords::getOutputComponentType ( const std::string & name ) const

Get the type for the named output component.

◆ getReplacementAction()

std::string PLMD::Keywords::getReplacementAction ( ) const

Get the action that should be used to replace this one if action has been deprecated.

◆ getStyle()

std::string PLMD::Keywords::getStyle ( const std::string & k ) const

Get the type for the keyword with string k.

◆ getTooltip()

std::string PLMD::Keywords::getTooltip ( const std::string & name ) const

Get the description of a particular keyword.

◆ isActionNeeded()

bool PLMD::Keywords::isActionNeeded ( std::string_view name ) const

Check if the requested action is in the list of the needed actions.

◆ isActionSuffixed()

bool PLMD::Keywords::isActionSuffixed	(	std::string_view	name,
		std::string_view	basename ) const

checks that name is is a composition of basename and one of the possible suffixes

Cycles on the registered suffixed and return true if the combination basename+suffix equals to the passed name

◆ isAnalysis()

void PLMD::Keywords::isAnalysis ( )

inline

◆ isDriver()

void PLMD::Keywords::isDriver ( )

inline

◆ linkActionInDocs()

void PLMD::Keywords::linkActionInDocs	(	const std::string &	k,
		const std::string &	action )

Create a link to this action in the documentation for it.

◆ needsAction()

void PLMD::Keywords::needsAction ( const std::string & name )

Note that another actions is required to create this shortcut.

◆ numbered()

bool PLMD::Keywords::numbered ( const std::string & k ) const

Check if numbered keywords are allowed for this action.

◆ outputComponentExists()

bool PLMD::Keywords::outputComponentExists ( const std::string & name ) const

Has a component with this name been added?

◆ print() [1/2]

void PLMD::Keywords::print ( FILE * out ) const

Print the documentation to a file (use by PLUMED::CLTool::readCommandLineArgs)

◆ print() [2/2]

void PLMD::Keywords::print ( Log & log ) const

Print the documentation to the log file (used by PLMD::Action::error)

◆ print_html()

void PLMD::Keywords::print_html ( ) const

Print an html version of the documentation.

◆ print_html_item()

void PLMD::Keywords::print_html_item ( const std::string & key ) const

private

Print the documentation for the named keyword in html.

◆ print_spelling()

void PLMD::Keywords::print_spelling ( ) const

Print a file containing the list of keywords for a particular action (used for spell checking)

◆ print_template()

void PLMD::Keywords::print_template	(	const std::string &	actionname,
		bool	include_optional ) const

Print the template version for the documentation.

◆ print_vim()

void PLMD::Keywords::print_vim ( ) const

Print keywords in form readable by vim.

◆ remove()

void PLMD::Keywords::remove ( const std::string & k )

Remove the keyword with name k.

◆ removeOutputComponent()

void PLMD::Keywords::removeOutputComponent ( const std::string & name )

Remove a component that can be output by this particular action.

◆ reserve()

void PLMD::Keywords::reserve	(	std::string_view	keytype,
		std::string_view	key,
		std::string_view	docstring )

Reserve a keyword.

◆ reserved()

bool PLMD::Keywords::reserved ( std::string_view k ) const

Check the keyword k has been reserved.

◆ reserveFlag()

void PLMD::Keywords::reserveFlag	(	const std::string &	key,
		bool	defaultValue,
		const std::string &	docstring )

Reserve a flag.

◆ reset_style()

void PLMD::Keywords::reset_style	(	const std::string &	k,
		const std::string &	style )

Change part of the style of a keyword.

The standard usecase for this method is creating a compulsory or an atom(s) numbered keyword. For example:

keys.add("numbered","ATOMS","the atoms involved in each of the contacts you wish to calculate. "
         "Keywords like ATOMS1, ATOMS2, ATOMS3,... should be listed and one contact will be "
         "calculated for each ATOM keyword you specify.");
keys.reset_style("ATOMS","atoms");
keys.add("numbered","SWITCH","The switching functions to use for each of the contacts in your map. "
         "You can either specify a global switching function using SWITCH or one "
         "switching function for each contact. Details of the various switching "
         "functions you can use are provided on \\ref switchingfunction.");
keys.reset_style("SWITCH","compulsory");

Note

Note that some option of the selected keyword may not change. In particular:

A numbered keyword will change the style but the keyInfo::allowmultiple will remain set to true
An eventual keyInfo::atomtag will not be changed unless the style is set to an atomlist

◆ setComponentsIntroduction()

void PLMD::Keywords::setComponentsIntroduction ( const std::string & instr )

Set the text that introduces how the components for this action are introduced.

◆ setDeprecated()

void PLMD::Keywords::setDeprecated ( const std::string & name )

Note that this action has been deprecated.

◆ setDisplayName()

void PLMD::Keywords::setDisplayName ( const std::string & name )

Set the display name.

◆ setValueDescription() [1/2]

void PLMD::Keywords::setValueDescription	(	componentType	type,
		const std::string &	descr )

Todo: prepend[[deprecated("Please specify the data type for the argument from scalar/vector/matrix/grid with the Keywords::argType enum")]]

◆ setValueDescription() [2/2]

void PLMD::Keywords::setValueDescription	(	const std::string &	type,
		const std::string &	descr )

Add the description of the value.

◆ size()

unsigned PLMD::Keywords::size ( ) const

Return the number of defined keywords.

◆ style()

bool PLMD::Keywords::style	(	const std::string &	k,
		const std::string &	t ) const

Check if the keyword with name k has style t.

◆ use()

void PLMD::Keywords::use ( std::string_view k )

Use one of the reserved keywords.

this "copies" a reserved key into the keylist so it can be used

Member Data Documentation

◆ actionNameSuffixes

std::vector<std::string> PLMD::Keywords::actionNameSuffixes

private

List of suffixes that can be used with this action.

◆ cnames

std::vector<std::string> PLMD::Keywords::cnames

private

The names of all the possible components for an action, in order of their (first) declaration.

◆ components

std::map<std::string,component,std::less<void> > PLMD::Keywords::components

private

◆ cstring

std::string PLMD::Keywords::cstring

private

The string that should be printed out to describe how the components work for this particular action.

◆ doilist

std::vector<std::string> PLMD::Keywords::doilist

private

List of doi's that should appear in the manual.

◆ isaction

bool PLMD::Keywords::isaction =true

private

Is this an action or driver (this bool affects what style==atoms does in print)

◆ isatoms

bool PLMD::Keywords::isatoms =true

private

This allows us to overwrite the behavior of the atoms type in analysis actions.

◆ keys

std::vector<std::string> PLMD::Keywords::keys

private

The names of the allowed keywords, in order of declaration.

◆ keywords

std::map<std::string,keyInfo,std::less<void> > PLMD::Keywords::keywords

private

Stores the keywords along with their settings.

◆ neededActions

std::vector<std::string> PLMD::Keywords::neededActions

private

The list of actions that are needed by this action.

◆ replaceaction

std::string PLMD::Keywords::replaceaction ="none"

private

The action to use in place of this deprecated action.

◆ reserved_keys

std::vector<std::string> PLMD::Keywords::reserved_keys

private

The names of the reserved keywords, in order of declaration.

◆ thisactname

std::string PLMD::Keywords::thisactname

private

The name of the action that has this set of keywords.

The documentation for this class was generated from the following files:

tools/Keywords.h
tools/Keywords.cpp

Classes

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ argType

◆ componentType

Constructor & Destructor Documentation

◆ Keywords()

Member Function Documentation

◆ add() [1/3]

◆ add() [2/3]

◆ add() [3/3]

◆ addActionNameSuffix()

◆ addDOI()

◆ addFlag()

◆ addInputKeyword() [1/4]

◆ addInputKeyword() [2/4]

◆ addInputKeyword() [3/4]

◆ addInputKeyword() [4/4]

◆ addOrReserve()

◆ addOutputComponent() [1/3]

◆ addOutputComponent() [2/3]

◆ addOutputComponent() [3/3]

◆ checkArgumentType()

◆ componentHasCorrectType()

◆ destroyData()

◆ exists()

◆ getArgumentKeys()

◆ getArgumentType()

◆ getDefaultValue()

◆ getDisplayName()

◆ getDOIList()

◆ getHelpString()

◆ getKeys()

◆ getKeyword()

◆ getKeywordDescription()

◆ getKeywordDocs()

◆ getLinkedActions()

◆ getLogicalDefault()

◆ getNeededKeywords()

◆ getOutputComponentDescription()

◆ getOutputComponentFlag()

◆ getOutputComponents()

◆ getOutputComponentType()

◆ getReplacementAction()

◆ getStyle()

◆ getTooltip()

◆ isActionNeeded()

◆ isActionSuffixed()

◆ isAnalysis()

◆ isDriver()

◆ linkActionInDocs()

◆ needsAction()

◆ numbered()

◆ outputComponentExists()

◆ print() [1/2]

◆ print() [2/2]

◆ print_html()

◆ print_html_item()

◆ print_spelling()

◆ print_template()

◆ print_vim()

◆ remove()

◆ removeOutputComponent()

◆ reserve()

◆ reserved()

◆ reserveFlag()

◆ reset_style()

◆ setComponentsIntroduction()

◆ setDeprecated()

◆ setDisplayName()

◆ setValueDescription() [1/2]

◆ setValueDescription() [2/2]

◆ size()

◆ style()

◆ use()

Member Data Documentation