File Coverage

blib/lib/Text/BibTeX/BibStyle.pm

Criterion	Covered	Total	%
statement	16	18	88.8
branch			n/a
condition			n/a
subroutine	6	6	100.0
pod			n/a
total	22	24	91.6

"; \n" : '';

line	stmt	sub	time	code
1				package Text::BibTeX::BibStyle;
2
3				=head1 NAME
4
5				Text::BibTeX::BibStyle - Format Text::BibTeX::Entry items using .bst
6
7				=cut
8
9				our $VERSION = '0.03';
10
11				=head1 DESCRIPTION
12
13				C is a module that can format
14				C objects by interpreting a bibstyle (C<.bst>) file
15				such as C. In this way, Perl can use the same
16				bibliographic style files that bibtex does.
17
18				For a large collection of C<.bst> files, see
19				http://www.math.utah.edu/pub/tex/bibtex/index.html.
20
21				=head1 SYNOPSIS
22
23				$bibstyle = Text::BibTeX::BibStyle->new(%options);
24
25				$ENV{BSTINPUTS} = "my/bstfiles/";
26				$bibstyle->read_bibstyle("bibstyle");
27				OR
28				$bibstyle->replace_bibstyle($bibstyle_def);
29
30				$ENV{BIBINPUTS} = "my/bibfiles/";
31				$bibstyle->execute([qw(bibfile1 bibfile2)]);
32				OR
33				$bibstyle->execute([qw(bibfile1 bibfile2)], \@ref_list);
34
35				@warnings = $bibstyle->warnings;
36
37				$output = $bibstyle->get_output();
38				$output = $bibstyle->convert_format(Text::BibTex::BibStyle::html);
39				OR
40				$output = $bibstyle->get_output(\%options);
41
42				=cut
43
44	4	4	10478	use strict;
	4		8
	4		127
45	4	4	19	use warnings;
	4		8
	4		125
46
47	4	4	19	use vars qw(@ISA @EXPORT_OK $LATEX $HTML $RST);
	4		10
	4		373
48
49	4	4	20	use Exporter;
	4		6
	4		235
50				@ISA = qw( Exporter );
51				@EXPORT_OK = qw($HTML $LATEX $RST);
52
53	4	4	19	use Carp;
	4		14
	4		310
54	4	4	3523	use Text::BibTeX qw(:metatypes :subs :joinmethods :macrosubs);
	0
	0
