1Text::BibTeX::Value(3pmU)ser Contributed Perl DocumentatiToenxt::BibTeX::Value(3pm)
2
3
4

NAME

6       Text::BibTeX::Value - interfaces to BibTeX values and simple values
7

SYNOPSIS

9          use Text::BibTeX;
10
11          $entry = Text::BibTeX::Entry->new;
12
13          # set the 'preserve_values' flag to 1 for this parse
14          $entry->parse ($filename, $filehandle, 1);
15
16          # 'get' method now returns a Text::BibTeX::Value object
17          # rather than a string
18          $value = $entry->get ($field);
19
20          # query the `Value' object (list of SimpleValue objects)
21          @all_values = $value->values;
22          $first_value = $value->value (0);
23          $last_value = $value->value (-1);
24
25          # query the simple value objects -- type will be one of BTAST_STRING,
26          # BTAST_MACRO, or BTAST_NUMBER
27          use Text::BibTex (':nodetypes');   # import "node type" constants
28          $is_macro = ($first_value->type == BTAST_MACRO);
29          $text = $first_value->text;
30

DESCRIPTION

32       The "Text::BibTeX::Value" module provides two classes,
33       "Text::BibTeX::Value" and "Text::BibTeX::SimpleValue", which
34       respectively give you access to BibTeX "compound values" and "simple
35       values".  Recall that every field value in a BibTeX entry is the
36       concatenation of one or more simple values, and that each of those
37       simple values may be a literal string, a macro (abbreviation), or a
38       number.  Normally with "Text::BibTeX", field values are "fully
39       processed," so that you only have access to the string that results
40       from expanding macros, converting numbers to strings, concatenating all
41       sub-strings, and collapsing whitespace in the resulting string.
42
43       For example, in the following entry:
44
45          @article{homer97,
46            author = "Homer Simpson" # and # "Ned Flanders",
47            title = {Territorial Imperatives in Modern Suburbia},
48            journal = jss,
49            year = 1997
50          }
51
52       we see the full range of options.  The "author" field consists of three
53       simple values: a string, a macro ("and"), and another string.  The
54       "title" field is a single string, and the "journal" and "year" fields
55       are, respectively, a single macro and a single number.  If you parse
56       this entry in the usual way:
57
58          $entry = Text::BibTeX::Entry->new($entry_text);
59
60       then the "get" method on $entry would return simple strings.  Assuming
61       that the "and" macro is defined as " and ", then
62
63          $entry->get ('author')
64
65       would return the Perl string "Homer Simpson and Ned Flanders".
66
67       However, you can also request that the library preserve the input
68       values in your entries, i.e. not lose the information about which
69       values use macros, which values are composed of multiple simple values,
70       and so on.  There are two ways to make this request: per-file and per-
71       entry.  For a per-file request, use the "preserve_values" method on
72       your "File" object:
73
74          $bibfile = Text::BibTeX::File->new($filename);
75          $bibfile->preserve_values (1);
76
77          $entry = Text::BibTeX::Entry->new($bibfile);
78          $entry->get ($field);        # returns a Value object
79
80          $bibfile->preserve_values (0);
81          $entry = Text::BibTeX::Entry->new($bibfile);
82          $entry->get ($field);        # returns a string
83
84       If you're not using a "File" object, or want to control things at a
85       finer scale, then you have to pass in the "preserve_values" flag when
86       invoking "read", "parse", or "parse_s" on your "Entry" objects:
87
88          # no File object, parsing from a string
89          $entry = Text::BibTeX::Entry->new;
90          $entry->parse_s ($entry_text, 0);  # preserve_values=0 (default)
91          $entry->get ($field);        # returns a string
92
93          $entry->parse_s ($entry_text, 1);
94          $entry->get ($field);        # returns a Value object
95
96          # using a File object, but want finer control
97          $entry->read ($bibfile, 0);  # now get will return strings (default)
98          $entry->read ($bibfile, 1);  # now get will return Value objects
99
100       A compound value, usually just called a value, is simply a list of
101       simple values.  The "Text::BibTeX::Value" class (hereinafter
102       abbreviated as "Value") provides a simple interface to this list; you
103       can request the whole list, or an individual member of the list.  The
104       "SimpleValue" class gives you access to the innards of each simple
105       value, which consist of the type and the text.  The type just tells you
106       if this simple value is a string, macro, or number; it is represented
107       using the Perl translation of the "node type" enumeration from C.  The
108       possible types are "BTAST_STRING", "BTAST_NUMBER", and "BTAST_MACRO".
109       The text is just what appears in the original entry text, be it a
110       string, number, or macro.
111
112       For example, we could parse the above entry in "preserve values" mode
113       as follows:
114
115          $entry->parse_s ($entry_text, 1);   # preserve_values is 1
116
117       Then, using the "get" method on $entry would return not a string, but a
118       "Value" object.  We can get the list of all simple values using the
119       "values" method, or a single value using "value":
120
121          $author = $entry->get ('author');   # now a Text::BibTeX::Value object
122          @all_values = $author->values;      # array of Text::BibTeX::SimpleValue
123          $second = $author->value (1);       # same as $all_values[1]
124
125       The simple values may be queried using the "Text::BibTeX::SimpleValue"
126       methods, "type" and "text":
127
128          $all_values[0]->type;               # returns BTAST_STRING
129          $second->type;                      # returns BTAST_MACRO
130
131          $all_values[0]->text;               # "Homer Simpson"
132          $second->text;                      # "and" (NOT the macro expansion!)
133
134          $entry->get ('year')->value (0)->text;   # "1997"
135

