3 * This source code is part of
7 * GROningen MAchine for Chemical Simulations
9 * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
10 * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
11 * Copyright (c) 2001-2009, The GROMACS development team,
12 * check out http://www.gromacs.org for more information.
14 * This program is free software; you can redistribute it and/or
15 * modify it under the terms of the GNU General Public License
16 * as published by the Free Software Foundation; either version 2
17 * of the License, or (at your option) any later version.
19 * If you want to redistribute modifications, please consider that
20 * scientific software is very special. Version control is crucial -
21 * bugs must be traceable. We will be happy to consider code for
22 * inclusion in the official distribution, but derived work must not
23 * be called official GROMACS. Details are found in the README & COPYING
24 * files - if they are missing, get the official version at www.gromacs.org.
26 * To help us fund GROMACS development, we humbly ask that you cite
27 * the papers on the package - you can find them in the top README file.
29 * For more info, check our website at http://www.gromacs.org
31 /*! \defgroup module_options Extensible Handling of Options
32 * \ingroup group_utilitymodules
34 * Provides functionality for handling options.
38 * Basic interface for providing options is implemented by the Options class
39 * and classes defined in basicoptions.h for specifying individual options.
40 * Only these are needed if a class wants to provide a set of standard options.
42 * Values for options can be set using option parsers.
43 * Currently, only one is defined: CommandLineParser.
44 * As the name suggests, this parser gets values from command-line arguments.
45 * Multiple parsers can be used in sequence to provide option values from
46 * multiple sources; in such cases, if an option is provided in multiple
47 * sources, new values overwrite any values from previous sources.
49 * In most cases, it is desirable to be able to provide a help describing the
50 * available options. When creating an Options object and adding options, it
51 * is possible to add descriptions for individual options as well as for the
52 * whole set of options. These can then be used to write out a help using one
53 * of the provided help writers.
54 * Currently, only one is defined: AsciiHelpWriter
55 * (implementation is not yet complete).
58 * <H3>Advanced Use (in library API)</H3>
60 * It is possible to extend the module with new option types and/or parsers for
63 * To implement new option types, it is necessary to subclass the templates
64 * OptionTemplate and OptionStorageTemplate with the type of the values that
65 * the option should provide as the template argument. After this is done, it
66 * is possible to add options of this new type using Options::addOption().
68 * There is limited support for options that need to share information across
69 * instances, e.g., to store values in a shared external data structure or to
70 * provide a global option to set a common setting for all such options,
71 * provided by the OptionsGlobalProperties class. This mechanism is not
72 * generic, meaning that it is required to change the options module to add
73 * data to this structure.
75 * To implement new parsers, one can use OptionsAssigner, which provides an
76 * interface to set values in an Options object.
78 * There is also an interface to iterate over all options in an Options object.
79 * One should implement the OptionsVisitor interface, and then use
80 * OptionsIterator to apply this visitor to the Options object.
83 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
87 * Public API convenience header for handling of options.
89 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
91 * \ingroup module_options
96 #include "options/basicoptions.h"
97 #include "options/options.h"