NAME

SYNOPSIS

   use Text::BibTeX;

   $entry = Text::BibTeX::Entry->new;

   # 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

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 = Text::BibTeX::Entry->new($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 = Text::BibTeX::File->new($filename);
   $bibfile->preserve_values (1);

   $entry = Text::BibTeX::Entry->new($bibfile);
   $entry->get ($field);        # returns a Value object

   $bibfile->preserve_values (0);
   $entry = Text::BibTeX::Entry->new($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 = Text::BibTeX::Entry->new;
   $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

SEE ALSO

AUTHOR

COPYRIGHT