libSBML C API  libSBML 5.8.0 C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
L3ParserSettings_t Class Reference

Detailed Description

A helper class for controlling the behavior of the text-string formula parser.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The function , along with its variants

and , are the interfaces to a parser for mathematical formulas expressed as text strings. The parser converts the text-string formulas into Abstract Syntax Trees (ASTs), represented in libSBML using ASTNode objects. Compared to the parser implemented by the function , which was designed primarily for converting the mathematical formula strings in SBML Level 1, the "L3" variant of the parser accepts an extended formula syntax. It also has a number of configurable behaviors. This class (L3ParserSettings) is an object used to communicate the configuration settings with callers.

The following aspects of the parser are configurable:

  • The function log with a single argument ("log(x)") can be parsed as log10(x), ln(x), or treated as an error, as desired.
  • Unary minus signs can be collapsed or preserved; that is, sequential pairs of unary minuses (e.g., "- -3") can be removed from the input entirely and single unary minuses can be incorporated into the number node, or all minuses can be preserved in the AST node structure.
  • Parsing of units embedded in the input string can be turned on and off.
  • The string avogadro can be parsed as a MathML csymbol or as an identifier.
  • A Model object may optionally be provided to the parser using the variant function call. or stored in a L3ParserSettings object passed to the variant functionWhen a Model object is provided, identifiers (values of type SId) from that model are used in preference to pre-defined MathML definitions. More precisely, the Model entities whose identifiers will shadow identical symbols in the mathematical formula are: Species, Compartment, Parameter, Reaction, and SpeciesReference. For instance, if the parser is given a Model containing a Species with the identifier "pi", and the formula to be parsed is "3*pi", the MathML produced will contain the construct <ci> pi </ci> instead of the construct <pi/>.
  • Similarly, when a Model object is provided, SId values of user-defined functions present in the Model will be used preferentially over pre-defined MathML functions. For example, if the passed-in Model contains a FunctionDefinition with the identifier "sin", that function will be used instead of the predefined MathML function <sin/>.

To obtain the default configuration values, callers can use the functionTo change the configuration, callers can create an L3ParserSettings object, set the desired characteristics using the methods provided, and pass that object to