.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.48) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "Text::BibTeX::Error 3pm" .TH Text::BibTeX::Error 3pm 2026-11-14 "perl v5.44.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Text::BibTeX::Error \- errors and warnings from the BibTeX parser .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& use Text::BibTeX; \& \& # Errors are warnings by default, reported through Perl\*(Aqs warn() \& my $entry = Text::BibTeX::Entry\->new($bibfile); \& for my $err ($entry\->errors) { \& printf "%s:%d: %s\en", $err\->filename, $err\->line, $err\->message; \& } \& \& # Silence them, or make them fatal, with the usual warnings pragma \& { \& no warnings \*(AqText::BibTeX\*(Aq; \& $entry = Text::BibTeX::Entry\->new($bibfile); \& } \& { \& use warnings FATAL => \*(AqText::BibTeX\*(Aq; \& 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); \& }; .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" Every problem found by Text::BibTeX \-\- a syntax error in a \fI.bib\fR file, an undefined macro, a malformed name, or a misuse of the library \-\- is reported as a \f(CW\*(C`Text::BibTeX::Error\*(C'\fR object. Nothing is ever written directly to the standard error stream by the C code, and nothing ever exits or aborts the program. .SS "How errors are reported" .IX Subsection "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: .IP \(bu 4 If \f(CW$Text::BibTeX::Error::Handler\fR is set to a code reference, it is called with the error object, and nothing else happens. .IP \(bu 4 Otherwise, fatal errors (misuse of the library, or internal errors) are thrown as exceptions with \f(CW\*(C`die\*(C'\fR. .IP \(bu 4 Other errors are passed to Perl\*(Aqs \f(CW\*(C`warn\*(C'\fR, with the same text as earlier versions of Text::BibTeX printed, for example: .Sp .Vb 2 \& foo.bib, line 12, warning: undefined macro "jan" \& foo.bib, line 30, syntax error: found "author", expected "," .Ve .Sp This means they can be caught with \f(CW$SIG{_\|_WARN_\|_}\fR, and that they go wherever \f(CW\*(C`STDERR\*(C'\fR goes. Their reporting follows the warnings pragma in effect in the code that called Text::BibTeX, using the warnings category \&\f(CW\*(C`Text::BibTeX\*(C'\fR: they are reported by default (even without \f(CW\*(C`use warnings\*(C'\fR), are suppressed by \f(CW\*(C`no warnings \*(AqText::BibTeX\*(Aq\*(C'\fR or \f(CW\*(C`no warnings\*(C'\fR, and are thrown as exceptions under \f(CWuse warnings FATAL => \&\*(AqText::BibTeX\*(Aq\fR. .SH METHODS .IX Header "METHODS" .IP message 4 .IX Item "message" The text of the message. .IP filename 4 .IX Item "filename" .PD 0 .IP line 4 .IX Item "line" .PD Where the problem was found, if known. .IP item_desc 4 .IX Item "item_desc" .PD 0 .IP item 4 .IX Item "item" .PD For problems with one item in a list (eg. the second name in a list of names), a description of the item (eg. \f(CW"name"\fR) and its number. .IP key 4 .IX Item "key" The key of the entry being parsed when the problem was found, if any. .IP caller_file 4 .IX Item "caller_file" .PD 0 .IP caller_line 4 .IX Item "caller_line" .PD 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. .IP errclass 4 .IX Item "errclass" One of the \f(CW\*(C`BTERR_*\*(C'\fR constants (export tag \f(CW\*(C`:errclasses\*(C'\fR): \&\f(CW\*(C`BTERR_NOTIFY\*(C'\fR, \f(CW\*(C`BTERR_CONTENT\*(C'\fR, \f(CW\*(C`BTERR_LEXWARN\*(C'\fR, \f(CW\*(C`BTERR_USAGEWARN\*(C'\fR, \&\f(CW\*(C`BTERR_LEXERR\*(C'\fR, \f(CW\*(C`BTERR_SYNTAX\*(C'\fR, \f(CW\*(C`BTERR_USAGEERR\*(C'\fR and \f(CW\*(C`BTERR_INTERNAL\*(C'\fR. .IP class 4 .IX Item "class" The name used in messages: \f(CW"warning"\fR, \f(CW"error"\fR, \f(CW"syntax error"\fR, \&\f(CW"fatal error"\fR or \f(CW"internal error"\fR (\f(CW\*(C`undef\*(C'\fR for notifications). .IP severity 4 .IX Item "severity" \&\f(CW"notify"\fR, \f(CW"warning"\fR, \f(CW"error"\fR or \f(CW"fatal"\fR. .IP is_serious 4 .IX Item "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. .IP is_fatal 4 .IX Item "is_fatal" True for errors that are always thrown as exceptions. .IP as_string 4 .IX Item "as_string" The full message, as shown above. Error objects also stringify to this.