libSBML C API  libSBML 5.8.0 C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
L3Parser.h File Reference

Detailed Description

Definition of the level 3 infix-to-mathml parser C functions.

Author
Lucian Smith
Include dependency graph for L3Parser.h:
This graph shows which files directly or indirectly include this file:

Functions

L3ParserSettings_t * SBML_getDefaultL3ParserSettings ()
 Returns a copy of the default parser settings used by. More...
 
char * SBML_getLastParseL3Error ()
 Returns the last error reported by the parser. More...
 
ASTNode_t * SBML_parseL3Formula (const char *formula)
 Parses the given mathematical formula and returns a representation of it as an Abstract Syntax Tree (AST). More...
 
ASTNode_t * SBML_parseL3FormulaWithModel (const char *formula, const Model_t *model)
 Parses the given mathematical formula using specific a specific Model to resolve symbols, and returns an Abstract Syntax Tree (AST) representation of the result. More...
 
ASTNode_t * SBML_parseL3FormulaWithSettings (const char *formula, const L3ParserSettings_t *settings)
 Parses the given mathematical formula using specific parser settings and returns an Abstract Syntax Tree (AST) representation of the result. More...
 

Function Documentation

L3ParserSettings_t* SBML_getDefaultL3ParserSettings ( )

Returns a copy of the default parser settings used by.

The settings structure allows callers to change the following parsing behaviors:

  • Use a specific Model object against which identifiers to compare identifiers. This causes the parser to search the Model for identifiers that the parser encounters in the formula. If a given symbol in the formula matches the identifier of a Species, Compartment, Parameter, Reaction, SpeciesReference or FunctionDefinition in the Model, then the symbol is assumed to refer to that model entity instead of any possible mathematical terms with the same symbol. For example, 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/>.
  • Whether to parse "log(x)" with a single argument as the base 10 logarithm of x, the natural logarithm of x, or treat the case as an error.
  • Whether to parse "number id" by interpreting id as the identifier of a unit of measurement associated with the number, or whether to treat the case as an error.
  • Whether to parse "avogadro" as an ASTNode of type AST_NAME_AVOGADRO or as type AST_NAME.
  • Whether to always create explicit ASTNodes of type AST_MINUS for all unary minuses, or collapse and remove minuses where possible.

For more details about the parser, please see the definition of L3ParserSettings and

char* SBML_getLastParseL3Error ( )

Returns the last error reported by the parser.

If, , or return NULL, an error is set internally which is accessible via this function.

Returns
a string describing the error that occurred. This will contain the string the parser was trying to parse, which character it had parsed when it encountered the error, and a description of the error.
ASTNode_t* SBML_parseL3Formula ( const char *  formula)

Parses the given mathematical formula and returns a representation of it as an Abstract Syntax Tree (AST).

The text-string form of mathematical formulas read by this function are expanded versions of the formats produced and read by and , respectively. The latter two libSBML functions were originally developed to support conversion between SBML Levels 1 and 2, and were focused on the syntax of mathematical formulas used in SBML Level 1. With time, and the use of MathML in SBML Levels 2 and 3, it became clear that supporting Level 2 and 3's expanded mathematical syntax would be useful for software developers. To maintain backwards compatibility, the original

and

have been left untouched, and instead, the new functionality is provided in the form of The following are the differences in the formula syntax supported by this function, compared to what is supported by:

  • Units may be asociated with bare numbers, using the following syntax:
    number unit
    The number may be in any form (an integer, real, or rational number), and the unit must conform to the syntax of an SBML identifier (technically, the type defined as SId in the SBML specifications). The whitespace between number and unit is optional.
  • The Boolean function symbols &&, ||, !, and != may be used.
  • The modulo operation is allowed as the symbol % and will produce a piecewise function in the MathML.
  • All inverse trigonometric functions may be defined in the infix either using arc as a prefix or simply a; in other words, both arccsc and acsc are interpreted as the operator arccosecant defined in MathML. (Many functions in the SBML Level 1 infix-notation parser implemented by are defined this way as well, but not all.)
  • The following expression is parsed as a rational number instead of as a numerical division:
    (integer/integer)
    No spaces are allowed in this construct; in other words, "(3 / 4)" will be parsed into the MathML <divide> construct rather than a rational number. The general number syntax allows you to assign units to a rational number, e.g., "(3/4) ml". (If the string is a division, units are not interpreted in this way.)
  • Various settings may be altered by using an L3ParserSettings object in conjunction with the alternative function call , including the following:
    • 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/>.
    These configuration settings cannot be changed using this function (i.e.,), but they can be change on a per-call basis by using the alternative function

This function returns the root node of the AST corresponding to the formula given as the argument. If the formula contains a syntax error, this function will return NULL instead. When NULL is returned, an error is set; information about the error can be retrieved using Note that this facility and the SBML Level 1-based are provided as a convenience by libSBML—the MathML standard does not actually define a "string-form" equivalent to MathML expressions, so the choice of formula syntax is arbitrary. The approach taken by libSBML is to start with the syntax defined by SBML Level 1 (which in fact used a text-string representation of formulas, and not MathML), and expand it to include the above functionality. This formula syntax is based mostly on C programming syntax, and may contain operators, function calls, symbols, and white space characters. The following table provides the precedence rules for the different entities that may appear in formula strings.

