w32tex
About: TeX Live provides a comprehensive TeX system including all the major TeX-related programs, macro packages, and fonts that are free software. Windows sources.
  Fossies Dox: w32tex-src.tar.xz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

error.hh
Go to the documentation of this file.
1 // -*- related-file-name: "../../liblcdf/error.cc" -*-
2 #ifndef LCDF_ERROR_HH
3 #define LCDF_ERROR_HH
4 #include <lcdf/string.hh>
5 #ifndef __KERNEL__
6 # include <stdio.h>
7 #endif
8 #include <stdarg.h>
9 #if HAVE_ADDRESSABLE_VA_LIST
10 # define VA_LIST_REF_T va_list *
11 # define VA_LIST_DEREF(val) (*(val))
12 # define VA_LIST_REF(val) (&(val))
13 #else
14 # define VA_LIST_REF_T va_list
15 # define VA_LIST_DEREF(val) (val)
16 # define VA_LIST_REF(val) (val)
17 #endif
18 #if __GNUC__ <= 3
19 # define ERRH_SENTINEL
20 # define ERRH_NORETURN
21 #else
22 # define ERRH_SENTINEL __attribute__((sentinel))
23 # define ERRH_NORETURN __attribute__((noreturn))
24 #endif
25 
26 /** @class ErrorHandler
27  * @brief Error reporting class.
28  *
29  * Report errors through ErrorHandler objects, which represent
30  * error collectors and printers. ErrorHandlers are passed to configure() and
31  * initialize() methods explicitly, as well as to write handlers; the
32  * click_chatter() function calls ErrorHandler implicitly.
33  *
34  * <h3>Cooked error messages</h3>
35  *
36  * Most ErrorHandler interactions consist of a simple call like this:
37  * @code
38  * errh->error("not enough arguments (%d needed)", 5);
39  * // prints something like "not enough arguments (5 needed)\n"
40  * @endcode
41  *
42  * This function constructs an error message string from the format arguments,
43  * annotates the string with a default error level (here, el_error), and
44  * prints it. Alternate versions take a landmark specifying where the error
45  * took place:
46  * @code
47  * errh->lwarning("file.click:2", "syntax error at '%s'", word.c_str());
48  * // prints something like "file.click:2: syntax error at 'foo'\n"
49  * @endcode
50  *
51  * <h3>Raw error messages</h3>
52  *
53  * For finer control over error levels and annotations, construct an error
54  * message string directly. An error message is a string consisting of one or
55  * more lines. Each line begins with a set of optional textual @em
56  * annotations. The following error message has a @em level annotation
57  * determining how serious the error is (this one is critical, since
58  * el_critical == 2), and a @em landmark annotation, which specifies where the
59  * error took place (here, "x.click:1"):
60  *
61  * <tt>"<2>{l:x.click:1}syntax error"</tt>
62  *
63  * The default ErrorHandlers understand the level and landmark
64  * annotations. Users can add other arbitrary annotations, which can be
65  * useful to pass error metadata. A pair of braces ends the annotation area.
66  * This example has one user annotation <tt>eoc</tt>, and a message area that
67  * would be mistaken for an annotation were it not for the <tt>{}</tt>:
68  *
69  * <tt>"<2>{l:x.click:1}{eoc:520}{}{not:an annotation}"</tt>
70  *
71  * <h3>Stacking handlers</h3>
72  *
73  * Some ErrorHandlers stack on top of others, adding useful functionality like
74  * automatic context description and prefixing. For example,
75  * ContextErrorHandler can be used to print messages like "In function
76  * 'xxx':".
77  * @code
78  * FileErrorHandler errh1(stderr);
79  * ContextErrorHandler errh2(&errh1, "While counting to 2:");
80  * errh2.error("An error occurred.");
81  * errh2.error("Another error occurred.");
82  * // prints "While counting to 2:\n"
83  * // " An error occurred.\n"
84  * // " Another error occurred.\n"
85  * @endcode */
86 class ErrorHandler { public:
87 
88  /** @brief Error level constants.
89  *
90  * Lower values represent more serious errors. Levels 0-7 correspond to
91  * Linux's error levels. Negative levels request immediate exit; at user
92  * level, the exit status is the absolute value of the
93  * error level. */
94  enum Level {
95  el_abort = -999, ///< Error level that triggers abort().
96  el_fatal = -1, ///< Fatal exit error level.
97  /// Exit status equals -(level).
98  el_emergency = 0, ///< Emergency error level: system is unusable.
99  el_alert = 1, ///< Alert error level: action must be taken.
100  el_critical = 2, ///< Error level for critical conditions.
101  el_error = 3, ///< Error level for normal error conditions.
102  el_warning = 4, ///< Error level for warning conditions.
103  el_notice = 5, ///< Error level for normal, but significant
104  /// conditions.
105  el_info = 6, ///< Error level for informational messages.
106  el_debug = 7 ///< Error level for debug messages.
107  };
108 
109  /** @brief Error level indicators. */
110  static const char e_abort[],
121 
122  /** @brief Construct an ErrorHandler. */
124  : _nerrors(0) {
125  }
126 
127  virtual ~ErrorHandler() {
128  }
129 
130 
131  /** @brief Initialize the ErrorHandler implementation.
132  * @param errh default error handler
133  * @return @a errh
134  *
135  * Call this function to initialize the ErrorHandler implementation. The
136  * function installs the default conversions, creates the
137  * silent_handler(), and installs @a errh as the default error handler
138  * (see default_handler()).
139  *
140  * @note The @a errh object becomes the property of the ErrorHandler
141  * implementation and must not be deleted.
142  * (ErrorHandler::static_cleanup() will delete it.) Only the first call
143  * to static_initialize() has any effect. */
145 
146  /** @brief Tear down the ErrorHandler implementation.
147  *
148  * Deletes the internal ErrorHandlers and uninstalls default
149  * conversions. */
150  static void static_cleanup();
151 
152 
153  /** @brief Return the default ErrorHandler.
154  * @sa static_initialize() */
156  return the_default_handler;
157  }
158 
159  /** @brief Set the default ErrorHandler to @a errh.
160  * @note @a errh becomes property of the ErrorHandler implementation,
161  * and will be freed by static_cleanup(). However, any prior default
162  * handler is @em not destroyed. Callers should delete the prior handler
163  * when necessary. */
164  static void set_default_handler(ErrorHandler *errh);
165 
166  /** @brief Return the global silent ErrorHandler. */
168  return the_silent_handler;
169  }
170 
171 
172  static const int ok_result; ///< Equals 0, used for error levels
173  /// <5> and above
174  static const int error_result; ///< Equals -EINVAL, used for error
175  /// levels <4> and below
176 
177 
178  /** @brief Print a debug message (level el_debug).
179  *
180  * @a fmt and any following arguments are parsed as by format(), and the
181  * resulting string is passed to xmessage(). */
182  void debug(const char *fmt, ...);
183  /** @brief Print an informational message (level el_info). */
184  void message(const char *fmt, ...);
185  /** @brief Print a warning message (level el_warning).
186  * @return error_result
187  *
188  * The string "warning: " is prepended to every line of the message. */
189  int warning(const char *fmt, ...);
190  /** @brief Print an error message (level el_error).
191  * @return error_result */
192  int error(const char *fmt, ...);
193  /** @brief Print a fatal error message (level el_fatal).
194  * @return error_result
195  *
196  * Calling fatal() will cause the process to abort. */
197  void fatal(const char *fmt, ...) ERRH_NORETURN;
198 
199  /** @brief Print a debug message with a landmark annotation. */
200  void ldebug(const String &landmark, const char *fmt, ...);
201  /** @brief Print an informational message with a landmark annotation. */
202  void lmessage(const String &landmark, const char *fmt, ...);
203  /** @brief Print a warning message with a landmark annotation. */
204  int lwarning(const String &landmark, const char *fmt, ...);
205  /** @brief Print an error message with a landmark annotation. */
206  int lerror(const String &landmark, const char *fmt, ...);
207  /** @brief Print a fatal error message with a landmark annotation. */
208  void lfatal(const String &landmark, const char *fmt, ...) ERRH_NORETURN;
209 
210 
211  /** @brief Print an annotated error message.
212  * @return ok_result if the minimum error level was el_notice or higher,
213  * otherwise error_result
214  *
215  * This function drives the virtual functions actually responsible for
216  * error message decoration and printing. It passes @a str to decorate(),
217  * separates the result into lines, calls emit() for each line, and calls
218  * account() with the minimum error level of any line.
219  *
220  * Most users will call shorthand functions like error(), warning(), or
221  * lmessage(), which add relevant annotations to the message. */
222  int xmessage(const String &str);
223  /** @brief Print an error message, adding annotations.
224  * @param anno annotations
225  * @param str error message
226  *
227  * Shorthand for xmessage(combine_anno(@a str, @a anno)). */
229  return xmessage(combine_anno(str, anno));
230  }
231  /** @brief Format and print an error message, adding annotations.
232  * @param anno annotations
233  * @param fmt error message format
234  * @param val format arguments
235  *
236  * Shorthand for xmessage(@a anno, vformat(@a fmt, @a val)). */
237  int xmessage(const String &anno, const char *fmt, va_list val) {
238  return xmessage(anno, vformat(fmt, val));
239  }
240  /** @brief Print an error message, adding landmark and other annotations.
241  * @param landmark landmark annotation
242  * @param anno additional annotations
243  * @param str error message
244  *
245  * Shorthand for xmessage(combine_anno(@a anno, make_landmark_anno(@a
246  * landmark)), @a str). */
247  int xmessage(const String &landmark, const String &anno,
248  const String &str) {
250  }
251  /** @brief Format and print an error message, adding landmark and other
252  * annotations.
253  * @param landmark landmark annotation
254  * @param anno additional annotations
255  * @param fmt error message format
256  * @param val format arguments
257  *
258  * Shorthand for xmessage(@a landmark, @a anno, vformat(@a fmt, @a
259  * val)). */
260  int xmessage(const String &landmark, const String &anno,
261  const char *fmt, va_list val) {
262  return xmessage(landmark, anno, vformat(fmt, val));
263  }
264 
265 
266  /** @brief Return the number of errors reported via this handler.
267  *
268  * An error is any message that contains at least one line with error
269  * level 3 (#el_error) or below.
270  *
271  * @note The error count will also contain errors reported via stacked
272  * handlers. For instance:
273  * @code
274  * SilentErrorHandler errh1;
275  * PrefixErrorHandler errh2(&errh1, "");
276  * assert(errh1.nerrors() == 0);
277  * errh2.error("blah");
278  * assert(errh1.nerrors() == 1);
279  * @endcode
280  *
281  * @sa account, clear */
282  int nerrors() const {
283  return _nerrors;
284  }
285 
286 
287  /** @brief Format an error string.
288  * @param default_flags default ConversionFlags
289  * @param fmt printf-like format string
290  * @return formatted error string
291  *
292  * Formats an error string using printf-like % conversions. Conversions
293  * include:
294  *
295  * <table>
296  *
297  * <tr><td><tt>\%d</tt>, <tt>\%i</tt></td><td>Format an <tt>int</tt> as a
298  * decimal string. Understands flags in <tt>#0- +</tt>, field widths
299  * (including <tt>*</tt>), and precisions.</td></tr>
300  *
301  * <tr><td><tt>\%hd</tt>, <tt>\%ld</tt>, <tt>\%lld</tt>,
302  * <tt>\%zd</tt></td><td>Format a <tt>short</tt>, <tt>long</tt>, <tt>long
303  * long</tt>, or <tt>size_t</tt>.</td></tr>
304  *
305  * <tr><td><tt>\%^16d</tt>, <tt>\%^32d</tt>, <tt>\%^64d</tt></td>
306  * <td>Format a 16-, 32-, or 64-bit integer.</td></tr>
307  *
308  * <tr><td><tt>\%o</tt>, <tt>\%u</tt>, <tt>\%x</tt>,
309  * <tt>\%X</tt></td><td>Format an unsigned integer in octal, decimal, or
310  * hexadecimal (with lower-case or upper-case letters).</td></tr>
311  *
312  * <tr><td><tt>\%s</tt></td><td>Format a C string (<tt>const char *</tt>).
313  * The alternate form <tt>\%\#s</tt> calls String::printable() on the
314  * input string. Both <tt>\%\#s</tt> and the alternate form <tt>\%'s</tt>
315  * ensure that no part of the string is mistaken for an error
316  * annotation.</td></tr>
317  *
318  * <tr><td><tt>\%c</tt></td><td>Format a character. Prints a C-like
319  * escape if the input character isn't printable ASCII.</td></tr>
320  *
321  * <tr><td><tt>\%p</tt></td><td>Format a pointer as a hexadecimal
322  * value.</td></tr>
323  *
324  * <tr><td><tt>\%e</tt>, <tt>\%E</tt>, <tt>\%f</tt>, <tt>\%F</tt>,
325  * <tt>\%g</tt>, <tt>\%G</tt></td><td>Format a <tt>double</tt> (user-level
326  * only).</td></tr>
327  *
328  * <tr><td><tt>\%p{...}</tt><td>Call a user-provided conversion function.
329  * For example, <tt>\%p{ip_ptr}</tt> reads an <tt>IPAddress *</tt> argument
330  * from the argument list, and formats the pointed-to address using
331  * IPAddress::unparse().</td></tr>
332  *
333  * <tr><td><tt>\%\%</tt></td><td>Format a literal \% character.</td></tr>
334  *
335  * <tr><td><tt>\%<</tt></td><td>Format a left quote string. Usually
336  * prints a single quote.</td></tr>
337  *
338  * <tr><td><tt>\%></tt></td><td>Format a right quote string. Usually
339  * prints a single quote.</td></tr>
340  *
341  * <tr><td><tt>\%,</tt></td><td>Format an apostrophe string. Usually
342  * prints a single quote.</td></tr>
343  *
344  * </table> */
345  static String xformat(int default_flags, const char *fmt, ...);
346  /** @overload */
347  static String vxformat(int default_flags, const char *fmt, va_list val);
348  /** @overload */
349  static String xformat(const char *fmt, ...);
350  /** @overload */
351  static String vxformat(const char *fmt, va_list val) {
352  return vxformat(0, fmt, val);
353  }
354 
355 
356  /** @brief Format an error string.
357  * @param fmt format string
358  * @param val argument list
359  *
360  * @warning ErrorHandler users don't need to call this function directly;
361  * it is called implicitly by the error()/xmessage() functions.
362  *
363  * This virtual function is called to format an error message. The
364  * default implementation returns the result of vxformat(@a fmt, @a val). */
365  virtual String vformat(const char *fmt, va_list val);
366 
367  /** @brief Format an error string.
368  * @param fmt format string
369  *
370  * @warning ErrorHandler users don't usually need to call this function
371  * directly.
372  *
373  * This is a convenience function that calls vformat(const char *fmt,
374  * va_list val) for a va_list taken from the ellipsis arguments. */
375  String format(const char *fmt, ...);
376 
377  /** @brief Decorate an error message.
378  * @param str error message, possibly with annotations
379  * @return decorated error message
380  *
381  * @warning ErrorHandler users don't need to call this function directly;
382  * it is called implicitly by the error()/xmessage() functions.
383  *
384  * This virtual function is called to decorate an error message before it
385  * is emitted. The input @a str is an error message string, possibly
386  * annotated. The default implementation returns @a str unchanged. Other
387  * ErrorHandlers might add context lines (ContextErrorHandler), prefixes
388  * (PrefixErrorHandler), or a default landmark (LandmarkErrorHandler). */
389  virtual String decorate(const String &str);
390 
391  /** @brief Output an error message line.
392  * @param str error message line, possibly with annotations
393  * @param user_data callback data, 0 for first line in a message
394  * @param more true iff this is the last line in the current message
395  * @return @a user_data to be passed to emit() for the next line
396  *
397  * @warning ErrorHandler users don't need to call this function directly;
398  * it is called implicitly by the error()/xmessage() functions.
399  *
400  * After calling decorate(), ErrorHandler splits the message into
401  * individual lines and calls emit() once per line. ErrorHandler
402  * subclasses should output the error lines as appropriate; for example,
403  * FileErrorHandler outputs the error message to a file.
404  *
405  * @a str does not contain a newline, but may contain annotations,
406  * including a landmark annotation. Most ErrorHandlers use parse_anno()
407  * to extract the landmark annotation, clean it with clean_landmark(), and
408  * print it ahead of the error message proper.
409  *
410  * ErrorHandler can handle multi-line error messages. However, the emit()
411  * function takes a line at a time; this is more useful in practice for
412  * most error message printers. The @a user_data and @a more arguments
413  * can help an ErrorHandler combine the lines of a multi-line error
414  * message. @a user_data is null for the first line; for second and
415  * subsequent lines, ErrorHandler passes the result of the last line's
416  * emit() call. @a more is true iff this is the last line in the current
417  * message.
418  *
419  * The default emit() implementation does nothing. */
420  virtual void *emit(const String &str, void *user_data, bool more);
421 
422  /** @brief Account for an error message at level @a level.
423  * @param level minimum error level in the message
424  *
425  * @warning ErrorHandler users don't need to call this function directly;
426  * it is called implicitly by the error()/xmessage() functions.
427  *
428  * After calling emit() for the lines of an error message, ErrorHandler
429  * calls account(), passing the minimum (worst) error level of any message
430  * line (or 1000 if no line had a level). The default implementation
431  * updates the nerrors() counter, and exits the program if @a level is
432  * small enough. */
433  virtual void account(int level);
434 
435  /** @brief Clear accumulated error state.
436  *
437  * The default implementation sets the nerrors() counter to zero. */
438  virtual void clear() {
439  _nerrors = 0;
440  }
441 
442 
443  /** @brief Create an error annotation.
444  * @param name annotation name
445  * @param value annotation value
446  * @return annotation string
447  *
448  * Returns an error annotation that associates annotation @a name with @a
449  * value.
450  *
451  * If @a name equals "<>", then returns a level annotation of the form
452  * "<@a value>". @a value must be valid number; if it isn't, the function
453  * returns the empty string.
454  *
455  * Otherwise, @a name must be a nonempty series of letters and digits.
456  * make_anno() returns a string of the form "{@a name:@a value}", where
457  * special characters in @a value are quoted with backslashes. */
458  static String make_anno(const char *name, const String &value);
459 
460  /** @brief Apply annotations from @a anno to every line in @a str.
461  * @param str string
462  * @param anno annotation string
463  *
464  * The annotations from @a anno are applied to every line in @a str. New
465  * annotations do not override existing annotations with the same names.
466  * If the @a anno string ends with non-annotation characters, this
467  * substring is prefixed to every line in @a str.
468  *
469  * For example:
470  * @code
471  * combine_anno("Line 1\n{l:old}{x:x}Line 2\n", "<0>{l:new} ")
472  * // returns "<0>{l:new} Line 1\n<0>{l:old}{x:x} Line 2\n"
473  * @endcode */
474  static String combine_anno(const String &str, const String &anno);
475 
476  /** @brief Parse error annotations from a string.
477  * @param str the string
478  * @param begin pointer within @a str to start of annotation area
479  * @param end pointer to end of error region, usually @a str.end()
480  * @return pointer to first character after annotation area
481  * @pre @a str.begin() <= {@a begin, @a end} <= @a str.end()
482  * @post @a begin <= returned value <= @a end
483  *
484  * Use this function to skip an error line's annotation area, possibly
485  * extracting named annotations.
486  *
487  * The variable arguments portion consists of a series of pairs of C
488  * strings and value pointers, terminated by a null character pointer.
489  * Each C string is an annotation name. The corresponding annotation
490  * value, if found, is stored as a String object in the value pointer.
491  * You can also store the <tt>int</tt> value of an annotation by prefixing
492  * an annotation name with the '#' character.
493  *
494  * For example:
495  * @code
496  * String line = "{l:file:30}<4.5>error message\n";
497  * String landmark_str, level_str;
498  * const char *s = ErrorHandler::parse_anno(line, line.begin(), line.end(),
499  * "l", &landmark_str, "<>", &level_str, (const char *) 0);
500  * // Results: s points to "error message\n",
501  * // landmark_str == "file:30", level_str == "4.5"
502  *
503  * int level;
504  * s = ErrorHandler::parse_anno(line, line.begin(), line.end(),
505  * "#<>", &level, (const char *) 0);
506  * // Results: s points to "error message\n", level_str == 4
507  * @endcode */
508  static const char *parse_anno(const String &str,
509  const char *begin, const char *end, ...) ERRH_SENTINEL;
510 
511  /** @brief Skip a string's error annotations.
512  * @param begin pointer to start of string
513  * @param end pointer one past end of string
514  * @return pointer to first character after annotation area
515  * @post @a begin <= returned value <= @a end
516  *
517  * Use this function to skip an error line's annotation area. The error
518  * line is defined as a pair of iterators. */
519  static const char *skip_anno(const char *begin, const char *end) {
520  String name, value;
521  const char *x = begin;
522  do {
523  x = skip_anno(String(), x, end, &name, &value, false);
524  } while (name);
525  return x;
526  }
527 
528 
529  /** @brief Return a landmark annotation equal to @a x.
530  * @param x landmark
531  *
532  * If @a x is empty, returns the empty string. Otherwise, if @a x looks
533  * like a formatted annotation (it starts with an open brace), returns @a
534  * x unchanged. Otherwise, returns make_anno("l", @a x). */
536  if (x && x[0] == '{')
537  return x;
538  else if (x)
539  return make_anno("l", x);
540  else
541  return String();
542  }
543 
544  /** @brief Clean the @a landmark.
545  * @param landmark landmark text
546  * @param colon if true, append <tt>": "</tt> to a nonempty landmark
547  *
548  * Removes trailing space and an optional trailing colon from @a landmark
549  * and returns the result. If @a colon is true, and the cleaned landmark
550  * isn't the empty string, then appends <tt>": "</tt> to the result. */
551  static String clean_landmark(const String &landmark, bool colon = false);
552 
553 
554  // error conversions
555  struct Conversion;
558  cf_zero_pad = 1, ///< Set for conversions using the '0' flag.
559  cf_plus_positive = 2, ///< Set for conversions using the '+' flag.
560  cf_space_positive = 4, ///< Set for conversions using the ' ' flag.
561  cf_left_just = 8, ///< Set for conversions using the '-' flag.
562  cf_alternate_form = 16, ///< Set for conversions using the '#' flag.
563  cf_singlequote = 32, ///< Set for conversions using the '\'' flag.
564  cf_uppercase = 64, ///< Set for 'X' conversions (not 'x').
565  cf_signed = 128, ///< Set for conversions of signed numbers.
566  cf_negative = 256, ///< Set for conversions of negative numbers.
567  cf_utf8 = 1024 ///< Set to use UTF-8 characters on output.
568  };
569  static Conversion *add_conversion(const String &name, ConversionFunction func);
570  static int remove_conversion(Conversion *conversion);
571 
572  private:
573 
574  int _nerrors;
575 
578 
579  static const char *skip_anno(const String &str,
580  const char *begin, const char *end,
581  String *name_result, String *value_result,
582  bool raw);
583 
584 };
585 
586 
587 /** @class SilentErrorHandler
588  * @brief An ErrorHandler that does not report messages.
589  *
590  * Use SilentErrorHandler when an ErrorHandler object is required, but error
591  * messages should not be printed. */
592 class SilentErrorHandler : public ErrorHandler { public:
593 
595  }
596 
597 };
598 
599 
600 /** @class ErrorVeneer
601  * @brief Base class for ErrorHandlers that forward messages.
602  *
603  * ErrorHandlers can stack. Stacking ErrorHandlers simplify modify a message
604  * and then pass the result to a base ErrorHandler, which does the actual
605  * printing. The ErrorVeneer base class simplifies the implementation of
606  * stacking ErrorHandlers. It provides versions of ErrorHandler's format(),
607  * decorate(), emit(), and account() methods that forward to the underlying
608  * handler. Note that the clear() method is <em>not</em> automatically
609  * forwarded. */
610 class ErrorVeneer : public ErrorHandler { public:
611 
612  /** @brief Construct an ErrorVeneer.
613  * @param errh base ErrorHandler
614  *
615  * If @a errh is 0, then the ErrorVeneer acts like a
616  * SilentErrorHandler. */
618  : _errh(errh) {
619  }
620 
621  String vformat(const char *fmt, va_list val);
622  String decorate(const String &str);
623  void *emit(const String &str, void *user_data, bool more);
624  void account(int level);
625 
626  private:
627 
629 
630 };
631 
632 
633 #ifndef __KERNEL__
634 /** @class FileErrorHandler
635  * @brief An ErrorHandler that prints error messages to a given file.
636  *
637  * FileErrorHandler is the typical base ErrorHandler used at user level. It
638  * prints messages to a file passed in to the constructor, and calls exit() or
639  * abort() based on the error level. */
640 class FileErrorHandler : public ErrorHandler { public:
641 
642  /** @brief Construct a FileErrorHandler.
643  * @param f file to print errors
644  * @param prefix string to prefix every error line */
645  FileErrorHandler(FILE *f, const String &prefix = String());
646 
647  void set_default_flags(int default_flags) {
648  _default_flags = default_flags;
649  }
650 
651  String vformat(const char *fmt, va_list val);
652  void *emit(const String &str, void *user_data, bool more);
653 
654  private:
655 
659 
660 };
661 #endif
662 
663 
664 /** @class LocalErrorHandler
665  * @brief A convenience stackable ErrorHandler.
666  *
667  * It's often convenient to pass a null ErrorHandler pointer when errors
668  * should not be printed. The LocalErrorHandler class simplifies dealing with
669  * ErrorHandler pointers that may or may not be null. LocalErrorHandler is a
670  * transparent layer on the base handler; but if the base handler is null, it
671  * acts like a SilentErrorHandler. For example:
672  * @code
673  * void f(ErrorHandler *errh) { // errh might or might not be null
674  * LocalErrorHandler lerrh(errh);
675  * ... lerrh.message("message") ...
676  * }
677  * @endcode */
678 class LocalErrorHandler : public ErrorVeneer { public:
679 
680  /** @brief Construct a LocalErrorHandler. */
682  : ErrorVeneer(errh) {
683  }
684 
685 };
686 
687 
688 /** @class ContextErrorHandler
689  * @brief A stackable ErrorHandler that prints context lines.
690  *
691  * The stackable ContextErrorHandler adds context to the first error
692  * message printed, and optionally indent error messages so that they appear
693  * grouped underneath the context.
694  * @code
695  * FileErrorHandler errh1(stderr);
696  * ContextErrorHandler errh2(&errh1, "While counting to 2:");
697  * errh2.error("An error occurred.");
698  * errh2.error("Another error occurred.");
699  * // prints "While counting to 2:\n"
700  * // " An error occurred.\n"
701  * // " Another error occurred.\n"
702  * @endcode
703  *
704  * To prevent ContextErrorHandler from indenting or printing context for a
705  * message, add a "{context:no}" annotation to the message's first line. To
706  * turn off the indent but keep the context, add a "{context:noindent}"
707  * annotation.
708  * @code
709  * FileErrorHandler errh1(stderr);
710  * ContextErrorHandler errh2(&errh1, "While counting to 2:");
711  * errh2.error("{context:no}An error occurred.");
712  * errh2.error("Another error occurred.");
713  * // prints "An error occurred.\n"
714  * // "While counting to 2:\n"
715  * // " Another error occurred.\n"
716  *
717  * FileErrorHandler errh1(stderr);
718  * PrefixErrorHandler noctx_errh(stderr, "{context:no}");
719  * ContextErrorHandler errh2(&errh1, "While counting to 2:");
720  * errh2.error("An error occurred.");
721  * errh2.error("Another error occurred.");
722  * // prints "An error occurred.\n"
723  * // "Another error occurred.\n"
724  * @endcode
725  *
726  * ContextErrorHandler adds the "{context:context}" annotation to context
727  * lines. */
728 class ContextErrorHandler : public ErrorVeneer { public:
729 
730  /** @brief Construct a ContextErrorHandler.
731  * @param errh base ErrorHandler
732  * @param fmt format for context lines
733  *
734  * The context message is formed by @a errh->format() using @a fmt and
735  * any additional arguments. */
736  ContextErrorHandler(ErrorHandler *errh, const char *fmt, ...);
737 
738  /** @brief Return true iff the context has already been printed. */
739  bool context_printed() const {
740  return _context_printed;
741  }
742 
743  /** @brief Set whether the context has been printed. */
744  void set_context_printed(bool x) {
746  }
747 
748  /** @brief Set the context string to @a str. */
749  void set_context(const String &str) {
750  _context = str;
751  }
752 
753  /** @brief Set the indent string to @a str.
754  *
755  * The indent string is prepended to all non-context messages. It can
756  * contain landmarks as well as non-landmark text. The default indent
757  * string is " " (two spaces). */
758  void set_indent(const String &str) {
759  _indent = str;
760  }
761 
762  /** @brief Set the context landmark to @a str.
763  *
764  * The context landmark is used to decorate the context, and also applied
765  * to any error messages that lack landmarks of their own. The default
766  * context landmark is empty.
767  *
768  * @note The input @a str is passed to
769  * ErrorHandler::make_landmark_anno(). */
772  }
773 
774  String decorate(const String &str);
775 
776  private:
777 
782 
783 };
784 
785 
786 /** @class PrefixErrorHandler
787  * @brief A stackable ErrorHandler that adds a prefix to error messages.
788  *
789  * The stackable ContextErrorHandler adds a prefix to every error line
790  * printed. For example:
791  * @code
792  * FileErrorHandler errh1(stderr);
793  * PrefixErrorHandler errh2(&errh1, "Blah--");
794  * errh2.error("An error occurred.");
795  * errh2.error("Another error occurred.");
796  * // prints "Blah--An error occurred.\n"
797  * // "Blah--Another error occurred.\n"
798  * @endcode */
799 class PrefixErrorHandler : public ErrorVeneer { public:
800 
801  /** @brief Construct a PrefixErrorHandler.
802  * @param errh base ErrorHandler
803  * @param prefix string to prefix to error lines */
805 
806  String decorate(const String &str);
807 
808  private:
809 
811 
812 };
813 
814 
815 /** @class LandmarkErrorHandler
816  * @brief A stackable ErrorHandler that adds a default landmark to error
817  * messages.
818  *
819  * The stackable ContextErrorHandler adds a default landmark to every error
820  * line printed. Error lines' own landmarks are preserved when they exist.
821  * For example:
822  * @code
823  * FileErrorHandler errh1(stderr);
824  * LandmarkErrorHandler errh2(&errh1, "file:1");
825  * errh2.error("An error occurred.");
826  * errh2.lerror("file:2", "Another error occurred.");
827  * // prints "file:1: An error occurred.\n"
828  * // "file:2: Another error occurred.\n"
829  * @endcode */
830 class LandmarkErrorHandler : public ErrorVeneer { public:
831 
832  /** @brief Construct a LandmarkErrorHandler.
833  * @param errh base ErrorHandler
834  * @param landmark default landmark */
836 
837  /** @brief Set the default landmark applied to error messages. */
838  void set_landmark(const String &landmark) {
840  }
841 
842  String decorate(const String &str);
843 
844  private:
845 
847 
848 };
849 
850 
851 #ifndef __KERNEL__
852 /** @class BailErrorHandler
853  * @brief A stackable ErrorHandler that exits when errors occur.
854  *
855  * The stackable BailErrorHandler, available only at user level, causes the
856  * process to exit if an error worse than a configurable level occurs. */
857 class BailErrorHandler : public ErrorVeneer { public:
858 
859  /** @brief Construct a BailErrorHandler.
860  * @param errh base ErrorHandler
861  * @param level error level that causes premature exit
862  *
863  * An error message with level less than or equal to @a el_error will
864  * cause the process to exit with status 1. */
866 
867  void account(int level);
868 
869  private:
870 
871  int _level;
872 
873 };
874 #endif
875 
876 #undef ERRH_SENTINEL
877 #endif
int level
Definition: afm2pl.c:1694
#define name
#define static
A stackable ErrorHandler that exits when errors occur.
Definition: error.hh:857
void account(int level)
Account for an error message at level level.
Definition: error.cc:1178
BailErrorHandler(ErrorHandler *errh, int level=el_error)
Construct a BailErrorHandler.
Definition: error.cc:1172
A stackable ErrorHandler that prints context lines.
Definition: error.hh:728
String _context_landmark
Definition: error.hh:780
bool _context_printed
Definition: error.hh:781
void set_context(const String &str)
Set the context string to str.
Definition: error.hh:749
void set_context_landmark(const String &str)
Set the context landmark to str.
Definition: error.hh:770
void set_context_printed(bool x)
Set whether the context has been printed.
Definition: error.hh:744
void set_indent(const String &str)
Set the indent string to str.
Definition: error.hh:758
ContextErrorHandler(ErrorHandler *errh, const char *fmt,...)
Construct a ContextErrorHandler.
Definition: error.cc:1092
String decorate(const String &str)
Decorate an error message.
Definition: error.cc:1106
bool context_printed() const
Return true iff the context has already been printed.
Definition: error.hh:739
Error reporting class.
Definition: error.hh:86
static Conversion * add_conversion(const String &name, ConversionFunction func)
Definition: error.cc:993
int xmessage(const String &anno, const char *fmt, va_list val)
Format and print an error message, adding annotations.
Definition: error.hh:237
static String xformat(int default_flags, const char *fmt,...)
Format an error string.
Definition: error.cc:757
static const char * parse_anno(const String &str, const char *begin, const char *end,...)
Parse error annotations from a string.
Definition: error.cc:200
@ cf_signed
Set for conversions of signed numbers.
Definition: error.hh:565
@ cf_alternate_form
Set for conversions using the '#' flag.
Definition: error.hh:562
@ cf_space_positive
Set for conversions using the ' ' flag.
Definition: error.hh:560
@ cf_utf8
Set to use UTF-8 characters on output.
Definition: error.hh:567
@ cf_negative
Set for conversions of negative numbers.
Definition: error.hh:566
@ cf_uppercase
Set for 'X' conversions (not 'x').
Definition: error.hh:564
@ cf_zero_pad
Set for conversions using the '0' flag.
Definition: error.hh:558
@ cf_left_just
Set for conversions using the '-' flag.
Definition: error.hh:561
@ cf_plus_positive
Set for conversions using the '+' flag.
Definition: error.hh:559
@ cf_singlequote
Set for conversions using the '\'' flag.
Definition: error.hh:563
static void static_cleanup()
Tear down the ErrorHandler implementation.
Definition: error.cc:1029
static const char e_notice[]
Definition: error.hh:118
static ErrorHandler * the_silent_handler
Definition: error.hh:577
virtual String decorate(const String &str)
Decorate an error message.
Definition: error.cc:920
static const char e_warning[]
Definition: error.hh:116
int error(const char *fmt,...)
Print an error message (level el_error).
Definition: error.cc:818
virtual void clear()
Clear accumulated error state.
Definition: error.hh:438
static String make_anno(const char *name, const String &value)
Create an error annotation.
Definition: error.cc:98
String(* ConversionFunction)(int flags, va_list)
Definition: error.hh:556
int _nerrors
Definition: error.hh:574
Level
Error level constants.
Definition: error.hh:94
@ el_error
Error level for normal error conditions.
Definition: error.hh:101
@ el_abort
Error level that triggers abort().
Definition: error.hh:95
@ el_alert
Alert error level: action must be taken.
Definition: error.hh:99
@ el_fatal
Definition: error.hh:96
@ el_emergency
Exit status equals -(level).
Definition: error.hh:98
@ el_debug
Error level for debug messages.
Definition: error.hh:106
@ el_critical
Error level for critical conditions.
Definition: error.hh:100
@ el_info
conditions.
Definition: error.hh:105
@ el_warning
Error level for warning conditions.
Definition: error.hh:102
int nerrors() const
Return the number of errors reported via this handler.
Definition: error.hh:282
int xmessage(const String &str)
Print an annotated error message.
Definition: error.cc:891
static const char e_error[]
Definition: error.hh:115
static const char e_warning_annotated[]
Definition: error.hh:117
virtual void * emit(const String &str, void *user_data, bool more)
Output an error message line.
Definition: error.cc:926
int xmessage(const String &landmark, const String &anno, const String &str)
Print an error message, adding landmark and other annotations.
Definition: error.hh:247
virtual void account(int level)
Account for an error message at level level.
Definition: error.cc:932
static ErrorHandler * the_default_handler
Definition: error.hh:576
static const char e_critical[]
Definition: error.hh:114
static const char e_abort[]
Error level indicators.
Definition: error.hh:110
static ErrorHandler * static_initialize(ErrorHandler *errh)
Initialize the ErrorHandler implementation.
Definition: error.cc:1019
static const char e_emergency[]
Definition: error.hh:112
virtual String vformat(const char *fmt, va_list val)
Format an error string.
Definition: error.cc:914
static const char * skip_anno(const char *begin, const char *end)
Skip a string's error annotations.
Definition: error.hh:519
void lfatal(const String &landmark, const char *fmt,...)
Print a fatal error message with a landmark annotation.
Definition: error.cc:880
ErrorHandler()
Construct an ErrorHandler.
Definition: error.hh:123
static const char e_info[]
Definition: error.hh:119
static const int ok_result
Definition: error.hh:172
int warning(const char *fmt,...)
Print a warning message (level el_warning).
Definition: error.cc:808
static ErrorHandler * silent_handler()
Return the global silent ErrorHandler.
Definition: error.hh:167
static String make_landmark_anno(const String &x)
Return a landmark annotation equal to x.
Definition: error.hh:535
void message(const char *fmt,...)
Print an informational message (level el_info).
Definition: error.cc:799
int xmessage(const String &landmark, const String &anno, const char *fmt, va_list val)
Format and print an error message, adding landmark and other annotations.
Definition: error.hh:260
static String vxformat(const char *fmt, va_list val)
Definition: error.hh:351
static String combine_anno(const String &str, const String &anno)
Apply annotations from anno to every line in str.
Definition: error.cc:238
static const char e_debug[]
Definition: error.hh:120
void lmessage(const String &landmark, const char *fmt,...)
Print an informational message with a landmark annotation.
Definition: error.cc:848
void ldebug(const String &landmark, const char *fmt,...)
Print a debug message with a landmark annotation.
Definition: error.cc:838
static void set_default_handler(ErrorHandler *errh)
Set the default ErrorHandler to errh.
Definition: error.cc:1042
static String vxformat(int default_flags, const char *fmt, va_list val)
Definition: error.cc:385
static String clean_landmark(const String &landmark, bool colon=false)
Clean the landmark.
Definition: error.cc:301
static const int error_result
<5> and above
Definition: error.hh:174
virtual ~ErrorHandler()
Definition: error.hh:127
void fatal(const char *fmt,...)
Print a fatal error message (level el_fatal).
Definition: error.cc:828
int lerror(const String &landmark, const char *fmt,...)
Print an error message with a landmark annotation.
Definition: error.cc:869
int lwarning(const String &landmark, const char *fmt,...)
Print a warning message with a landmark annotation.
Definition: error.cc:858
void debug(const char *fmt,...)
levels <4> and below
Definition: error.cc:790
static const char e_fatal[]
Definition: error.hh:111
String format(const char *fmt,...)
Format an error string.
Definition: error.cc:777
static int remove_conversion(Conversion *conversion)
Definition: error.cc:1006
static const char e_alert[]
Definition: error.hh:113
static ErrorHandler * default_handler()
Return the default ErrorHandler.
Definition: error.hh:155
Base class for ErrorHandlers that forward messages.
Definition: error.hh:610
void account(int level)
Account for an error message at level level.
Definition: error.cc:1080
String decorate(const String &str)
Decorate an error message.
Definition: error.cc:1062
ErrorVeneer(ErrorHandler *errh)
Construct an ErrorVeneer.
Definition: error.hh:617
String vformat(const char *fmt, va_list val)
Format an error string.
Definition: error.cc:1053
ErrorHandler * _errh
Definition: error.hh:628
void * emit(const String &str, void *user_data, bool more)
Output an error message line.
Definition: error.cc:1071
An ErrorHandler that prints error messages to a given file.
Definition: error.hh:640
int _default_flags
Definition: error.hh:658
void set_default_flags(int default_flags)
Definition: error.hh:647
String _context
Definition: error.hh:657
FileErrorHandler(FILE *f, const String &prefix=String())
Construct a FileErrorHandler.
Definition: error.cc:950
void * emit(const String &str, void *user_data, bool more)
Output an error message line.
Definition: error.cc:972
String vformat(const char *fmt, va_list val)
Format an error string.
Definition: error.cc:966
A stackable ErrorHandler that adds a default landmark to error messages.
Definition: error.hh:830
String decorate(const String &str)
Decorate an error message.
Definition: error.cc:1160
LandmarkErrorHandler(ErrorHandler *errh, const String &landmark)
Construct a LandmarkErrorHandler.
Definition: error.cc:1154
void set_landmark(const String &landmark)
Set the default landmark applied to error messages.
Definition: error.hh:838
A convenience stackable ErrorHandler.
Definition: error.hh:678
LocalErrorHandler(ErrorHandler *errh)
Construct a LocalErrorHandler.
Definition: error.hh:681
A stackable ErrorHandler that adds a prefix to error messages.
Definition: error.hh:799
PrefixErrorHandler(ErrorHandler *errh, const String &prefix)
Construct a PrefixErrorHandler.
Definition: error.cc:1137
String decorate(const String &str)
Decorate an error message.
Definition: error.cc:1144
String _prefix
Definition: error.hh:810
An ErrorHandler that does not report messages.
Definition: error.hh:592
#define ERRH_SENTINEL
Definition: error.hh:19
#define VA_LIST_REF_T
Definition: error.hh:14
#define ERRH_NORETURN
Definition: error.hh:20
mpz_t * f
Definition: gen-fib.c:34
static FIELD_PTR begin
Definition: genind.c:37
#define colon
Definition: globals.h:58
char String
Definition: tttypes.h:35
#define const
Definition: ftzconf.h:91
static luaL_Reg func[]
Definition: except.c:32
float x
Definition: cordic.py:15
union value value
Definition: obx.h:44
#define flags
static ErrorHandler * errh
Definition: main.cc:71
#define str(s)
Definition: sh6.c:399
The LCDF String class.
A string of characters.
Definition: t1part.c:49
Definition: strexpr.c:21
static String landmark(const String &filename, int line)
Definition: t1reencode.cc:832
#define FILE
Definition: t1stdio.h:34
char fmt[256]
Definition: tex4ht.c:3925
Definition: obx.h:51
char * va_list
Definition: varargs.h:22
#define end(cp)
Definition: zic.c:71