LaTeXML...::Error(3)

🌸 NAME 🌸

Okay bestie, welcome to the LaTeXML...::Error(3) page — yep, that's the LaTeXML...::Error(3) manual from User Contributed Perl Documentation. This module is LaTeXML::Common::Error, and it handles error and progress reporting plus logging support. 💖

💖 DESCRIPTION 💖

LaTeXML::Common::Error does some simple stack analysis to make LaTeXML's error messages more informative and readable. Its routines get used by the error reporting methods from LaTeXML::Global — specifically Warn, Error, and Fatal. ✨

The whole idea: print a minimal amount to STDERR (maybe with colors, spinners, etc. if it's a terminal), and print more complete info to a log file. Neither of those is enabled by default, okay? see below. 🫶

• SetVerbosity($verbosity); — controls how verbose the terminal output is. 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. 😌

$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: pass 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. 🧚

$message should be a somewhat concise but readable explanation of the problem, but it 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 incident specific. 💜

• Fatal($category,$object,$where,$message,@details); — signals a 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 is 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); — yes, this exact item appears again in the original. Its description says: end a processing stage "bugin" with ProgressSpindown($stage);. Keepin' it exactly as written, bestie. 💅
• 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 [the original's spelling 💀] 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, it 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, and @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. 🫡

---

Okay bye bestie 💅 this page is from perl v5.42.3, dated 2024-02-26, and it's the LaTeXML...::Error(3) manual. Mwah 🫶💖