NAME¶
"LaTeXML::Common::Error" - Error and Progress Reporting and Logging
support.
DESCRIPTION¶
"LaTeXML::Common::Error" does some simple stack analysis to generate
more informative, readable, error messages for LaTeXML. Its routines are used
by the error reporting methods from LaTeXML::Global, namely "Warn",
"Error" and "Fatal".
Error Reporting¶
The Error reporting functions all take a similar set of arguments, the
differences are in the implied severity of the situation, and in the amount of
detail that will be reported.
The $category is a string naming a broad category of errors, such as
"undefined". The set is open-ended, but see the manual for a list of
recognized categories. $object is the object whose presence or lack caused the
problem.
$where indicates where the problem occurred; passs in the $gullet or $stomach if
the problem occurred during expansion or digestion; pass in a document node if
it occurred there. A string will be used as is; if an undefined value is used,
the error handler will try to guess.
The $message should be a somewhat concise, but readable, explanation of the
problem, but ought to not refer to the document or any "incident
specific" information, so as to support indexing in build systems.
@details provides additional lines of information that may be indident
specific.
- "Fatal($category,$object,$where,$message,@details);"
- Signals an fatal error, printing $message along with some context. In
verbose mode a stack trace is printed.
- "Error($category,$object,$where,$message,@details);"
- Signals an error, printing $message along with some context. If in strict
mode, this is the same as Fatal(). Otherwise, it attempts to
continue processing..
- "Warn($category,$object,$where,$message,@details);"
- Prints a warning message along with a short indicator of the input
context, unless verbosity is quiet.
- "Info($category,$object,$where,$message,@details);"
- Prints an informational message along with a short indicator of the input
context, unless verbosity is quiet.
- "NoteProgress($message);"
- Prints $message unless the verbosity level below 0. Typically just a short
mark to indicate motion, but can be longer; provide your own newlines, if
needed.
- "NoteProgressDetailed($message);"
- Like "NoteProgress", but for noiser progress, only prints when
verbosity >= 1.
Internal Functions¶
No user serviceable parts inside. These symbols are not exported.
- "$string =
LaTeXML::Common::Error::generateMessage($typ,$msg,$lng,@more);"
- Constructs an error or warning message based on the current stack and the
current location in the document. $typ is a short string characterizing
the type of message, such as "Error". $msg is the error message
itself. If $lng is true, will generate a more verbose message; this also
uses the VERBOSITY set in the $STATE. Longer messages will show a trace of
the objects invoked on the stack, @more are additional strings to include
in the message.
- "$string = LaTeXML::Common::Error::stacktrace;"
- Return a formatted string showing a trace of the stackframes up until this
function was invoked.
- "@objects = LaTeXML::Common::Error::objectStack;"
- Return a list of objects invoked on the stack. This procedure only
considers those stackframes which involve methods, and the objects are
those (unique) objects that the method was called on.
AUTHOR¶
Bruce Miller <bruce.miller@nist.gov>
COPYRIGHT¶
Public domain software, produced as part of work done by the United States
Government & not subject to copyright in the US.