Token Operation Class Precedence Associates
namesymbol referenceoperand10n/a
(expression)expression groupingoperand10n/a
f(...)function callprefix9left
-negationunary8right
^powerbinary7left
*, /, %multiplication, division, and modulobinary6left
+, -addition and subtractionbinary5left
!boolean 'not'unary4right
==, <, >, <=, >=, !=boolean equality, inequality, and comparisonbinary3left
&&, ||boolean 'and' and 'or'binary2left
,argument delimiterbinary1left
A table of the expression operators and their precedence in the text-string format for mathematical expressions used by SBML_parseL3Formula().

In the table above, operand implies the construct is an operand, prefix implies the operation is applied to the following arguments, unary implies there is one argument, and binary implies there are two arguments. The values in the Precedence column show how the order of different types of operation are determined. For example, the expression a + b * c is evaluated as a + (b * c) because the * operator has higher precedence. The Associates column shows how the order of similar precedence operations is determined; for example, a && b || c is evaluated as (a && b) || c because the && and || operators are left-associative and have the same precedence.

The function call syntax consists of a function name, followed by optional white space, followed by an opening parenthesis token, followed by a sequence of zero or more arguments separated by commas (with each comma optionally preceded and/or followed by zero or more white space characters), followed by a closing parenthesis token. The function name must be chosen from one of the pre-defined functions in SBML or a user-defined function in the model. The following table lists the names of certain common mathematical functions; this table corresponds to Table 6 in the SBML Level 1 Version 2 specification with additions based on the functions added in SBML Level 2 and Level 3:

Name Argument(s) Formula or meaning Argument Constraints Result constraints
abs x Absolute value of x.
acos, arccos x Arccosine of x in radians. -1.0 ≤ x ≤ 1.0 0 ≤ acos(x) ≤ π
acosh, arccosh x Hyperbolic arccosine of x in radians.
acot, arccot x Arccotangent of x in radians.
acoth, arccoth x Hyperbolic arccotangent of x in radians.
acsc, arccsc x Arccosecant of x in radians.
acsch, arccsch x Hyperbolic arccosecant of x in radians.
asec, arcsec x Arcsecant of x in radians.
asech, arcsech x Hyperbolic arcsecant of x in radians.
asin, arcsin xArcsine of x in radians. -1.0 ≤ x ≤ 1.0 0 ≤ asin(x) ≤ π
atan, arctan x Arctangent of x in radians. 0 ≤ atan(x) ≤ π
atanh, arctanh x Hyperbolic arctangent of x in radians.
ceil, ceiling x Smallest number not less than x whose value is an exact integer.
cos x Cosine of x
cosh x Hyperbolic cosine of x.
cot x Cotangent of x.
coth x Hyperbolic cotangent of x.
csc x Cosecant of x.
csch x Hyperbolic cosecant of x.
delay x, y The value of x at y time units in the past.
factorial n The factorial of n. Factorials are defined by n! = n*(n-1)* ... * 1. n must be an integer.
exp x e x, where e is the base of the natural logarithm.
floor x The largest number not greater than x whose value is an exact integer.
ln x Natural logarithm of x. x > 0
log x By default, the base 10 logarithm of x, but can be set to be the natural logarithm of x, or to be an illegal construct. x > 0
log x, y The base x logarithm of y. y > 0
log10 x Base 10 logarithm of x. x > 0
piecewise x1, y1, [x2, y2,] [...] [z] A piecewise function: if (y1), x1. Otherwise, if (y2), x2, etc. Otherwise, z. y1, y2, y3 [etc] must be boolean
pow, power x, y x y.
root b, x The root base b of x.
sec x Secant of x.
sech x Hyperbolic secant of x.
sqr x x2.
sqrt x x. x > 0 sqrt(x) ≥ 0
sin x Sine of x.
sinh x Hyperbolic sine of x.
tan x Tangent of x. x ≠ n*π/2, for odd integer n
tanh x Hyperbolic tangent of x.
and x, y, z... Boolean and(x, y, z...): returns true if all of its arguments are true. Note that 'and' is an n-ary function, taking 0 or more arguments, and that and() returns 'true'. All arguments must be boolean
not x Boolean not(x) x must be boolean
or x, y, z... Boolean or(x, y, z...): returns true if at least one of its arguments is true. Note that 'or' is an n-ary function, taking 0 or more arguments, and that or() returns 'false'. All arguments must be boolean
xor x, y, z... Boolean xor(x, y, z...): returns true if an odd number of its arguments is true. Note that 'xor' is an n-ary function, taking 0 or more arguments, and that xor() returns 'false'. All arguments must be boolean
eq x, y, z... Boolean eq(x, y, z...): returns true if all arguments are equal. Note that 'eq' is an n-ary function, but must take 2 or more arguments.
geq x, y, z... Boolean geq(x, y, z...): returns true if each argument is greater than or equal to the argument following it. Note that 'geq' is an n-ary function, but must take 2 or more arguments.
gt x, y, z... Boolean gt(x, y, z...): returns true if each argument is greater than the argument following it. Note that 'gt' is an n-ary function, but must take 2 or more arguments.
leq x, y, z... Boolean leq(x, y, z...): returns true if each argument is less than or equal to the argument following it. Note that 'leq' is an n-ary function, but must take 2 or more arguments.
lt x, y, z... Boolean lt(x, y, z...): returns true if each argument is less than the argument following it. Note that 'lt' is an n-ary function, but must take 2 or more arguments.
neq x, y Boolean x != y: returns true unless x and y are equal.
plus x, y, z... x + y + z + ...: The sum of the arguments of the function. Note that 'plus' is an n-ary function taking 0 or more arguments, and that 'plus()' returns 0.
times x, y, z... x * y * z * ...: The product of the arguments of the function. Note that 'times' is an n-ary function taking 0 or more arguments, and that 'times()' returns 1.
minus x, y x - y.
divide x, y x / y.
The names of mathematical functions defined in the text-string formula syntax understood by SBML_parseL3Formula() and related functions.

