public class L3ParserSettings extends java.lang.Object
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
libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)
,
along with its variants libsbml.parseL3Formula(String)
and
libsbml.parseL3FormulaWithModel(String, Model)
,
are the interfaces to a parser for mathematical formulas written as
text strings. The inverse function is libsbml.formulaToL3String(ASTNode)
and its variants such as
libsbml.formulaToL3StringWithSettings(ASTNode, L3ParserSettings)
.
The parsers and the formula writers convert between a text-string
representation of mathematical formulas and Abstract Syntax Trees (ASTs),
represented in libSBML using ASTNode
objects.
Compared to the parser and writer implemented by the functions
libsbml.parseFormula(String)
and
libsbml.formulaToString(ASTNode)
,
which were designed primarily for converting the mathematical formula
strings in SBML Level 1, the SBML Level 3 or 'L3' variants of
the parser and writer use an extended formula syntax. They also have 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 using
L3ParserSettings
objects. (For the formula writer, only a subset of these
settings is relevant please see the documentation for
libsbml.formulaToL3StringWithSettings(ASTNode, L3ParserSettings)
for more information about which ones).
Model
object may optionally be provided to use identifiers (values
of type SId
) from the model in preference to pre-defined MathML symbols
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 by the parser will
contain the construct <ci> pi </ci>
instead of
the construct <pi/>
. Another 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/>
.
log
with a single argument
("log(x)
") can be parsed as log10(x)
,
ln(x)
, or treated as an error, as desired.
- -3
") from the input and incorporate single unary
minuses into the number node, or (2) preserve all minuses in the AST node
structure, turning them into ASTNode
objects of type
AST_MINUS
.
number id
" can be
interpreted as a numerical value number
followed by units of measurement
indicated by id
, or it can be treated as a syntax error. (In
Level 3, MathML <cn>
elements can have an
attribute named units
placed in the SBML namespace, which can be used
to indicate the units to be associated with the number. The text-string
infix formula parser allows units to be placed after raw numbers they are
interpreted as unit identifiers for units defined by the SBML
specification or in the containing Model
object.)
avogadro
can be parsed either as a MathML csymbol or
as a identifier. More specifically, "avogadro
" can
be treated as an ASTNode
of type
AST_NAME_AVOGADRO
or of type
AST_NAME
.
To obtain the default configuration values, callers can use the function
libsbml.getDefaultL3ParserSettings()
. To change the configuration,
callers can create an L3ParserSettings
object, set the desired
characteristics using the methods provided, and pass that object to
libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)
.
libsbml.parseL3Formula(String)
,
libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)
,
libsbml.parseL3FormulaWithModel(String, Model)
,
libsbml.parseFormula(String)
,
libsbml.formulaToL3StringWithSettings(ASTNode, L3ParserSettings)
,
libsbml.formulaToL3String(ASTNode)
,
libsbml.formulaToString(ASTNode)
,
libsbml.getDefaultL3ParserSettings()
Constructor and Description |
---|
L3ParserSettings()
Creates a new
L3ParserSettings object with default values. |
L3ParserSettings(L3ParserSettings source)
Copy constructor.
|
L3ParserSettings(Model model,
int parselog,
boolean collapseminus,
boolean parseunits,
boolean avocsymbol)
Creates a new
L3ParserSettings object with specific values for all
possible settings. |
L3ParserSettings(Model model,
int parselog,
boolean collapseminus,
boolean parseunits,
boolean avocsymbol,
boolean caseSensitive)
Creates a new
L3ParserSettings object with specific values for all
possible settings. |
L3ParserSettings(Model model,
int parselog,
boolean collapseminus,
boolean parseunits,
boolean avocsymbol,
boolean caseSensitive,
SBMLNamespaces sbmlns)
Creates a new
L3ParserSettings object with specific values for all
possible settings. |
L3ParserSettings(Model model,
int parselog,
boolean collapseminus,
boolean parseunits,
boolean avocsymbol,
boolean caseSensitive,
SBMLNamespaces sbmlns,
boolean moduloL3v2)
Creates a new
L3ParserSettings object with specific values for all
possible settings. |
L3ParserSettings(Model model,
int parselog,
boolean collapseminus,
boolean parseunits,
boolean avocsymbol,
boolean caseSensitive,
SBMLNamespaces sbmlns,
boolean moduloL3v2,
boolean l3v2functions)
Creates a new
L3ParserSettings object with specific values for all
possible settings. |
Modifier and Type | Method and Description |
---|---|
void |
delete()
Explicitly deletes the underlying native object.
|
boolean |
getComparisonCaseSensitivity()
Returns
true if the parser is configured to match built-in symbols
in a case-insensitive way. |
Model |
getModel()
Returns the
Model object referenced by this L3ParserSettings object. |
boolean |
getParseAvogadroCsymbol()
Indicates the current behavior set for handling
avogadro for SBML
Level 3. |
boolean |
getParseCollapseMinus()
Indicates the current behavior set for handling multiple unary minuses
in formulas.
|
boolean |
getParseL3v2Functions()
Indicates the current behavior set for handling the '%' sumbol in
mathematical formulas.
|
int |
getParseLog()
Indicates the current behavior set for handling the function
log with
one argument. |
boolean |
getParseModuloL3v2()
Indicates the current behavior set for handling the '%' sumbol in
mathematical formulas.
|
boolean |
getParseUnits()
Indicates the current behavior set for handling units in text-string
mathematical formulas.
|
void |
setComparisonCaseSensitivity(boolean strcmp)
Sets the parser's behavior with respect to case sensitivity for
recognizing predefined symbols.
|
void |
setModel(Model model)
Sets the model reference in this
L3ParserSettings object. |
void |
setParseAvogadroCsymbol(boolean l2only)
Sets the parser's behavior in handling the symbol
avogadro in
mathematical formulas. |
void |
setParseCollapseMinus(boolean collapseminus)
Sets the behavior for handling unary minuses appearing in mathematical
formulas.
|
void |
setParseL3v2Functions(boolean l3v2functions)
Sets the behavior for handling functions added in SBML L3v2
|
void |
setParseLog(int type)
Sets the behavior for handling
log in mathematical formulas. |
void |
setParseModuloL3v2(boolean modulol3v2)
Sets the behavior for handling the '%' sumbol in mathematical
formulas.
|
void |
setParseUnits(boolean units)
Sets the parser's behavior in handling units associated with numbers
in a mathematical formula.
|
void |
setPlugins(SBMLNamespaces sbmlns)
Set up the plugins for this
L3ParserSettings , based on the
SBMLNamespaces object. |
void |
unsetModel()
Unsets the
Model reference in this L3ParserSettings object. |
public L3ParserSettings()
L3ParserSettings
object with default values.
This is the default constructor for the L3ParserSettings
object. It
sets the stored Model
object to null
and sets the following
field values in the L3ParserSettings
object:
L3P_PARSE_UNITS
.
L3P_EXPAND_UNARY_MINUS
.
L3P_PARSE_LOG_AS_LOG10
.
L3P_AVOGADRO_IS_CSYMBOL
.
L3P_COMPARE_BUILTINS_CASE_INSENSITIVE
.
L3P_MODULO_IS_PIECEWISE
.
null
(which
indicates that no syntax extensions due to SBML Level 3 packages
will be assumed&mdashthe formula parser will only understand the
core syntax described in the documentation for
libsbml.parseL3Formula(String)
).
public L3ParserSettings(Model model, int parselog, boolean collapseminus, boolean parseunits, boolean avocsymbol, boolean caseSensitive, SBMLNamespaces sbmlns, boolean moduloL3v2, boolean l3v2functions)
L3ParserSettings
object with specific values for all
possible settings.
model
- a Model
object to be used for disambiguating identifiers
encountered by libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)
in mathematical formulas.
parselog
- ('parse log') a flag that controls how the parser will
handle the symbol log
in mathematical formulas. The function log
with a single argument ("log(x)
") can be parsed
as log10(x)
, ln(x)
, or treated as an error, as
desired, by using the parameter values
L3P_PARSE_LOG_AS_LOG10
,
L3P_PARSE_LOG_AS_LN
, or
L3P_PARSE_LOG_AS_ERROR
, respectively.
collapseminus
- ('collapse minus') a flag that controls how the
parser will handle minus signs in formulas. 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.
The possible values of this field are
L3P_COLLAPSE_UNARY_MINUS
(to collapse unary minuses) and
L3P_EXPAND_UNARY_MINUS
(to expand unary minuses).
parseunits
- ('parse units') a flag that controls how the parser
will handle apparent references to units of measurement associated with
raw numbers in a formula. If set to the value
L3P_PARSE_UNITS
, units are parsed if set to the value
L3P_NO_UNITS
, units are not parsed.
avocsymbol
- ('Avogadro csymbol') a flag that controls how the
parser will handle the appearance of the symbol avogadro
in a
formula. If set to the value L3P_AVOGADRO_IS_CSYMBOL
,
the symbol is interpreted as the SBML/MathML csymbol avogadro
if
set to the value L3P_AVOGADRO_IS_NAME
, the symbol is
interpreted as a plain symbol name.
caseSensitive
- ('case sensitive') a flag that controls how the
cases of alphabetical characters are treated when symbols are compared.
If the flag is set to the value
L3P_COMPARE_BUILTINS_CASE_INSENSITIVE
, symbols are
compared in a case-insensitive manner, which means that mathematical
functions such as 'sin'
will be matched no matter what their case is:
'Sin'
, 'SIN'
, etc. If the flag is set to the value
L3P_COMPARE_BUILTINS_CASE_SENSITIVE
, symbols are
interpreted in a case-sensitive manner.
moduloL3v2
- ('modulo L3v2') a flag that controls how the
parser will handle the '%' ('modulo') symbol in formulas. By default,
the parser will convert 'a % b' to a piecewise function that properly
calculates the remainder of a with respect to be, but the parser can
also be set to produce the MathML rem
function, should the target
of the produced ASTNode
be an SBML Level 3 Version 2
document, where the rem
function is legal.
The possible values of this field are
L3P_MODULO_IS_PIECEWISE
(to parse '%' as a piecewise function) and
L3P_MODULO_IS_REM
(to parse '%' as rem
).
sbmlns
- ('SBML namespaces') an SBML namespaces object. The
namespaces identify the SBML Level 3 packages that can extend the
syntax understood by the formula parser. When non-null
, the parser
will interpret additional syntax defined by the packages for example,
it may understand vector/array extensions introduced by the SBML
Level 3 Arrays package.
l3v2functions
- ('parse L3v2 functions directly') is a Boolean flag
that controls how to translate certain mathematical functions added in SBML
Level 3 Version 2 Core. The parser can either turn them into
specific AST node types, or turn them all into
AST_FUNCTION
with the name set to the
function name in question.
L3ParserSettings.getModel()
,
L3ParserSettings.setModel(Model)
,
L3ParserSettings.unsetModel()
,
L3ParserSettings.getParseLog()
,
L3ParserSettings.setParseLog(int)
,
L3ParserSettings.getParseUnits()
,
L3ParserSettings.setParseUnits(boolean)
,
L3ParserSettings.getParseCollapseMinus()
,
L3ParserSettings.setParseCollapseMinus(boolean)
,
L3ParserSettings.getParseAvogadroCsymbol()
,
L3ParserSettings.setParseAvogadroCsymbol(boolean)
,
L3ParserSettings.getParseModuloL3v2()
,
L3ParserSettings.setParseModuloL3v2(boolean)
,
L3ParserSettings.getParseL3v2Functions()
,
L3ParserSettings.setParseL3v2Functions(boolean)
public L3ParserSettings(Model model, int parselog, boolean collapseminus, boolean parseunits, boolean avocsymbol, boolean caseSensitive, SBMLNamespaces sbmlns, boolean moduloL3v2)
L3ParserSettings
object with specific values for all
possible settings.
model
- a Model
object to be used for disambiguating identifiers
encountered by libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)
in mathematical formulas.
parselog
- ('parse log') a flag that controls how the parser will
handle the symbol log
in mathematical formulas. The function log
with a single argument ("log(x)
") can be parsed
as log10(x)
, ln(x)
, or treated as an error, as
desired, by using the parameter values
L3P_PARSE_LOG_AS_LOG10
,
L3P_PARSE_LOG_AS_LN
, or
L3P_PARSE_LOG_AS_ERROR
, respectively.
collapseminus
- ('collapse minus') a flag that controls how the
parser will handle minus signs in formulas. 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.
The possible values of this field are
L3P_COLLAPSE_UNARY_MINUS
(to collapse unary minuses) and
L3P_EXPAND_UNARY_MINUS
(to expand unary minuses).
parseunits
- ('parse units') a flag that controls how the parser
will handle apparent references to units of measurement associated with
raw numbers in a formula. If set to the value
L3P_PARSE_UNITS
, units are parsed if set to the value
L3P_NO_UNITS
, units are not parsed.
avocsymbol
- ('Avogadro csymbol') a flag that controls how the
parser will handle the appearance of the symbol avogadro
in a
formula. If set to the value L3P_AVOGADRO_IS_CSYMBOL
,
the symbol is interpreted as the SBML/MathML csymbol avogadro
if
set to the value L3P_AVOGADRO_IS_NAME
, the symbol is
interpreted as a plain symbol name.
caseSensitive
- ('case sensitive') a flag that controls how the
cases of alphabetical characters are treated when symbols are compared.
If the flag is set to the value
L3P_COMPARE_BUILTINS_CASE_INSENSITIVE
, symbols are
compared in a case-insensitive manner, which means that mathematical
functions such as 'sin'
will be matched no matter what their case is:
'Sin'
, 'SIN'
, etc. If the flag is set to the value
L3P_COMPARE_BUILTINS_CASE_SENSITIVE
, symbols are
interpreted in a case-sensitive manner.
moduloL3v2
- ('modulo L3v2') a flag that controls how the
parser will handle the '%' ('modulo') symbol in formulas. By default,
the parser will convert 'a % b' to a piecewise function that properly
calculates the remainder of a with respect to be, but the parser can
also be set to produce the MathML rem
function, should the target
of the produced ASTNode
be an SBML Level 3 Version 2
document, where the rem
function is legal.
The possible values of this field are
L3P_MODULO_IS_PIECEWISE
(to parse '%' as a piecewise function) and
L3P_MODULO_IS_REM
(to parse '%' as rem
).
sbmlns
- ('SBML namespaces') an SBML namespaces object. The
namespaces identify the SBML Level 3 packages that can extend the
syntax understood by the formula parser. When non-null
, the parser
will interpret additional syntax defined by the packages for example,
it may understand vector/array extensions introduced by the SBML
Level 3 Arrays package.
l3v2functions
- ('parse L3v2 functions directly') is a Boolean flag
that controls how to translate certain mathematical functions added in SBML
Level 3 Version 2 Core. The parser can either turn them into
specific AST node types, or turn them all into
AST_FUNCTION
with the name set to the
function name in question.
L3ParserSettings.getModel()
,
L3ParserSettings.setModel(Model)
,
L3ParserSettings.unsetModel()
,
L3ParserSettings.getParseLog()
,
L3ParserSettings.setParseLog(int)
,
L3ParserSettings.getParseUnits()
,
L3ParserSettings.setParseUnits(boolean)
,
L3ParserSettings.getParseCollapseMinus()
,
L3ParserSettings.setParseCollapseMinus(boolean)
,
L3ParserSettings.getParseAvogadroCsymbol()
,
L3ParserSettings.setParseAvogadroCsymbol(boolean)
,
L3ParserSettings.getParseModuloL3v2()
,
L3ParserSettings.setParseModuloL3v2(boolean)
,
L3ParserSettings.getParseL3v2Functions()
,
L3ParserSettings.setParseL3v2Functions(boolean)
public L3ParserSettings(Model model, int parselog, boolean collapseminus, boolean parseunits, boolean avocsymbol, boolean caseSensitive, SBMLNamespaces sbmlns)
L3ParserSettings
object with specific values for all
possible settings.
model
- a Model
object to be used for disambiguating identifiers
encountered by libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)
in mathematical formulas.
parselog
- ('parse log') a flag that controls how the parser will
handle the symbol log
in mathematical formulas. The function log
with a single argument ("log(x)
") can be parsed
as log10(x)
, ln(x)
, or treated as an error, as
desired, by using the parameter values
L3P_PARSE_LOG_AS_LOG10
,
L3P_PARSE_LOG_AS_LN
, or
L3P_PARSE_LOG_AS_ERROR
, respectively.
collapseminus
- ('collapse minus') a flag that controls how the
parser will handle minus signs in formulas. 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.
The possible values of this field are
L3P_COLLAPSE_UNARY_MINUS
(to collapse unary minuses) and
L3P_EXPAND_UNARY_MINUS
(to expand unary minuses).
parseunits
- ('parse units') a flag that controls how the parser
will handle apparent references to units of measurement associated with
raw numbers in a formula. If set to the value
L3P_PARSE_UNITS
, units are parsed if set to the value
L3P_NO_UNITS
, units are not parsed.
avocsymbol
- ('Avogadro csymbol') a flag that controls how the
parser will handle the appearance of the symbol avogadro
in a
formula. If set to the value L3P_AVOGADRO_IS_CSYMBOL
,
the symbol is interpreted as the SBML/MathML csymbol avogadro
if
set to the value L3P_AVOGADRO_IS_NAME
, the symbol is
interpreted as a plain symbol name.
caseSensitive
- ('case sensitive') a flag that controls how the
cases of alphabetical characters are treated when symbols are compared.
If the flag is set to the value
L3P_COMPARE_BUILTINS_CASE_INSENSITIVE
, symbols are
compared in a case-insensitive manner, which means that mathematical
functions such as 'sin'
will be matched no matter what their case is:
'Sin'
, 'SIN'
, etc. If the flag is set to the value
L3P_COMPARE_BUILTINS_CASE_SENSITIVE
, symbols are
interpreted in a case-sensitive manner.
moduloL3v2
- ('modulo L3v2') a flag that controls how the
parser will handle the '%' ('modulo') symbol in formulas. By default,
the parser will convert 'a % b' to a piecewise function that properly
calculates the remainder of a with respect to be, but the parser can
also be set to produce the MathML rem
function, should the target
of the produced ASTNode
be an SBML Level 3 Version 2
document, where the rem
function is legal.
The possible values of this field are
L3P_MODULO_IS_PIECEWISE
(to parse '%' as a piecewise function) and
L3P_MODULO_IS_REM
(to parse '%' as rem
).
sbmlns
- ('SBML namespaces') an SBML namespaces object. The
namespaces identify the SBML Level 3 packages that can extend the
syntax understood by the formula parser. When non-null
, the parser
will interpret additional syntax defined by the packages for example,
it may understand vector/array extensions introduced by the SBML
Level 3 Arrays package.
l3v2functions
- ('parse L3v2 functions directly') is a Boolean flag
that controls how to translate certain mathematical functions added in SBML
Level 3 Version 2 Core. The parser can either turn them into
specific AST node types, or turn them all into
AST_FUNCTION
with the name set to the
function name in question.
L3ParserSettings.getModel()
,
L3ParserSettings.setModel(Model)
,
L3ParserSettings.unsetModel()
,
L3ParserSettings.getParseLog()
,
L3ParserSettings.setParseLog(int)
,
L3ParserSettings.getParseUnits()
,
L3ParserSettings.setParseUnits(boolean)
,
L3ParserSettings.getParseCollapseMinus()
,
L3ParserSettings.setParseCollapseMinus(boolean)
,
L3ParserSettings.getParseAvogadroCsymbol()
,
L3ParserSettings.setParseAvogadroCsymbol(boolean)
,
L3ParserSettings.getParseModuloL3v2()
,
L3ParserSettings.setParseModuloL3v2(boolean)
,
L3ParserSettings.getParseL3v2Functions()
,
L3ParserSettings.setParseL3v2Functions(boolean)
public L3ParserSettings(Model model, int parselog, boolean collapseminus, boolean parseunits, boolean avocsymbol, boolean caseSensitive)
L3ParserSettings
object with specific values for all
possible settings.
model
- a Model
object to be used for disambiguating identifiers
encountered by libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)
in mathematical formulas.
parselog
- ('parse log') a flag that controls how the parser will
handle the symbol log
in mathematical formulas. The function log
with a single argument ("log(x)
") can be parsed
as log10(x)
, ln(x)
, or treated as an error, as
desired, by using the parameter values
L3P_PARSE_LOG_AS_LOG10
,
L3P_PARSE_LOG_AS_LN
, or
L3P_PARSE_LOG_AS_ERROR
, respectively.
collapseminus
- ('collapse minus') a flag that controls how the
parser will handle minus signs in formulas. 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.
The possible values of this field are
L3P_COLLAPSE_UNARY_MINUS
(to collapse unary minuses) and
L3P_EXPAND_UNARY_MINUS
(to expand unary minuses).
parseunits
- ('parse units') a flag that controls how the parser
will handle apparent references to units of measurement associated with
raw numbers in a formula. If set to the value
L3P_PARSE_UNITS
, units are parsed if set to the value
L3P_NO_UNITS
, units are not parsed.
avocsymbol
- ('Avogadro csymbol') a flag that controls how the
parser will handle the appearance of the symbol avogadro
in a
formula. If set to the value L3P_AVOGADRO_IS_CSYMBOL
,
the symbol is interpreted as the SBML/MathML csymbol avogadro
if
set to the value L3P_AVOGADRO_IS_NAME
, the symbol is
interpreted as a plain symbol name.
caseSensitive
- ('case sensitive') a flag that controls how the
cases of alphabetical characters are treated when symbols are compared.
If the flag is set to the value
L3P_COMPARE_BUILTINS_CASE_INSENSITIVE
, symbols are
compared in a case-insensitive manner, which means that mathematical
functions such as 'sin'
will be matched no matter what their case is:
'Sin'
, 'SIN'
, etc. If the flag is set to the value
L3P_COMPARE_BUILTINS_CASE_SENSITIVE
, symbols are
interpreted in a case-sensitive manner.
moduloL3v2
- ('modulo L3v2') a flag that controls how the
parser will handle the '%' ('modulo') symbol in formulas. By default,
the parser will convert 'a % b' to a piecewise function that properly
calculates the remainder of a with respect to be, but the parser can
also be set to produce the MathML rem
function, should the target
of the produced ASTNode
be an SBML Level 3 Version 2
document, where the rem
function is legal.
The possible values of this field are
L3P_MODULO_IS_PIECEWISE
(to parse '%' as a piecewise function) and
L3P_MODULO_IS_REM
(to parse '%' as rem
).
sbmlns
- ('SBML namespaces') an SBML namespaces object. The
namespaces identify the SBML Level 3 packages that can extend the
syntax understood by the formula parser. When non-null
, the parser
will interpret additional syntax defined by the packages for example,
it may understand vector/array extensions introduced by the SBML
Level 3 Arrays package.
l3v2functions
- ('parse L3v2 functions directly') is a Boolean flag
that controls how to translate certain mathematical functions added in SBML
Level 3 Version 2 Core. The parser can either turn them into
specific AST node types, or turn them all into
AST_FUNCTION
with the name set to the
function name in question.
L3ParserSettings.getModel()
,
L3ParserSettings.setModel(Model)
,
L3ParserSettings.unsetModel()
,
L3ParserSettings.getParseLog()
,
L3ParserSettings.setParseLog(int)
,
L3ParserSettings.getParseUnits()
,
L3ParserSettings.setParseUnits(boolean)
,
L3ParserSettings.getParseCollapseMinus()
,
L3ParserSettings.setParseCollapseMinus(boolean)
,
L3ParserSettings.getParseAvogadroCsymbol()
,
L3ParserSettings.setParseAvogadroCsymbol(boolean)
,
L3ParserSettings.getParseModuloL3v2()
,
L3ParserSettings.setParseModuloL3v2(boolean)
,
L3ParserSettings.getParseL3v2Functions()
,
L3ParserSettings.setParseL3v2Functions(boolean)
public L3ParserSettings(Model model, int parselog, boolean collapseminus, boolean parseunits, boolean avocsymbol)
L3ParserSettings
object with specific values for all
possible settings.
model
- a Model
object to be used for disambiguating identifiers
encountered by libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)
in mathematical formulas.
parselog
- ('parse log') a flag that controls how the parser will
handle the symbol log
in mathematical formulas. The function log
with a single argument ("log(x)
") can be parsed
as log10(x)
, ln(x)
, or treated as an error, as
desired, by using the parameter values
L3P_PARSE_LOG_AS_LOG10
,
L3P_PARSE_LOG_AS_LN
, or
L3P_PARSE_LOG_AS_ERROR
, respectively.
collapseminus
- ('collapse minus') a flag that controls how the
parser will handle minus signs in formulas. 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.
The possible values of this field are
L3P_COLLAPSE_UNARY_MINUS
(to collapse unary minuses) and
L3P_EXPAND_UNARY_MINUS
(to expand unary minuses).
parseunits
- ('parse units') a flag that controls how the parser
will handle apparent references to units of measurement associated with
raw numbers in a formula. If set to the value
L3P_PARSE_UNITS
, units are parsed if set to the value
L3P_NO_UNITS
, units are not parsed.
avocsymbol
- ('Avogadro csymbol') a flag that controls how the
parser will handle the appearance of the symbol avogadro
in a
formula. If set to the value L3P_AVOGADRO_IS_CSYMBOL
,
the symbol is interpreted as the SBML/MathML csymbol avogadro
if
set to the value L3P_AVOGADRO_IS_NAME
, the symbol is
interpreted as a plain symbol name.
caseSensitive
- ('case sensitive') a flag that controls how the
cases of alphabetical characters are treated when symbols are compared.
If the flag is set to the value
L3P_COMPARE_BUILTINS_CASE_INSENSITIVE
, symbols are
compared in a case-insensitive manner, which means that mathematical
functions such as 'sin'
will be matched no matter what their case is:
'Sin'
, 'SIN'
, etc. If the flag is set to the value
L3P_COMPARE_BUILTINS_CASE_SENSITIVE
, symbols are
interpreted in a case-sensitive manner.
moduloL3v2
- ('modulo L3v2') a flag that controls how the
parser will handle the '%' ('modulo') symbol in formulas. By default,
the parser will convert 'a % b' to a piecewise function that properly
calculates the remainder of a with respect to be, but the parser can
also be set to produce the MathML rem
function, should the target
of the produced ASTNode
be an SBML Level 3 Version 2
document, where the rem
function is legal.
The possible values of this field are
L3P_MODULO_IS_PIECEWISE
(to parse '%' as a piecewise function) and
L3P_MODULO_IS_REM
(to parse '%' as rem
).
sbmlns
- ('SBML namespaces') an SBML namespaces object. The
namespaces identify the SBML Level 3 packages that can extend the
syntax understood by the formula parser. When non-null
, the parser
will interpret additional syntax defined by the packages for example,
it may understand vector/array extensions introduced by the SBML
Level 3 Arrays package.
l3v2functions
- ('parse L3v2 functions directly') is a Boolean flag
that controls how to translate certain mathematical functions added in SBML
Level 3 Version 2 Core. The parser can either turn them into
specific AST node types, or turn them all into
AST_FUNCTION
with the name set to the
function name in question.
L3ParserSettings.getModel()
,
L3ParserSettings.setModel(Model)
,
L3ParserSettings.unsetModel()
,
L3ParserSettings.getParseLog()
,
L3ParserSettings.setParseLog(int)
,
L3ParserSettings.getParseUnits()
,
L3ParserSettings.setParseUnits(boolean)
,
L3ParserSettings.getParseCollapseMinus()
,
L3ParserSettings.setParseCollapseMinus(boolean)
,
L3ParserSettings.getParseAvogadroCsymbol()
,
L3ParserSettings.setParseAvogadroCsymbol(boolean)
,
L3ParserSettings.getParseModuloL3v2()
,
L3ParserSettings.setParseModuloL3v2(boolean)
,
L3ParserSettings.getParseL3v2Functions()
,
L3ParserSettings.setParseL3v2Functions(boolean)
public L3ParserSettings(L3ParserSettings source)
source
- the instance to copy.public void delete()
In general, application software will not need to call this method directly. The Java language binding for libSBML is implemented as a language wrapper that provides a Java interface to libSBML's underlying C++/C code. Some of the Java methods return objects that are linked to objects created not by Java code, but by C++ code. The Java objects wrapped around them will be deleted when the garbage collector invokes the corresponding C++ finalize()
methods for the objects. The finalize()
methods in turn call the L3ParserSettings.delete()
method on the libSBML object.
This method is exposed in case calling programs want to ensure that the underlying object is freed immediately, and not at some arbitrary time determined by the Java garbage collector. In normal usage, callers do not need to invoke L3ParserSettings.delete()
themselves.
public void setModel(Model model)
L3ParserSettings
object.
When a Model
object is provided, identifiers (values of type SId
)
from that model are used in preference to pre-defined MathML symbol
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/>
.
model
- a Model
object to be used for disambiguating identifiers.
L3ParserSettings.getModel()
,
L3ParserSettings.unsetModel()
Model
object.
This means that modifications made to the Model
after invoking this
method may affect parsing behavior, because the parser will query the
current contents of the model.
public Model getModel()
Model
object referenced by this L3ParserSettings
object.
When a Model
object is provided, identifiers (values of type SId
)
from that model are used in preference to pre-defined MathML symbol
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/>
.
public void unsetModel()
Model
reference in this L3ParserSettings
object.
The effect of calling this method is to set the stored model value
to null.
public void setParseLog(int type)
log
in mathematical formulas.
The function log
with a single argument
("log(x)
") can be parsed as
log10(x)
, ln(x)
, or treated as an error.
These three behaviors are set, respectively, by using the value
L3P_PARSE_LOG_AS_LOG10
,
L3P_PARSE_LOG_AS_LN
, or
L3P_PARSE_LOG_AS_ERROR
for the type
parameter.
type
- a constant, one of following three possibilities:
L3ParserSettings.getParseLog()
public int getParseLog()
log
with
one argument.
The function log
with a single argument
("log(x)
") can be parsed as
log10(x)
, ln(x)
, or treated as an error, as
desired. These three possible behaviors are indicated, respectively, by
the values
L3P_PARSE_LOG_AS_LOG10
,
L3P_PARSE_LOG_AS_LN
, and
L3P_PARSE_LOG_AS_ERROR
.
L3ParserSettings.setParseLog(int)
public void setParseCollapseMinus(boolean collapseminus)
This setting affects two behaviors. First, pairs of multiple unary
minuses in a row (e.g., "- -3
") can be collapsed
and ignored in the input, or the multiple minuses can be preserved in the
AST node tree that is generated by the parser. Second, minus signs in
front of numbers can be collapsed into the number node itself for
example, a "- 4.1
" can be turned into a single
ASTNode
of type AST_REAL
with a value of
-4.1
, or it can be turned into a node of type
AST_MINUS
having a child node of type
AST_REAL
.
This method lets you tell the parser which behavior to use&mdasheither collapse minuses or always preserve them. The two possibilities are represented using the following constants:
L3P_COLLAPSE_UNARY_MINUS
(value = true
): collapse
unary minuses where possible.
L3P_EXPAND_UNARY_MINUS
(value = false
): do not
collapse unary minuses, and instead translate each one into an AST node of
type AST_MINUS
.
collapseminus
- a boolean value (one of the constants
L3P_COLLAPSE_UNARY_MINUS
or
L3P_EXPAND_UNARY_MINUS
)
indicating how unary minus signs in the input should be handled.
L3ParserSettings.getParseCollapseMinus()
public boolean getParseCollapseMinus()
This setting affects two behaviors. First, pairs of multiple unary
minuses in a row (e.g., "- -3
") can be collapsed
and ignored in the input, or the multiple minuses can be preserved in the
AST node tree that is generated by the parser. Second, minus signs in
front of numbers can be collapsed into the number node itself for
example, a "- 4.1
" can be turned into a single
ASTNode
of type AST_REAL
with a value of
-4.1
, or it can be turned into a node of type
AST_MINUS
having a child node of type
AST_REAL
.
L3P_COLLAPSE_UNARY_MINUS
(value = true
): collapse
unary minuses where possible.
L3P_EXPAND_UNARY_MINUS
(value = false
): do not
collapse unary minuses, and instead translate each one into an AST node of
type AST_MINUS
.
L3ParserSettings.setParseCollapseMinus(boolean)
public void setParseUnits(boolean units)
In SBML Level 2, there is no means of associating a unit of
measurement with a pure number in a formula, while SBML Level 3 does
define a syntax for this. In Level 3, MathML <cn>
elements can have an attribute named units
placed in the SBML
namespace, which can be used to indicate the units to be associated with
the number. The text-string infix formula parser allows units to be
placed after raw numbers they are interpreted as unit identifiers for
units defined by the SBML specification or in the containing Model
object.
Some examples include: "4 mL
", "2.01
Hz
", "3.1e-6 M
", and "(5/8)
inches
". To produce a valid SBML model, there must either
exist a UnitDefinition
corresponding to the identifier of the unit, or the
unit must be defined in Table 2 of the SBML Level 3 specification.
This method sets the formula parser's behavior with respect to units.
units
- a boolean indicating whether to parse units. The
possible values are as follows:
L3P_PARSE_UNITS
(value = true
): parse units in the
text-string formula.
L3P_NO_UNITS
(value = false
): treat units in the
text-string formula as errors.
L3ParserSettings.getParseUnits()
public boolean getParseUnits()
In SBML Level 2, there is no means of associating a unit of
measurement with a pure number in a formula, while SBML Level 3 does
define a syntax for this. In Level 3, MathML <cn>
elements can have an attribute named units
placed in the SBML
namespace, which can be used to indicate the units to be associated with
the number. The text-string infix formula parser allows units to be
placed after raw numbers they are interpreted as unit identifiers for
units defined by the SBML specification or in the containing Model
object.
Some examples include: "4 mL
", "2.01
Hz
", "3.1e-6 M
", and "(5/8)
inches
". To produce a valid SBML model, there must either
exist a UnitDefinition
corresponding to the identifier of the unit, or the
unit must be defined in Table 2 of the SBML Level 3 specification.
Since SBML Level 2 does not have the ability to associate units
with pure numbers, the value should be expected to be false
(L3P_NO_UNITS
) when parsing text-string
formulas intended for use in SBML Level 2 documents.
L3P_PARSE_UNITS
(value = true
): parse units in the
text-string formula.
L3P_NO_UNITS
(value = false
): treat units in the
text-string formula as errors.
L3ParserSettings.setParseUnits(boolean)
public void setParseAvogadroCsymbol(boolean l2only)
avogadro
in
mathematical formulas.
SBML Level 3 defines a symbol for representing the value of
Avogadro's constant, but it is not defined in SBML Level 2. As a
result, the text-string formula parser must behave differently
depending on which SBML Level is being targeted. For Level 3
documents, it can interpret instances of avogadro
in the input
as a reference to the MathML csymbol for Avogadro's constant
defined in the SBML Level 3 specification. For Level 2,
it must treat avogadro
as just another plain symbol.
This method allows callers to set the avogadro
-handling
behavior in this L3ParserSettings
object. The possible values of
l2only
are as follows:
L3P_AVOGADRO_IS_CSYMBOL
(value = true
): tells the
parser to translate the string avogadro
(in any capitalization) into an
AST node of type AST_NAME_AVOGADRO
.
L3P_AVOGADRO_IS_NAME
(value = false
): tells the
parser to translate the string avogadro
into an AST of type
AST_NAME
.
Since SBML Level 2 does not define a symbol for Avogadro's
constant, the value should be set to
L3P_AVOGADRO_IS_NAME
when parsing text-string formulas
intended for use in SBML Level 2 documents.
l2only
- a boolean value indicating how the string avogadro
should be treated when encountered in a formula. This will be one of
the values L3P_AVOGADRO_IS_CSYMBOL
or
L3P_AVOGADRO_IS_NAME
.
L3ParserSettings.getParseAvogadroCsymbol()
public boolean getParseAvogadroCsymbol()
avogadro
for SBML
Level 3.
SBML Level 3 defines a symbol for representing the value of
Avogadro's constant, but it is not defined in SBML Level 2. As a
result, the text-string formula parser must behave differently
depending on which SBML Level is being targeted. For Level 3
documents, it can interpret instances of avogadro
in the input
as a reference to the MathML csymbol for Avogadro's constant
defined in the SBML Level 3 specification. For Level 2,
it must treat avogadro
as just another plain symbol.
This method returns the current setting of the
avogadro
-handling behavior in this L3ParserSettings
object.
The possible values are as follows:
L3P_AVOGADRO_IS_CSYMBOL
(value = true
): tells the
parser to translate the string avogadro
(in any capitalization) into an
AST node of type AST_NAME_AVOGADRO
.
L3P_AVOGADRO_IS_NAME
(value = false
): tells the
parser to translate the string avogadro
into an AST of type
AST_NAME
.
L3P_AVOGADRO_IS_CSYMBOL
or
L3P_AVOGADRO_IS_NAME
.
L3ParserSettings.setParseAvogadroCsymbol(boolean)
public void setComparisonCaseSensitivity(boolean strcmp)
By default (which is the value
L3P_COMPARE_BUILTINS_CASE_INSENSITIVE
), the parser
compares symbols in a case insensitive manner for built-in functions
such as 'sin'
and 'piecewise'
, and for constants such as 'true'
and 'avogadro'.
Setting this option to
L3P_COMPARE_BUILTINS_CASE_SENSITIVE
causes the parser to
become case sensitive. In that mode, for example, the symbols 'sin'
and 'true'
will match the built-in values, but the symbols 'SIN'
,
'Sin'
, 'True'
, 'TRUE'
, and so on, will not.
strcmp
- a boolean indicating whether to be case sensitive (if
true
) or be case insensitive (if false
).
L3ParserSettings.getComparisonCaseSensitivity()
public boolean getComparisonCaseSensitivity()
true
if the parser is configured to match built-in symbols
in a case-insensitive way.
By default (which is the value
L3P_COMPARE_BUILTINS_CASE_INSENSITIVE
), the parser
compares symbols in a case insensitive manner for built-in functions
such as 'sin'
and 'piecewise'
, and for constants such as 'true'
and 'avogadro'.
Setting this option to
L3P_COMPARE_BUILTINS_CASE_SENSITIVE
causes the parser to
become case sensitive. In that mode, for example, the symbols 'sin'
and 'true'
will match the built-in values, but the symbols 'SIN'
,
'Sin'
, 'True'
, 'TRUE'
, and so on, will not.
true
if matches are done in a case-sensitive manner, and
false
if the parser will recognize built-in functions and
constants regardless of case,.
L3ParserSettings.setComparisonCaseSensitivity(boolean)
public void setParseModuloL3v2(boolean modulol3v2)
This setting affects whether the '%' symbol (modulo) is parsed as a piecewise equation that returns the modulo value of the entries on either side of the symbol, or whether it is parsed as the MathML 'rem' function, which was allowed in SBML Level 3 Version 2, but not in previous level/versions. The latter is more succinct, but might not be legal SBML for the desired target SBML document.
This method lets you tell the parser which behavior to use&mdasheither parse '%' as the 'rem' function or as a piecewise function with the same interpretation. The two possibilities are represented using the following constants:
L3P_MODULO_IS_REM
(value = true
): use the
'rem' MathML function (AST_FUNCTION_REM
).
L3P_MODULO_IS_PIECEWISE
(value = false
): use
a piecewise function (AST_FUNCTION_PIECEWISE
)
to encode the modulo rule explicitly.
modulol3v2
- a boolean value (one of the constants
L3P_MODULO_IS_PIECEWISE
or
L3P_MODULO_IS_REM
)
indicating how the '%' symbol in the input should be handled.
L3ParserSettings.getParseModuloL3v2()
public boolean getParseModuloL3v2()
This setting affects whether the '%' symbol (modulo) is parsed as a piecewise equation that returns the modulo value of the entries on either side of the symbol, or whether it is parsed as the MathML 'rem' function, which was allowed in SBML Level 3 Version 2, but not in previous level/versions. The latter is more succinct, but might not be legal SBML for the desired target SBML document.
L3P_MODULO_IS_REM
(value = true
): use the
'rem' MathML function (AST_FUNCTION_REM
).
L3P_MODULO_IS_PIECEWISE
(value = false
): use
a piecewise function (AST_FUNCTION_PIECEWISE
)
to encode the modulo rule explicitly.
L3ParserSettings.setParseModuloL3v2(boolean)
public void setParseL3v2Functions(boolean l3v2functions)
This setting affects whether the names of functions added in SBML Level 3 Version 2 are parsed as those added MathML functions, or whether they are added as generic functions with those names (to be used in SBML as function definitions).
This method lets you tell the parser which behavior to use&mdasheither to parse the functions added in L3v2 as their built-in counterparts, or as generic functions with that name (to be defined by SBML as function definitions). The two possibilities are represented using the following constants:
L3P_PARSE_L3V2_FUNCTIONS_DIRECTLY
(value = true
):
parse the strings rateOf
, implies
,
max
, min
, quotient
, and
rem
as
AST_FUNCTION_RATE_OF
,
AST_LOGICAL_IMPLIES
,
AST_FUNCTION_MAX
,
AST_FUNCTION_MIN
,
AST_FUNCTION_QUOTIENT
, and
AST_FUNCTION_REM
, respectively.
L3P_PARSE_L3V2_FUNCTIONS_AS_GENERIC
(value = false
):
parse the strings rateOf
, implies
,
max
, min
, quotient
, and
rem
all as
AST_FUNCTION
with the appropriate
name set.
l3v2functions
- a boolean value (one of the constants
L3P_PARSE_L3V2_FUNCTIONS_DIRECTLY
or
L3P_PARSE_L3V2_FUNCTIONS_AS_GENERIC
)
indicating how to interpret those function names.
L3ParserSettings.getParseL3v2Functions()
public boolean getParseL3v2Functions()
This setting affects whether the names of functions added in SBML Level 3 Version 2 are parsed as those added MathML functions, or whether they are added as generic functions with those names (to be used in SBML as function definitions).
L3P_PARSE_L3V2_FUNCTIONS_DIRECTLY
(value = true
):
parse the strings rateOf
, implies
,
max
, min
, quotient
, and
rem
as
AST_FUNCTION_RATE_OF
,
AST_LOGICAL_IMPLIES
,
AST_FUNCTION_MAX
,
AST_FUNCTION_MIN
,
AST_FUNCTION_QUOTIENT
, and
AST_FUNCTION_REM
, respectively.
L3P_PARSE_L3V2_FUNCTIONS_AS_GENERIC
(value = false
):
parse the strings rateOf
, implies
,
max
, min
, quotient
, and
rem
all as
AST_FUNCTION
with the appropriate
name set.
L3ParserSettings.setParseModuloL3v2(boolean)
public void setPlugins(SBMLNamespaces sbmlns)
L3ParserSettings
, based on the
SBMLNamespaces
object.
When a SBMLNamespaces
object is provided, the parser will only interpret
infix syntax understood by the core libSBML plus the packages
indicated by the SBMLNamespaces
objects provided. ASTNode
objects
returned by the L3Parser will contain those SBMLNamespaces
objects, and
will be used to parse certain constructs that may only be understood by
packages (e.g., vectors for the SBML Level 3 'arrays' package).
Note that by default, all packages that were compiled with this version
of libSBML are included, so this function is most useful as a way to
turn off certain namespaces, such as might be desired if your tool
does not support vectors, for example.
sbmlns
- a SBMLNamespaces
object to be used. If null
is given
as the value, all plugins will be loaded.