Namespace for encapsulating options processing. More...
|Combines a set of OptionsPackages. More...|
|Options common to all tools (including –fullhelp) More...|
|Provides a single LOOS selection (–selection) More...|
|Provides a mechanism for controlling how to split an AtomicGroup. More...|
|Basic trajectory with a –skip option. More...|
|Options specific to tools that work with water/internal-water. More...|
|Request a model with coordinates. More...|
|Base class for options. More...|
|Gets a string as prefix for output files (–prefix) More...|
|Provides simple way to add command-line arguments (required options) More...|
|Trajectory with either a –range or –skip. More...|
|Request Two models with coordinates. More...|
|typedef std::vector< OptionsPackage * >||vOpts|
Namespace for encapsulating options processing.
The OptionsFramework provides a consistent set of "common" options across all LOOS tools. By mixing and matching the subclasses of OptionsPackage, a tool can decide which set of "common" options it will use. Packages may also define their own package-wide set of common options. In addition, subclassing OptionsPackage within a tool is an easy mechanism for providing command-line options that are specific to an individual tool without having to write the support-code that using boost::program_options requires.
The basic pattern for using OptionsFramework is to create a new object that represents the options required by the tool. Once all objects are created, they are added to an AggregateOptions object that is responbile for parsing and validating the command-line as well as generating help messages and serializing the options' state for inclusion in the tool's output. For example, a tool that requires a model (with coordinates) and an output prefix would setup its options as follows:
The values of the options are generally stored in the member variables of the appropriate object. Simply use these, or copy them out into the tool. For example, to find the verbosity level in the above example, check
bopts->verbosity, and to access the model read in, use
One feature of boost::program_options is that the long-name options may have a single letter short-cut. Since OptionsFramework integrates options from many different sources, there is a possibility of short-cut collisions (i.e. two classes using the same single letter code). We therefore recommend the following convention when providing these short-cuts:
The full set of command-line options is created by the AggregateOptions class. Using AggregateOptions::add(), different OptionsPackage instances can be combined to build up the full set of command-line options. The order that the OptionsPackage objects are added is important, as it will determine the order of "positional" options as well as how the options are listed in the help. We recommend the following convention in options order:
Frequently, a tool requires a number of command-line arguments that are not optional. The RequiredArguments class can be used to incorporate these, rather than handling it within a tool-specific subclass of OptionsPackage. A RequiredArguments object can build up a command line by passing a string tag and description to RequiredArguments::addArgument() in the same order that the arguments would appear on the command line.
Another common command line format is to have an argument that can appear one or more times. This can also be handled by RequiredArguments by using the RequiredArguments::addVariableArguments() method. If this feature is used, the specified argument will appear after all other required arguments. Since the final argument can appear one or more times, it will consume all remaining command-line arguments. This means that if you use RequiredArguments, it should be the last OptionsPackage included in the AggregateOptions object.
Which OptionsPackage subclasses to use in a tool depends on what the tool needs. All tools, however, should include BasicOptions to provide a help message and optional full-help message. While verbosity is defined in BasicOptions, tools do not need to support it. If a tool needs an output prefix, then include OutputPrefix. Similarly, if a tool needs a single selection to determine which atoms to operate on, include a BasicSelection. If the tool needs multiple selections, then you will need to handle this explicitly with a tool-specific subclass of OptionsPackage or via RequiredArguments.
For tools that work with a model only, we recommend that you use ModelWithCoords. This will guarantee that the generatic AtomicGroup has coordinates (e.g. the user specified a PSF file rather than a PDF). Tools that iterate over all frames in a trajectory should use BasicTrajectory. This class does provide a –skip option that lets the user skip the first n-frames of a trajectory (presumably, the equilibration stage). The trajectory it creates will be "primed" so that the first read will be the n+1'th frame. Finally, tools that can operate on a range of a trajectory, or an arbitrary set of frames, should use TrajectoryWithFrameIndices. The TrajectoryWithFrameIndices::frameList() method returns a vector of unsigned integers that specify which frames of the trajectory a tool should use. For example:
Writing a ToolOption class
The common idiom to add tool-specific options not covered by the existing objects is to subclass
OptionsPackage. The virtual memberfunctions (e.g.
addHidden(), etc) mimic the steps you would normally take to use
boost::program_options. It is only necessary to override the functions required speficially for the tool.
As a trivial example, here is a class that will add a bool option to the command line,
This class can then be used as follows,
In more complex cases,
check() can be used to validate the command-line and
postConditions() can be used to implement any necessary post-processing of command-line options but still within the context of the parser. This means that an error will result in a help message being printed. For example, if a file is required for input, the
ifstream can be opened here. If it fails, then
postConditions() will report the error and a help message will be printed out.