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 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 2.0; similarly, the production <code>digit</code> consists of 165the numerals <code>0..9</code> along with related Unicode 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 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 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 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<sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3' 276 xmlns:xhtml='http://www.w3.org/1999/xhtml'> 277 <model> 278 <notes> 279 <xhtml:body> 280 <xhtml:center><xhtml:h2>A Simple Mitotic Oscillator</xhtml:h2></xhtml:center> 281 <xhtml:p>A minimal cascade model for the mitotic oscillator.</xhtml:p> 282 </xhtml:body> 283 </notes> 284 ... rest of model ... 285</sbml> 286</pre></div> 287 * Contrast the above with the following, self-contained version, which 288 * places the XML namespace declaration within the <code><notes></code> 289 * element itself: 290 * <div class='fragment'><pre> 291<sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'> 292 <model> 293 <notes> 294 <html xmlns='http://www.w3.org/1999/xhtml'> 295 <head> 296 <title/> 297 </head> 298 <body> 299 <center><h2>A Simple Mitotic Oscillator</h2></center> 300 A minimal cascade model for the mitotic oscillator.</p> 301 </body> 302 </html> 303 </notes> 304 ... rest of model ... 305</sbml> 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 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 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 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<sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3' 374 xmlns:xhtml='http://www.w3.org/1999/xhtml'> 375 <model> 376 <notes> 377 <xhtml:body> 378 <xhtml:center><xhtml:h2>A Simple Mitotic Oscillator</xhtml:h2></xhtml:center> 379 <xhtml:p>A minimal cascade model for the mitotic oscillator.</xhtml:p> 380 </xhtml:body> 381 </notes> 382 ... rest of model ... 383</sbml> 384</pre></div> 385 * Contrast the above with the following, self-contained version, which 386 * places the XML namespace declaration within the <code><notes></code> 387 * element itself: 388 * <div class='fragment'><pre> 389<sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'> 390 <model> 391 <notes> 392 <html xmlns='http://www.w3.org/1999/xhtml'> 393 <head> 394 <title/> 395 </head> 396 <body> 397 <center><h2>A Simple Mitotic Oscillator</h2></center> 398 A minimal cascade model for the mitotic oscillator.</p> 399 </body> 400 </html> 401 </notes> 402 ... rest of model ... 403</sbml> 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 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}