001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 2.0.11
004 *
005 * Do not make changes to this file unless you know what you are doing--modify
006 * the SWIG interface file instead.
007 * ----------------------------------------------------------------------------- */
008
009package org.sbml.libsbml;
010
011/** 
012 * 
013 * Methods for checking syntax of SBML identifiers and other strings.
014 * <p>
015 * <p style='color: #777; font-style: italic'>
016This class of objects is defined by libSBML only and has no direct
017equivalent in terms of SBML components.  This class is not prescribed by
018the SBML specifications, although it is used to implement features
019defined in SBML.
020</p>
021
022 * <p>
023 * This utility class provides static methods for checking the syntax of
024 * identifiers and other text used in an SBML model.  The methods allow
025 * callers to verify that strings such as SBML identifiers and XHTML notes
026 * text conform to the SBML specifications.
027 */
028
029public class SyntaxChecker {
030   private long swigCPtr;
031   protected boolean swigCMemOwn;
032
033   protected SyntaxChecker(long cPtr, boolean cMemoryOwn)
034   {
035     swigCMemOwn = cMemoryOwn;
036     swigCPtr    = cPtr;
037   }
038
039   protected static long getCPtr(SyntaxChecker obj)
040   {
041     return (obj == null) ? 0 : obj.swigCPtr;
042   }
043
044   protected static long getCPtrAndDisown (SyntaxChecker obj)
045   {
046     long ptr = 0;
047
048     if (obj != null)
049     {
050       ptr             = obj.swigCPtr;
051       obj.swigCMemOwn = false;
052     }
053
054     return ptr;
055   }
056
057  protected void finalize() {
058    delete();
059  }
060
061  public synchronized void delete() {
062    if (swigCPtr != 0) {
063      if (swigCMemOwn) {
064        swigCMemOwn = false;
065        libsbmlJNI.delete_SyntaxChecker(swigCPtr);
066      }
067      swigCPtr = 0;
068    }
069  }
070
071  
072/**
073   * Returns true <code>true</code> or <code>false</code> depending on whether the argument
074   * string conforms to the syntax of SBML identifiers.
075   * <p>
076   * In SBML, identifiers that are the values of 'id' attributes on objects
077   * must conform to a data type called <code>SId</code> in the SBML
078   * specifications.  LibSBML does not provide an explicit <code>SId</code>
079   * data type; it uses ordinary character strings, which is easier for
080   * applications to support.  LibSBML does, however, test for identifier
081   * validity at various times, such as when reading in models from files
082   * and data streams.
083   * <p>
084   * This method provides programs with the ability to test explicitly that
085   * the identifier strings they create conform to the SBML identifier
086   * syntax.
087   * <p>
088   * @param sid string to be checked for conformance to SBML identifier
089   * syntax.
090   * <p>
091   * @return <code>true</code> if the string conforms to type SBML data type
092   * <code>SId</code>, <code>false</code> otherwise.
093   * <p>
094   * @note The following is a summary of the definition of the SBML identifier type 
095<code>SId</code>, which defines the permitted syntax of identifiers.  We
096express the syntax using an extended form of BNF notation: 
097<pre style='margin-left: 2em; border: none; font-weight: bold; font-size: 13px; color: black'>
098letter .= 'a'..'z','A'..'Z'
099digit  .= '0'..'9'
100idChar .= letter | digit | '_'
101SId    .= ( letter | '_' ) idChar*
102</pre>
103The characters <code>(</code> and <code>)</code> are used for grouping, the
104character <code>*</code> 'zero or more times', and the character
105<code>|</code> indicates logical 'or'.  The equality of SBML identifiers is
106determined by an exact character sequence match; i.e., comparisons must be
107performed in a case-sensitive manner.  In addition, there are a few
108conditions for the uniqueness of identifiers in an SBML model.  Please
109consult the SBML specifications for the exact formulations.
110<p>
111
112   * <p>
113   * @note Because this is a <em>static</em> method, the
114   * non-C++ language interfaces for libSBML will contain two variants.  One
115   * will be a static method on the class (i.e., {@link SyntaxChecker}), and the
116   * other will be a standalone top-level function with the name
117   * SyntaxChecker_isValidSBMLSId(). They are functionally
118   * identical. 
119   * <p>
120   * @see SyntaxChecker#isValidUnitSId(String sid) 
121   * @see SyntaxChecker#isValidXMLID(String sid) 
122   */ public
123 static boolean isValidSBMLSId(String sid) {
124    return libsbmlJNI.SyntaxChecker_isValidSBMLSId(sid);
125  }
126
127  
128/**
129   * Returns <code>true</code> or <code>false</code> depending on whether the argument string
130   * conforms to the XML data type <code>ID</code>.
131   * <p>
132   * In SBML, identifiers that are the values of 'metaid' attributes on
133   * objects must conform to the <a target='_blank'
134   * href='http://www.w3.org/TR/REC-xml/#id'>XML ID</a> data type.  LibSBML
135   * does not provide an explicit XML <code>ID</code> data type; it uses
136   * ordinary character strings, which is easier for applications to
137   * support.  LibSBML does, however, test for identifier validity at
138   * various times, such as when reading in models from files and data
139   * streams.
140   * <p>
141   * This method provides programs with the ability to test explicitly that
142   * the identifier strings they create conform to the SBML identifier
143   * syntax.
144   * <p>
145   * @param id string to be checked for conformance to the syntax of
146   * <a target='_blank' href='http://www.w3.org/TR/REC-xml/#id'>XML ID</a>.
147   * <p>
148   * @return <code>true</code> if the string is a syntactically-valid value for the
149   * XML type <a target='_blank'
150   * href='http://www.w3.org/TR/REC-xml/#id'>ID</a>, <code>false</code> otherwise.
151   * <p>
152   * @note The following is a summary of the definition of the XML&nbsp;1.0 data type
153<a target='_blank' href='http://www.w3.org/TR/REC-xml/#id'>ID</a>.  We
154express the syntax using an extended form of BNF notation:
155<p>
156<nobr><code style='margin-left: 2em'>NCNameChar .= letter | digit | '.' | '-' | '_' | ':' | CombiningChar | Extender</code><br></nobr>
157<code style='margin-left: 2em'>ID .= ( letter | '_' | ':' ) NCNameChar*</code><br>
158<p>
159The characters <code>(</code> and <code>)</code> are used for grouping, the
160character <code>*</code> means 'zero or more times', and the character
161<code>|</code> indicates logical 'or'. The production <code>letter</code>
162consists of the basic upper and lower case alphabetic characters of the
163Latin alphabet along with a large number of related characters defined by
164Unicode&nbsp;2.0; similarly, the production <code>digit</code> consists of
165the numerals <code>0..9</code> along with related Unicode&nbsp;2.0
166characters.  The <code>CombiningChar</code> production is a list of
167characters that add such things as accents to the preceding character. (For
168example, the Unicode character <code>\#x030A</code> when combined with
169<code>a</code> produces <code>a</code>.)  The <code>Extender</code>
170production is a list of characters that extend the shape of the preceding
171character.  Please consult the <a target='_blank'
172href='http://www.w3.org/TR/2004/REC-xml-20040204/'>XML&nbsp;1.0
173specification</a> for the complete definitions of <code>letter</code>,
174<code>digit</code>, <code>CombiningChar</code>, and <code>Extender</code>.
175<p>
176
177   * <p>
178   * @note Because this is a <em>static</em> method, the
179   * non-C++ language interfaces for libSBML will contain two variants.  One
180   * will be a static method on the class (i.e., {@link SyntaxChecker}), and the
181   * other will be a standalone top-level function with the name
182   * SyntaxChecker_isValidXMLID(). They are functionally
183   * identical. 
184   * <p>
185   * @see SyntaxChecker#isValidSBMLSId(String sid) 
186   * @see SyntaxChecker#isValidUnitSId(String sid) 
187   */ public
188 static boolean isValidXMLID(String id) {
189    return libsbmlJNI.SyntaxChecker_isValidXMLID(id);
190  }
191
192  
193/**
194   * Returns <code>true</code> or <code>false</code> depending on whether the argument string
195   * conforms to the syntax of SBML unit identifiers.
196   * <p>
197   * In SBML, the identifiers of units (of both the predefined units and
198   * user-defined units) must conform to a data type called
199   * <code>UnitSId</code> in the SBML specifications.  LibSBML does not
200   * provide an explicit <code>UnitSId</code> data type; it uses ordinary
201   * character strings, which is easier for applications to support.
202   * LibSBML does, however, test for identifier validity at various times,
203   * such as when reading in models from files and data streams.
204   * <p>
205   * This method provides programs with the ability to test explicitly that
206   * the identifier strings they create conform to the SBML identifier
207   * syntax.
208   * <p>
209   * @param units string to be checked for conformance to SBML unit
210   * identifier syntax.
211   * <p>
212   * @return <code>true</code> if the string conforms to type SBML data type
213   * <code>UnitSId</code>, <code>false</code> otherwise.
214   * <p>
215   * @note The following is a summary of the definition of the SBML identifier type
216<code>UnitSId</code>, which defines the permitted syntax of identifiers.
217We express the syntax using an extended form of BNF notation:
218<p>
219<code style='margin-left: 2em'>letter .= 'a'..'z','A'..'Z'</code><br>
220<code style='margin-left: 2em'>digit  .= '0'..'9'</code><br>
221<code style='margin-left: 2em'>idChar .= letter | digit | '_'</code><br>
222<code style='margin-left: 2em'>SId    .= ( letter | '_' ) idChar*</code><br>
223<p>
224The characters <code>(</code> and <code>)</code> are used for grouping, the
225character <code>*</code> 'zero or more times', and the character
226<code>|</code> indicates logical 'or'.  The equality of SBML unit
227identifiers is determined by an exact character sequence match; i.e.,
228comparisons must be performed in a case-sensitive manner.  In addition,
229there are a few conditions for the uniqueness of unit identifiers in an
230SBML model.  Please consult the SBML specifications for the exact
231formulations.
232<p>
233
234   * <p>
235   * @note Because this is a <em>static</em> method, the
236   * non-C++ language interfaces for libSBML will contain two variants.  One
237   * will be a static method on the class (i.e., {@link SyntaxChecker}), and the
238   * other will be a standalone top-level function with the name
239   * SyntaxChecker_isValidUnitSId(). They are functionally
240   * identical. 
241   * <p>
242   * @see SyntaxChecker#isValidSBMLSId(String sid) 
243   * @see SyntaxChecker#isValidXMLID(String sid) 
244   */ public
245 static boolean isValidUnitSId(String units) {
246    return libsbmlJNI.SyntaxChecker_isValidUnitSId(units);
247  }
248
249  
250/**
251   * Returns <code>true</code> or <code>false</code> depending on whether the given {@link XMLNode}
252   * object contains valid XHTML content.
253   * <p>
254   * In SBML, the content of the 'notes' subelement available on {@link SBase}, as
255   * well as the 'message' subelement available on {@link Constraint}, must conform
256   * to <a target='_blank'
257   * href='http://www.w3.org/TR/xhtml1/'>XHTML&nbsp;1.0</a> (which is
258   * simply an XML-ized version of HTML).  However, the content cannot be
259   * <em>entirely</em> free-form; it must satisfy certain requirements defined in
260   * the <a target='_blank'
261   * href='http://sbml.org/Documents/Specifications'>SBML
262   * specifications</a> for specific SBML Levels.  This method implements a
263   * verification process that lets callers check whether the content of a
264   * given {@link XMLNode} object conforms to the SBML requirements for 'notes' and
265   * 'message' structure.
266   * <p>
267   * An aspect of XHTML validity is that the content is declared to be in
268   * the XML namespace for XHTML&nbsp;1.0.  There is more than one way in
269   * which this can be done in XML.  In particular, a model might not
270   * contain the declaration within the 'notes' or 'message' subelement
271   * itself, but might instead place the declaration on an enclosing
272   * element and use an XML namespace prefix within the 'notes' element to
273   * refer to it.  In other words, the following is valid:
274   * <div class='fragment'><pre>
275&lt;sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'
276      xmlns:xhtml='http://www.w3.org/1999/xhtml'&gt;
277  &lt;model&gt;
278    &lt;notes&gt;
279      &lt;xhtml:body&gt;
280        &lt;xhtml:center&gt;&lt;xhtml:h2&gt;A Simple Mitotic Oscillator&lt;/xhtml:h2&gt;&lt;/xhtml:center&gt;
281        &lt;xhtml:p&gt;A minimal cascade model for the mitotic oscillator.&lt;/xhtml:p&gt;
282      &lt;/xhtml:body&gt;
283    &lt;/notes&gt;
284  ... rest of model ...
285&lt;/sbml&gt;
286</pre></div>
287   * Contrast the above with the following, self-contained version, which
288   * places the XML namespace declaration within the <code>&lt;notes&gt;</code>
289   * element itself:
290   * <div class='fragment'><pre>
291&lt;sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'&gt;
292  &lt;model&gt;
293    &lt;notes&gt;
294      &lt;html xmlns='http://www.w3.org/1999/xhtml'&gt;
295        &lt;head&gt;
296          &lt;title/&gt;
297        &lt;/head&gt;
298        &lt;body&gt;
299          &lt;center&gt;&lt;h2&gt;A Simple Mitotic Oscillator&lt;/h2&gt;&lt;/center&gt;
300          A minimal cascade model for the mitotic oscillator.&lt;/p&gt;
301        &lt;/body&gt;
302      &lt;/html&gt;
303    &lt;/notes&gt;
304  ... rest of model ...
305&lt;/sbml&gt;
306</pre></div>
307   * <p>
308   * Both of the above are valid XML.  The purpose of the <code>sbmlns</code>
309   * argument to this method is to allow callers to check the validity of
310   * 'notes' and 'message' subelements whose XML namespace declarations
311   * have been put elsewhere in the manner illustrated above.  Callers can
312   * can pass in the {@link SBMLNamespaces} object of a higher-level model
313   * component if the {@link XMLNode} object does not itself have the XML namespace
314   * declaration for XHTML&nbsp;1.0.
315   * <p>
316   * @param xhtml the {@link XMLNode} to be checked for conformance.
317   * @param sbmlns the {@link SBMLNamespaces} associated with the object.
318   * <p>
319   * @return <code>true</code> if the {@link XMLNode} content conforms, <code>false</code> otherwise.
320   * <p>
321   * @note Because this is a <em>static</em> method, the
322   * non-C++ language interfaces for libSBML will contain two variants.  One
323   * will be a static method on the class (i.e., {@link SyntaxChecker}), and the
324   * other will be a standalone top-level function with the name
325   * SyntaxChecker_hasExpectedXHTMLSyntax(). They are functionally
326   * identical. 
327   * <p>
328   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
329</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
330The native C++ implementation of this method defines a default argument
331value. In the documentation generated for different libSBML language
332bindings, you may or may not see corresponding arguments in the method
333declarations. For example, in Java and C#, a default argument is handled by
334declaring two separate methods, with one of them having the argument and
335the other one lacking the argument. However, the libSBML documentation will
336be <em>identical</em> for both methods. Consequently, if you are reading
337this and do not see an argument even though one is described, please look
338for descriptions of other variants of this method near where this one
339appears in the documentation.
340</dd></dl>
341 
342   */ public
343 static boolean hasExpectedXHTMLSyntax(XMLNode xhtml, SBMLNamespaces sbmlns) {
344    return libsbmlJNI.SyntaxChecker_hasExpectedXHTMLSyntax__SWIG_0(XMLNode.getCPtr(xhtml), xhtml, SBMLNamespaces.getCPtr(sbmlns), sbmlns);
345  }
346
347  
348/**
349   * Returns <code>true</code> or <code>false</code> depending on whether the given {@link XMLNode}
350   * object contains valid XHTML content.
351   * <p>
352   * In SBML, the content of the 'notes' subelement available on {@link SBase}, as
353   * well as the 'message' subelement available on {@link Constraint}, must conform
354   * to <a target='_blank'
355   * href='http://www.w3.org/TR/xhtml1/'>XHTML&nbsp;1.0</a> (which is
356   * simply an XML-ized version of HTML).  However, the content cannot be
357   * <em>entirely</em> free-form; it must satisfy certain requirements defined in
358   * the <a target='_blank'
359   * href='http://sbml.org/Documents/Specifications'>SBML
360   * specifications</a> for specific SBML Levels.  This method implements a
361   * verification process that lets callers check whether the content of a
362   * given {@link XMLNode} object conforms to the SBML requirements for 'notes' and
363   * 'message' structure.
364   * <p>
365   * An aspect of XHTML validity is that the content is declared to be in
366   * the XML namespace for XHTML&nbsp;1.0.  There is more than one way in
367   * which this can be done in XML.  In particular, a model might not
368   * contain the declaration within the 'notes' or 'message' subelement
369   * itself, but might instead place the declaration on an enclosing
370   * element and use an XML namespace prefix within the 'notes' element to
371   * refer to it.  In other words, the following is valid:
372   * <div class='fragment'><pre>
373&lt;sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'
374      xmlns:xhtml='http://www.w3.org/1999/xhtml'&gt;
375  &lt;model&gt;
376    &lt;notes&gt;
377      &lt;xhtml:body&gt;
378        &lt;xhtml:center&gt;&lt;xhtml:h2&gt;A Simple Mitotic Oscillator&lt;/xhtml:h2&gt;&lt;/xhtml:center&gt;
379        &lt;xhtml:p&gt;A minimal cascade model for the mitotic oscillator.&lt;/xhtml:p&gt;
380      &lt;/xhtml:body&gt;
381    &lt;/notes&gt;
382  ... rest of model ...
383&lt;/sbml&gt;
384</pre></div>
385   * Contrast the above with the following, self-contained version, which
386   * places the XML namespace declaration within the <code>&lt;notes&gt;</code>
387   * element itself:
388   * <div class='fragment'><pre>
389&lt;sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'&gt;
390  &lt;model&gt;
391    &lt;notes&gt;
392      &lt;html xmlns='http://www.w3.org/1999/xhtml'&gt;
393        &lt;head&gt;
394          &lt;title/&gt;
395        &lt;/head&gt;
396        &lt;body&gt;
397          &lt;center&gt;&lt;h2&gt;A Simple Mitotic Oscillator&lt;/h2&gt;&lt;/center&gt;
398          A minimal cascade model for the mitotic oscillator.&lt;/p&gt;
399        &lt;/body&gt;
400      &lt;/html&gt;
401    &lt;/notes&gt;
402  ... rest of model ...
403&lt;/sbml&gt;
404</pre></div>
405   * <p>
406   * Both of the above are valid XML.  The purpose of the <code>sbmlns</code>
407   * argument to this method is to allow callers to check the validity of
408   * 'notes' and 'message' subelements whose XML namespace declarations
409   * have been put elsewhere in the manner illustrated above.  Callers can
410   * can pass in the {@link SBMLNamespaces} object of a higher-level model
411   * component if the {@link XMLNode} object does not itself have the XML namespace
412   * declaration for XHTML&nbsp;1.0.
413   * <p>
414   * @param xhtml the {@link XMLNode} to be checked for conformance.
415   * @param sbmlns the {@link SBMLNamespaces} associated with the object.
416   * <p>
417   * @return <code>true</code> if the {@link XMLNode} content conforms, <code>false</code> otherwise.
418   * <p>
419   * @note Because this is a <em>static</em> method, the
420   * non-C++ language interfaces for libSBML will contain two variants.  One
421   * will be a static method on the class (i.e., {@link SyntaxChecker}), and the
422   * other will be a standalone top-level function with the name
423   * SyntaxChecker_hasExpectedXHTMLSyntax(). They are functionally
424   * identical. 
425   * <p>
426   * <!-- Don't remove the leading </dl> below. It's a hack for javadoc. -->
427</dl><dl class='docnote'><dt><b>Documentation note:</b></dt><dd>
428The native C++ implementation of this method defines a default argument
429value. In the documentation generated for different libSBML language
430bindings, you may or may not see corresponding arguments in the method
431declarations. For example, in Java and C#, a default argument is handled by
432declaring two separate methods, with one of them having the argument and
433the other one lacking the argument. However, the libSBML documentation will
434be <em>identical</em> for both methods. Consequently, if you are reading
435this and do not see an argument even though one is described, please look
436for descriptions of other variants of this method near where this one
437appears in the documentation.
438</dd></dl>
439 
440   */ public
441 static boolean hasExpectedXHTMLSyntax(XMLNode xhtml) {
442    return libsbmlJNI.SyntaxChecker_hasExpectedXHTMLSyntax__SWIG_1(XMLNode.getCPtr(xhtml), xhtml);
443  }
444
445  
446/**
447   * Returns true <code>true</code> or <code>false</code> depending on whether the argument
448   * string conforms to the syntax of SBML identifiers or is empty.
449   * @internal
450   */ public
451 static boolean isValidInternalSId(String sid) {
452    return libsbmlJNI.SyntaxChecker_isValidInternalSId(sid);
453  }
454
455  
456/**
457   * Returns true <code>true</code> or <code>false</code> depending on whether the argument
458   * string conforms to the syntax of SBML identifiers or is empty.
459   * @internal
460   */ public
461 static boolean isValidInternalUnitSId(String sid) {
462    return libsbmlJNI.SyntaxChecker_isValidInternalUnitSId(sid);
463  }
464
465  public SyntaxChecker() {
466    this(libsbmlJNI.new_SyntaxChecker(), true);
467  }
468
469}