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 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.
  59  *
  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().
  67  *
  68  * \see setManagerForSelectionOptions()
  69  *
  70  * \inpublicapi
  71  * \ingroup module_selection
  72  */
  73 class SelectionOptionManager
  74 {
  75     public:
  76         /*! \brief
  77          * Creates a manager for selection options.
  78          *
  79          * \throws  std::bad_alloc if out of memory.
  80          */
  81         explicit SelectionOptionManager(SelectionCollection *selections);
  82         ~SelectionOptionManager();
  83
  84         /*! \brief
  85          * Returns the selection collection for this manager.
  86          *
  87          * Does not throw.
  88          */
  89         SelectionCollection &selectionCollection();
  90         /*! \brief
  91          * Adds a selection option for delayed user input.
  92          *
  93          * \param     storage  Storage object for the option to request.
  94          * \throws    std::bad_alloc if out of memory.
  95          *
  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.
  99          *
 100          * Strong exception safety.
 101          */
 102         void requestDelayedParsing(SelectionOptionStorage *storage);
 103
 104         /*! \brief
 105          * Parses selection(s) from standard input for options not yet
 106          * provided.
 107          *
 108          * \param[in]  bInteractive Whether the parser should behave
 109          *      interactively.
 110          * \throws     unspecified  Can throw any exception thrown by
 111          *      SelectionCollection::parseFromStdin().
 112          * \throws     std::bad_alloc if out of memory.
 113          *
 114          * This method cooperates with SelectionOption to allow interactive
 115          * input of requested selections after all options have been processed.
 116          * It should be called after the Options::finish() method has been
 117          * called on all options that add selections to this collection.
 118          * For each required selection option that has not been given, as well
 119          * as for optional selection options that have been specified without
 120          * values, it will prompt the user to input the necessary selections.
 121          */
 122         void parseRequestedFromStdin(bool bInteractive);
 123         /*! \brief
 124          * Parses selection(s) from a file for options not yet provided.
 125          *
 126          * \param[in]  filename Name of the file to parse selections from.
 127          * \throws     unspecified  Can throw any exception thrown by
 128          *      SelectionCollection::parseFromFile().
 129          * \throws     std::bad_alloc if out of memory.
 130          * \throws     InvalidInputError if
 131          *      - the number of selections in \p filename doesn't match the
 132          *        number requested.
 133          *      - any selection uses a feature that is not allowed for the
 134          *        corresponding option.
 135          *      - if there is a request for any number of selections that is
 136          *        not the last (in which case it is not possible to determine
 137          *        which selections belong to which request).
 138          *
 139          * This method behaves as parseRequestedFromStdin(), but reads the
 140          * selections from a file instead of standard input.
 141          * This is used to implement SelectionFileOption.
 142          *
 143          * \see parseRequestedFromStdin()
 144          */
 145         void parseRequestedFromFile(const std::string &filename);
 146         /*! \brief
 147          * Parses selection(s) from a string for options not yet provided.
 148          *
 149          * \param[in]  str     String to parse.
 150          * \throws     unspecified  Can throw any exception thrown by
 151          *      SelectionCollection::parseFromString().
 152          * \throws     std::bad_alloc if out of memory.
 153          * \throws     InvalidInputError in same conditions as
 154          *      parseRequestedFromFile().
 155          *
 156          * This method behaves as parseRequestedFromFile(), but reads the
 157          * selections from a string instead of a file.
 158          * This method is mainly used for testing.
 159          *
 160          * \see parseRequestedFromFile()
 161          */
 162         void parseRequestedFromString(const std::string &str);
 163
 164     private:
 165         class Impl;
 166
 167         PrivateImplPointer<Impl> impl_;
 168
 169         /*! \brief
 170          * Needed for handling delayed selection parsing requests.
 171          */
 172         friend class SelectionOptionStorage;
 173 };
 174
 175 } // namespace gmx
 176
 177 #endif