| Text::BibTeX::Error(3pm) | User Contributed Perl Documentation | Text::BibTeX::Error(3pm) |
NAME
Text::BibTeX::Error - errors and warnings from the BibTeX parser
SYNOPSIS
use Text::BibTeX;
# Errors are warnings by default, reported through Perl's warn()
my $entry = Text::BibTeX::Entry->new($bibfile);
for my $err ($entry->errors) {
printf "%s:%d: %s\n", $err->filename, $err->line, $err->message;
}
# Silence them, or make them fatal, with the usual warnings pragma
{
no warnings 'Text::BibTeX';
$entry = Text::BibTeX::Entry->new($bibfile);
}
{
use warnings FATAL => 'Text::BibTeX';
eval { $entry = Text::BibTeX::Entry->new($bibfile) };
warn "bad input: " . $@->message if ref $@;
}
# Or take over reporting completely
local $Text::BibTeX::Error::Handler = sub {
my $err = shift;
$logger->warn($err->as_string);
};
DESCRIPTION
Every problem found by Text::BibTeX -- a syntax error in a .bib file, an undefined macro, a malformed name, or a misuse of the library -- is reported as a "Text::BibTeX::Error" object. Nothing is ever written directly to the standard error stream by the C code, and nothing ever exits or aborts the program.
How errors are reported
Errors that arise while parsing an entry are stored in the entry; see "errors" in Text::BibTeX::Entry. In addition, each error is reported as follows:
- If $Text::BibTeX::Error::Handler is set to a code reference, it is called with the error object, and nothing else happens.
- Otherwise, fatal errors (misuse of the library, or internal errors) are thrown as exceptions with "die".
- Other errors are passed to Perl's
"warn", with the same text as earlier
versions of Text::BibTeX printed, for example:
foo.bib, line 12, warning: undefined macro "jan" foo.bib, line 30, syntax error: found "author", expected ","
This means they can be caught with $SIG{__WARN__}, and that they go wherever "STDERR" goes. Their reporting follows the warnings pragma in effect in the code that called Text::BibTeX, using the warnings category "Text::BibTeX": they are reported by default (even without "use warnings"), are suppressed by "no warnings 'Text::BibTeX'" or "no warnings", and are thrown as exceptions under use warnings FATAL => 'Text::BibTeX'.
METHODS
- message
- The text of the message.
- filename
- line
- Where the problem was found, if known.
- item_desc
- item
- For problems with one item in a list (eg. the second name in a list of names), a description of the item (eg. "name") and its number.
- key
- The key of the entry being parsed when the problem was found, if any.
- caller_file
- caller_line
- The place in your program where Text::BibTeX was called (the innermost caller outside Text::BibTeX). This is added to the message of fatal errors.
- errclass
- One of the "BTERR_*" constants (export tag ":errclasses"): "BTERR_NOTIFY", "BTERR_CONTENT", "BTERR_LEXWARN", "BTERR_USAGEWARN", "BTERR_LEXERR", "BTERR_SYNTAX", "BTERR_USAGEERR" and "BTERR_INTERNAL".
- class
- The name used in messages: "warning", "error", "syntax error", "fatal error" or "internal error" ("undef" for notifications).
- severity
- "notify", "warning", "error" or "fatal".
- is_serious
- True if the error makes an entry fail to parse (see "parse_ok" in Text::BibTeX::Entry): lexical and syntax errors, and usage warnings.
- is_fatal
- True for errors that are always thrown as exceptions.
- as_string
- The full message, as shown above. Error objects also stringify to this.
| 2026-11-14 | perl v5.44.0 |