1Text::BibTeX::StructureU(s3e)r Contributed Perl DocumentaTteixotn::BibTeX::Structure(3)
2
6 Text::BibTeX::Structure - provides base classes for user structure
7 modules
8
10 # Define a 'Foo' structure for BibTeX databases: first, the
11 # structure class:
12 package Text::BibTeX::FooStructure;
14 @ISA = ('Text::BibTeX::Structure');
15 sub known_option
17 {
18 my ($self, $option) = @_;
19 ...
21 }
22 sub default_option
24 {
25 my ($self, $option) = @_;
26 ...
28 }
29 sub describe_entry
31 {
32 my $self = shift;
33 $self->set_fields ($type,
35 \@required_fields,
36 \@optional_fields,
37 [$constraint_1, $constraint_2, ...]);
38 ...
39 }
40 # Now, the structured entry class
43 package Text::BibTeX::FooEntry;
45 @ISA = ('Text::BibTeX::StructuredEntry');
46 # define whatever methods you like
48
50 The module "Text::BibTeX::Structure" provides two classes that form the
51 basis of the btOOL "structure module" system. This system is how
52 database structures are defined and imposed on BibTeX files, and
53 provides an elegant synthesis of object-oriented techniques with
54 BibTeX-style database structures. Nothing described here is
55 particularly deep or subtle; anyone familiar with object-oriented
56 programming should be able to follow it. However, a fair bit of jargon
57 in invented and tossed around, so pay attention.
58 A database structure, in btOOL parlance, is just a set of allowed entry
60 types and the rules for fields in each of those entry types.
61 Currently, there are three kinds of rules that apply to fields: some
62 fields are required, meaning they must be present in every entry for a
63 given type; some are optional, meaning they may be present, and will be
64 used if they are; other fields are members of constraint sets, which
65 are explained in "Field lists and constraint sets" below.
66 A btOOL structure is implemented with two classes: the structure class
68 and the structured entry class. The former defines everything that
69 applies to the structure as a whole (allowed types and field rules).
70 The latter provides methods that operate on individual entries which
71 conform (or are supposed to conform) to the structure. The two classes
72 provided by the "Text::BibTeX::Structure" module are
73 "Text::BibTeX::Structure" and "Text::BibTeX::StructuredEntry"; these
74 serve as base classes for, respectively, all structure classes and all
75 structured entry classes. One canonical structure is provided as an
76 example with btOOL: the "Bib" structure, which (via the "BibStructure"
77 and "BibEntry" classes) provides the same functionality as the standard
78 style files of BibTeX 0.99. It is hoped that other programmers will
79 write new bibliography-related structures, possibly deriving from the
80 "Bib" structure, to emulate some of the functionality that is available
81 through third-party BibTeX style files.
82 The purpose of this manual page is to describe the whole "structure
84 module" system. It is mainly for programmers wishing to implement a
85 new database structure for data files with BibTeX syntax; if you are
86 interested in the particular rules for the BibTeX-emulating "Bib"
87 structure, see Text::BibTeX::Bib.
88 Please note that the "Text::BibTeX" prefix is dropped from most module
90 and class names in this manual page, except where necessary.
91
93 Structure classes have two roles: to define the list of allowed types
94 and field rules, and to handle structure options.
95 Field lists and constraint sets
97 Field lists and constraint sets define the database structure for a
98 particular entry type: that is, they specify the rules which an entry
99 must follow to conform to the structure (assuming that entry is of an
100 allowed type). There are three components to the field rules for each
101 entry type: a list of required fields, a list of optional fields, and
102 field constraints. Required and optional fields should be obvious to
103 anyone with BibTeX experience: all required fields must be present, and
104 any optional fields that are present have some meaning to the
105 structure. (One could conceive of a "strict" interpretation, where any
106 field not mentioned in the official definition is disallowed; this
107 would be contrary to the open spirit of BibTeX databases, but could be
108 useful in certain applications where a stricter level of control is
109 desired. Currently, btOOL does not offer such an option.)
110 Field constraints capture the "one or the other, but not both" type of
112 relationships present for some entry types in the BibTeX standard style
113 files. Most BibTeX documentation glosses over the distinction between
114 mutually constrained fields and required/optional fields. For
115 instance, one of the standard entry types is "book", and ""author" or
116 "editor"" is given in the list of required fields for that type. The
117 meaning of this is that an entry of type "book" must have either the
118 "author" or "editor" fields, but not both. Likewise, the ""volume" or
119 "number"" are listed under the "optional fields" heading for "book"
120 entries; it would be more accurate to say that every "book" entry may
121 have one or the other, or neither, of "volume" or "number"---but not
122 both.
123 btOOL attempts to clarify this situation by creating a third category
125 of fields, those that are mutually constrained. For instance, neither
126 "author" nor "editor" appears in the list of required fields for the
127 "inbook" type according to btOOL; rather, a field constraint is created
128 to express this relationship:
129 [1, 1, ['author', 'editor']]
131 That is, a field constraint is a reference to a three-element list.
133 The last element is a reference to the constraint set, the list of
134 fields to which the constraint applies. (Calling this a set is a bit
135 inaccurate, as there are conditions in which the order of fields
136 matters---see the "check_field_constraints" method in "METHODS 2: BASE
137 STRUCTURED ENTRY CLASS".) The first two elements are the minimum and
138 maximum number of fields from the constraint set that must be present
139 for an entry to conform to the constraint. This constraint thus
140 expresses that there must be exactly one (>= 1 and <= 1) of the fields
141 "author" and "editor" in a "book" entry.
142 The "either one or neither, but not both" constraint that applies to
144 the "volume" and "number" fields for "book" entries is expressed
145 slightly differently:
146 [0, 1, ['volume', 'number']]
148 That is, either 0 or 1, but not the full 2, of "volume" and "number"
150 may be present.
151 It is important to note that checking and enforcing field constraints
153 is based purely on counting which fields from a set are actually
154 present; this mechanism can't capture "x must be present if y is"
155 relationships.
156 The requirements imposed on the actual structure class are simple: it
158 must provide a method "describe_entry" which sets up a fancy data
159 structure describing the allowed entry types and all the field rules
160 for those types. The "Structure" class provides methods (inherited by
161 a particular structure class) to help particular structure classes
162 create this data structure in a consistent, controlled way. For
163 instance, the "describe_structure" method in the BibTeX 0.99-emulating
164 "BibStructure" class is quite simple:
165 sub describe_entry
167 {
168 my $self = shift;
169 # series of 13 calls to $self->set_fields (one for each standard
171 # entry type)
172 }
173 One of those calls to the "set_fields" method defines the rules for
175 "book" entries:
176 $self->set_fields ('book',
178 [qw(title publisher year)],
179 [qw(series address edition month note)],
180 [1, 1, [qw(author editor)]],
181 [0, 1, [qw(volume number)]]);
182 The first field list is the list of required fields, and the second is
184 the list of optional fields. Any number of field constraints may
185 follow the list of optional fields; in this case, there are two, one
186 for each of the constraints ("author"/"editor" and "volume"/"number")
187 described above. At no point is a list of allowed types explicitly
188 supplied; rather, each call to "set_fields" adds one more allowed type.
189 New structure modules that derive from existing ones will probably use
191 the "add_fields" method (and possibly "add_constraints") to augment an
192 existing entry type. Adding new types should be done with
193 "set_fields", though.
194 Structure options
196 The other responsibility of structure classes is to handle structure
197 options. These are scalar values that let the user customize the
198 behaviour of both the structure class and the structured entry class.
199 For instance, one could have an option to enable "extended structure",
200 which might add on a bunch of new entry types and new fields. (In this
201 case, the "describe_entry" method would have to pay attention to this
202 option and modify its behaviour accordingly.) Or, one could have
203 options to control how the structured entry class sorts or formats
204 entries (for bibliography structures such as "Bib").
205 The easy way to handle structure options is to provide two methods,
207 "known_option" and "default_option". These return, respectively,
208 whether a given option is supported, and what its default value is.
209 (If your structure doesn't support any options, you can just inherit
210 these methods from the "Structure" class. The default "known_option"
211 returns false for all options, and its companion "default_option"
212 crashes with an "unknown option" error.)
213 Once "known_option" and "default_option" are provided, the structure
215 class can sit back and inherit the more visible "set_options" and
216 "get_options" methods from the "Structure" class. These are the
217 methods actually used to modify/query options, and will be used by
218 application programs to customize the structure module's behaviour, and
219 by the structure module itself to pay attention to the user's wishes.
220 Options should generally have pure string values, so that the generic
222 set_options method doesn't have to parse user-supplied strings into
223 some complicated structure. However, "set_options" will take any
224 scalar value, so if the structure module clearly documents its
225 requirements, the application program could supply a structure that
226 meets its needs. Keep in mind that this requires cooperation between
227 the application and the structure module; the intermediary code in
228 "Text::BibTeX::Structure" knows nothing about the format or syntax of
229 your structure's options, and whatever scalar the application passes
230 via "set_options" will be stored for your module to retrieve via
231 "get_options".
232 As an example, the "Bib" structure supports a number of "markup"
234 options that allow applications to control the markup language used for
235 formatting bibliographic entries. These options are naturally paired,
236 as formatting commands in markup languages generally have to be turned
237 on and off. The "Bib" structure thus expects references to two-element
238 lists for markup options; to specify LaTeX 2e-style emphasis for book
239 titles, an application such as "btformat" would set the "btitle_mkup"
240 option as follows:
241 $structure->set_options (btitle_mkup => ['\emph{', '}']);
243 Other options for other structures might have a more complicated
245 structure, but it's up to the structure class to document and enforce
246 this.
247
249 A structured entry class defines the behaviour of individual entries
250 under the regime of a particular database structure. This is the
251 raison d'etre for any database structure: the structure class merely
252 lays out the rules for entries to conform to the structure, but the
253 structured entry class provides the methods that actually operate on
254 individual entries. Because this is completely open-ended, the
255 requirements of a structured entry class are much less rigid than for a
256 structure class. In fact, all of the requirements of a structured
257 entry class can be met simply by inheriting from
258 "Text::BibTeX::StructuredEntry", the other class provided by the
259 "Text::BibTeX::Structure" module. (For the record, those requirements
260 are: a structured entry class must provide the entry
261 parse/query/manipulate methods of the "Entry" class, and it must
262 provide the "check", "coerce", and "silently_coerce" methods of the
263 "StructuredEntry" class. Since "StructuredEntry" inherits from
264 "Entry", both of these requirements are met "for free" by structured
265 entry classes that inherit from "Text::BibTeX::StructuredEntry", so
266 naturally this is the recommended course of action!)
267 There are deliberately no other methods required of structured entry
269 classes. A particular application (eg. "btformat" for bibliography
270 structures) will require certain methods, but it's up to the
271 application and the structure module to work out the requirements
272 through documentation.
273
275 Imposing a database structure on your entries sets off a chain reaction
276 of interactions between various classes in the "Text::BibTeX" library
277 that should be transparent when all goes well. It could prove
278 confusing if things go wrong and you have to go wading through several
279 levels of application program, core "Text::BibTeX" classes, and some
280 structure module.
281 The justification for this complicated behaviour is that it allows you
283 to write programs that will use a particular structured module without
284 knowing the name of the structure when you write the program. Thus,
285 the user can supply a database structure, and ultimately the entry
286 objects you manipulate will be blessed into a class supplied by the
287 structure module. A short example will illustrate this.
288 Typically, a "Text::BibTeX"-based program is based around a kernel of
290 code like this:
291 $bibfile = Text::BibTeX::File->new("foo.bib");
293 while ($entry = Text::BibTeX::Entry->new($bibfile))
294 {
295 # process $entry
296 }
297 In this case, nothing fancy is happening behind the scenes: the
299 $bibfile object is blessed into the "Text::BibTeX::File" class, and
300 $entry is blessed into "Text::BibTeX::Entry". This is the conventional
301 behaviour of Perl classes, but it is not the only possible behaviour.
302 Let us now suppose that $bibfile is expected to conform to a database
303 structure specified by $structure (presumably a user-supplied value,
304 and thus unknown at compile-time):
305 $bibfile = Text::BibTeX::File->new("foo.bib");
307 $bibfile->set_structure ($structure);
308 while ($entry = Text::BibTeX::Entry->new($bibfile))
309 {
310 # process $entry
311 }
312 A lot happens behind the scenes with the call to $bibfile's
314 "set_structure" method. First, a new structure object is created from
315 $structure. The structure name implies the name of a Perl module---the
316 structure module---which is "require"'d by the "Structure" constructor.
317 (The main consequence of this is that any compile-time errors in your
318 structure module will not be revealed until a
319 "Text::BibTeX::File::set_structure" or "Text::BibTeX::Structure::new"
320 call attempts to load it.)
321 Recall that the first responsibility of a structure module is to define
323 a structure class. The "structure object" created by the
324 "set_structure" method call is actually an object of this class; this
325 is the first bit of trickery---the structure object (buried behind the
326 scenes) is blessed into a class whose name is not known until run-time.
327 Now, the behaviour of the "Text::BibTeX::Entry::new" constructor
329 changes subtly: rather than returning an object blessed into the
330 "Text::BibTeX::Entry" class as you might expect from the code, the
331 object is blessed into the structured entry class associated with
332 $structure.
333 For example, if the value of $structure is "Foo", that means the user
335 has supplied a module implementing the "Foo" structure. (Ordinarily,
336 this module would be called "Text::BibTeX::Foo"---but you can customize
337 this.) Calling the "set_structure" method on $bibfile will attempt to
338 create a new structure object via the "Text::BibTeX::Structure"
339 constructor, which loads the structure module "Text::BibTeX::Foo".
340 Once this module is successfully loaded, the new object is blessed into
341 its structure class, which will presumably be called
342 "Text::BibTeX::FooStructure" (again, this is customizable). The new
343 object is supplied with the user's structure options via the
344 "set_options" method (usually inherited), and then it is asked to
345 describe the actual entry layout by calling its "describe_entry"
346 method. This, in turn, will usually call the inherited "set_fields"
347 method for each entry type in the database structure. When the
348 "Structure" constructor is finished, the new structure object is stored
349 in the "File" object (remember, we started all this by calling
350 "set_structure" on a "File" object) for future reference.
351 Then, when a new "Entry" object is created and parsed from that
353 particular "File" object, some more trickery happens. Trivially, the
354 structure object stored in the "File" object is also stored in the
355 "Entry" object. (The idea is that entries could belong to a database
356 structure independently of any file, but usually they will just get the
357 structure that was assigned to their database file.) More importantly,
358 the new "Entry" object is re-blessed into the structured entry class
359 supplied by the structure module---presumably, in this case,
360 "Text::BibTeX::FooEntry" (also customizable).
361 Once all this sleight-of-hand is accomplished, the application may
363 treat its entry objects as objects of the structured entry class for
364 the "Foo" structure---they may call the check/coerce methods inherited
365 from "Text::BibTeX::StructuredEntry", and they may also call any
366 methods specific to entries for this particular database structure.
367 What these methods might be is up to the structure implementor to
368 decide and document; thus, applications may be specific to one
369 particular database structure, or they may work on all structures that
370 supply certain methods. The choice is up to the application developer,
371 and the range of options open to him depends on which methods structure
372 implementors provide.
373
375 For example code, please refer to the source of the "Bib" module and
376 the "btcheck", "btsort", and "btformat" applications supplied with
377 "Text::BibTeX".
378
380 The first class provided by the "Text::BibTeX::Structure" module is
381 "Text::BibTeX::Structure". This class is intended to provide methods
382 that will be inherited by user-supplied structure classes; such classes
383 should not override any of the methods described here (except
384 "known_option" and "default_option") without very good reason.
385 Furthermore, overriding the "new" method would be useless, because in
386 general applications won't know the name of your structure class---they
387 can only call "Text::BibTeX::Structure::new" (usually via
388 "Text::BibTeX::File::set_structure").
389 Finally, there are three methods that structure classes should
391 implement: "known_option", "default_option", and "describe_entry". The
392 first two are described in "Structure options" above, the latter in
393 "Field lists and constraint sets". Note that "describe_entry" depends
394 heavily on the "set_fields", "add_fields", and "add_constraints"
395 methods described here.
396 Constructor/simple query methods
398 new (STRUCTURE, [OPTION => VALUE, ...])
399 Constructs a new structure object---not a "Text::BibTeX::Structure"
400 object, but rather an object blessed into the structure class
401 associated with STRUCTURE. More precisely:
402 • Loads (with "require") the module implementing STRUCTURE. In
404 the absence of other information, the module name is derived by
405 appending STRUCTURE to "Text::BibTeX::"---thus, the module
406 "Text::BibTeX::Bib" implements the "Bib" structure. Use the
407 pseudo-option "module" to override this module name. For
408 instance, if the structure "Foo" is implemented by the module
409 "Foo":
410 $structure = Text::BibTeX::Structure->new
412 ('Foo', module => 'Foo');
413 This method "die"s if there are any errors loading/compiling
415 the structure module.
416 • Verifies that the structure module provides a structure class
418 and a structured entry class. The structure class is named by
419 appending "Structure" to the name of the module, and the
420 structured entry class by appending "Entry". Thus, in the
421 absence of a "module" option, these two classes (for the "Bib"
422 structure) would be named "Text::BibTeX::BibStructure" and
423 "Text::BibTeX::BibEntry". Either or both of the default class
424 names may be overridden by having the structure module return a
425 reference to a hash (as opposed to the traditional 1 returned
426 by modules). This hash could then supply a "structure_class"
427 element to name the structure class, and an "entry_class"
428 element to name the structured entry class.
429 Apart from ensuring that the two classes actually exist, "new"
431 verifies that they inherit correctly (from
432 "Text::BibTeX::Structure" and "Text::BibTeX::StructuredEntry"
433 respectively), and that the structure class provides the
434 required "known_option", "default_option", and "describe_entry"
435 methods.
436 • Creates the new structure object, and blesses it into the
438 structure class. Supplies it with options by passing all
439 (OPTION, VALUE) pairs to its "set_options" method. Calls its
440 "describe_entry" method, which should list the field
441 requirements for all entry types recognized by this structure.
442 "describe_entry" will most likely use some or all of the
443 "set_fields", "add_fields", and "add_constraints"
444 methods---described below---for this.
445 name ()
447 Returns the name of the structure described by the object.
448 entry_class ()
450 Returns the name of the structured entry class associated with this
451 structure.
452 Field structure description methods
454 add_constraints (TYPE, CONSTRAINT, ...)
455 Adds one or more field constraints to the structure. A field
456 constraint is specified as a reference to a three-element list; the
457 last element is a reference to the list of fields affected, and the
458 first two elements are the minimum and maximum number of fields
459 from the constraint set allowed in an entry of type TYPE. See
460 "Field lists and constraint sets" for a full explanation of field
461 constraints.
462 add_fields (TYPE, REQUIRED [, OPTIONAL [, CONSTRAINT, ...]])
464 Adds fields to the required/optional lists for entries of type
465 TYPE. Can also add field constraints, but you can just as easily
466 use "add_constraints" for that.
467 REQUIRED and OPTIONAL, if defined, should be references to lists of
469 fields to add to the respective field lists. The CONSTRAINTs, if
470 given, are exactly as described for "add_constraints" above.
471 set_fields (TYPE, REQUIRED [, OPTIONAL [, CONSTRAINTS, ...]])
473 Sets the lists of required/optional fields for entries of type
474 TYPE. Identical to "add_fields", except that the field lists and
475 list of constraints are set from scratch here, rather than being
476 added to.
477 Field structure query methods
479 types ()
480 Returns the list of entry types supported by the structure.
481 known_type (TYPE)
483 Returns true if TYPE is a supported entry type.
484 known_field (TYPE, FIELD)
486 Returns true if FIELD is in the required list, optional list, or
487 one of the constraint sets for entries of type TYPE.
488 required_fields (TYPE)
490 Returns the list of required fields for entries of type TYPE.
491 optional_fields ()
493 Returns the list of optional fields for entries of type TYPE.
494 field_constraints ()
496 Returns the list of field constraints (in the format supplied to
497 "add_constraints") for entries of type TYPE.
498 Option methods
500 known_option (OPTION)
501 Returns false. This is mainly for the use of derived structures
502 that don't have any options, and thus don't need to provide their
503 own "known_option" method. Structures that actually offer options
504 should override this method; it should return true if OPTION is a
505 supported option.
506 default_option (OPTION)
508 Crashes with an "unknown option" message. Again, this is mainly
509 for use by derived structure classes that don't actually offer any
510 options. Structures that handle options should override this
511 method; every option handled by "known_option" should have a
512 default value (which might just be "undef") that is returned by
513 "default_option". Your "default_options" method should crash on an
514 unknown option, perhaps by calling "SUPER::default_option" (in
515 order to ensure consistent error messages). For example:
516 sub default_option
518 {
519 my ($self, $option) = @_;
520 return $default_options{$option}
521 if exists $default_options{$option};
522 $self->SUPER::default_option ($option); # crash
523 }
524 The default value for an option is returned by "get_options" when
526 that options has not been explicitly set with "set_options".
527 set_options (OPTION => VALUE, ...)
529 Sets one or more option values. (You can supply as many "OPTION =>
530 VALUE" pairs as you like, just so long as there are an even number
531 of arguments.) Each OPTION must be handled by the structure module
532 (as indicated by the "known_option" method); if not "set_options"
533 will "croak". Each VALUE may be any scalar value; it's up to the
534 structure module to validate them.
535 get_options (OPTION, ...)
537 Returns the value(s) of one or more options. Any OPTION that has
538 not been set by "set_options" will return its default value,
539 fetched using the "default_value" method. If OPTION is not
540 supported by the structure module, then your program either already
541 crashed (when it tried to set it with "set_option"), or it will
542 crash here (thanks to calling "default_option").
543
545 The other class provided by the "Structure" module is
546 "StructuredEntry", the base class for all structured entry classes.
547 This class inherits from "Entry", so all of its entry
548 query/manipulation methods are available. "StructuredEntry" adds
549 methods for checking that an entry conforms to the database structure
550 defined by a structure class.
551 It only makes sense for "StructuredEntry" to be used as a base class;
553 you would never create standalone "StructuredEntry" objects. The
554 superficial reason for this is that only particular structured-entry
555 classes have an actual structure class associated with them,
556 "StructuredEntry" on its own doesn't have any information about allowed
557 types, required fields, field constraints, and so on. For a deeper
558 understanding, consult "CLASS INTERACTIONS" above.
559 Since "StructuredEntry" derives from "Entry", it naturally operates on
561 BibTeX entries. Hence, the following descriptions refer to "the
562 entry"---this is just the object (entry) being operated on. Note that
563 these methods are presented in bottom-up order, meaning that the
564 methods you're most likely to actually use---"check", "coerce", and
565 "silently_coerce" are at the bottom. On a first reading, you'll
566 probably want to skip down to them for a quick summary.
567 structure ()
569 Returns the object that defines the structure the entry to which is
570 supposed to conform. This will be an instantiation of some
571 structure class, and exists mainly so the check/coerce methods can
572 query the structure about the types and fields it recognizes. If,
573 for some reason, you wanted to query an entry's structure about the
574 validity of type "foo", you might do this:
575 # assume $entry is an object of some structured entry class, i.e.
577 # it inherits from Text::BibTeX::StructuredEntry
578 $structure = $entry->structure;
579 $foo_known = $structure->known_type ('foo');
580 check_type ([WARN])
582 Returns true if the entry has a valid type according to its
583 structure. If WARN is true, then an invalid type results in a
584 warning being printed.
585 check_required_fields ([WARN [, COERCE]])
587 Checks that all required fields are present in the entry. If WARN
588 is true, then a warning is printed for every missing field. If
589 COERCE is true, then missing fields are set to the empty string.
590 This isn't generally used by other code; see the "check" and
592 "coerce" methods below.
593 check_field_constraints ([WARN [, COERCE]])
595 Checks that the entry conforms to all of the field constraints
596 imposed by its structure. Recall that a field constraint consists
597 of a list of fields, and a minimum and maximum number of those
598 fields that must be present in an entry. For each constraint,
599 "check_field_constraints" simply counts how many fields in the
600 constraint's field set are present. If this count falls below the
601 minimum or above the maximum for that constraint and WARN is true,
602 a warning is issued. In general, this warning is of the form
603 "between x and y of fields foo, bar, and baz must be present". The
604 more common cases are handled specially to generate more useful and
605 human-friendly warning messages.
606 If COERCE is true, then the entry is modified to force it into
608 conformance with all field constraints. How this is done depends
609 on whether the violation is a matter of not enough fields present
610 in the entry, or of too many fields present. In the former case,
611 just enough fields are added (as empty strings) to meet the
612 requirements of the constraint; in the latter case, fields are
613 deleted. Which fields to add or delete is controlled by the order
614 of fields in the constraint's field list.
615 An example should clarify this. For instance, a field constraint
617 specifying that exactly one of "author" or "editor" must appear in
618 an entry would look like this:
619 [1, 1, ['author', 'editor']]
621 Suppose the following entry is parsed and expected to conform to
623 this structure:
624 @inbook{unknown:1997a,
626 title = "An Unattributed Book Chapter",
627 booktitle = "An Unedited Book",
628 publisher = "Foo, Bar \& Company",
629 year = 1997
630 }
631 If "check_field_constraints" is called on this method with COERCE
633 true (which is done by any of the "full_check", "coerce", and
634 "silently_coerce" methods), then the "author" field is set to the
635 empty string. (We go through the list of fields in the
636 constraint's field set in order -- since "author" is the first
637 missing field, we supply it; with that done, the entry now conforms
638 to the "author"/"editor" constraint, so we're done.)
639 However, if the same structure was applied to this entry:
641 @inbook{smith:1997a,
643 author = "John Smith",
644 editor = "Fred Jones",
645 ...
646 }
647 then the "editor" field would be deleted. In this case, we allow
649 the first field in the constraint's field list---"author". Since
650 only one field from the set may be present, all fields after the
651 first one are in violation, so they are deleted.
652 Again, this method isn't generally used by other code; rather, it
654 is called by "full_check" and its friends below.
655 full_check ([WARN [, COERCE]])
657 Returns true if an entry's type and fields are all valid. That is,
658 it calls "check_type", "check_required_fields", and
659 "check_field_constraints"; if all of them return true, then so does
660 "full_check". WARN and COERCE are simply passed on to the three
661 "check_*" methods: the first controls the printing of warnings, and
662 the second decides whether we should modify the entry to force it
663 into conformance.
664 check ()
666 Checks that the entry conforms to the requirements of its
667 associated database structure: the type must be known, all required
668 fields must be present, and all field constraints must be met. See
669 "check_type", "check_required_fields", and
670 "check_field_constraints" for details.
671 Calling "check" is the same as calling "full_check" with WARN true
673 and COERCE false.
674 coerce ()
676 Same as "check", except entries are coerced into conformance with
677 the database structure---that is, it's just like "full_check" with
678 both WARN and COERCE true.
679 silently_coerce ()
681 Same as "coerce", except warnings aren't printed---that is, it's
682 just like "full_check" with WARN false and COERCE true.
683
685 Text::BibTeX, Text::BibTeX::Entry, Text::BibTeX::File
686
688 Greg Ward <gward@python.net>
689
691 Copyright (c) 1997-2000 by Gregory P. Ward. All rights reserved. This
692 file is part of the Text::BibTeX library. This library is free
693 software; you may redistribute it and/or modify it under the same terms
694 as Perl itself.
695perl v5.32.1 2021-01-27 Text::BibTeX::Structure(3)