#include <gromacs/options/filenameoption.h>

Inheritance diagram for gmx::FileNameOption:

Collaboration diagram for gmx::FileNameOption:

Description

Specifies an option that provides file names.

Public methods in this class do not throw.

Examples:: template.cpp.

Public Types
typedef FileNameOptionInfo	InfoType
	OptionInfo subclass corresponding to this option type.

typedef std::string	ValueType
	Type that stores a single option value.

typedef FileNameOption	MyClass
	Alias for the derived class type.

Public Member Functions
	FileNameOption (const char *name)
	Initializes an option with the given name.

MyClass &	filetype (OptionFileType type)
	Sets the type of the file this option accepts. More...

MyClass &	legacyType (int type)
	Sets the type of the file from an enum in filetypes.h. More...

MyClass &	legacyOptionalBehavior ()
	Changes the behavior of optional options to match old t_filenm. More...

MyClass &	inputFile ()
	Tells that the file provided by this option is used for input only.

MyClass &	outputFile ()
	Tells that the file provided by this option is used for output only.

MyClass &	inputOutputFile ()
	Tells that the file provided by this option is used for input and output both.

MyClass &	readWriteFlags (bool bRead, bool bWrite)
	Sets the read/write usage for this file from boolean flags.

MyClass &	libraryFile (bool bLibrary=true)
	Tells that the file will be looked up in library directories in addition to working directory. More...

MyClass &	allowMissing (bool bAllow=true)
	Tells that missing file names explicitly provided by the user are valid for this input option. More...

MyClass &	defaultBasename (const char *basename)
	Sets a default basename for the file option. More...

MyClass &	defaultType (int filetype)
	Sets a default type/extension for the file option. More...

MyClass &	description (const char *descr)
	Sets a description for the option. More...

MyClass &	hidden (bool bHidden=true)
	Hides the option from normal help output.

MyClass &	required (bool bRequired=true)
	Requires the option to be specified explicitly. More...

MyClass &	allowMultiple (bool bMulti=true)
	Allows the option to be specified multiple times.

MyClass &	valueCount (int count)
	Requires exactly `count` values for the option.

MyClass &	multiValue (bool bMulti=true)
	Allows any number of values for the option.

MyClass &	defaultValue (const std::string &defaultValue)
	Sets a default value for the option. More...

MyClass &	defaultValueIfSet (const std::string &defaultValue)
	Sets a default value for the option when it is set. More...

MyClass &	store (std::string *store)
	Stores value(s) in memory pointed by `store`. More...

MyClass &	storeCount (int *countptr)
	Stores number of values in the value pointed by `countptr`. More...

MyClass &	storeVector (std::vector< std::string > *store)
	Stores option values in the provided vector. More...

MyClass &	storeIsSet (bool *store)
	Stores whether the option was explicitly set. More...

Protected Types
typedef OptionTemplate < std::string, FileNameOption >	MyBase
	Alias for the template class for use in base classes.

Protected Member Functions
const std::string *	defaultValue () const
	Returns a pointer to user-specified default value, or NULL if there is none.

const std::string *	defaultValueIfSet () const
	Returns a pointer to user-specified default value, or NULL if there is none.

std::string *	store () const
	Returns a pointer to the storage location, or NULL if none specified.

std::vector< std::string > *	storeVector () const
	Returns a pointer to the storage vector, or NULL if none specified.

MyClass &	me ()
	Returns `*this` casted into MyClass to reduce typing.

void	setDescription (const char *descr)
	Sets the description for the option.

void	setStoreIsSet (bool *store)
	Sets the storage location for whether the option is set.

void	setFlag (OptionFlag flag)
	Sets a flag for the option.

void	setFlag (OptionFlag flag, bool bSet)
	Sets or clears a flag for the option.

void	clearFlag (OptionFlag flag)
	Clears a flag for the option.

bool	isVector () const
	Returns true if the option is vector-valued.

void	setVector ()
	Sets the option to be vector-valued. More...

void	setValueCount (int count)
	Sets the required number of values for the option.

Protected Attributes
int	minValueCount_
	Minimum number of values required for the option.

int	maxValueCount_
	Maximum number of values allowed for the option.

Friends
class	FileNameOptionStorage
	Needed to initialize FileNameOptionStorage from this class without otherwise unnecessary accessors.

Member Function Documentation

MyClass& gmx::FileNameOption::allowMissing ( bool bAllow = true )

inline

Tells that missing file names explicitly provided by the user are valid for this input option.

If this method is not called, an error will be raised if the user explicitly provides a file name that does not name an existing file, or if the default value does not resolve to a valid file name for a required option that the user has not set.

This method only has effect with input files, and only if a FileNameOptionManager is being used.

MyClass& gmx::FileNameOption::defaultBasename ( const char * basename )

inline

Sets a default basename for the file option.

Use this method instead of defaultValue() or defaultValueIfSet() to set a default value for a file name option. No extension needs to be provided; it is automatically added based on filetype() or defaultType(). The behavior is also adjusted based on required(): if the option is required, the value given to defaultBasename() is treated as for both defaultValue() and defaultValueIfSet(), otherwise it is treated as for defaultValueIfSet().

For input files that accept multiple extensions, the extension is completed to the default extension on creation of the option or at time of parsing an option without a value.

