LaTeXML::Common::Error3pm

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.

Progress Reporting

"Note($message);"

General status message, printed whenever verbosity at or above 0, to both STDERR and the Log file (when enabled).

"NoteLog($message);"

Prints a status message to the Log file (when enabled).

"NoteSTDERR($message);"

Prints a status message to the terminal (STDERR) (when enabled).

"ProgressSpinup($stage);"

Begin a processing stage, which will be ended with ProgressSpindown($stage); This prints a message to the log such as "(stage... runtime)", where runtime is the time required. In conjunction with ProgressStep(), creates a progress spinner on STDERR.

"ProgressSpinup($stage);"

End a processing stage bugin with "ProgressSpindown($stage);".

"ProgressStep();"

Steps a progress spinner on STDERR.

Debugging

Debugging statements may be embedded throughout the program. These are associated with a feature keyword. A given feature is enabled using the command-line option "--debug=feature".

"Debug($message) if $LaTeXML::DEBUG{$feature}"

Prints $message if debugging has been enabled for the given feature.

"DebuggableFeature($feature,$description)"

Declare that $feature is a known debuggable feature, and give a description of it.

CheckDebuggable()

A untility to check and report if all requested debugging features actually have debugging messages declared.

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.