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 formula,
,
along with its variants
L3ParserSettings
settings)libsbml.parseFormula(java.lang.String formula)
and
libsbml.parseL3FormulaWithModel(String formula,
,
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 Model
model)ASTNode
objects. Compared to the parser implemented by the function
libsbml.parseFormula(java.lang.String formula)
,
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:
log
with a single argument ("log(x)
")
can be parsed as log10(x)
, ln(x)
, or treated
as an error, as desired.
- -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.
avogadro
can be parsed as a MathML csymbol or
as an identifier.
Model
object may optionally be provided to the parser using
the variant function call libsbml.parseL3FormulaWithModel(String formula, Model
model)
.
or stored in a L3ParserSettings
object passed to the variant function
libsbml.parseL3FormulaWithSettings(String formula, org.sbml.libsbml.L3ParserSettings settings)
.
When 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/>
.
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 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)
Constructor and Description |
---|
L3ParserSettings()
Creates a new
L3ParserSettings object with default values. |
L3ParserSettings(Model model,
int parselog,
boolean collapseminus,
boolean parseunits,
boolean avocsymbol)
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.
|
Model |
getModel()
Returns the
Model object referenced by this L3ParserSettings object. |
boolean |
getParseAvogadroCsymbol()
Returns
true if the current settings are oriented towards handling
avogadro for SBML Level 3. |
boolean |
getParseCollapseMinus()
Returns a flag indicating the current behavior set for handling
multiple unary minuses in formulas.
|
int |
getParseLog()
Returns the current setting indicating what to do with formulas
containing the function
log with one argument. |
boolean |
getParseUnits()
Returns
if the current settings allow units in text-string
mathematical formulas. |
void |
setModel(Model model)
Sets the model reference in this
L3ParserSettings object. |
void |
setParseAvogadroCsymbol(boolean l2only)
Sets the parser's behavior in handling the string
avogadro in
mathematical formulas. |
void |
setParseCollapseMinus(boolean collapseminus)
Sets the behavior for handling unary minuses appearing in mathematical
formulas.
|
void |
setParseLog(int type)
Sets the behavior for handling
log in mathematical formulas. |
void |
setParseUnits(boolean units)
Sets the parser's behavior in handling units associated with numbers
in a mathematical formula.
|
void |
unsetModel()
|
public L3ParserSettings()
L3ParserSettings
object with default values.
This is the default constructor for the L3ParserSettings
object. It
sets the Model
to null
and other settings to
L3P_PARSE_LOG_AS_LOG10
, L3P_EXPAND_UNARY_MINUS
, L3P_PARSE_UNITS
,
and L3P_AVOGADRO_IS_CSYMBOL.
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
parselog
- a flag that controls how the parser will handle
the symbol log
in formulas
collapseminus
- a flag that controls how the parser will handle
minus signs
parseunits
- a flag that controls how the parser will handle
apparent references to units of measurement associated with raw
numbers in a formula
avocsymbol
- a flag that controls how the parser will handle
the appearance of the symbol avogadro
in a formula
L3ParserSettings.getModel()
,
L3ParserSettings.setModel(Model model)
,
L3ParserSettings.unsetModel()
,
L3ParserSettings.getParseLog()
,
L3ParserSettings.setParseLog(int type)
,
L3ParserSettings.getParseUnits()
,
L3ParserSettings.setParseUnits(boolean units)
,
L3ParserSettings.getParseCollapseMinus()
,
L3ParserSettings.setParseCollapseMinus(boolean collapseminus)
,
L3ParserSettings.getParseAvogadroCsymbol()
,
L3ParserSettings.setParseAvogadroCsymbol(boolean l2only)
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 Model getModel()
Model
object referenced by this L3ParserSettings
object.
public boolean getParseAvogadroCsymbol()
true
if the current settings are oriented towards handling
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.
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
.
L3ParserSettings.setParseAvogadroCsymbol(boolean l2only)
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
. 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
.
L3P_COLLAPSE_UNARY_MINUS
or L3P_EXPAND_UNARY_MINUS
.
L3ParserSettings.setParseCollapseMinus(boolean collapseminus)
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.
L3ParserSettings.setParseLog(int type)
public boolean getParseUnits()
if
the current settings allow units in text-string
mathematical formulas.
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 specification.
Since SBML Level 2 does not have the ability to associate units with
pure numbers, the value should be set to false
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 units)
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
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 object after invoking this
method may affect parsing behavior.
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. The argument to this method can be one of two values:
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 false
when parsing text-string
formulas intended for use in SBML Level 2 documents.
l2only
- a boolean value (one of the constants
L3P_AVOGADRO_IS_CSYMBOL
or
L3P_AVOGADRO_IS_NAME
) indicating how the string avogadro
should be treated when encountered in a formula.
L3ParserSettings.getParseAvogadroCsymbol()
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 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, as
desired.
type
- a constant, one of following three possibilities:
L3ParserSettings.getParseLog()
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 specification.
units
- A boolean indicating whether to parse units:
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 void unsetModel()