src/gromacs/selection/selectionoptionmanager.h

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   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.
  13
  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.
  18  *
  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.
  25  *
  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.
  28  *
  29  * For more info, check our website at http://www.gromacs.org
  30  */
  31 /*! \file
  32  * \brief
  33  * Declares gmx::SelectionOptionManager.
  34  *
  35  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  36  * \inpublicapi
  37  * \ingroup module_selection
  38  */
  39 #ifndef GMX_SELECTION_SELECTIONOPTIONMANAGER_H
  40 #define GMX_SELECTION_SELECTIONOPTIONMANAGER_H
  41
  42 #include <string>
  43
  44 #include "../utility/common.h"
  45
  46 namespace gmx
  47 {
  48
  49 class SelectionCollection;
  50 class SelectionOptionStorage;
  51
  52 /*! \brief
  53  * Handles interaction of selection options with other options and user input.
  54  *
  55  * This class implements interaction of SelectionOption with
  56  * SelectionCollection, and also implements features of SelectionOption that
  57  * require actions outside options parsing.
  58  * It also implements the coupling between SelectionOption and
  59  * SelectionFileOption.
  60  *
  61  * The main features of this class are:
  62  *  - convertOptionValue(), which is used to convert string values into
  63  *    selections for options.
  64  *  - requestOptionDelayedParsing(), which is called by the internal
  65  *    implementation of selection options when an option is provided on the
  66  *    command line without a value.  Such calls are remembered, and the value
  67  *    for all requested options can be later provided by calling one of
  68  *    parseRequestedFromStdin(), parseRequestedFromFile() or
  69  *    parseRequstedFromString().
  70  *
  71  * \see setManagerForSelectionOptions()
  72  *
  73  * \inpublicapi
  74  * \ingroup module_selection
  75  */
  76 class SelectionOptionManager
  77 {
  78     public:
  79         /*! \brief
  80          * Creates a manager for selection options.
  81          *
  82          * \throws  std::bad_alloc if out of memory.
  83          */
  84         explicit SelectionOptionManager(SelectionCollection *selections);
  85         ~SelectionOptionManager();
  86
  87         /*! \brief
  88          * Adds a selection option to be managed.
  89          *
  90          * \param     storage  Storage object for the option to register.
  91          * \throws    std::bad_alloc if out of memory.
  92          *
  93          * This is only for internal use by the selection module.
  94          * It is not possible to obtain a SelectionOptionStorage pointer
  95          * through any public or library API.
  96          *
  97          * Strong exception safety.
  98          */
  99         void registerOption(SelectionOptionStorage *storage);
 100         /*! \brief
 101          * Converts a string value to selections for an option.
 102          *
 103          * \param     storage  Storage object to receive the selections.
 104          * \param[in] value    Value to convert.
 105          * \throws    std::bad_alloc if out of memory.
 106          * \throws    InvalidInputError if the selection string is not valid,
 107          *      or uses a feature not supported by the option.
 108          *
 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.
 112          */
 113         void convertOptionValue(SelectionOptionStorage *storage,
 114                                 const std::string &value);
 115         /*! \brief
 116          * Adds a selection option for delayed user input.
 117          *
 118          * \param     storage  Storage object for the option to request.
 119          * \throws    std::bad_alloc if out of memory.
 120          *
 121          * This is only for internal use by the selection module.
 122          * It is not possible to obtain a SelectionOptionStorage pointer
 123          * through any public or library API.
 124          *
 125          * Strong exception safety.
 126          */
 127         void requestOptionDelayedParsing(SelectionOptionStorage *storage);
 128
 129         /*! \brief
 130          * Parses selection(s) from standard input for options not yet
 131          * provided.
 132          *
 133          * \param[in]  bInteractive Whether the parser should behave
 134          *      interactively.
 135          * \throws     unspecified  Can throw any exception thrown by
 136          *      SelectionCollection::parseFromStdin().
 137          * \throws     std::bad_alloc if out of memory.
 138          *
 139          * This method cooperates with SelectionOption to allow interactive
 140          * input of requested selections after all options have been processed.
 141          * It should be called after the Options::finish() method has been
 142          * called on all options that add selections to this collection.
 143          * For each required selection option that has not been given, as well
 144          * as for optional selection options that have been specified without
 145          * values, it will prompt the user to input the necessary selections.
 146          */
 147         void parseRequestedFromStdin(bool bInteractive);
 148         /*! \brief
 149          * Parses selection(s) from a file for options not yet provided.
 150          *
 151          * \param[in]  filename Name of the file to parse selections from.
 152          * \throws     unspecified  Can throw any exception thrown by
 153          *      SelectionCollection::parseFromFile().
 154          * \throws     std::bad_alloc if out of memory.
 155          * \throws     InvalidInputError if
 156          *      - the number of selections in \p filename doesn't match the
 157          *        number requested.
 158          *      - any selection uses a feature that is not allowed for the
 159          *        corresponding option.
 160          *      - if there is a request for any number of selections that is
 161          *        not the last (in which case it is not possible to determine
 162          *        which selections belong to which request).
 163          *
 164          * This method behaves as parseRequestedFromStdin(), with two
 165          * exceptions:
 166          *  -# It reads the selections from a file instead of standard input.
 167          *  -# If no requests are pending, assigns values to all required
 168          *     options that have not yet been set.
 169          *
 170          * This method used to implement SelectionFileOption.
 171          *
 172          * \see parseRequestedFromStdin()
 173          */
 174         void parseRequestedFromFile(const std::string &filename);
 175         /*! \brief
 176          * Parses selection(s) from a string for options not yet provided.
 177          *
 178          * \param[in]  str     String to parse.
 179          * \throws     unspecified  Can throw any exception thrown by
 180          *      SelectionCollection::parseFromString().
 181          * \throws     std::bad_alloc if out of memory.
 182          * \throws     InvalidInputError in same conditions as
 183          *      parseRequestedFromFile().
 184          *
 185          * This method behaves as parseRequestedFromFile(), but reads the
 186          * selections from a string instead of a file.
 187          * This method is mainly used for testing.
 188          *
 189          * \see parseRequestedFromFile()
 190          */
 191         void parseRequestedFromString(const std::string &str);
 192
 193     private:
 194         class Impl;
 195
 196         PrivateImplPointer<Impl> impl_;
 197
 198         /*! \brief
 199          * Needed for handling delayed selection parsing requests.
 200          */
 201         friend class SelectionOptionStorage;
 202 };
 203
 204 } // namespace gmx
 205
 206 #endif