1Text::BibTeX::StructureU(s3e)r Contributed Perl DocumentaTteixotn::BibTeX::Structure(3)
2
3
4

NAME

6       Text::BibTeX::Structure - provides base classes for user structure
7       modules
8

SYNOPSIS

10          # Define a 'Foo' structure for BibTeX databases: first, the
11          # structure class:
12
13          package Text::BibTeX::FooStructure;
14          @ISA = ('Text::BibTeX::Structure');
15
16          sub known_option
17          {
18             my ($self, $option) = @_;
19
20             ...
21          }
22
23          sub default_option
24          {
25             my ($self, $option) = @_;
26
27             ...
28          }
29
30          sub describe_entry
31          {
32             my $self = shift;
33
34             $self->set_fields ($type,
35                                \@required_fields,
36                                \@optional_fields,
37                                [$constraint_1, $constraint_2, ...]);
38             ...
39          }
40
41
42          # Now, the structured entry class
43
44          package Text::BibTeX::FooEntry;
45          @ISA = ('Text::BibTeX::StructuredEntry');
46
47          # define whatever methods you like
48

DESCRIPTION

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
59       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
67       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
83       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
89       Please note that the "Text::BibTeX" prefix is dropped from most module
90       and class names in this manual page, except where necessary.
91

STRUCTURE CLASSES

93       Structure classes have two roles: to define the list of allowed types
94       and field rules, and to handle structure options.
95
96   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
111       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
124       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
130          [1, 1, ['author', 'editor']]
131
132       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
143       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
147          [0, 1, ['volume', 'number']]
148
149       That is, either 0 or 1, but not the full 2, of "volume" and "number"
150       may be present.
151
152       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
157       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
166          sub describe_entry
167          {
168             my $self = shift;
169
170             # series of 13 calls to $self->set_fields (one for each standard
171             # entry type)
172          }
173
174       One of those calls to the "set_fields" method defines the rules for
175       "book" entries:
176
177          $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
183       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
190       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
195   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
206       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
214       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
221       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
233       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
242          $structure->set_options (btitle_mkup => ['\emph{', '}']);
243
244       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

STRUCTURED ENTRY CLASSES

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
268       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

CLASS INTERACTIONS

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
282       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
289       Typically, a "Text::BibTeX"-based program is based around a kernel of
290       code like this:
291
292          $bibfile = Text::BibTeX::File->new("foo.bib");
293          while ($entry = Text::BibTeX::Entry->new($bibfile))
294          {
295             # process $entry
296          }
297
298       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
306          $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
313       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
322       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
328       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
334       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
352       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
362       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

EXAMPLE

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

METHODS 1: BASE STRUCTURE CLASS

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
390       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
397   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
403           •   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
411                  $structure = Text::BibTeX::Structure->new
412                     ('Foo', module => 'Foo');
413
414               This method "die"s if there are any errors loading/compiling
415               the structure module.
416
417           •   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
430               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
437           •   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
446       name ()
447           Returns the name of the structure described by the object.
448
449       entry_class ()
450           Returns the name of the structured entry class associated with this
451           structure.
452
453   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
463       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
468           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
472       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
478   Field structure query methods
479       types ()
480           Returns the list of entry types supported by the structure.
481
482       known_type (TYPE)
483           Returns true if TYPE is a supported entry type.
484
485       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
489       required_fields (TYPE)
490           Returns the list of required fields for entries of type TYPE.
491
492       optional_fields ()
493           Returns the list of optional fields for entries of type TYPE.
494
495       field_constraints ()
496           Returns the list of field constraints (in the format supplied to
497           "add_constraints") for entries of type TYPE.
498
499   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
507       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
517              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
525           The default value for an option is returned by "get_options" when
526           that options has not been explicitly set with "set_options".
527
528       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
536       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

METHODS 2: BASE STRUCTURED ENTRY CLASS

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
552       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
560       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
568       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
576              # 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
581       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
586       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
591           This isn't generally used by other code; see the "check" and
592           "coerce" methods below.
593
594       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
607           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
616           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
620              [1, 1, ['author', 'editor']]
621
622           Suppose the following entry is parsed and expected to conform to
623           this structure:
624
625              @inbook{unknown:1997a,
626                title = "An Unattributed Book Chapter",
627                booktitle = "An Unedited Book",
628                publisher = "Foo, Bar \& Company",
629                year = 1997
630              }
631
632           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
640           However, if the same structure was applied to this entry:
641
642              @inbook{smith:1997a,
643                author = "John Smith",
644                editor = "Fred Jones",
645                ...
646              }
647
648           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
653           Again, this method isn't generally used by other code; rather, it
654           is called by "full_check" and its friends below.
655
656       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
665       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
672           Calling "check" is the same as calling "full_check" with WARN true
673           and COERCE false.
674
675       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
680       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

SEE ALSO

685       Text::BibTeX, Text::BibTeX::Entry, Text::BibTeX::File
686

AUTHOR

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.
695
696
697
698perl v5.32.1                      2021-01-27        Text::BibTeX::Structure(3)
Impressum