Detailed Description

Methods for checking the validity of SBML identifiers.

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.

This utility class provides static methods for checking the syntax of identifiers and other text used in an SBML model. The methods allow callers to verify that strings such as SBML identifiers and XHTML notes text conform to the SBML specifications.

Static Public Member Functions
static bool	hasExpectedXHTMLSyntax (const XMLNode xhtml, SBMLNamespaces sbmlns=NULL)
	Returns `true` or `false` depending on whether the given XMLNode object contains valid XHTML content. More...

static bool	isValidSBMLSId (std::string sid)
	Returns `true` or `false` depending on whether the argument string conforms to the syntax of SBML identifiers. More...

static bool	isValidUnitSId (std::string units)
	Returns `true` or `false` depending on whether the argument string conforms to the syntax of SBML unit identifiers. More...

static bool	isValidXMLanyURI (std::string uri)
	Returns `true` or `false` depending on whether the `uri` argument string conforms to the XML data type `anyURI`. More...

static bool	isValidXMLID (std::string id)
	Returns `true` or `false` depending on whether the argument string conforms to the XML data type `ID`. More...

Member Function Documentation

bool SyntaxChecker::hasExpectedXHTMLSyntax	(	const XMLNode *	xhtml,
		SBMLNamespaces *	sbmlns = `NULL`
	)

static

Returns true or false depending on whether the given XMLNode object contains valid XHTML content.

: The optional SBML element named "notes", present on every major SBML component type (and in SBML Level 3, the "message" subelement of Constraint), is intended as a place for storing optional information intended to be seen by humans. An example use of the "notes" element would be to contain formatted user comments about the model element in which the "notes" element is enclosed. Every object derived directly or indirectly from type SBase can have a separate value for "notes", allowing users considerable freedom when adding comments to their models.

The format of "notes" elements conform to the definition of XHTML 1.0. However, the content cannot be entirely free-form; it must satisfy certain requirements defined in the SBML specifications for specific SBML Levels. To help verify the formatting of "notes" content, libSBML provides the static utility method SyntaxChecker::hasExpectedXHTMLSyntax(); this method implements a verification process that lets callers check whether the content of a given XMLNode object conforms to the SBML requirements for "notes" and "message" structure. Developers are urged to consult the appropriate SBML specification document for the Level and Version of their model for more in-depth explanations of using "notes" in SBML. The SBML Level 2 and 3 specifications have considerable detail about how "notes" element content must be structured.

An aspect of XHTML validity is that the content is declared to be in the XML namespace for XHTML 1.0. There is more than one way in which this can be done in XML. In particular, a model might not contain the declaration within the "notes" or "message" subelement itself, but might instead place the declaration on an enclosing element and use an XML namespace prefix within the "notes" element to refer to it. In other words, the following is valid:

<sbml xmlns="http://www.sbml.org/sbml/level2/version3" level="2" version="3"
      xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <model>
    <notes>
      <xhtml:body>
        <xhtml:center><xhtml:h2>A Simple Mitotic Oscillator</xhtml:h2></xhtml:center>
        <xhtml:p>A minimal cascade model for the mitotic oscillator.</xhtml:p>
      </xhtml:body>
    </notes>
  ... rest of model ...
</sbml>

Contrast the above with the following, self-contained version, which places the XML namespace declaration within the <notes> element itself:

<sbml xmlns="http://www.sbml.org/sbml/level2/version3" level="2" version="3">
  <model>
    <notes>
      <html xmlns="http://www.w3.org/1999/xhtml">
        <head>
          <title/>
        </head>
        <body>
          <center><h2>A Simple Mitotic Oscillator</h2></center>
          <p>A minimal cascade model for the mitotic oscillator.</p>
        </body>
      </html>
    </notes>
  ... rest of model ...
</sbml>

Both of the above are valid XML. The purpose of the sbmlns argument to this method is to allow callers to check the validity of "notes" and "message" subelements whose XML namespace declarations have been put elsewhere in the manner illustrated above. Callers can can pass in the SBMLNamespaces object of a higher-level model component if the XMLNode object does not itself have the XML namespace declaration for XHTML 1.0.

Parameters

xhtml	the XMLNode to be checked for conformance.
sbmlns	the SBMLNamespaces associated with the object.

Returns: true if the XMLNode content conforms, false otherwise.

bool SyntaxChecker::isValidSBMLSId ( std::string sid )

static

Returns true or false depending on whether the argument string conforms to the syntax of SBML identifiers.

: In SBML, identifiers that are the values of "id" attributes on objects must conform to a data type called SId in the SBML specifications. LibSBML does not provide an explicit SId data type; it uses ordinary character strings, which is easier for applications to support. (LibSBML does, however, test for identifier validity at various times, such as when reading in models from files and data streams.)

This method provides programs with the ability to test explicitly that the identifier strings they create conform to the SBML identifier syntax.

Parameters

sid	string to be checked for conformance to SBML identifier syntax.

Returns: true if the string conforms to type SBML data type SId, false otherwise.

