001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 2.0.12
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 *  Methods for checking syntax of SBML identifiers and other
013 * 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   * <p>
077 * In SBML, identifiers that are the values of 'id' attributes on objects
078 * must conform to a data type called <code>SId</code> in the SBML
079 * specifications.  LibSBML does not provide an explicit <code>SId</code>
080 * data type; it uses ordinary character strings, which is easier for
081 * applications to support.  (LibSBML does, however, test for identifier
082 * validity at various times, such as when reading in models from files
083 * and data streams.) 
084   <p>
085   * This method provides programs with the ability to test explicitly that
086   * the identifier strings they create conform to the SBML identifier
087   * syntax.
088   <p>
089   * @param sid string to be checked for conformance to SBML identifier
090   * syntax.
091   <p>
092   * @return <code>true</code> if the string conforms to type SBML data type
093   * <code>SId</code>, <code>false</code> otherwise.
094   <p>
095   * <p>
096 * SBML has strict requirements for the syntax of identifiers, that is, the
097 * values of the 'id' attribute present on most types of SBML objects.
098 * The following is a summary of the definition of the SBML identifier type 
099 * <code>SId</code>, which defines the permitted syntax of identifiers.  We
100 * express the syntax using an extended form of BNF notation: 
101 * <pre style='margin-left: 2em; border: none; font-weight: bold; font-size: 13px; color: black'>
102 * letter .= 'a'..'z','A'..'Z'
103 * digit  .= '0'..'9'
104 * idChar .= letter | digit | '_'
105 * SId    .= ( letter | '_' ) idChar*
106 * </pre>
107 * The characters <code>(</code> and <code>)</code> are used for grouping, the
108 * character <code>*</code> 'zero or more times', and the character
109 * <code>|</code> indicates logical 'or'.  The equality of SBML identifiers is
110 * determined by an exact character sequence match; i.e., comparisons must be
111 * performed in a case-sensitive manner.  In addition, there are a few
112 * conditions for the uniqueness of identifiers in an SBML model.  Please
113 * consult the SBML specifications for the exact details of the uniqueness
114 * requirements.
115   <p>
116   * 
117   <p>
118   * @see SyntaxChecker#isValidUnitSId(String sid) 
119   * @see SyntaxChecker#isValidXMLID(String sid) 
120   */ public
121 static boolean isValidSBMLSId(String sid) {
122    return libsbmlJNI.SyntaxChecker_isValidSBMLSId(sid);
123  }
124
125  
126/**
127   * Returns <code>true</code> or <code>false</code> depending on whether the argument string
128   * conforms to the XML data type <code>ID</code>.
129   <p>
130   * <p>
131 * The optional attribute named 'metaid', present on every major SBML
132 * component type, is for supporting metadata annotations using RDF (<a
133 * href='http://www.w3.org/RDF/'>Resource Description Format</a>).  The
134 * attribute value has the data type <a
135 * href='http://www.w3.org/TR/REC-xml/#id'>XML <code>ID</code></a>, the XML
136 * identifier type, which means each 'metaid' value must be globally unique
137 * within an SBML file.  The latter point is important, because the
138 * uniqueness criterion applies across <em>any</em> attribute with type
139 * <code>ID</code> anywhere in the file, not just the 'metaid' attribute used
140 * by SBML&mdash;something to be aware of if your application-specific XML
141 * content inside the 'annotation' subelement happens to use the XML
142 * <code>ID</code> type.  Although SBML itself specifies the use of <a
143 * href='http://www.w3.org/TR/REC-xml/#id'>XML <code>ID</code></a> only for
144 * the 'metaid' attribute, SBML-compatible applications should be careful if
145 * they use XML <code>ID</code>'s in XML portions of a model that are not
146 * defined by SBML, such as in the application-specific content of the
147 * 'annotation' subelement.  Finally, note that LibSBML does not provide an
148 * explicit XML <code>ID</code> data type; it uses ordinary character
149 * strings, which is easier for applications to support. 
150   <p>
151   * This method provides programs with the ability to test explicitly that
152   * the identifier strings they create conform to the SBML identifier
153   * syntax.
154   <p>
155   * @param id string to be checked for conformance to the syntax of
156   * <a target='_blank' href='http://www.w3.org/TR/REC-xml/#id'>XML ID</a>.
157   <p>
158   * @return <code>true</code> if the string is a syntactically-valid value for the
159   * XML type <a target='_blank'
160   * href='http://www.w3.org/TR/REC-xml/#id'>ID</a>, <code>false</code> otherwise.
161   <p>
162   * @note The following is a summary of the definition of the XML&nbsp;1.0 data type
163<a target="_blank" href="http://www.w3.org/TR/REC-xml/#id">ID</a>.  We
164express the syntax using an extended form of BNF notation:
165<p>
166<nobr><code style="margin-left: 2em">NCNameChar ::= letter | digit | '.' | '-' | '_' | ':' | CombiningChar | Extender</code><br></nobr>
167<code style="margin-left: 2em">ID ::= ( letter | '_' | ':' ) NCNameChar*</code><br>
168<p>
169The characters <code>(</code> and <code>)</code> are used for grouping, the
170character <code>*</code> means "zero or more times", and the character
171<code>|</code> indicates logical "or". The production <code>letter</code>
172consists of the basic upper and lower case alphabetic characters of the
173Latin alphabet along with a large number of related characters defined by
174Unicode&nbsp;2.0; similarly, the production <code>digit</code> consists of
175the numerals <code>0..9</code> along with related Unicode&nbsp;2.0
176characters.  The <code>CombiningChar</code> production is a list of
177characters that add such things as accents to the preceding character. (For
178example, the Unicode character <code>\#x030A</code> when combined with
179<code>a</code> produces <code>a</code>.)  The <code>Extender</code>
180production is a list of characters that extend the shape of the preceding
181character.  Please consult the <a target="_blank"
182href="http://www.w3.org/TR/2004/REC-xml-20040204/">XML&nbsp;1.0
183specification</a> for the complete definitions of <code>letter</code>,
184<code>digit</code>, <code>CombiningChar</code>, and <code>Extender</code>.
185<p>
186
187   <p>
188   * 
189   <p>
190   * @see SyntaxChecker#isValidSBMLSId(String sid) 
191   * @see SyntaxChecker#isValidUnitSId(String sid) 
192   */ public
193 static boolean isValidXMLID(String id) {
194    return libsbmlJNI.SyntaxChecker_isValidXMLID(id);
195  }
196
197  
198/**
199   * Returns <code>true</code> or <code>false</code> depending on whether the <code>uri</code> argument string
200   * conforms to the XML data type <code>anyURI</code>.
201   <p>
202   * Type anyURI is defined by XML Schema 1.0. It is a character string 
203   * data type whose values are interpretable as URIs (Universal Resource 
204   * Identifiers) as described by the W3C document RFC 3986.  LibSBML
205   * does not provide an explicit XML <code>anyURI</code> data type; it uses
206   * ordinary character strings, which is easier for applications to
207   * support.  LibSBML does, however, test for anyURI validity at
208   * various times, such as when reading in models from files and data
209   * streams.
210   <p>
211   * This method provides programs with the ability to test explicitly that
212   * the strings they create conform to the XML anyURI syntax.
213   <p>
214   * @param uri string to be checked for conformance to the syntax of
215   * <a target='_blank' 
216   * href='http://www.w3.org/TR/xmlschema-2/#anyURI'>anyURI</a>.
217   <p>
218   * @return <code>true</code> if the string is a syntactically-valid value for the
219   * XML type <a target='_blank'
220   * href='http://www.w3.org/TR/xmlschema-2/#anyURI'>anyURI</a>, 
221   * <code>false</code> otherwise.
222   <p>
223   * 
224   */ public
225 static boolean isValidXMLanyURI(String uri) {
226    return libsbmlJNI.SyntaxChecker_isValidXMLanyURI(uri);
227  }
228
229  
230/**
231   * Returns <code>true</code> or <code>false</code> depending on whether the argument string
232   * conforms to the syntax of SBML unit identifiers.
233   <p>
234   * In SBML, the identifiers of units (of both the predefined units and
235   * user-defined units) must conform to a data type called
236   * <code>UnitSId</code> in the SBML specifications.  LibSBML does not
237   * provide an explicit <code>UnitSId</code> data type; it uses ordinary
238   * character strings, which is easier for applications to support.
239   * LibSBML does, however, test for identifier validity at various times,
240   * such as when reading in models from files and data streams.
241   <p>
242   * This method provides programs with the ability to test explicitly that
243   * the identifier strings they create conform to the SBML identifier
244   * syntax.
245   <p>
246   * @param units string to be checked for conformance to SBML unit
247   * identifier syntax.
248   <p>
249   * @return <code>true</code> if the string conforms to type SBML data type
250   * <code>UnitSId</code>, <code>false</code> otherwise.
251   <p>
252   * @note The following is a summary of the definition of the SBML identifier type
253<code>UnitSId</code>, which defines the permitted syntax of identifiers.
254We express the syntax using an extended form of BNF notation:
255<p>
256<code style="margin-left: 2em">letter ::= 'a'..'z','A'..'Z'</code><br>
257<code style="margin-left: 2em">digit  ::= '0'..'9'</code><br>
258<code style="margin-left: 2em">idChar ::= letter | digit | '_'</code><br>
259<code style="margin-left: 2em">SId    ::= ( letter | '_' ) idChar*</code><br>
260<p>
261The characters <code>(</code> and <code>)</code> are used for grouping, the
262character <code>*</code> "zero or more times", and the character
263<code>|</code> indicates logical "or".  The equality of SBML unit
264identifiers is determined by an exact character sequence match; i.e.,
265comparisons must be performed in a case-sensitive manner.  In addition,
266there are a few conditions for the uniqueness of unit identifiers in an
267SBML model.  Please consult the SBML specifications for the exact
268formulations.
269<p>
270
271   <p>
272   * 
273   <p>
274   * @see SyntaxChecker#isValidSBMLSId(String sid) 
275   * @see SyntaxChecker#isValidXMLID(String sid) 
276   */ public
277 static boolean isValidUnitSId(String units) {
278    return libsbmlJNI.SyntaxChecker_isValidUnitSId(units);
279  }
280
281  
282/**
283   * Returns <code>true</code> or <code>false</code> depending on whether the given {@link XMLNode}
284   * object contains valid XHTML content.
285   <p>
286   * <p>
287 * The optional SBML element named 'notes', present on every major SBML
288 * component type (and in SBML Level&nbsp;3, the 'message' subelement of
289 * {@link Constraint}), is intended as a place for storing optional information
290 * intended to be seen by humans.  An example use of the 'notes' element
291 * would be to contain formatted user comments about the model element in
292 * which the 'notes' element is enclosed.  Every object derived directly or
293 * indirectly from type {@link SBase} can have a separate value for 'notes', allowing
294 * users considerable freedom when adding comments to their models.
295 <p>
296 * The format of 'notes' elements conform to the definition of <a
297 * target='_blank' href='http://www.w3.org/TR/xhtml1/'>XHTML&nbsp;1.0</a>.
298 * However, the content cannot be <em>entirely</em> free-form; it must satisfy
299 * certain requirements defined in the <a target='_blank'
300 * href='http://sbml.org/Documents/Specifications'>SBML specifications</a>
301 * for specific SBML Levels.  To help verify the formatting of 'notes'
302 * content, libSBML provides the static utility method
303 * {@link SyntaxChecker#hasExpectedXHTMLSyntax(XMLNode xhtml)}; The
304 * method implements a verification process that lets callers check whether
305 * the content of a given {@link XMLNode} object conforms to the SBML requirements
306 * for 'notes' and 'message' structure.  Developers are urged to consult the
307 * appropriate <a target='_blank'
308 * href='http://sbml.org/Documents/Specifications'>SBML specification
309 * document</a> for the Level and Version of their model for more in-depth
310 * explanations of using 'notes' in SBML.  The SBML Level&nbsp;2 and &nbsp;3
311 * specifications have considerable detail about how 'notes' element content
312 * must be structured.
313   <p>
314   * An aspect of XHTML validity is that the content is declared to be in
315   * the XML namespace for XHTML&nbsp;1.0.  There is more than one way in
316   * which this can be done in XML.  In particular, a model might not
317   * contain the declaration within the 'notes' or 'message' subelement
318   * itself, but might instead place the declaration on an enclosing
319   * element and use an XML namespace prefix within the 'notes' element to
320   * refer to it.  In other words, the following is valid:
321   * <div class='fragment'><pre class='fragment'>
322&lt;sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'
323      xmlns:xhtml='http://www.w3.org/1999/xhtml'&gt;
324  &lt;model&gt;
325    &lt;notes&gt;
326      &lt;xhtml:body&gt;
327        &lt;xhtml:center&gt;&lt;xhtml:h2&gt;A Simple Mitotic Oscillator&lt;/xhtml:h2&gt;&lt;/xhtml:center&gt;
328        &lt;xhtml:p&gt;A minimal cascade model for the mitotic oscillator.&lt;/xhtml:p&gt;
329      &lt;/xhtml:body&gt;
330    &lt;/notes&gt;
331  ... rest of model ...
332&lt;/sbml&gt;
333</pre></div>
334   * Contrast the above with the following, self-contained version, which
335   * places the XML namespace declaration within the <code>&lt;notes&gt;</code>
336   * element itself:
337   * <div class='fragment'><pre class='fragment'>
338&lt;sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'&gt;
339  &lt;model&gt;
340    &lt;notes&gt;
341      &lt;html xmlns='http://www.w3.org/1999/xhtml'&gt;
342        &lt;head&gt;
343          &lt;title/&gt;
344        &lt;/head&gt;
345        &lt;body&gt;
346          &lt;center&gt;&lt;h2&gt;A Simple Mitotic Oscillator&lt;/h2&gt;&lt;/center&gt;
347          A minimal cascade model for the mitotic oscillator.&lt;/p&gt;
348        &lt;/body&gt;
349      &lt;/html&gt;
350    &lt;/notes&gt;
351  ... rest of model ...
352&lt;/sbml&gt;
353</pre></div>
354   <p>
355   * Both of the above are valid XML.  The purpose of the <code>sbmlns</code>
356   * argument to this method is to allow callers to check the validity of
357   * 'notes' and 'message' subelements whose XML namespace declarations
358   * have been put elsewhere in the manner illustrated above.  Callers can
359   * can pass in the {@link SBMLNamespaces} object of a higher-level model
360   * component if the {@link XMLNode} object does not itself have the XML namespace
361   * declaration for XHTML&nbsp;1.0.
362   <p>
363   * @param xhtml the {@link XMLNode} to be checked for conformance.
364   * @param sbmlns the {@link SBMLNamespaces} associated with the object.
365   <p>
366   * @return <code>true</code> if the {@link XMLNode} content conforms, <code>false</code> otherwise.
367   <p>
368   * 
369   <p>
370   * 
371</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
372The native C++ implementation of this method defines a default argument
373value. In the documentation generated for different libSBML language
374bindings, you may or may not see corresponding arguments in the method
375declarations. For example, in Java and C#, a default argument is handled by
376declaring two separate methods, with one of them having the argument and
377the other one lacking the argument. However, the libSBML documentation will
378be <em>identical</em> for both methods. Consequently, if you are reading
379this and do not see an argument even though one is described, please look
380for descriptions of other variants of this method near where this one
381appears in the documentation.
382</dd></dl>
383 
384   */ public
385 static boolean hasExpectedXHTMLSyntax(XMLNode xhtml, SBMLNamespaces sbmlns) {
386    return libsbmlJNI.SyntaxChecker_hasExpectedXHTMLSyntax__SWIG_0(XMLNode.getCPtr(xhtml), xhtml, SBMLNamespaces.getCPtr(sbmlns), sbmlns);
387  }
388
389  
390/**
391   * Returns <code>true</code> or <code>false</code> depending on whether the given {@link XMLNode}
392   * object contains valid XHTML content.
393   <p>
394   * <p>
395 * The optional SBML element named 'notes', present on every major SBML
396 * component type (and in SBML Level&nbsp;3, the 'message' subelement of
397 * {@link Constraint}), is intended as a place for storing optional information
398 * intended to be seen by humans.  An example use of the 'notes' element
399 * would be to contain formatted user comments about the model element in
400 * which the 'notes' element is enclosed.  Every object derived directly or
401 * indirectly from type {@link SBase} can have a separate value for 'notes', allowing
402 * users considerable freedom when adding comments to their models.
403 <p>
404 * The format of 'notes' elements conform to the definition of <a
405 * target='_blank' href='http://www.w3.org/TR/xhtml1/'>XHTML&nbsp;1.0</a>.
406 * However, the content cannot be <em>entirely</em> free-form; it must satisfy
407 * certain requirements defined in the <a target='_blank'
408 * href='http://sbml.org/Documents/Specifications'>SBML specifications</a>
409 * for specific SBML Levels.  To help verify the formatting of 'notes'
410 * content, libSBML provides the static utility method
411 * {@link SyntaxChecker#hasExpectedXHTMLSyntax(XMLNode xhtml)}; The
412 * method implements a verification process that lets callers check whether
413 * the content of a given {@link XMLNode} object conforms to the SBML requirements
414 * for 'notes' and 'message' structure.  Developers are urged to consult the
415 * appropriate <a target='_blank'
416 * href='http://sbml.org/Documents/Specifications'>SBML specification
417 * document</a> for the Level and Version of their model for more in-depth
418 * explanations of using 'notes' in SBML.  The SBML Level&nbsp;2 and &nbsp;3
419 * specifications have considerable detail about how 'notes' element content
420 * must be structured.
421   <p>
422   * An aspect of XHTML validity is that the content is declared to be in
423   * the XML namespace for XHTML&nbsp;1.0.  There is more than one way in
424   * which this can be done in XML.  In particular, a model might not
425   * contain the declaration within the 'notes' or 'message' subelement
426   * itself, but might instead place the declaration on an enclosing
427   * element and use an XML namespace prefix within the 'notes' element to
428   * refer to it.  In other words, the following is valid:
429   * <div class='fragment'><pre class='fragment'>
430&lt;sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'
431      xmlns:xhtml='http://www.w3.org/1999/xhtml'&gt;
432  &lt;model&gt;
433    &lt;notes&gt;
434      &lt;xhtml:body&gt;
435        &lt;xhtml:center&gt;&lt;xhtml:h2&gt;A Simple Mitotic Oscillator&lt;/xhtml:h2&gt;&lt;/xhtml:center&gt;
436        &lt;xhtml:p&gt;A minimal cascade model for the mitotic oscillator.&lt;/xhtml:p&gt;
437      &lt;/xhtml:body&gt;
438    &lt;/notes&gt;
439  ... rest of model ...
440&lt;/sbml&gt;
441</pre></div>
442   * Contrast the above with the following, self-contained version, which
443   * places the XML namespace declaration within the <code>&lt;notes&gt;</code>
444   * element itself:
445   * <div class='fragment'><pre class='fragment'>
446&lt;sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'&gt;
447  &lt;model&gt;
448    &lt;notes&gt;
449      &lt;html xmlns='http://www.w3.org/1999/xhtml'&gt;
450        &lt;head&gt;
451          &lt;title/&gt;
452        &lt;/head&gt;
453        &lt;body&gt;
454          &lt;center&gt;&lt;h2&gt;A Simple Mitotic Oscillator&lt;/h2&gt;&lt;/center&gt;
455          A minimal cascade model for the mitotic oscillator.&lt;/p&gt;
456        &lt;/body&gt;
457      &lt;/html&gt;
458    &lt;/notes&gt;
459  ... rest of model ...
460&lt;/sbml&gt;
461</pre></div>
462   <p>
463   * Both of the above are valid XML.  The purpose of the <code>sbmlns</code>
464   * argument to this method is to allow callers to check the validity of
465   * 'notes' and 'message' subelements whose XML namespace declarations
466   * have been put elsewhere in the manner illustrated above.  Callers can
467   * can pass in the {@link SBMLNamespaces} object of a higher-level model
468   * component if the {@link XMLNode} object does not itself have the XML namespace
469   * declaration for XHTML&nbsp;1.0.
470   <p>
471   * @param xhtml the {@link XMLNode} to be checked for conformance.
472   * @param sbmlns the {@link SBMLNamespaces} associated with the object.
473   <p>
474   * @return <code>true</code> if the {@link XMLNode} content conforms, <code>false</code> otherwise.
475   <p>
476   * 
477   <p>
478   * 
479</dl><dl class="docnote"><dt><b>Documentation note:</b></dt><dd>
480The native C++ implementation of this method defines a default argument
481value. In the documentation generated for different libSBML language
482bindings, you may or may not see corresponding arguments in the method
483declarations. For example, in Java and C#, a default argument is handled by
484declaring two separate methods, with one of them having the argument and
485the other one lacking the argument. However, the libSBML documentation will
486be <em>identical</em> for both methods. Consequently, if you are reading
487this and do not see an argument even though one is described, please look
488for descriptions of other variants of this method near where this one
489appears in the documentation.
490</dd></dl>
491 
492   */ public
493 static boolean hasExpectedXHTMLSyntax(XMLNode xhtml) {
494    return libsbmlJNI.SyntaxChecker_hasExpectedXHTMLSyntax__SWIG_1(XMLNode.getCPtr(xhtml), xhtml);
495  }
496
497  
498/**
499   * Returns true <code>true</code> or <code>false</code> depending on whether the argument
500   * string conforms to the syntax of SBML identifiers or is empty.
501   * @internal
502   */ public
503 static boolean isValidInternalSId(String sid) {
504    return libsbmlJNI.SyntaxChecker_isValidInternalSId(sid);
505  }
506
507  
508/** * @internal */ public
509 static boolean isValidInternalUnitSId(String sid) {
510    return libsbmlJNI.SyntaxChecker_isValidInternalUnitSId(sid);
511  }
512
513  public SyntaxChecker() {
514    this(libsbmlJNI.new_SyntaxChecker(), true);
515  }
516
517}