Selection parsing

The selection parser is implemented in the following files:

• scanner.l: Tokenizer implemented using Flex, splits the input into tokens (scanner.c and scanner_flex.h are generated from this file).
• scanner.h, scanner_internal.h, scanner_internal.cpp: Helper functions for scanner.l and for interfacing between scanner.l and parser.y. Functions in scanner_internal.h are only used from scanner.l, while scanner.h is used from the parser.
• symrec.h, symrec.cpp: Functions used by the tokenizer to handle the symbol table, i.e., the recognized keywords. Some basic keywords are hardcoded into scanner.l, but all method and variable references go through the symbol table, as do position evaluation keywords.
• parser.y: Semantic rules for parsing the grammar (parser.cpp and parser.h are generated from this file by Bison).
• parsetree.h, parsetree.cpp: Functions called from actions in parser.y to construct the evaluation elements corresponding to different grammar elements.
• params.c: Defines a function that processes the parameters of selection methods and initializes the children of the method element.
• selectioncollection.h, selectioncollection.cpp: These files define the high-level public interface to the parser through SelectionCollection::parseInteractive(), SelectionCollection::parseFromStdin(), SelectionCollection::parseFromFile(), and SelectionCollection::parseFromString().

The basic control flow in the parser is as follows: when a parser function in SelectionCollection gets called, it performs some initialization, and then calls the _gmx_sel_yyparse() function generated by Bison. This function then calls _gmx_sel_yylex() to repeatedly read tokens from the input (more complex tasks related to token recognition and bookkeeping are done by functions in scanner_internal.cpp) and uses the grammar rules to decide what to do with them. Whenever a grammar rule matches, a corresponding function in parsetree.cpp is called to construct either a temporary representation for the object or a gmx::SelectionTreeElement object (some simple rules are handled internally in parser.y). When a complete selection has been parsed, the functions in parsetree.cpp also take care of updating the gmx_ana_selcollection_t structure appropriately.

The rest of this page describes the resulting gmx::SelectionTreeElement object tree. Before the selections can be evaluated, this tree needs to be passed to the selection compiler, which is described on a separate page: Selection compilation

Element tree constructed by the parser

The parser initializes the following fields in all selection elements: gmx::SelectionTreeElement::name, gmx::SelectionTreeElement::type, gmx::SelectionTreeElement::v.type, gmx::SelectionTreeElement::flags, gmx::SelectionTreeElement::child, and gmx::SelectionTreeElement::next. Some other fields are also initialized for particular element types as discussed below. Fields that are not initialized are set to zero, NULL, or other similar value.

Root elements

The parser creates a SEL_ROOT selection element for each variable assignment and each selection. However, there are two exceptions that do not result in a SEL_ROOT element (in these cases, only the symbol table is modified):

• Variable assignments that assign a variable to another variable.
• Variable assignments that assign a non-group constant.

The SEL_ROOT elements are linked together in a chain in the same order as in the input.

The children of the SEL_ROOT elements can be used to distinguish the two types of root elements from each other:

• For variable assignments, the first and only child is always a SEL_SUBEXPR element.
• For selections, the first child is a SEL_EXPRESSION or a SEL_MODIFIER element that evaluates the final positions (if the selection defines a constant position, the child is a SEL_CONST). The rest of the children are SEL_MODIFIER elements with NO_VALUE, in the order given by the user.

The name of the selection/variable is stored in gmx::SelectionTreeElement::cgrp.name. It is set to either the name provided by the user or the selection string for selections not explicitly named by the user. SEL_ROOT or SEL_SUBEXPR elements do not appear anywhere else.

Constant elements

SEL_CONST elements are created for every constant that is required for later evaluation. Currently, SEL_CONST elements can be present for

• selections that consist of a constant position,
• GROUP_VALUE method parameters if provided using external index groups,

For group-valued elements, the value is stored in gmx::SelectionTreeElement::cgrp; other types of values are stored in gmx::SelectionTreeElement::v. Constants that appear as parameters for selection methods are not present in the selection tree unless they have GROUP_VALUE. SEL_CONST elements have no children.

Method evaluation elements

SEL_EXPRESSION and SEL_MODIFIER elements are treated very similarly. The gmx_ana_selmethod_t structure corresponding to the evaluation method is in gmx::SelectionTreeElement::method, and the method data in gmx::SelectionTreeElement::mdata has been allocated using sel_datafunc(). If a non-standard reference position type was set, gmx::SelectionTreeElement::pc has also been created, but only the type has been set. All children of these elements are of the type SEL_SUBEXPRREF, and each describes a selection that needs to be evaluated to obtain a value for one parameter of the method. No children are present for parameters that were given a constant non-GROUP_VALUE value. The children are sorted in the order in which the parameters appear in the gmx_ana_selmethod_t structure.

In addition to actual selection keywords, SEL_EXPRESSION elements are used internally to implement numerical comparisons (e.g., "x < 5") and keyword matching (e.g., "resnr 1 to 3" or "name CA").

Subexpression elements

SEL_SUBEXPR elements only appear for variables, as described above. gmx::SelectionTreeElement::name points to the name of the variable (from the SEL_ROOT element). The element always has exactly one child, which represents the value of the variable.

SEL_SUBEXPRREF elements are used for two purposes:

• Variable references that need to be evaluated (i.e., there is a SEL_SUBEXPR element for the variable) are represented using SEL_SUBEXPRREF elements. In this case, gmx::SelectionTreeElement::param is NULL, and the first and only child of the element is the SEL_SUBEXPR element of the variable. Such references can appear anywhere where the variable value (the child of the SEL_SUBEXPR element) would be valid.
• Children of SEL_EXPRESSION and SEL_MODIFIER elements are always of this type. For these elements, gmx::SelectionTreeElement::param is initialized to point to the parameter that receives the value from the expression. Each such element has exactly one child, which can be of any type; the SEL_SUBEXPR element of a variable is used if the value comes from a variable, otherwise the child type is not SEL_SUBEXPR.

Boolean elements

One SEL_BOOLEAN element is created for each boolean keyword in the input, and the tree structure represents the evaluation order. The gmx::SelectionTreeElement::boolt type gives the type of the operation. Each element has exactly two children (one for BOOL_NOT elements), which are in the order given in the input. The children always have GROUP_VALUE, but different element types are possible.

Arithmetic elements

One SEL_ARITHMETIC element is created for each arithmetic operation in the input, and the tree structure represents the evaluation order. The gmx::SelectionTreeElement::optype type gives the name of the operation. Each element has exactly two children (one for unary negation elements), which are in the order given in the input.