/ 
Text-BibTeX-1.00
/ Text::BibTeX::Error

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.