1Text::BibTeX::Value(3pmU)ser Contributed Perl DocumentatiToenxt::BibTeX::Value(3pm)
2
6 Text::BibTeX::Value - interfaces to BibTeX values and simple values
7
9 use Text::BibTeX;
10 $entry = Text::BibTeX::Entry->new;
12 # set the 'preserve_values' flag to 1 for this parse
14 $entry->parse ($filename, $filehandle, 1);
15 # 'get' method now returns a Text::BibTeX::Value object
17 # rather than a string
18 $value = $entry->get ($field);
19 # 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 # 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
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 For example, in the following entry:
44 @article{homer97,
46 author = "Homer Simpson" # and # "Ned Flanders",
47 title = {Territorial Imperatives in Modern Suburbia},
48 journal = jss,
49 year = 1997
50 }
51 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 $entry = Text::BibTeX::Entry->new($entry_text);
59 then the "get" method on $entry would return simple strings. Assuming
61 that the "and" macro is defined as " and ", then
62 $entry->get ('author')
64 would return the Perl string "Homer Simpson and Ned Flanders".
66 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 $bibfile = Text::BibTeX::File->new($filename);
75 $bibfile->preserve_values (1);
76 $entry = Text::BibTeX::Entry->new($bibfile);
78 $entry->get ($field); # returns a Value object
79 $bibfile->preserve_values (0);
81 $entry = Text::BibTeX::Entry->new($bibfile);
82 $entry->get ($field); # returns a string
83 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 # 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 $entry->parse_s ($entry_text, 1);
94 $entry->get ($field); # returns a Value object
95 # 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 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 For example, we could parse the above entry in "preserve values" mode
113 as follows:
114 $entry->parse_s ($entry_text, 1); # preserve_values is 1
116 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 $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 The simple values may be queried using the "Text::BibTeX::SimpleValue"
126 methods, "type" and "text":
127 $all_values[0]->type; # returns BTAST_STRING
129 $second->type; # returns BTAST_MACRO
130 $all_values[0]->text; # "Homer Simpson"
132 $second->text; # "and" (NOT the macro expansion!)
133 $entry->get ('year')->value (0)->text; # "1997"
135
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 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 $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 The resulting "Value" object could then be installed into an entry
163 using the "set" method of the "Entry" class.
164 values ()
166 Returns the list of "SimpleValue" objects that make up a "Value"
167 object.
168 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 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 use Text::BibTeX qw(:nodetypes);
184 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 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 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
205 Text::BibTeX, Text::BibTeX::File, Text::BibTeX::Entry
206
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.
215perl v5.38.0 2023-07-21 Text::BibTeX::Value(3pm)