--- name: "LaTeXML::Common::Error" section: "3pm" platform: "linux" package: "latexml" version: "0.8.8-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/LaTeXML::Common::Error" --- # LaTeXML::Common::Error(3pm) Error and Progress Reporting and Logging support. ## 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"`. The general idea is that a minimal amount should be printed to STDERR (possibly with colors, spinners, etc if it is a terminal), and more complete information is printed to a log file. Neither of these are enabled, by default; see below. - "SetVerbosity($verbosity);" Controls the verbosity of output to the terminal; default is 0, higher gives more information, lower gives less. A verbosity less than 0 inhibits all output to STDERR. - "UseSTDERR(); ... UseSTDERR(undef);" `"UseSTDERR();"` Enables and initializes STDERR to accept messages. If this is not called, there will be no output to STDERR. `"UseSTDERR(undef);"` disables STDERR from further messages. - "UseLog($path, $append); ... UseLog(undef);" `"UseLog($path, $append);"` opens a log file on the given path. If `$append` is true, this file will be appended to, otherwise, it will be created initially empty. If this is not called, there will be no log file. `"UseLog(undef);"` disables and closes the log file. ### 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. ## AUTHOR Bruce Miller \ ## COPYRIGHT Public domain software, produced as part of work done by the United States Government & not subject to copyright in the US.