NAME¶
Text::BibTeX::Value - interfaces to BibTeX values and simple values
SYNOPSIS¶
use Text::BibTeX;
$entry = new Text::BibTeX::Entry;
# set the 'preserve_values' flag to 1 for this parse
$entry->parse ($filename, $filehandle, 1);
# 'get' method now returns a Text::BibTeX::Value object
# rather than a string
$value = $entry->get ($field);
# query the `Value' object (list of SimpleValue objects)
@all_values = $value->values;
$first_value = $value->value (0);
$last_value = $value->value (-1);
# query the simple value objects -- type will be one of BTAST_STRING,
# BTAST_MACRO, or BTAST_NUMBER
use Text::BibTex (':nodetypes'); # import "node type" constants
$is_macro = ($first_value->type == BTAST_MACRO);
$text = $first_value->text;
DESCRIPTION¶
The "Text::BibTeX::Value" module provides two classes,
"Text::BibTeX::Value" and "Text::BibTeX::SimpleValue",
which respectively give you access to BibTeX "compound values" and
"simple values". Recall that every field value in a BibTeX entry is
the concatenation of one or more simple values, and that each of those simple
values may be a literal string, a macro (abbreviation), or a number. Normally
with "Text::BibTeX", field values are "fully processed,"
so that you only have access to the string that results from expanding macros,
converting numbers to strings, concatenating all sub-strings, and collapsing
whitespace in the resulting string.
For example, in the following entry:
@article{homer97,
author = "Homer Simpson" # and # "Ned Flanders",
title = {Territorial Imperatives in Modern Suburbia},
journal = jss,
year = 1997
}
we see the full range of options. The "author" field consists of three
simple values: a string, a macro ("and"), and another string. The
"title" field is a single string, and the "journal" and
"year" fields are, respectively, a single macro and a single number.
If you parse this entry in the usual way:
$entry = new Text::BibTeX::Entry $entry_text;
then the "get" method on $entry would return simple strings. Assuming
that the "and" macro is defined as " and ", then
$entry->get ('author')
would return the Perl string "Homer Simpson and Ned Flanders".
However, you can also request that the library preserve the input values in your
entries, i.e. not lose the information about which values use macros, which
values are composed of multiple simple values, and so on. There are two ways
to make this request: per-file and per-entry. For a per-file request, use the
"preserve_values" method on your "File" object:
$bibfile = new Text::BibTeX::File $filename;
$bibfile->preserve_values (1);
$entry = new Text::BibTeX::Entry $bibfile;
$entry->get ($field); # returns a Value object
$bibfile->preserve_values (0);
$entry = new Text::BibTeX::Entry $bibfile;
$entry->get ($field); # returns a string
If you're not using a "File" object, or want to control things at a
finer scale, then you have to pass in the "preserve_values" flag
when invoking "read", "parse", or "parse_s" on
your "Entry" objects:
# no File object, parsing from a string
$entry = new Text::BibTeX::Entry;
$entry->parse_s ($entry_text, 0); # preserve_values=0 (default)
$entry->get ($field); # returns a string
$entry->parse_s ($entry_text, 1);
$entry->get ($field); # returns a Value object
# using a File object, but want finer control
$entry->read ($bibfile, 0); # now get will return strings (default)
$entry->read ($bibfile, 1); # now get will return Value objects
A compound value, usually just called a value, is simply a list of simple
values. The "Text::BibTeX::Value" class (hereinafter abbreviated as
"Value") provides a simple interface to this list; you can request
the whole list, or an individual member of the list. The
"SimpleValue" class gives you access to the innards of each simple
value, which consist of the
type and the
text. The type just
tells you if this simple value is a string, macro, or number; it is
represented using the Perl translation of the "node type"
enumeration from C. The possible types are "BTAST_STRING",
"BTAST_NUMBER", and "BTAST_MACRO". The text is just what
appears in the original entry text, be it a string, number, or macro.
For example, we could parse the above entry in "preserve values" mode
as follows:
$entry->parse_s ($entry_text, 1); # preserve_values is 1
Then, using the "get" method on $entry would return not a string, but
a "Value" object. We can get the list of all simple values using the
"values" method, or a single value using "value":
$author = $entry->get ('author'); # now a Text::BibTeX::Value object
@all_values = $author->values; # array of Text::BibTeX::SimpleValue
$second = $author->value (1); # same as $all_values[1]
The simple values may be queried using the "Text::BibTeX::SimpleValue"
methods, "type" and "text":
$all_values[0]->type; # returns BTAST_STRING
$second->type; # returns BTAST_MACRO
$all_values[0]->text; # "Homer Simpson"
$second->text; # "and" (NOT the macro expansion!)
$entry->get ('year')->value (0)->text; # "1997"
METHODS¶
Normally, you won't need to create "Value" or "SimpleValue"
objects---they'll be created for you when an entry is parsed, and returned to
you by the "get" method in the "Entry" class. Thus, the
query methods ("values" and "value" for the
"Value" class, "type" and "text" for
"SimpleValue") are probably all you need to worry about. If you
wish, though, you can create new values and simple values using the two
classes' respective constructors. You can also put newly-created
"Value" objects back into an existing "Entry" object using
the "set" entry method; it doesn't matter how the entry was parsed,
this is acceptable anytime.
Text::BibTeX::Value methods¶
- new (SVAL, ...)
- Creates a new "Value" object from a list of
simple values. Each simple value, SVAL, may be either a
"SimpleValue" object or a reference to a two-element list
containing the type and text of the simple value. For example, one way to
recreate the "author" field of the example entry in
"DESCRIPTION" would be:
$and_macro = new Text::BibTeX::SimpleValue (BTAST_MACRO, 'and');
$value = new Text::BibTeX::Value
([BTAST_STRING, 'Homer Simpson'],
$and_macro,
[BTAST_STRING, 'Ned Flanders']);
The resulting "Value" object could then be installed into an entry
using the "set" method of the "Entry" class.
- values ()
- Returns the list of "SimpleValue" objects that
make up a "Value" object.
- value (NUM)
- Returns the NUM'th "SimpleValue" object from the
list of "SimpleValue" objects that make up a "Value"
object. This is just like a Perl array reference: NUM is zero-based, and
negative numbers count from the end of the array.
Text::BibTeX::SimpleValue methods¶
- new (TYPE, TEXT)
- Creates a new "SimpleValue" object with the
specified TYPE and TEXT. TYPE must be one of the allowed types for BibTeX
simple values, i.e. "BTAST_STRING", "BTAST_NUMBER", or
"BTAST_MACRO". You'll probably want to import these constants
from "Text::BibTeX" using the "nodetypes" export tag:
use Text::BibTeX qw(:nodetypes);
TEXT may be any string. Note that if TYPE is "BTAST_NUMBER" and
TEXT is not a string of digits, the "SimpleValue" object will be
created anyways, but a warning will be issued. No warning is issued about
non-existent macros.
- type ()
- Returns the type of a simple value. This will be one of the
allowed "node types" as described under "new"
above.
- text ()
- Returns the text of a simple value. This is just the text
that appears in the original entry---unexpanded macro name, or unconverted
number. (Of course, converting numbers doesn't make any difference from
Perl; in fact, it's all the same in C too, since the C code just keeps
numbers as strings of digits. It's simply a matter of whether the string
of digits is represented as a string or a number, which you might be
interested in knowing if you want to preserve the structure of the input
as much possible.)
SEE ALSO¶
Text::BibTeX, Text::BibTeX::File, Text::BibTeX::Entry
AUTHOR¶
Greg Ward <gward@python.net>
COPYRIGHT¶
Copyright (c) 1997-2000 by Gregory P. Ward. All rights reserved. This file is
part of the Text::BibTeX library. This library is free software; you may
redistribute it and/or modify it under the same terms as Perl itself.