If FileNameOptionManager is used, the extension may change during Options::finish(), as this is the time when the default names are checked against the file system to provide an extension that matches an existing file if that is possible.

If FileNameOptionManager is used, and FileNameOptionManager::addDefaultFileNameOption() is used, and the user provides a global default file name using that option, then the global default takes precedence over defaultBasename().

MyClass& gmx::FileNameOption::defaultType ( int filetype )

inline

Sets a default type/extension for the file option.

For options that accept multiple types of files (e.g., eftTrajectory), this method sets the default extension used for completing defaultBasename(), as well as the default extension used by FileNameOptionManager to complete various file names.

The value should be one of the enumerated ef* values from filetypes.h, and be a valid type for the type specified with filetype().

MyClass& gmx::OptionTemplate< std::string , FileNameOption >::defaultValue ( const std::string & defaultValue )

inlineinherited

Sets a default value for the option.

Parameters

[in] defaultValue Default value.

If the option is never set, the default value is copied to the assigned storage. Note that if the option is not set and there is no default value, the storage is not altered, which can also be used to provide a default value. The latter method has to be used if the option can take multiple values.

defaultValue is copied when the option is created.

MyClass& gmx::OptionTemplate< std::string , FileNameOption >::defaultValueIfSet ( const std::string & defaultValue )

inlineinherited

Sets a default value for the option when it is set.

Parameters

[in] defaultValue Default value.

This value is used if the option is set, but no value is provided. If the option is never set, the value set with defaultValue() is used. Can only be used for options that accept a single value.

defaultValue is copied when the option is created.

MyClass& gmx::OptionTemplate< std::string , FileNameOption >::description ( const char * descr )

inlineinherited

Sets a description for the option.

Parameters

[in] descr Description to set.

String in descr is copied when the option is created.

MyClass& gmx::FileNameOption::filetype ( OptionFileType type )

inline

Sets the type of the file this option accepts.

Either this attribute or legacyType() must be provided.

MyClass& gmx::FileNameOption::legacyOptionalBehavior ( )

inline

Changes the behavior of optional options to match old t_filenm.

If this is not set, optional options return an empty string if not set. If this is set, a non-empty value is always returned. In the latter case, whether the option is set only affects the return value of OptionInfo::isSet() and Options::isSet().

MyClass& gmx::FileNameOption::legacyType ( int type )

inline

Sets the type of the file from an enum in filetypes.h.

New code should prefer filetype(), extending the enumeration if necessary.

MyClass& gmx::FileNameOption::libraryFile ( bool bLibrary = true )

inline

Tells that the file will be looked up in library directories in addition to working directory.

Todo:: Currently, this flag only affects the help output. Callers must take care themselves to actually search the file in the library directories. It would be nicer to do this searching within the file name option implementation.

MyClass& gmx::OptionTemplate< std::string , FileNameOption >::required ( bool bRequired = true )

inlineinherited

Requires the option to be specified explicitly.

Note that if you specify defaultValue() together with required(), the user is not required to explicitly provide the option. In this case, required() only affects possible help output.

void gmx::AbstractOption::setVector ( )

inlineprotectedinherited

Sets the option to be vector-valued.

This method is provided for convenience to make management of value counts easier. In order to implement a vector-valued option, the class derived from AbstractOption should expose a method that calls this method, and the storage object derived from AbstractOptionStorage should check isVector(). If only a single value is provided, the storage object should fill the whole vector with that value.

The length of the vector (the value of maxValueCount_) must be fixed. The default length is 3 elements.

MyClass& gmx::OptionTemplate< std::string , FileNameOption >::store ( std::string * store )

inlineinherited

Stores value(s) in memory pointed by store.

Parameters

[in] store Storage for option value(s).

The caller is responsible for allocating enough memory such that the any allowed number of values fits into the array pointed by store. If there is no maximum allowed number or if the maximum is inconveniently large, storeVector() should be used.

For information on when values are available in the storage, see storeVector().

The pointer provided should remain valid as long as the associated Options object exists.

MyClass& gmx::OptionTemplate< std::string , FileNameOption >::storeCount ( int * countptr )

inlineinherited

Stores number of values in the value pointed by countptr.

Parameters

[in] countptr Storage for the number of values.

For information on when values are available in the storage, see storeVector().

The pointers provided should remain valid as long as the associated Options object exists.

MyClass& gmx::OptionTemplate< std::string , FileNameOption >::storeIsSet ( bool * store )

inlineinherited

Stores whether the option was explicitly set.

Parameters

[in] store Variable to store the flag in.

The value is set to false on creation of the option, and to true as soon as a value is assigned to the option. A default value does not set the flag to true, but assignment that uses defaultValueIfSet() does.

The pointer provided should remain valid as long as the associated Options object exists.

MyClass& gmx::OptionTemplate< std::string , FileNameOption >::storeVector ( std::vector< std::string > * store )

inlineinherited

Stores option values in the provided vector.

Parameters

[in] store Vector to store option values in.

Values are added to the vector after each successful set of values is parsed. Note that for some options, the value may be changed later, and is only guaranteed to be correct after Options::finish() has been called.

The pointer provided should remain valid as long as the associated Options object exists.

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

src/gromacs/options/filenameoption.h
src/gromacs/options/filenameoption.cpp

Description

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Friends

Member Function Documentation