METHODS

137       Normally, you won't need to create "Value" or "SimpleValue"
138       objects---they'll be created for you when an entry is parsed, and
139       returned to you by the "get" method in the "Entry" class.  Thus, the
140       query methods ("values" and "value" for the "Value" class, "type" and
141       "text" for "SimpleValue") are probably all you need to worry about.  If
142       you wish, though, you can create new values and simple values using the
143       two classes' respective constructors.  You can also put newly-created
144       "Value" objects back into an existing "Entry" object using the "set"
145       entry method; it doesn't matter how the entry was parsed, this is
146       acceptable anytime.
147
148   Text::BibTeX::Value methods
149       new (SVAL, ...)
150           Creates a new "Value" object from a list of simple values.  Each
151           simple value, SVAL, may be either a "SimpleValue" object or a
152           reference to a two-element list containing the type and text of the
153           simple value.  For example, one way to recreate the "author" field
154           of the example entry in "DESCRIPTION" would be:
155
156              $and_macro = Text::BibTeX::SimpleValue->new (BTAST_MACRO, 'and');
157              $value = Text::BibTeX::Value->new
158                 ([BTAST_STRING, 'Homer Simpson'],
159                  $and_macro,
160                  [BTAST_STRING, 'Ned Flanders']);
161
162           The resulting "Value" object could then be installed into an entry
163           using the "set" method of the "Entry" class.
164
165       values ()
166           Returns the list of "SimpleValue" objects that make up a "Value"
167           object.
168
169       value (NUM)
170           Returns the NUM'th "SimpleValue" object from the list of
171           "SimpleValue" objects that make up a "Value" object.  This is just
172           like a Perl array reference: NUM is zero-based, and negative
173           numbers count from the end of the array.
174
175   Text::BibTeX::SimpleValue methods
176       new (TYPE, TEXT)
177           Creates a new "SimpleValue" object with the specified TYPE and
178           TEXT.  TYPE must be one of the allowed types for BibTeX simple
179           values, i.e. "BTAST_STRING", "BTAST_NUMBER", or "BTAST_MACRO".
180           You'll probably want to import these constants from "Text::BibTeX"
181           using the "nodetypes" export tag:
182
183              use Text::BibTeX qw(:nodetypes);
184
185           TEXT may be any string.  Note that if TYPE is "BTAST_NUMBER" and
186           TEXT is not a string of digits, the "SimpleValue" object will be
187           created anyways, but a warning will be issued.  No warning is
188           issued about non-existent macros.
189
190       type ()
191           Returns the type of a simple value.  This will be one of the
192           allowed "node types" as described under "new" above.
193
194       text ()
195           Returns the text of a simple value.  This is just the text that
196           appears in the original entry---unexpanded macro name, or
197           unconverted number.  (Of course, converting numbers doesn't make
198           any difference from Perl; in fact, it's all the same in C too,
199           since the C code just keeps numbers as strings of digits.  It's
200           simply a matter of whether the string of digits is represented as a
201           string or a number, which you might be interested in knowing if you
202           want to preserve the structure of the input as much possible.)
203

SEE ALSO

205       Text::BibTeX, Text::BibTeX::File, Text::BibTeX::Entry
206

AUTHOR

208       Greg Ward <gward@python.net>
209
211       Copyright (c) 1997-2000 by Gregory P. Ward.  All rights reserved.  This
212       file is part of the Text::BibTeX library.  This library is free
213       software; you may redistribute it and/or modify it under the same terms
214       as Perl itself.
215
216
217
218perl v5.38.0                      2023-07-21          Text::BibTeX::Value(3pm)
Impressum