libSBML Perl API
libSBML 5.17.2 Perl API
|
{core}
An error, warning or other diagnostic.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.
When a libSBML operation on SBML content results in an error, or when there is something wrong with the SBML content, the problems are reported as SBMLError objects. These are generally stored in an SBMLErrorLog object; this log object, in turn, is kept in the SBMLDocument object containing the SBML content. Applications can obtain the list of logged errors using SBMLDocument::getErrorLog() and then use the methods provided by SBMLErrorLog to access individual SBMLError objects. (Note that despite the word "error" in the name, SBMLError objects are used to represent not only "true" errors, but also warnings and some informational diagnostics. The name is a historical hold-over from early versions of libSBML, in which the object really was only used to report errors.)
Error codes are useful mainly for software. For human readers, SBMLError also includes text messages that describe the nature of a given problem. The messages can be accessed using SBMLError::getShortMessage() and SBMLError::getMessage(). The former provides a brief one-line description of the issue, while SBMLError::getMessage() provides a more detailed text, including (if appropriate) references to sections of the SBML specifications where relevant topics are discussed. These text strings are suitable for displaying to human users.
Public Member Functions | |
unsigned int | getCategory () const |
Returns the category of this error. More... | |
const std::string & | getCategoryAsString () const |
Returns a string describing the category of this error. More... | |
unsigned int | getColumn () const |
Returns the column number in the XML input near where the error, warning or other diagnostic occurred. More... | |
unsigned int | getErrorId () const |
Returns the identifier of this error. More... | |
unsigned int | getErrorIdOffset () const |
Returns libSBML's internal numerical offset for the error code associated with this error. More... | |
unsigned int | getLine () const |
Returns the line number in the XML input near where the error, warning or other diagnostic occurred. More... | |
const std::string & | getMessage () const |
Returns the message text of this error. More... | |
const std::string & | getPackage () const |
Returns the SBML Level 3 package extension (if any) that logged this error. More... | |
unsigned int | getSeverity () const |
Returns the severity of this error. More... | |
const std::string & | getSeverityAsString () const |
Returns a string describing the severity level of this error. More... | |
const std::string & | getShortMessage () const |
Returns a brief message for this error. More... | |
bool | isError () const |
Predicate returning true or false depending on whether this error is a significant error. More... | |
bool | isFatal () const |
Predicate returning true or false depending on whether this error is a fatal run-time error. More... | |
bool | isInfo () const |
Predicate returning true or false depending on whether this error object is for information purposes only. More... | |
bool | isInternal () const |
Predicate returning true or false depending on whether this error resulted from an internal program error. More... | |
bool | isSystem () const |
Predicate returning true or false depending on whether this error was generated by the operating system. More... | |
bool | isValid () const |
Predicate returning true or false depending on whether this error resulted from a problem or whether it was logged as an unknown error. More... | |
bool | isWarning () const |
Predicate returning true or false depending on whether this error object is a warning. More... | |
bool | isXML () const |
Predicate returning true or false depending on whether this error resulted from a problem in the XML input (e.g., an XML syntax error). More... | |
SBMLError (const unsigned int errorId=0, const unsigned int level=SBML_DEFAULT_LEVEL, const unsigned int version=SBML_DEFAULT_VERSION, const std::string &details="", const unsigned int line=0, const unsigned int column=0, const unsigned int severity=LIBSBML_SEV_ERROR, const unsigned int category=LIBSBML_CAT_SBML, const std::string &package="core", const unsigned int pkgVersion=1) | |
Creates a new SBMLError to report that something occurred during SBML processing. More... | |
SBMLError (const SBMLError &orig) | |
Copy constructor; creates a copy of this SBMLError. More... | |
int | setColumn (unsigned int column) |
Sets the column number where this error occurred. More... | |
int | setLine (unsigned int line) |
Sets the line number where this error occurred. More... | |
virtual | ~SBMLError () |
Destroys this SBMLError. More... | |
Static Public Member Functions | |
static const std::string | getStandardMessage (const int code) |
Returns a copy of the message string associated with the given predefined XMLError code. More... | |
SBMLError::SBMLError | ( | const unsigned int | errorId = 0 , |
const unsigned int | level = SBML_DEFAULT_LEVEL , |
||
const unsigned int | version = SBML_DEFAULT_VERSION , |
||
const std::string & | details = "" , |
||
const unsigned int | line = 0 , |
||
const unsigned int | column = 0 , |
||
const unsigned int | severity = LIBSBML_SEV_ERROR , |
||
const unsigned int | category = LIBSBML_CAT_SBML , |
||
const std::string & | package = "core" , |
||
const unsigned int | pkgVersion = 1 |
||
) |
Creates a new SBMLError to report that something occurred during SBML processing.
When a libSBML operation on SBML content results in a warning, error or other diagnostic, the issue is reported as an SBMLError object. SBMLError objects have identification numbers to indicate the nature of the exception. The argument errorId
to this constructor can be (but does not have to be) a value from this set of constants. If it is one of the predefined error identifiers, the SBMLError class assumes the error is a low-level system or SBML layer error and prepends a built-in, predefined error message to any string passed in the argument details
to this constructor. In addition, all the predefined error identifiers have associated values for the severity
and category
codes, and these fields are filled-in using the libSBML defaults for each different error identifier.
If the error identifier errorId
is a number greater than 99999, the SBMLError class assumes the error was generated from another part of the software and does not do additional filling in of values beyond the default in the constructor itself. This allows SBMLError to serve as a base class for other errors, such as for user-defined validation rules (see Validator). Callers should fill in all the parameters with suitable values if generating errors with codes greater than 99999 to make maximum use of the SBMLError facilities.
As mentioned above, there are additional constants defined for standard severity and standard category codes, and every predefined error in libSBML has an associated value for severity and category taken from these predefined sets. These constants have symbol names prefixed with LIBSBML_SEV_
and LIBSBML_CAT_
, respectively. If the value of errorId
is one of the standard error codes, callers do not need to fill in severity
and category
in a call to this constructor. Conversely, if errorId
is not an existing SBML-level error code, callers can use other values for severity
and category
.
Please see the top of the documentation for SBMLError for a longer discussion of the possible error codes, their meanings, and their applicability to different combinations of Level+Version of SBML.
errorId | an unsigned int, the identification number of the error. |
level | the SBML Level of the SBML model. |
version | the SBML Version within the Level of the SBML model. |
details | a string containing additional details about the error. If the error code in errorId is one that is recognized by SBMLError, the given message is appended to a predefined message associated with the given code. If the error code is not recognized, the message is stored as-is as the text of the error. |
line | an unsigned int, the line number at which the error occured. |
column | an unsigned int, the column number at which the error occured. |
severity | an integer indicating severity of the error. |
category | an integer indicating the category to which the error belongs. |
package | the SBML Level package involved. |
pkgVersion | the version of the package . |
SBMLError::SBMLError | ( | const SBMLError & | orig | ) |
Copy constructor; creates a copy of this SBMLError.
orig | the instance to copy. |
|
virtual |
Destroys this SBMLError.
|
inherited |
Returns the category of this error.
XMLError defines an enumeration of category codes for the XML layer. Applications that build on XMLError by subclassing it may add their own categories with numbers higher than those in the predefined set of category codes.
Categories can be used to partition errors into distinct groups. Among other things, this can be used to prevent id conflicts by uniquely identifying an XMLError by both id and category.
|
inherited |
Returns a string describing the category of this error.
XMLError defines an enumeration of category codes for the XML layer. Applications that build on XMLError by subclassing it may add their own categories with numbers higher than those in the predefined set of category codes.
Categories can be used to partition errors into distinct groups. Among other things, this can be used to prevent id conflicts by uniquely identifying an XMLError by both id and category.
|
inherited |
Returns the column number in the XML input near where the error, warning or other diagnostic occurred.
We say "near where the problem occurred", because many factors affect how accurate the line/column information ultimately is. For example, sometimes, the underlying XML parsers can only report such information for the parent XML element where an error occurs, and not for the specific point where the problem occurs. In other situations, some parsers report invalid line and/or column numbers altogether. If this occurs, libSBML sets the line and/or column number in the XMLError object to either 0
or the value of the maximum unsigned long integer representable on the platform where libSBML is running. The probability that a true line or column number in an SBML model would equal this value is vanishingly small; thus, if an application encounters these values in an XMLError object, it can assume no valid line/column number could be provided by libSBML in that situation.
|
inherited |
Returns the identifier of this error.
|
inherited |
Returns libSBML's internal numerical offset for the error code associated with this error.
In the SBML Level 3 package specifications, package validation rules are identified by 5-digit numbers prefixed with the nickname of the package itself—e.g., “comp-10101”, “fbc-20301”, etc. Historically, libSBML reported error codes as pure integers, and some application software systems make decisions based on the numerical values of the error codes. To permit these applications to continue to function in this fashion, libSBML internally continues to maintain error identifiers as pure integers. To handle the possibility that errors may come from package extensions, libSBML uses numerical offsets added to the internal error codes. These offsets add two leading digits to the regular 5-digit error codes; for example, “comp” error codes are stored as 1010101, 1020102, etc. The offset in this case is 1000000. Another package will have the offset 2000000, yet another will have 3000000, etc.
This method returns the integer offset in this error's error code. Calling applications can get the 5-digit package-specific number for a given error code by subtracting the offset from the value reported by getErrorId():
getErrorId() - getErrorIdOffset()
When libSBML produces error messages, it combines the text string returned by getPackage() with the subtracted value of the error code, to produce a text string of the form “comp-10101”.
|
inherited |
Returns the line number in the XML input near where the error, warning or other diagnostic occurred.
We say "near where the problem occurred", because many factors affect how accurate the line/column information ultimately is. For example, sometimes, the underlying XML parsers can only report such information for the parent XML element where an error occurs, and not for the specific point where the problem occurs. In other situations, some parsers report invalid line and/or column numbers altogether. If this occurs, libSBML sets the line and/or column number in the XMLError object to either 0
or the value of the maximum unsigned long integer representable on the platform where libSBML is running. The probability that a true line or column number in an SBML model would equal this value is vanishingly small; thus, if an application encounters these values in an XMLError object, it can assume no valid line/column number could be provided by libSBML in that situation.
|
inherited |
Returns the message text of this error.
The message associated with an error object describes the nature of the problem. The message returned by this method is generally longer and clearer than the message returned by XMLError::getShortMessage(), but not in all cases.
Callers may use XMLError::getCategory() and XMLError::getSeverity() to obtain additional information about the nature and severity of the problem.
|
inherited |
Returns the SBML Level 3 package extension (if any) that logged this error.
Each error logged by an libSBML extension for SBML Level 3 packages includes a record of the package that logged it. The field is a simple text string. If the string is empty or has the value "core"
, then the error came from libSBML core; otherwise, the string will be the short-form name of the package (e.g., "comp"
for the Hierarchical Model Composition package).
"core"
.
|
inherited |
Returns the severity of this error.
XMLError defines an enumeration of severity codes for the XML layer. Applications that build on XMLError by subclassing it may add their own severity codes with numbers higher than those in the predefined set of severity codes.
|
inherited |
Returns a string describing the severity level of this error.
XMLError defines an enumeration of severity codes for the XML layer. Applications that build on XMLError by subclassing it may add their own severity codes with numbers higher than those in the predefined set of severity codes.
|
inherited |
Returns a brief message for this error.
This is an alternative error message that, in general, is as short as the authors could make it. However, brevity is often inversely proportional to clarity, so this short message may not be sufficiently informative to understand the nature of the error. Calling applications may wish to check XMLError::getMessage() in addition or instead.
|
staticinherited |
Returns a copy of the message string associated with the given predefined XMLError code.
code | the error code whose message is sought; it must be a predefined value from the set of predefined error identifiers. |
|
inherited |
Predicate returning true
or false
depending on whether this error is a significant error.
This is equivalent to obtaining the severity code from an XMLError object (via XMLError::getSeverity()) and then comparing it to the value
|
inherited |
Predicate returning true
or false
depending on whether this error is a fatal run-time error.
This is equivalent to obtaining the severity code from an XMLError object (via XMLError::getSeverity()) and then comparing it to the value
|
inherited |
Predicate returning true
or false
depending on whether this error object is for information purposes only.
This is equivalent to obtaining the severity code from an XMLError object (via XMLError::getSeverity()) and then comparing it to the value
|
inherited |
Predicate returning true
or false
depending on whether this error resulted from an internal program error.
This is equivalent to obtaining the category identifier from an XMLError object (via XMLError::getCategory()) and then comparing it to the value
|
inherited |
Predicate returning true
or false
depending on whether this error was generated by the operating system.
This is equivalent to obtaining the category identifier from an XMLError object (via XMLError::getCategory()) and then comparing it to the value
|
inherited |
Predicate returning true
or false
depending on whether this error resulted from a problem or whether it was logged as an unknown error.
This is equivalent to obtaining the error identifier from an XMLError object (via XMLError::getErrorId()) and then comparing it to the value XMLUnknownError or UnknownError from the set of predefined error codes.
true
) or whether it is unknown (false
).
|
inherited |
Predicate returning true
or false
depending on whether this error object is a warning.
This is equivalent to obtaining the severity code from an XMLError object (via XMLError::getSeverity()) and then comparing it to the value
|
inherited |
Predicate returning true
or false
depending on whether this error resulted from a problem in the XML input (e.g., an XML syntax error).
This is equivalent to obtaining the category identifier from an XMLError object (via XMLError::getCategory()) and then comparing it to the value
|
inherited |
Sets the column number where this error occurred.
column | an unsigned int, the column number to set. |
|
inherited |
Sets the line number where this error occurred.
line | an unsigned int, the line number to set. |