src/gromacs/selection/parsetree.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2009,2010,2011,2012,2013,2014, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \internal \file
  36  * \brief
  37  * Handling of intermediate selection parser data.
  38  *
  39  * The data types declared in this header are used by the parser to store
  40  * intermediate data when constructing method expressions.
  41  * In particular, the parameters for the method are stored.
  42  * The intermediate data is freed once a gmx::SelectionTreeElement object can
  43  * be constructed.
  44  *
  45  * This is an implementation header: there should be no need to use it outside
  46  * this directory.
  47  *
  48  * \author Teemu Murtola <teemu.murtola@gmail.com>
  49  * \ingroup module_selection
  50  */
  51 #ifndef GMX_SELECTION_PARSETREE_H
  52 #define GMX_SELECTION_PARSETREE_H
  53
  54 #include <exception>
  55 #include <list>
  56 #include <string>
  57
  58 #include "gromacs/math/vec.h"
  59 #include "gromacs/math/vectypes.h"
  60 #include "gromacs/utility/gmxassert.h"
  61 #include "gromacs/utility/real.h"
  62 #include "gromacs/utility/uniqueptr.h"
  63
  64 #include "selelem.h"
  65 #include "selvalue.h"
  66
  67 struct gmx_ana_indexgrps_t;
  68 struct gmx_ana_selmethod_t;
  69 struct gmx_ana_selparam_t;
  70
  71 namespace gmx
  72 {
  73
  74 //! \cond internal
  75 /*! \internal \brief
  76  * String matching mode for string keyword expressions.
  77  *
  78  * \ingroup module_selection
  79  */
  80 enum SelectionStringMatchType
  81 {
  82     eStringMatchType_Auto,              //!< Deduce from the string.
  83     eStringMatchType_Exact,             //!< Match as a literal string.
  84     eStringMatchType_Wildcard,          //!< Match using ? and * as wildcards.
  85     eStringMatchType_RegularExpression  //!< Match using regular expressions.
  86 };
  87 /*! \endcond */
  88
  89 class SelectionParserValue;
  90
  91 //! Container for a list of SelectionParserValue objects.
  92 typedef std::list<SelectionParserValue>
  93     SelectionParserValueList;
  94 //! Smart pointer type for managing a SelectionParserValueList.
  95 typedef gmx::gmx_unique_ptr<SelectionParserValueList>::type
  96     SelectionParserValueListPointer;
  97
  98 /*! \internal
  99  * \brief
 100  * Describes a parsed value, possibly resulting from expression evaluation.
 101  *
 102  * All factory methods and the constructors may throw an std::bad_alloc if
 103  * out of memory.
 104  *
 105  * \ingroup module_selection
 106  */
 107 class SelectionParserValue
 108 {
 109     public:
 110         //! Allocates and initializes an empty value list.
 111         static SelectionParserValueListPointer createList()
 112         {
 113             return SelectionParserValueListPointer(new SelectionParserValueList);
 114         }
 115         /*! \brief
 116          * Allocates and initializes a value list with a single value.
 117          *
 118          * \param[in] value  Initial value to put in the list.
 119          * \returns   Pointer to a new value list that contains \p value.
 120          */
 121         static SelectionParserValueListPointer
 122         createList(const SelectionParserValue &value)
 123         {
 124             SelectionParserValueListPointer list(new SelectionParserValueList);
 125             list->push_back(value);
 126             return move(list);
 127         }
 128         /*! \brief
 129          * Allocates and initializes an expression value.
 130          *
 131          * \param[in] expr  Root of the expression tree to assign to the value.
 132          * \returns   The newly created value.
 133          */
 134         static SelectionParserValue
 135         createExpr(const gmx::SelectionTreeElementPointer &expr)
 136         {
 137             return SelectionParserValue(expr);
 138         }
 139         /*! \brief
 140          * Allocates and initializes a constant integer value.
 141          *
 142          * \param[in] value    Integer value to assign to the value.
 143          * \param[in] location Location of the value.
 144          * \returns   The newly created value.
 145          */
 146         static SelectionParserValue
 147         createInteger(int value, const SelectionLocation &location)
 148         {
 149             SelectionParserValue result(INT_VALUE, location);
 150             result.u.i.i1 = result.u.i.i2 = value;
 151             return result;
 152         }
 153         /*! \brief
 154          * Allocates and initializes a constant integer range value.
 155          *
 156          * \param[in] from     Beginning of the range to assign to the value.
 157          * \param[in] to       End of the range to assign to the value.
 158          * \param[in] location Location of the value.
 159          * \returns   The newly created value.
 160          */
 161         static SelectionParserValue
 162         createIntegerRange(int from, int to, const SelectionLocation &location)
 163         {
 164             SelectionParserValue result(INT_VALUE, location);
 165             result.u.i.i1 = from;
 166             result.u.i.i2 = to;
 167             return result;
 168         }
 169         /*! \brief
 170          * Allocates and initializes a constant floating-point value.
 171          *
 172          * \param[in] value    Floating-point value to assign to the value.
 173          * \param[in] location Location of the value.
 174          * \returns   The newly created value.
 175          */
 176         static SelectionParserValue
 177         createReal(real value, const SelectionLocation &location)
 178         {
 179             SelectionParserValue result(REAL_VALUE, location);
 180             result.u.r.r1 = result.u.r.r2 = value;
 181             return result;
 182         }
 183         /*! \brief
 184          * Allocates and initializes a constant floating-point range value.
 185          *
 186          * \param[in] from     Beginning of the range to assign to the value.
 187          * \param[in] to       End of the range to assign to the value.
 188          * \param[in] location Location of the value.
 189          * \returns   The newly created value.
 190          */
 191         static SelectionParserValue
 192         createRealRange(real from, real to, const SelectionLocation &location)
 193         {
 194             SelectionParserValue result(REAL_VALUE, location);
 195             result.u.r.r1 = from;
 196             result.u.r.r2 = to;
 197             return result;
 198         }
 199         /*! \brief
 200          * Allocates and initializes a constant string value.
 201          *
 202          * \param[in] value    String to assign to the value.
 203          * \param[in] location Location of the value.
 204          * \returns   The newly created value.
 205          */
 206         static SelectionParserValue
 207         createString(const char *value, const SelectionLocation &location)
 208         {
 209             SelectionParserValue result(STR_VALUE, location);
 210             result.str = value;
 211             return result;
 212         }
 213         /*! \brief
 214          * Allocates and initializes a constant position value.
 215          *
 216          * \param[in] value    Position vector to assign to the value.
 217          * \param[in] location Location of the value.
 218          * \returns   The newly created value.
 219          */
 220         static SelectionParserValue
 221         createPosition(rvec value, const SelectionLocation &location)
 222         {
 223             SelectionParserValue result(POS_VALUE, location);
 224             copy_rvec(value, result.u.x);
 225             return result;
 226         }
 227
 228         //! Returns the location of this value in the parsed selection text.
 229         const SelectionLocation &location() const { return location_; }
 230         //! Returns true if the value comes from expression evaluation.
 231         bool hasExpressionValue() const { return static_cast<bool>(expr); }
 232
 233         //! Returns the string value (\a type must be ::STR_VALUE).
 234         const std::string &stringValue() const
 235         {
 236             GMX_ASSERT(type == STR_VALUE && !hasExpressionValue(),
 237                        "Attempted to retrieve string value from a non-string value");
 238             return str;
 239         }
 240
 241         // TODO: boost::any or similar could be nicer for the implementation.
 242         //! Type of the value.
 243         e_selvalue_t                     type;
 244         //! Expression pointer if the value is the result of an expression.
 245         gmx::SelectionTreeElementPointer expr;
 246         //! String value for \a type ::STR_VALUE.
 247         std::string                      str;
 248         //! The actual value if \a expr is NULL and \a type is not ::STR_VALUE.
 249         union {
 250             //! The integer value/range (\a type ::INT_VALUE).
 251             struct {
 252                 //! Beginning of the range.
 253                 int             i1;
 254                 //! End of the range; equals \a i1 for a single integer.
 255                 int             i2;
 256             }                   i;
 257             //! The real value/range (\a type ::REAL_VALUE).
 258             struct {
 259                 //! Beginning of the range.
 260                 real            r1;
 261                 //! End of the range; equals \a r1 for a single number.
 262                 real            r2;
 263             }                   r;
 264             //! The position value (\a type ::POS_VALUE).
 265             rvec                x;
 266         }                       u;
 267
 268     private:
 269         /*! \brief
 270          * Initializes a new value.
 271          *
 272          * \param[in] type     Type for the new value.
 273          * \param[in] location Location for the value.
 274          */
 275         SelectionParserValue(e_selvalue_t type, const SelectionLocation &location);
 276         /*! \brief
 277          * Initializes a new expression value.
 278          *
 279          * \param[in] expr  Expression for the value.
 280          */
 281         explicit SelectionParserValue(const gmx::SelectionTreeElementPointer &expr);
 282
 283         //! Location of the value in the parsed text.
 284         SelectionLocation       location_;
 285 };
 286
 287 class SelectionParserParameter;
 288
 289 //! Container for a list of SelectionParserParameter objects.
 290 typedef std::list<SelectionParserParameter>
 291     SelectionParserParameterList;
 292 //! Smart pointer type for managing a SelectionParserParameterList.
 293 typedef gmx::gmx_unique_ptr<SelectionParserParameterList>::type
 294     SelectionParserParameterListPointer;
 295
 296 /*! \internal \brief
 297  * Describes a parsed method parameter.
 298  *
 299  * \ingroup module_selection
 300  */
 301 class SelectionParserParameter
 302 {
 303     public:
 304         //! Allocates and initializes an empty parameter list.
 305         static SelectionParserParameterListPointer createList()
 306         {
 307             return SelectionParserParameterListPointer(
 308                     new SelectionParserParameterList);
 309         }
 310         /*! \brief
 311          * Allocates and initializes a parsed method parameter.
 312          *
 313          * \param[in] name     Name for the new parameter (can be NULL).
 314          * \param[in] values   List of values for the parameter.
 315          * \param[in] location Location of the parameter.
 316          * \returns   Pointer to the newly allocated parameter.
 317          * \throws    std::bad_alloc if out of memory.
 318          */
 319         static SelectionParserParameter
 320         create(const char *name, SelectionParserValueListPointer values,
 321                const SelectionLocation &location)
 322         {
 323             return SelectionParserParameter(name, move(values), location);
 324         }
 325         //! \copydoc create(const char *, SelectionParserValueListPointer, const SelectionLocation &)
 326         static SelectionParserParameter
 327         create(const std::string &name, SelectionParserValueListPointer values,
 328                const SelectionLocation &location)
 329         {
 330             return SelectionParserParameter(name.c_str(), move(values), location);
 331         }
 332         /*! \brief
 333          * Allocates and initializes a parsed method parameter.
 334          *
 335          * \param[in] name     Name for the new parameter (can be NULL).
 336          * \param[in] value    Value for the parameter.
 337          * \param[in] location Location of the parameter.
 338          * \returns   Pointer to the newly allocated parameter.
 339          * \throws    std::bad_alloc if out of memory.
 340          *
 341          * This overload is a convenience wrapper for the case when creating
 342          * parameters outside the actual Bison parser and only a single value
 343          * is necessary.
 344          */
 345         static SelectionParserParameter
 346         create(const char *name, const SelectionParserValue &value,
 347                const SelectionLocation &location)
 348         {
 349             return create(name, SelectionParserValue::createList(value), location);
 350         }
 351         /*! \brief
 352          * Allocates and initializes a parsed method parameter.
 353          *
 354          * \param[in] name    Name for the new parameter (can be NULL).
 355          * \param[in] expr    Expression value for the parameter.
 356          * \returns   Pointer to the newly allocated parameter.
 357          * \throws    std::bad_alloc if out of memory.
 358          *
 359          * This overload is a convenience wrapper for the case when creating
 360          * parameters outside the actual Bison parser and only a single
 361          * expression value is necessary.
 362          */
 363         static SelectionParserParameter
 364         createFromExpression(const char                        *name,
 365                              const SelectionTreeElementPointer &expr)
 366         {
 367             return create(name, SelectionParserValue::createExpr(expr),
 368                           expr->location());
 369         }
 370         //! \copydoc createFromExpression(const char *, const SelectionTreeElementPointer &)
 371         static SelectionParserParameter
 372         createFromExpression(const std::string                 &name,
 373                              const SelectionTreeElementPointer &expr)
 374         {
 375             return create(name.c_str(), SelectionParserValue::createExpr(expr),
 376                           expr->location());
 377         }
 378
 379         //! Returns the name of the parameter (may be empty).
 380         const std::string &name() const { return name_; }
 381         //! Returns the location of this parameter in the parsed selection text.
 382         const SelectionLocation        &location() const { return location_; }
 383         //! Returns the values for the parameter.
 384         const SelectionParserValueList &values() const { return *values_; }
 385
 386     private:
 387         /*! \brief
 388          * Initializes a parsed method parameter.
 389          *
 390          * \param[in] name     Name for the new parameter (can be NULL).
 391          * \param[in] values   List of values for the parameter.
 392          * \param[in] location Location of the parameter.
 393          * \throws    std::bad_alloc if out of memory.
 394          */
 395         SelectionParserParameter(const char                      *name,
 396                                  SelectionParserValueListPointer  values,
 397                                  const SelectionLocation         &location);
 398
 399         //! Name of the parameter.
 400         std::string                     name_;
 401         //! Location of the parameter in the parsed text.
 402         SelectionLocation               location_;
 403
 404         // TODO: Make private, there is only one direct user.
 405     public:
 406         //! Values for this parameter.
 407         SelectionParserValueListPointer values_;
 408 };
 409
 410 } // namespace gmx
 411
 412 /** Error reporting function for the selection parser. */
 413 void
 414 _gmx_selparser_error(void *scanner, const char *fmt, ...);
 415 /*! \brief
 416  * Handles exceptions caught within the Bison code.
 417  *
 418  * \retval `true`  if the parser should attempt error recovery.
 419  * \retval `false` if the parser should immediately abort.
 420  *
 421  * This function is called whenever an exception is caught within Bison
 422  * actions.  Since exceptions cannot propagate through Bison code, the
 423  * exception is saved (potentially with some extra context information) so that
 424  * the caller of the parser can rethrow the exception.
 425  *
 426  * If it is possible to recover from the exception, then the function returns
 427  * `true`, and Bison enters error recovery state.  At the end of the recovery,
 428  * _gmx_selparser_handle_error() is called.
 429  * If this function returns false, then Bison immediately aborts the parsing
 430  * so that the caller can rethrow the exception.
 431  */
 432 bool
 433 _gmx_selparser_handle_exception(void *scanner, std::exception *ex);
 434 /*! \brief
 435  * Handles errors in the selection parser.
 436  *
 437  * \returns `true` if parsing can continue with the next selection.
 438  * \throws  std::bad_alloc if out of memory during the error processing.
 439  * \throws  unspecified    Can throw the stored exception if recovery from that
 440  *     exception is not possible.
 441  *
 442  * This function is called during error recovery, after Bison has discarded all
 443  * the symbols for the erroneous selection.
 444  * At this point, the full selection that caused the error is known, and can be
 445  * added to the error context.
 446  *
 447  * For an interactive parser, this function returns `true` to let the parsing
 448  * continue with the next selection, or to let the user enter the next
 449  * selection, if it was possible to recover from the exception.
 450  * For other cases, this will either rethrow the original exception with added
 451  * context, or return `false` after adding the context to the error reporter.
 452  * Any exceptions thrown from this method are again caught by Bison and result
 453  * in termination of the parsing; the caller can then rethrow them.
 454  */
 455 bool
 456 _gmx_selparser_handle_error(void *scanner);
 457
 458 /** Propagates the flags for selection elements. */
 459 void
 460 _gmx_selelem_update_flags(const gmx::SelectionTreeElementPointer &sel);
 461
 462 /** Initializes the method parameter data of \ref SEL_EXPRESSION and
 463  * \ref SEL_MODIFIER elements. */
 464 void
 465 _gmx_selelem_init_method_params(const gmx::SelectionTreeElementPointer &sel,
 466                                 void                                   *scanner);
 467 /** Initializes the method for a \ref SEL_EXPRESSION selection element. */
 468 void
 469 _gmx_selelem_set_method(const gmx::SelectionTreeElementPointer &sel,
 470                         struct gmx_ana_selmethod_t *method, void *scanner);
 471
 472 /* An opaque pointer. */
 473 #ifndef YY_TYPEDEF_YY_SCANNER_T
 474 #define YY_TYPEDEF_YY_SCANNER_T
 475 typedef void* yyscan_t;
 476 #endif
 477 /** \brief Creates a gmx::SelectionTreeElement for arithmetic expression evaluation.
 478  *
 479  * \param[in]  left    Selection element for the left hand side.
 480  * \param[in]  right   Selection element for the right hand side.
 481  * \param[in]  op      String representation of the operator.
 482  * \param[in]  scanner Scanner data structure.
 483  * \returns    The created selection element.
 484  *
 485  * This function handles the creation of a gmx::SelectionTreeElement object for
 486  * arithmetic expressions.
 487  */
 488 gmx::SelectionTreeElementPointer
 489 _gmx_sel_init_arithmetic(const gmx::SelectionTreeElementPointer &left,
 490                          const gmx::SelectionTreeElementPointer &right,
 491                          char op, yyscan_t scanner);
 492 /** Creates a gmx::SelectionTreeElement for comparsion expression evaluation. */
 493 gmx::SelectionTreeElementPointer
 494 _gmx_sel_init_comparison(const gmx::SelectionTreeElementPointer &left,
 495                          const gmx::SelectionTreeElementPointer &right,
 496                          const char *cmpop, void *scanner);
 497 /** Creates a gmx::SelectionTreeElement for a keyword expression from the parsed data. */
 498 gmx::SelectionTreeElementPointer
 499 _gmx_sel_init_keyword(struct gmx_ana_selmethod_t *method,
 500                       gmx::SelectionParserValueListPointer args,
 501                       const char *rpost, void *scanner);
 502 /** Creates a gmx::SelectionTreeElement for string-matching keyword expression. */
 503 gmx::SelectionTreeElementPointer
 504 _gmx_sel_init_keyword_strmatch(struct gmx_ana_selmethod_t *method,
 505                                gmx::SelectionStringMatchType matchType,
 506                                gmx::SelectionParserValueListPointer args,
 507                                const char *rpost, void *scanner);
 508 /** Creates a gmx::SelectionTreeElement for "keyword of" expression. */
 509 gmx::SelectionTreeElementPointer
 510 _gmx_sel_init_keyword_of(struct gmx_ana_selmethod_t *method,
 511                          const gmx::SelectionTreeElementPointer &group,
 512                          const char *rpost, void *scanner);
 513 /** Creates a gmx::SelectionTreeElement for a method expression from the parsed data. */
 514 gmx::SelectionTreeElementPointer
 515 _gmx_sel_init_method(struct gmx_ana_selmethod_t *method,
 516                      gmx::SelectionParserParameterListPointer params,
 517                      const char *rpost, void *scanner);
 518 /** Creates a gmx::SelectionTreeElement for a modifier expression from the parsed data. */
 519 gmx::SelectionTreeElementPointer
 520 _gmx_sel_init_modifier(struct gmx_ana_selmethod_t              *mod,
 521                        gmx::SelectionParserParameterListPointer params,
 522                        const gmx::SelectionTreeElementPointer  &sel,
 523                        void                                    *scanner);
 524 /** Creates a gmx::SelectionTreeElement for evaluation of reference positions. */
 525 gmx::SelectionTreeElementPointer
 526 _gmx_sel_init_position(const gmx::SelectionTreeElementPointer &expr,
 527                        const char *type, void *scanner);
 528
 529 /** Creates a gmx::SelectionTreeElement for a constant position. */
 530 gmx::SelectionTreeElementPointer
 531 _gmx_sel_init_const_position(real x, real y, real z, void *scanner);
 532 /** Creates a gmx::SelectionTreeElement for a index group expression using group name. */
 533 gmx::SelectionTreeElementPointer
 534 _gmx_sel_init_group_by_name(const char *name, void *scanner);
 535 /** Creates a gmx::SelectionTreeElement for a index group expression using group index. */
 536 gmx::SelectionTreeElementPointer
 537 _gmx_sel_init_group_by_id(int id, void *scanner);
 538 /** Creates a gmx::SelectionTreeElement for a variable reference */
 539 gmx::SelectionTreeElementPointer
 540 _gmx_sel_init_variable_ref(const gmx::SelectionTreeElementPointer &sel,
 541                            void                                   *scanner);
 542
 543 /** Creates a root gmx::SelectionTreeElement for a selection. */
 544 gmx::SelectionTreeElementPointer
 545 _gmx_sel_init_selection(const char                             *name,
 546                         const gmx::SelectionTreeElementPointer &sel,
 547                         void                                   *scanner);
 548 /** Creates a root gmx::SelectionTreeElement elements for a variable assignment. */
 549 gmx::SelectionTreeElementPointer
 550 _gmx_sel_assign_variable(const char                             *name,
 551                          const gmx::SelectionTreeElementPointer &expr,
 552                          void                                   *scanner);
 553 /** Appends a root gmx::SelectionTreeElement to a selection collection. */
 554 gmx::SelectionTreeElementPointer
 555 _gmx_sel_append_selection(const gmx::SelectionTreeElementPointer &sel,
 556                           gmx::SelectionTreeElementPointer        last,
 557                           void                                   *scanner);
 558 /** Check whether the parser should finish. */
 559 bool
 560 _gmx_sel_parser_should_finish(void *scanner);
 561
 562 /* In params.c */
 563 /** Initializes an array of parameters based on input from the selection parser. */
 564 void
 565 _gmx_sel_parse_params(const gmx::SelectionParserParameterList &params,
 566                       int nparam, struct gmx_ana_selparam_t *param,
 567                       const gmx::SelectionTreeElementPointer &root,
 568                       void *scanner);
 569
 570 #endif