55				use Text::BibTeX::Name;
56
57				=head1 METHODS
58
59				=over
60
61				=item C
62
63				Class method. Creates a new C object with the
64				options specified in the optional C'value'> arguments.The
65				following options are understood:
66
67				=over
68
69				=item C
70
71				Turns on debugging messages during execute.
72
73				=item C
74
75				Turns off warnings from certain sanity checks, such as the existence
76				of a unique C and C statement within the bibstyle.
77
78				=back
79
80				=cut
81
82				# Exportable output options
83				$LATEX = { wrap => 1 };
84				{ # Closure
85				my $ASCIIMathML_parser;
86				my %Styles = (em => 'em',
87				bf => 'b',
88				it => 'i',
89				sl => 'i',
90				tt => 'tt');
91
92				$HTML = {
93				delete_braces => 1,
94				substitute_newcommand => 1,
95				character => sub {
96				my ($bst, $latex, $unicode, $chars, $accent) = @_;
97				use HTML::Entities;
98				return $unicode ? encode_entities($unicode) : $chars;
99				},
100				command => sub {
101				my ($bst, $cmd, @args) = @_;
102				if ($cmd =~ /^(begin\|end)$/) {
103				if ($args[0] eq 'thebibliography') {
104				my $slash = $cmd eq 'end' ? '/' : '';
105				my $pre;
106				if ($cmd eq 'begin') {
107				$pre = qq( References \n\n);
108				}
109				else {
110				$pre = "
111				}
112				return "$pre<${slash}table>";
113				}
114				}
115				elsif ($cmd eq 'bibitem') {
116				my $key = pop @args;
117				$bst->{html}{Bib_count}++;
118				my $label = $args[0] \|\| $bst->{html}{Bib_count};
119				($bst->{html}{Cites}{$key} = $label) =~ s/[{}]//g; # Remove braces
120				my $pre = $bst->{html}{Bib_count} > 1 ? "
121				return qq($pre
[$label]	);
122				}
123				elsif ($cmd eq 'mbox') {
124				return $args[0];
125				}
126				elsif ($cmd eq 'cite') {
127				return qq($args[0]);
128				}
129				},
130				init => sub {
131				my ($bst) = @_;
132				# Initialize instance variables
133				$bst->{html} = { Bib_count => 0, Cites => {} };
134				},
135				math => sub {
136				my ($bst, $latex, $math) = @_;
137				use Text::ASCIIMathML;
138				$ASCIIMathML_parser = Text::ASCIIMathML->new()
139				unless $ASCIIMathML_parser;
140				return $ASCIIMathML_parser->TextToMathML($math);
141				},
142				postprocess => sub {
143				my ($bst, $text) = @_;
144
145				# Substitute back any cite tags
146				$text =~ s!(.*?)![$bst->{html}{Cites}{$1}]!g;
147				return $text;
148				},
149				style => sub {
150				my ($bst, $latex, $style, $text) = @_;
151				my $html_style = $Styles{$style};
152				return defined $html_style ? "<$html_style>$text" :
153				$text;
154				},
155				};
156				}
157				{ # Closure
158				my %Styles = (em => '*',
159				bf => '**',
160				it => '*',
161				sl => '*',
162				tt => '``');
163
164				$RST = {
165				delete_braces => 1,
166				substitute_newcommand => 1,
167				# prologue => "",
168				character => sub {
169				my ($bst, $latex, $unicode, $chars, $accent) = @_;
170				return $chars if ! $unicode;
171				my $code = ord $unicode;
172				$bst->{rst}{unicode}{$code} = 1;
173				return sprintf '\\ \|unicode(%x)\|\\ ', $code;
174				},
175				command => sub {
176				my ($bst, $cmd, @args) = @_;
177				if ($cmd =~ /^(begin\|end)$/) {
178				if ($args[0] eq 'thebibliography') {
179				if ($cmd eq 'begin') {
180				return qq(References\n\n\n);
181				}
182				}
183				}
184				elsif ($cmd eq 'bibitem') {
185				my $key = pop @args;
186				$bst->{rst}{Bib_count}++;
187				my $label = $args[0] \|\| $bst->{rst}{Bib_count};
188				if ($args[0]) {
189				my $bst2 = Text::BibTeX::BibStyle->new;
190				$label = $bst2->convert_format($label, $RST);
191				}
192				$bst->{rst}{Cites}{$key} = $label;
193				return ".. [$key] ";
194				}
195				elsif ($cmd eq 'mbox') {
196				return $args[0];
197				}
198				elsif ($cmd eq 'cite') {
199				return "\\ [$args[0]]_";
200				}
201				},
202				init => sub {
203				my ($bst) = @_;
204				# Initialize instance variables
205				$bst->{rst} = { Bib_count => 0, Cites => {}, unicode => {} };
206				},
207				math => sub {
208				my ($bst, $latex, $math) = @_;
209				# Latex sometimes starts with ^ or _ for super/subscript
210				$math =~ s/^([_^])/{::}$1/;
211				$math =~ s/([{}])/\\$1/g;
212				$math =~ s/\\/\\\\/g;
213				return "\\ :mathml:`$math`\\ ";
214				},
215				postprocess => sub {
216				my ($bst, $text) = @_;
217
218				# Fix the indentations
219				$text =~ s/^[ ]*$//mg;
220				$text =~ s/^(?!\A\|\.\.\|\\)[ ]*(.+)/ $1/mg;
221				$text =~ s/\\([\\{}])/$1/g;
222				foreach my $code (sort keys %{$bst->{rst}{unicode}}) {
223				$text .= sprintf ".. \|unicode(%x)\| unicode:: U+%x\n", $code, $code;
224				}
225				return $text;
226				},
227				style => sub {
228				my ($bst, $latex, $style, $text) = @_;
229				my $rst_style = $Styles{$style};
230				if ($rst_style) {
231				my ($pre, undef, $post) = $text =~ s/^(\s.)(.*?)(\s.)$/$2/;
232				$post \|\|= '';
233				return "$pre$rst_style$text$rst_style$post" ;
234				}
235				return $text;
236				},
237				};
238				}
239				sub new {
240				my ($class, %options) = @_;
241
242				my $self = bless {}, $class;
243
244				$self->{options} = \%options;
245
246				return $self;
247				}
248
249				# A Text::BibTeX::BibStyle hash has the following keys:
250				# bibtex A reference to a "bibtex" hash
251				# interp Array reference containing the interpreter
252				# stack Reference to array of evaluation stack
253				# symbols Reference to "symbols" hash
254				# warnings Array of warnings produced during execution
255				#
256				# "Symbols" hash has the following keys, each of which is a hash reference
257				# whose key is the symbol name and whose value is its definition:
258				# const Built-in constants
259				# field Reference to hash of field/value pairs for current entry
260				# entry_int Reference to hash of integer/value pairs for current entry
261				# entry_str Reference to hash of string/value pairs for current entry
262				# function Function defined in FUNCTION command or built-in function
263				# integer Integer defined in INTEGERS command
264				# string String defined in STRINGS command
265				#
266				# "Bibtex" hash has the following key/value pairs
267				# bibfiles Reference to array of bib file names
268				# bt_entry Reference to the current Text::BibTeX::Entry object
269				# bt_entries Reference to hash whose keys are bibtex keys and whose value
270				# is the corresponding Text::BibTeX::Entry for that key
271				# cite Cite key for the current entry
272				# cites Optional reference to array of keys of citations to format
273				# entries Reference to hash whose keys are bibtex keys and whose value
274				# is a reference to its entry hash
275				# format Reference to a format hash defined by an ENTRY command
276				# preamble Reference to array of @PREAMBLE items
277				#
278				# "Entry" hash has the following keys, each of which is a hash reference
279				# whose key is the symbol name and whose value is its definition:
280				# field Bibliography field from ENTRY command
281				# integer Entry integer from ENTRY command
282				# string Entry string from ENTRY command
283				#
284				# "Format" hash has the following keys, each of which is a reference to
285				# an array of names that can appear in a corresponding entry hash
286				# field Bibliography fields from ENTRY command
287				# integer Entry integer variables from ENTRY command
288				# string Entry string variables from ENTRY command
289
290				=item C
291
292				Method. Converts a LaTeX bibliography in $text into some other format
293				using the options specified by C<%options> and returns the result.
294				This method can also be used to convert a standard BibTeX output to
295				a different format.
296
297				Assuming that C<$text> contains a LaTeX bibliography (e.g., the
298				contents of a C<.bbl> file), the following option packages may be
299				useful for the options hash reference:
300
301				=over
302
303				=item C<$Text::BibTeX::BibStyle::HTML>
304
305				Produces HTML code to render the formatted bibliography. Exportable.
306
307				=item C<$Text::BibTeX::BibStyle::LATEX>
308
309				Outputs LaTeX code identical to bibtex (specifies (wrap => 1)). Exportable.
310
311				=item C<$Text::BibTeX::BibStyle::RST>
312
313				Produces reStructuredText code. Exportable.
314
315				=back
316
317				The following options are supported, if you want to write your own
318				translation package:
319
320				=over
321
322				=item C
323
324				Reference to a subroutine to call for special characters. The
325				subroutine is called with the arguments C<($bst, $latex, [$unicode],
326				$char, [$accent])>, where C<$bst> is the Text::BibTeX::BibStyle
327				object, C<$latex> is the original latex for the special character,
328				C<$unicode> is the equivalent unicode character (if it exists), $char
329				is the special character(s), and C<$accent> is the latex accent code
330				to be applied (if specified). It should return the string to be
331				substituted.
332
333				=item C
334
335				Reference to a subroutine to call for LaTeX commands. The subroutine
336				is called with the arguments C<($bst, $cmd, @args)>, where C<$bst> is
337				the Text::BibTeX::BibStyle object, C<$cmd> is the name of the LaTeX
338				command and C<@args> is the array of arguments (including optional
339				arguments) to the command. At a minimum, the subroutine should handle
340				the following commands: C<\begin{thebibliography}>,
341				C<\bibitem[label]{key}>, C<\cite{ref}>, C<\end{thebibliography}>,
342				C<\mbox{text}>, C<\newblock>. It should return the string to be
343				substituted.
344
345				=item C
346
347				Boolean to delete from the output any braces that are not
348				backslash-quoted.
349
350				=item C
351
352				Reference to a subroutine to call before processing the output. The
353				subroutine is called with the argument C<($bst)>, which is the
354				Text::BibTeX::BibStyle object.
355
356				=item C
357
358				Reference to a subroutine to call for latex math. The subroutine is
359				called with the arguments C<($bst, $latex, $math)>, where C<$bst> is
360				the Text::BibTeX::BibStyle object, C<$latex> is the original latex and
361				C<$math> is the part that actually translates to math. It should
362				return the string to be substituted.
363
364				=item C
365
366				Reference to a subroutine to call to post-process the output. The
367				subroutine is called with the arguments C<($bst, $text)>, where
368				C<$bst> is the Text::BibTeX::BibStyle object and C<$text> contains the
369				text of the entire formatted bibliography. It should return the final
370				formatted bibliography.
371
372				=item C
373
374				A string or reference to a subroutine to call to produce any
375				pre-bibliography definitions needed by the format.
376
377				=item C

File Coverage

References