src/gromacs/selection/symrec.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2009,2010,2011,2012,2013 by the GROMACS development team.
   5  * Copyright (c) 2014,2015,2019,2020, by the GROMACS development team, led by
   6  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   7  * and including many others, as listed in the AUTHORS file in the
   8  * top-level source directory and at http://www.gromacs.org.
   9  *
  10  * GROMACS is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public License
  12  * as published by the Free Software Foundation; either version 2.1
  13  * of the License, or (at your option) any later version.
  14  *
  15  * GROMACS is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with GROMACS; if not, see
  22  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  24  *
  25  * If you want to redistribute modifications to GROMACS, please
  26  * consider that scientific software is very special. Version
  27  * control is crucial - bugs must be traceable. We will be happy to
  28  * consider code for inclusion in the official distribution, but
  29  * derived work must not be called official GROMACS. Details are found
  30  * in the README & COPYING files - if they are missing, get the
  31  * official version at http://www.gromacs.org.
  32  *
  33  * To help us fund GROMACS development, we humbly ask that you cite
  34  * the research papers on the package. Check out http://www.gromacs.org.
  35  */
  36 /*! \internal \file
  37  * \brief Handling of selection parser symbol table.
  38  *
  39  * This is an implementation header: there should be no need to use it outside
  40  * this directory.
  41  *
  42  * \author Teemu Murtola <teemu.murtola@gmail.com>
  43  * \ingroup module_selection
  44  */
  45 #ifndef GMX_SELECTION_SYMREC_H
  46 #define GMX_SELECTION_SYMREC_H
  47
  48 #include <iterator>
  49 #include <string>
  50
  51 #include <boost/stl_interfaces/iterator_interface.hpp>
  52
  53 #include "gromacs/utility/classhelpers.h"
  54
  55 #include "selelem.h"
  56
  57 struct gmx_ana_selmethod_t;
  58
  59 namespace gmx
  60 {
  61
  62 class SelectionParserSymbolTable;
  63
  64 /*! \internal
  65  * \brief
  66  * Single symbol for the selection parser.
  67  *
  68  * Public methods in this class do not throw.
  69  *
  70  * \ingroup module_selection
  71  */
  72 class SelectionParserSymbol
  73 {
  74 public:
  75     //! Defines the type of the symbol.
  76     enum SymbolType
  77     {
  78         ReservedSymbol, //!< The symbol is a reserved keyword.
  79         VariableSymbol, //!< The symbol is a variable.
  80         MethodSymbol,   //!< The symbol is a selection method.
  81         PositionSymbol  //!< The symbol is a position keyword.
  82     };
  83
  84     ~SelectionParserSymbol();
  85
  86     //! Returns the name of the symbol.
  87     const std::string& name() const;
  88     //! Returns the type of the symbol.
  89     SymbolType type() const;
  90
  91     /*! \brief
  92      * Returns the method associated with a \ref MethodSymbol symbol.
  93      *
  94      * \returns   The method associated with the symbol.
  95      *
  96      * Must only be called if type() returns \ref MethodSymbol.
  97      */
  98     gmx_ana_selmethod_t* methodValue() const;
  99     /*! \brief
 100      * Returns the selection tree associated with a \ref VariableSymbol symbol.
 101      *
 102      * \returns   The variable expression associated with the symbol.
 103      *
 104      * Must only be called if type() returns \ref VariableSymbol.
 105      */
 106     const SelectionTreeElementPointer& variableValue() const;
 107
 108 private:
 109     class Impl;
 110
 111     /*! \brief
 112      * Initializes a new symbol with the given data.
 113      *
 114      * \param  impl  Implementation data.
 115      * \throws std::bad_alloc if out of memory.
 116      *
 117      * Only the parent symbol table creates symbol objects.
 118      */
 119     explicit SelectionParserSymbol(Impl* impl);
 120
 121     PrivateImplPointer<Impl> impl_;
 122
 123     /*! \brief
 124      * Needed to call the constructor and for other initialization.
 125      */
 126     friend class SelectionParserSymbolTable;
 127 };
 128
 129 /*! \internal
 130  * \brief
 131  * Forward iterator for iterating symbols of a given type.
 132  *
 133  * Behaves as standard C++ forward iterator.  To get an iterator, call
 134  * SelectionParserSymbolTable::beginIterator().  Each time the iterator is
 135  * incremented, it moves to the next symbol of the type given when the iterator
 136  * was created.  When there are no more symbols, the iterator will equal
 137  * SelectionParserSymbolTable::endIterator().  It is not allowed to dereference
 138  * or increment an iterator that has reached the end.
 139  *
 140  * Construction and assignment may throw std::bad_alloc if out of memory.
 141  * Other methods do not throw.
 142  *
 143  * \see SelectionParserSymbolTable::beginIterator()
 144  *
 145  * \ingroup module_selection
 146  */
 147 class SelectionParserSymbolIterator :
 148     public boost::stl_interfaces::iterator_interface<SelectionParserSymbolIterator, std::forward_iterator_tag, const SelectionParserSymbol>
 149 {
 150     using Base =
 151             boost::stl_interfaces::iterator_interface<SelectionParserSymbolIterator, std::forward_iterator_tag, const SelectionParserSymbol>;
 152
 153 public:
 154     //! Creates an independent copy of an iterator.
 155     SelectionParserSymbolIterator(const SelectionParserSymbolIterator& other);
 156     ~SelectionParserSymbolIterator();
 157
 158     //! Creates an independent copy of an iterator.
 159     SelectionParserSymbolIterator& operator=(const SelectionParserSymbolIterator& other);
 160
 161     //! Equality comparison for iterators.
 162     bool operator==(const SelectionParserSymbolIterator& other) const;
 163     //! Dereferences the iterator.
 164     reference operator*() const;
 165     //! Moves the iterator to the next symbol.
 166     SelectionParserSymbolIterator& operator++();
 167     using Base::                   operator++;
 168
 169 private:
 170     class Impl;
 171
 172     /*! \brief
 173      * Initializes a new iterator with the given data.
 174      *
 175      * \param  impl  Implementation data.
 176      *
 177      * Only the parent symbol table can create non-default-constructed
 178      * iterators.
 179      */
 180     explicit SelectionParserSymbolIterator(Impl* impl);
 181
 182     PrivateImplPointer<Impl> impl_;
 183
 184     /*! \brief
 185      * Needed to access the constructor.
 186      */
 187     friend class SelectionParserSymbolTable;
 188 };
 189
 190 /*! \internal \brief
 191  * Symbol table for the selection parser.
 192  *
 193  * \ingroup module_selection
 194  */
 195 class SelectionParserSymbolTable
 196 {
 197 public:
 198     /*! \brief
 199      * Creates a new symbol table.
 200      *
 201      * \throws std::bad_alloc if out of memory.
 202      *
 203      * The created table is initialized with reserved and position symbols.
 204      */
 205     SelectionParserSymbolTable();
 206     ~SelectionParserSymbolTable();
 207
 208     /*! \brief
 209      * Finds a symbol by name.
 210      *
 211      * \param[in] name   Symbol name to find.
 212      * \returns   Pointer to the symbol with name \p name, or
 213      *      NULL if not found.
 214      *
 215      * Does not throw.
 216      */
 217     const SelectionParserSymbol* findSymbol(const std::string& name) const;
 218
 219     /*! \brief
 220      * Returns the start iterator for iterating symbols of a given type.
 221      *
 222      * \param[in] type  Type of symbols to iterate over.
 223      * \returns   Iterator that points to the first symbol of type \p type.
 224      * \throws    std::bad_alloc if out of memory.
 225      *
 226      * \see SelectionParserSymbolIterator
 227      */
 228     SelectionParserSymbolIterator beginIterator(SelectionParserSymbol::SymbolType type) const;
 229     /*! \brief
 230      * Returns the end iterator for symbol iteration.
 231      *
 232      * \throws    std::bad_alloc if out of memory.
 233      *
 234      * Currently, the end value is the same for all symbol types.
 235      *
 236      * \see SelectionParserSymbolIterator
 237      */
 238     SelectionParserSymbolIterator endIterator() const;
 239
 240     /*! \brief
 241      * Adds a new variable symbol.
 242      *
 243      * \param[in] name   Name of the new symbol.
 244      * \param[in] sel    Value of the variable.
 245      * \throws    std::bad_alloc if out of memory.
 246      * \throws    InvalidInputError if there was a symbol with the same
 247      *      name.
 248      */
 249     void addVariable(const char* name, const SelectionTreeElementPointer& sel);
 250     /*! \brief
 251      * Adds a new method symbol.
 252      *
 253      * \param[in] name   Name of the new symbol.
 254      * \param[in] method Method that this symbol represents.
 255      * \throws    std::bad_alloc if out of memory.
 256      * \throws    APIError if there was a symbol with the same name.
 257      */
 258     void addMethod(const char* name, gmx_ana_selmethod_t* method);
 259
 260 private:
 261     class Impl;
 262
 263     PrivateImplPointer<Impl> impl_;
 264
 265     /*! \brief
 266      * Needed to access implementation types.
 267      */
 268     friend class SelectionParserSymbolIterator;
 269 };
 270
 271 } // namespace gmx
 272
 273 #endif