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 "gromacs/utility/classhelpers.h"
  52
  53 #include "selelem.h"
  54
  55 struct gmx_ana_selmethod_t;
  56
  57 namespace gmx
  58 {
  59
  60 class SelectionParserSymbolTable;
  61
  62 /*! \internal
  63  * \brief
  64  * Single symbol for the selection parser.
  65  *
  66  * Public methods in this class do not throw.
  67  *
  68  * \ingroup module_selection
  69  */
  70 class SelectionParserSymbol
  71 {
  72 public:
  73     //! Defines the type of the symbol.
  74     enum SymbolType
  75     {
  76         ReservedSymbol, //!< The symbol is a reserved keyword.
  77         VariableSymbol, //!< The symbol is a variable.
  78         MethodSymbol,   //!< The symbol is a selection method.
  79         PositionSymbol  //!< The symbol is a position keyword.
  80     };
  81
  82     ~SelectionParserSymbol();
  83
  84     //! Returns the name of the symbol.
  85     const std::string& name() const;
  86     //! Returns the type of the symbol.
  87     SymbolType type() const;
  88
  89     /*! \brief
  90      * Returns the method associated with a \ref MethodSymbol symbol.
  91      *
  92      * \returns   The method associated with the symbol.
  93      *
  94      * Must only be called if type() returns \ref MethodSymbol.
  95      */
  96     gmx_ana_selmethod_t* methodValue() const;
  97     /*! \brief
  98      * Returns the selection tree associated with a \ref VariableSymbol symbol.
  99      *
 100      * \returns   The variable expression associated with the symbol.
 101      *
 102      * Must only be called if type() returns \ref VariableSymbol.
 103      */
 104     const SelectionTreeElementPointer& variableValue() const;
 105
 106 private:
 107     class Impl;
 108
 109     /*! \brief
 110      * Initializes a new symbol with the given data.
 111      *
 112      * \param  impl  Implementation data.
 113      * \throws std::bad_alloc if out of memory.
 114      *
 115      * Only the parent symbol table creates symbol objects.
 116      */
 117     explicit SelectionParserSymbol(Impl* impl);
 118
 119     PrivateImplPointer<Impl> impl_;
 120
 121     /*! \brief
 122      * Needed to call the constructor and for other initialization.
 123      */
 124     friend class SelectionParserSymbolTable;
 125 };
 126
 127 /*! \internal
 128  * \brief
 129  * Input iterator for iterating symbols of a given type.
 130  *
 131  * Behaves as standard C++ input iterator.  To get an iterator, call
 132  * SelectionParserSymbolTable::beginIterator().  Each time the iterator is
 133  * incremented, it moves to the next symbol of the type given when the iterator
 134  * was created.  When there are no more symbols, the iterator will equal
 135  * SelectionParserSymbolTable::endIterator().  It is not allowed to dereference
 136  * or increment an iterator that has reached the end.
 137  *
 138  * Construction and assignment may throw std::bad_alloc if out of memory.
 139  * Other methods do not throw.
 140  *
 141  * \see SelectionParserSymbolTable::beginIterator()
 142  *
 143  * \ingroup module_selection
 144  */
 145 class SelectionParserSymbolIterator
 146 {
 147 public:
 148     /*! \name Iterator type traits
 149      * Satisfies the requirements for STL input iterator.
 150      * \{
 151      */
 152     using iterator_category = std::input_iterator_tag;
 153     using value_type        = const SelectionParserSymbol;
 154     using difference_type   = std::ptrdiff_t;
 155     using pointer           = const SelectionParserSymbol*;
 156     using reference         = const SelectionParserSymbol&;
 157     //! \}
 158
 159     //! Creates an independent copy of an iterator.
 160     SelectionParserSymbolIterator(const SelectionParserSymbolIterator& other);
 161     ~SelectionParserSymbolIterator();
 162
 163     //! Creates an independent copy of an iterator.
 164     SelectionParserSymbolIterator& operator=(const SelectionParserSymbolIterator& other);
 165
 166     //! Equality comparison for iterators.
 167     bool operator==(const SelectionParserSymbolIterator& other) const;
 168     //! Inequality comparison for iterators.
 169     bool operator!=(const SelectionParserSymbolIterator& other) const { return !operator==(other); }
 170     //! Dereferences the iterator.
 171     reference operator*() const;
 172     //! Dereferences the iterator.
 173     pointer operator->() const { return &operator*(); }
 174     //! Moves the iterator to the next symbol.
 175     SelectionParserSymbolIterator& operator++();
 176     //! Moves the iterator to the next symbol.
 177     SelectionParserSymbolIterator operator++(int)
 178     {
 179         SelectionParserSymbolIterator tmp(*this);
 180                                       operator++();
 181         return tmp;
 182     }
 183
 184 private:
 185     class Impl;
 186
 187     /*! \brief
 188      * Initializes a new iterator with the given data.
 189      *
 190      * \param  impl  Implementation data.
 191      *
 192      * Only the parent symbol table can create non-default-constructed
 193      * iterators.
 194      */
 195     explicit SelectionParserSymbolIterator(Impl* impl);
 196
 197     PrivateImplPointer<Impl> impl_;
 198
 199     /*! \brief
 200      * Needed to access the constructor.
 201      */
 202     friend class SelectionParserSymbolTable;
 203 };
 204
 205 /*! \internal \brief
 206  * Symbol table for the selection parser.
 207  *
 208  * \ingroup module_selection
 209  */
 210 class SelectionParserSymbolTable
 211 {
 212 public:
 213     /*! \brief
 214      * Creates a new symbol table.
 215      *
 216      * \throws std::bad_alloc if out of memory.
 217      *
 218      * The created table is initialized with reserved and position symbols.
 219      */
 220     SelectionParserSymbolTable();
 221     ~SelectionParserSymbolTable();
 222
 223     /*! \brief
 224      * Finds a symbol by name.
 225      *
 226      * \param[in] name   Symbol name to find.
 227      * \returns   Pointer to the symbol with name \p name, or
 228      *      NULL if not found.
 229      *
 230      * Does not throw.
 231      */
 232     const SelectionParserSymbol* findSymbol(const std::string& name) const;
 233
 234     /*! \brief
 235      * Returns the start iterator for iterating symbols of a given type.
 236      *
 237      * \param[in] type  Type of symbols to iterate over.
 238      * \returns   Iterator that points to the first symbol of type \p type.
 239      * \throws    std::bad_alloc if out of memory.
 240      *
 241      * \see SelectionParserSymbolIterator
 242      */
 243     SelectionParserSymbolIterator beginIterator(SelectionParserSymbol::SymbolType type) const;
 244     /*! \brief
 245      * Returns the end iterator for symbol iteration.
 246      *
 247      * \throws    std::bad_alloc if out of memory.
 248      *
 249      * Currently, the end value is the same for all symbol types.
 250      *
 251      * \see SelectionParserSymbolIterator
 252      */
 253     SelectionParserSymbolIterator endIterator() const;
 254
 255     /*! \brief
 256      * Adds a new variable symbol.
 257      *
 258      * \param[in] name   Name of the new symbol.
 259      * \param[in] sel    Value of the variable.
 260      * \throws    std::bad_alloc if out of memory.
 261      * \throws    InvalidInputError if there was a symbol with the same
 262      *      name.
 263      */
 264     void addVariable(const char* name, const SelectionTreeElementPointer& sel);
 265     /*! \brief
 266      * Adds a new method symbol.
 267      *
 268      * \param[in] name   Name of the new symbol.
 269      * \param[in] method Method that this symbol represents.
 270      * \throws    std::bad_alloc if out of memory.
 271      * \throws    APIError if there was a symbol with the same name.
 272      */
 273     void addMethod(const char* name, gmx_ana_selmethod_t* method);
 274
 275 private:
 276     class Impl;
 277
 278     PrivateImplPointer<Impl> impl_;
 279
 280     /*! \brief
 281      * Needed to access implementation types.
 282      */
 283     friend class SelectionParserSymbolIterator;
 284 };
 285
 286 } // namespace gmx
 287
 288 #endif