The identifier given by an object's "id" attribute value is used to identify the object within the SBML model definition. Other objects can refer to the component using this identifier. The data type of "id" is always SId or a type derived from that, such as UnitSId, depending on the object in question. All data types are defined as follows:

  letter ::= 'a'..'z','A'..'Z'
  digit  ::= '0'..'9'
  idChar ::= letter | digit | '_'
  SId    ::= ( letter | '_' ) idChar*

The equality of SId and SId-derived values in SBML is determined by an exact character sequence match; i.e., comparisons of these identifiers must be performed in a case-sensitive manner. This applies to all uses of SId, SIdRef, and derived types.

See also: isValidUnitSId(std::string sid); isValidXMLID(std::string sid)

bool SyntaxChecker::isValidUnitSId ( std::string units )

static

Returns true or false depending on whether the argument string conforms to the syntax of SBML unit identifiers.

In SBML, the identifiers of units (of both the predefined units and user-defined units) must conform to a data type called UnitSId in the SBML specifications. LibSBML does not provide an explicit UnitSId data type; it uses ordinary character strings, which is easier for applications to support. LibSBML does, however, test for identifier validity at various times, such as when reading in models from files and data streams.

This method provides programs with the ability to test explicitly that the identifier strings they create conform to the SBML identifier syntax.

Parameters

units string to be checked for conformance to SBML unit identifier syntax.

Returns: true if the string conforms to type SBML data type UnitSId, false otherwise.

Note

The following is a summary of the definition of the SBML identifier type UnitSId, which defines the permitted syntax of identifiers. We express the syntax using an extended form of BNF notation:

letter ::= 'a'..'z','A'..'Z'
digit ::= '0'..'9'
idChar ::= letter | digit | '_'
SId ::= ( letter | '_' ) idChar*

The characters ( and ) are used for grouping, the character * "zero or more times", and the character | indicates logical "or". The equality of SBML unit identifiers is determined by an exact character sequence match; i.e., comparisons must be performed in a case-sensitive manner. In addition, there are a few conditions for the uniqueness of unit identifiers in an SBML model. Please consult the SBML specifications for the exact formulations.

See also: isValidSBMLSId(std::string sid); isValidXMLID(std::string sid)

bool SyntaxChecker::isValidXMLanyURI ( std::string uri )

static

Returns true or false depending on whether the uri argument string conforms to the XML data type anyURI.

Type anyURI is defined by XML Schema 1.0. It is a character string data type whose values are interpretable as URIs (Universal Resource Identifiers) as described by the W3C document RFC 3986. LibSBML does not provide an explicit XML anyURI data type; it uses ordinary character strings, which is easier for applications to support. LibSBML does, however, test for anyURI validity at various times, such as when reading in models from files and data streams.

This method provides programs with the ability to test explicitly that the strings they create conform to the XML anyURI syntax.

Parameters

uri	string to be checked for conformance to the syntax of anyURI.

Returns: true if the string is a syntactically-valid value for the XML type anyURI, false otherwise.

bool SyntaxChecker::isValidXMLID ( std::string id )

static

Returns true or false depending on whether the argument string conforms to the XML data type ID.

: The optional attribute named "metaid", present on every major SBML component type, is for supporting metadata annotations using RDF (Resource Description Format). The attribute value has the data type XML ID, the XML identifier type, which means each "metaid" value must be globally unique within an SBML file. The latter point is important, because the uniqueness criterion applies across any attribute with type ID anywhere in the file, not just the "metaid" attribute used by SBML—something to be aware of if your application-specific XML content inside the "annotation" subelement happens to use the XML ID type. Although SBML itself specifies the use of XML ID only for the "metaid" attribute, SBML-compatible applications should be careful if they use XML ID's in XML portions of a model that are not defined by SBML, such as in the application-specific content of the "annotation" subelement. Finally, note that LibSBML does not provide an explicit XML ID data type; it uses ordinary character strings, which is easier for applications to support.

This method provides programs with the ability to test explicitly that the identifier strings they create conform to the SBML identifier syntax.

Parameters

id	string to be checked for conformance to the syntax of XML ID.

Returns: true if the string is a syntactically-valid value for the XML type ID, false otherwise.

Note

The following is a summary of the definition of the XML 1.0 data type ID. We express the syntax using an extended form of BNF notation:

NCNameChar ::= letter | digit | '.' | '-' | '_' | ':' | CombiningChar | Extender
ID ::= ( letter | '_' | ':' ) NCNameChar*

The characters ( and ) are used for grouping, the character * means "zero or more times", and the character | indicates logical "or". The production letter consists of the basic upper and lower case alphabetic characters of the Latin alphabet along with a large number of related characters defined by Unicode 2.0; similarly, the production digit consists of the numerals 0..9 along with related Unicode 2.0 characters. The CombiningChar production is a list of characters that add such things as accents to the preceding character. (For example, the Unicode character \#x030A when combined with a produces \aa.) The Extender production is a list of characters that extend the shape of the preceding character. Please consult the XML 1.0 specification for the complete definitions of letter, digit, CombiningChar, and Extender.

See also: isValidSBMLSId(std::string sid); isValidUnitSId(std::string sid)

Detailed Description

Static Public Member Functions

Member Function Documentation