1LaTeXML::Common::Error(U3s)er Contributed Perl DocumentatLiaoTneXML::Common::Error(3)
2
3
4

NAME

6       "LaTeXML::Common::Error" - Error and Progress Reporting and Logging
7       support.
8

DESCRIPTION

10       "LaTeXML::Common::Error" does some simple stack analysis to generate
11       more informative, readable, error messages for LaTeXML.  Its routines
12       are used by the error reporting methods from LaTeXML::Global, namely
13       "Warn", "Error" and "Fatal".
14
15       The general idea is that a minimal amount should be printed to STDERR
16       (possibly with colors, spinners, etc if it is a terminal), and more
17       complete information is printed to a log file. Neither of these are
18       enabled, by default; see below.
19
20       "SetVerbosity($verbosity);"
21           Controls the verbosity of output to the terminal; default is 0,
22           higher gives more information, lower gives less.  A verbosity less
23           than 0 inhibits all output to STDERR.
24
25       "UseSTDERR(); ... UseSTDERR(undef);"
26           "UseSTDERR();" Enables and initializes STDERR to accept messages.
27           If this is not called, there will be no output to STDERR.
28           "UseSTDERR(undef);" disables STDERR from further messages.
29
30       "UseLog($path, $append); ... UseLog(undef);"
31           "UseLog($path, $append);" opens a log file on the given path.  If
32           $append is true, this file will be appended to, otherwise, it will
33           be created initially empty.  If this is not called, there will be
34           no log file.  "UseLog(undef);" disables and closes the log file.
35
36   Error Reporting
37       The Error reporting functions all take a similar set of arguments, the
38       differences are in the implied severity of the situation, and in the
39       amount of detail that will be reported.
40
41       The $category is a string naming a broad category of errors, such as
42       "undefined". The set is open-ended, but see the manual for a list of
43       recognized categories.  $object is the object whose presence or lack
44       caused the problem.
45
46       $where indicates where the problem occurred; passs in the $gullet or
47       $stomach if the problem occurred during expansion or digestion; pass in
48       a document node if it occurred there.  A string will be used as is; if
49       an undefined value is used, the error handler will try to guess.
50
51       The $message should be a somewhat concise, but readable, explanation of
52       the problem, but ought to not refer to the document or any "incident
53       specific" information, so as to support indexing in build systems.
54       @details provides additional lines of information that may be indident
55       specific.
56
57       "Fatal($category,$object,$where,$message,@details);"
58           Signals an fatal error, printing $message along with some context.
59           In verbose mode a stack trace is printed.
60
61       "Error($category,$object,$where,$message,@details);"
62           Signals an error, printing $message along with some context.  If in
63           strict mode, this is the same as Fatal().  Otherwise, it attempts
64           to continue processing..
65
66       "Warn($category,$object,$where,$message,@details);"
67           Prints a warning message along with a short indicator of the input
68           context, unless verbosity is quiet.
69
70       "Info($category,$object,$where,$message,@details);"
71           Prints an informational message along with a short indicator of the
72           input context, unless verbosity is quiet.
73
74   Progress Reporting
75       "Note($message);"
76           General status message, printed whenever verbosity at or above 0,
77           to both STDERR and the Log file (when enabled).
78
79       "NoteLog($message);"
80           Prints a status message to the Log file (when enabled).
81
82       "NoteSTDERR($message);"
83           Prints a status message to the terminal (STDERR) (when enabled).
84
85       "ProgressSpinup($stage);"
86           Begin a processing stage, which will be ended with
87           "ProgressSpindown($stage)"; This prints a message to the log such
88           as "(stage... runtime)", where runtime is the time required.  In
89           conjunction with "ProgressStep()", creates a progress spinner on
90           STDERR.
91
92       "ProgressSpinup($stage);"
93           End a processing stage bugin with "ProgressSpindown($stage);".
94
95       "ProgressStep();"
96           Steps a progress spinner on STDERR.
97
98   Debugging
99       Debugging statements may be embedded throughout the program. These are
100       associated with a feature keyword.  A given feature is enabled using
101       the command-line option "--debug=feature".
102
103       "Debug($message) if $LaTeXML::DEBUG{$feature}"
104           Prints $message if debugging has been enabled for the given
105           feature.
106
107       "DebuggableFeature($feature,$description)"
108           Declare that $feature is a known debuggable feature, and give a
109           description of it.
110
111       "CheckDebuggable()"
112           A untility to check and report if all requested debugging features
113           actually have debugging messages declared.
114
115   Internal Functions
116       No user serviceable parts inside.  These symbols are not exported.
117
118       "$string =
119       LaTeXML::Common::Error::generateMessage($typ,$msg,$lng,@more);"
120           Constructs an error or warning message based on the current stack
121           and the current location in the document.  $typ is a short string
122           characterizing the type of message, such as "Error".  $msg is the
123           error message itself. If $lng is true, will generate a more verbose
124           message; this also uses the VERBOSITY set in the $STATE.  Longer
125           messages will show a trace of the objects invoked on the stack,
126           @more are additional strings to include in the message.
127
128       "$string = LaTeXML::Common::Error::stacktrace;"
129           Return a formatted string showing a trace of the stackframes up
130           until this function was invoked.
131
132       "@objects = LaTeXML::Common::Error::objectStack;"
133           Return a list of objects invoked on the stack.  This procedure only
134           considers those stackframes which involve methods, and the objects
135           are those (unique) objects that the method was called on.
136

AUTHOR

138       Bruce Miller <bruce.miller@nist.gov>
139
141       Public domain software, produced as part of work done by the United
142       States Government & not subject to copyright in the US.
143
144
145
146perl v5.34.0                      2021-11-24         LaTeXML::Common::Error(3)
Impressum