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
33 * Declares gmx::SelectionOptionManager.
35 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
37 * \ingroup module_selection
39 #ifndef GMX_SELECTION_SELECTIONOPTIONMANAGER_H
40 #define GMX_SELECTION_SELECTIONOPTIONMANAGER_H
44 #include "../utility/common.h"
49 class SelectionCollection;
50 class SelectionOptionStorage;
53 * Handles interaction of selection options with other options and user input.
55 * This class implements features of SelectionOption that require actions
56 * outside options parsing. It is also used to pass the selection collection
57 * to the selection options, and to implement the coupling between
58 * SelectionOption and SelectionFileOption.
60 * The main feature of this class (in addition to passing the
61 * selectionCollection() method) is that the internal implementation of
62 * selection options calls requestDelayedParsing() when an option is provided
63 * on the command line without a value. Such calls are remembered, and
64 * the value for all requested options can be later provided by calling one of
65 * parseRequestedFromStdin(), parseRequestedFromFile() or
66 * parseRequstedFromString().
68 * \see setManagerForSelectionOptions()
71 * \ingroup module_selection
73 class SelectionOptionManager
77 * Creates a manager for selection options.
79 * \throws std::bad_alloc if out of memory.
81 explicit SelectionOptionManager(SelectionCollection *selections);
82 ~SelectionOptionManager();
85 * Returns the selection collection for this manager.
89 SelectionCollection &selectionCollection();
91 * Adds a selection option to be managed.
93 * \param storage Storage object for the option to register.
94 * \throws std::bad_alloc if out of memory.
96 * This is only for internal use by the selection module.
97 * It is not possible to obtain a SelectionOptionStorage pointer
98 * through any public or library API.
100 * Strong exception safety.
102 void registerOption(SelectionOptionStorage *storage);
104 * Adds a selection option for delayed user input.
106 * \param storage Storage object for the option to request.
107 * \throws std::bad_alloc if out of memory.
109 * This is only for internal use by the selection module.
110 * It is not possible to obtain a SelectionOptionStorage pointer
111 * through any public or library API.
113 * Strong exception safety.
115 void requestDelayedParsing(SelectionOptionStorage *storage);
118 * Parses selection(s) from standard input for options not yet
121 * \param[in] bInteractive Whether the parser should behave
123 * \throws unspecified Can throw any exception thrown by
124 * SelectionCollection::parseFromStdin().
125 * \throws std::bad_alloc if out of memory.
127 * This method cooperates with SelectionOption to allow interactive
128 * input of requested selections after all options have been processed.
129 * It should be called after the Options::finish() method has been
130 * called on all options that add selections to this collection.
131 * For each required selection option that has not been given, as well
132 * as for optional selection options that have been specified without
133 * values, it will prompt the user to input the necessary selections.
135 void parseRequestedFromStdin(bool bInteractive);
137 * Parses selection(s) from a file for options not yet provided.
139 * \param[in] filename Name of the file to parse selections from.
140 * \throws unspecified Can throw any exception thrown by
141 * SelectionCollection::parseFromFile().
142 * \throws std::bad_alloc if out of memory.
143 * \throws InvalidInputError if
144 * - the number of selections in \p filename doesn't match the
146 * - any selection uses a feature that is not allowed for the
147 * corresponding option.
148 * - if there is a request for any number of selections that is
149 * not the last (in which case it is not possible to determine
150 * which selections belong to which request).
152 * This method behaves as parseRequestedFromStdin(), with two
154 * -# It reads the selections from a file instead of standard input.
155 * -# If no requests are pending, assigns values to all required
156 * options that have not yet been set.
158 * This method used to implement SelectionFileOption.
160 * \see parseRequestedFromStdin()
162 void parseRequestedFromFile(const std::string &filename);
164 * Parses selection(s) from a string for options not yet provided.
166 * \param[in] str String to parse.
167 * \throws unspecified Can throw any exception thrown by
168 * SelectionCollection::parseFromString().
169 * \throws std::bad_alloc if out of memory.
170 * \throws InvalidInputError in same conditions as
171 * parseRequestedFromFile().
173 * This method behaves as parseRequestedFromFile(), but reads the
174 * selections from a string instead of a file.
175 * This method is mainly used for testing.
177 * \see parseRequestedFromFile()
179 void parseRequestedFromString(const std::string &str);
184 PrivateImplPointer<Impl> impl_;
187 * Needed for handling delayed selection parsing requests.
189 friend class SelectionOptionStorage;