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—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 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 2.0; similarly, the production <code>digit</code> consists of 175the numerals <code>0..9</code> along with related Unicode 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 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 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 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 2 and 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 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<sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3' 323 xmlns:xhtml='http://www.w3.org/1999/xhtml'> 324 <model> 325 <notes> 326 <xhtml:body> 327 <xhtml:center><xhtml:h2>A Simple Mitotic Oscillator</xhtml:h2></xhtml:center> 328 <xhtml:p>A minimal cascade model for the mitotic oscillator.</xhtml:p> 329 </xhtml:body> 330 </notes> 331 ... rest of model ... 332</sbml> 333</pre></div> 334 * Contrast the above with the following, self-contained version, which 335 * places the XML namespace declaration within the <code><notes></code> 336 * element itself: 337 * <div class='fragment'><pre class='fragment'> 338<sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'> 339 <model> 340 <notes> 341 <html xmlns='http://www.w3.org/1999/xhtml'> 342 <head> 343 <title/> 344 </head> 345 <body> 346 <center><h2>A Simple Mitotic Oscillator</h2></center> 347 A minimal cascade model for the mitotic oscillator.</p> 348 </body> 349 </html> 350 </notes> 351 ... rest of model ... 352</sbml> 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 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 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 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 2 and 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 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<sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3' 431 xmlns:xhtml='http://www.w3.org/1999/xhtml'> 432 <model> 433 <notes> 434 <xhtml:body> 435 <xhtml:center><xhtml:h2>A Simple Mitotic Oscillator</xhtml:h2></xhtml:center> 436 <xhtml:p>A minimal cascade model for the mitotic oscillator.</xhtml:p> 437 </xhtml:body> 438 </notes> 439 ... rest of model ... 440</sbml> 441</pre></div> 442 * Contrast the above with the following, self-contained version, which 443 * places the XML namespace declaration within the <code><notes></code> 444 * element itself: 445 * <div class='fragment'><pre class='fragment'> 446<sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'> 447 <model> 448 <notes> 449 <html xmlns='http://www.w3.org/1999/xhtml'> 450 <head> 451 <title/> 452 </head> 453 <body> 454 <center><h2>A Simple Mitotic Oscillator</h2></center> 455 A minimal cascade model for the mitotic oscillator.</p> 456 </body> 457 </html> 458 </notes> 459 ... rest of model ... 460</sbml> 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 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}