Note that this function's interpretation of the string "log" as a function with a single argument can be changed; use the function instead of this function and pass it an appropriate L3ParserSettings object. By default, unlike the SBML Level 1 parser implemented by , the string "log" is interpreted as the base 10 logarithm, and not as the natural logarithm. However, you can change the interpretation to be base-10 log, natural log, or as an error; since the name "log" by itself is ambiguous, you require that the parser uses log10 or ln instead, which are more clear. Please refer to In addition, the following symbols will be translated to their MathML equivalents, if no symbol with the same SId identifier string exists in the Model object provided:

Name Meaning MathML
true The boolean value true <true/>
false The boolean value false <false/>
pi The mathematical constant pi <pi/>
avogadro The numerical value of Avogadro's constant, as defined in the SBML specification <csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/avogadro"> avogadro </csymbol/>
time Simulation time as defined in SBML <csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/time"> time </csymbol/>
inf or infinity The mathematical constant "infinity" <infinity/>
nan or notanumber The mathematical concept "not a number" <notanumber/>
The names of mathematical symbols defined in the text-string formula syntax understood by SBML_parseL3Formula() and related functions.

Note that whether the string "avogadro" is parsed as an AST node of type AST_NAME_AVOGADRO or AST_NAME is configurable; use the alternate version of this function, calledThis functionality is provided because SBML Level 2 models may not use AST_NAME_AVOGADRO AST nodes.

Parameters
formulathe text-string formula expression to be parsed
Returns
the root node of an AST representing the mathematical formula, or NULL if an error occurred while parsing the formula. When NULL is returned, an error is recorded internally; information about the error can be retrieved using
ASTNode_t* SBML_parseL3FormulaWithModel ( const char *  formula,
const Model_t *  model 
)

Parses the given mathematical formula using specific a specific Model to resolve symbols, and returns an Abstract Syntax Tree (AST) representation of the result.

This is identical to , except that this function uses the given model in the argument model to check against identifiers that appear in the formula.

For more details about the parser, please see the definition of the function.

Parameters
formulathe mathematical formula expression to be parsed
modelthe Model object to use for checking identifiers
Returns
the root node of an AST representing the mathematical formula, or NULL if an error occurred while parsing the formula. When NULL is returned, an error is recorded internally; information about the error can be retrieved using
ASTNode_t* SBML_parseL3FormulaWithSettings ( const char *  formula,
const L3ParserSettings_t *  settings 
)

Parses the given mathematical formula using specific parser settings and returns an Abstract Syntax Tree (AST) representation of the result.

This is identical to , except that this function uses the parser settings given in the argument settings. The settings override the default parsing behavior.

The parameter settings allows callers to change the following parsing behaviors:

  • Use a specific Model object against which identifiers to compare identifiers. This causes the parser to search the Model for identifiers that the parser encounters in the formula. If a given symbol in the formula matches the identifier of a Species, Compartment, Parameter, Reaction, SpeciesReference or FunctionDefinition in the Model, then the symbol is assumed to refer to that model entity instead of any possible mathematical terms with the same symbol. For example, 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/>.
  • Whether to parse "log(x)" with a single argument as the base 10 logarithm of x, the natural logarithm of x, or treat the case as an error.
  • Whether to parse "number id" by interpreting id as the identifier of a unit of measurement associated with the number, or whether to treat the case as an error.
  • Whether to parse "avogadro" as an ASTNode of type AST_NAME_AVOGADRO or as type AST_NAME.
  • Whether to always create explicit ASTNodes of type AST_MINUS for all unary minuses, or collapse and remove minuses where possible.

For more details about the parser, please see the definition of L3ParserSettings and

Parameters
formulathe mathematical formula expression to be parsed
settingsthe settings to be used for this parser invocation
Returns
the root node of an AST representing the mathematical formula, or NULL if an error occurred while parsing the formula. When NULL is returned, an error is recorded internally; information about the error can be retrieved using