NAME
Text::Refer - parse Unix "refer" files
*This is Alpha code, and may be subject to changes in its public
interface. It will stabilize by June 1997, at which point this notice
will be removed. Until then, if you have any feedback, please let me
know!*
SYNOPSIS
Pull in the module:
use Text::Refer;
Parse a refer stream from a filehandle:
while ($ref = input Text::Refer \*FH) {
# ...do stuff with $ref...
}
defined($ref) or die "error parsing input";
Same, but using a parser object for more control:
# Create a new parser:
$parser = new Text::Refer::Parser LeadWhite=>'KEEP';
# Parse:
while ($ref = $parser->input(\*FH)) {
# ...do stuff with $ref...
}
defined($ref) or die "error parsing input";
Manipulating reference objects, using high-level methods:
# Get the title, author, etc.:
$title = $ref->title;
@authors = $ref->author; # list context
$lastAuthor = $ref->author; # scalar context
# Set the title and authors:
$ref->title("Cyberiad");
$ref->author(["S. Trurl", "C. Klapaucius"]); # arrayref for >1 value!
# Delete the abstract:
$ref->abstract(undef);
Same, using low-level methods:
# Get the title, author, etc.:
$title = $ref->get('T');
@authors = $ref->get('A'); # list context
$lastAuthor = $ref->get('A'); # scalar context
# Set the title and authors:
$ref->set('T', "Cyberiad");
$ref->set('A', "S. Trurl", "C. Klapaucius");
# Delete the abstract:
$ref->set('X'); # sets to empty array of values
Output:
print $ref->as_string;
DESCRIPTION
*This module supercedes the old Text::Bib.*
This module provides routines for parsing in the contents of "refer"-
format bibliographic databases: these are simple text files which
contain one or more bibliography records. They are usually found lurking
on Unix-like operating systems, with the extension .bib.
Each record in a "refer" file describes a single paper, book, or
article. Users of nroff/troff often employ such databases when
typesetting papers.
Even if you don't use *roff, this simple, easily-parsed parameter-value
format is still useful for recording/exchanging bibliographic
information. With this module, you can easily post-process "refer"
files: search them, convert them into LaTeX, whatever.
Example
Here's a possible "refer" file with three entries:
%T Cyberiad
%A Stanislaw Lem
%K robot fable
%I Harcourt/Brace/Jovanovich
%T Invisible Cities
%A Italo Calvino
%K city fable philosophy
%X In this surreal series of fables, Marco Polo tells an
aged Kublai Khan of the many cities he has visited in
his lifetime.
%T Angels and Visitations
%A Neil Gaiman
%D 1993
The lines separating the records must be *completely blank*; that is,
they cannot contain anything but a single newline.
See refer(1) or grefer(1) for more information on "refer" files.
Syntax
*From the GNU manpage, `grefer(1)':*
The bibliographic database is a text file consisting of records
separated by one or more blank lines. Within each record fields start
with a % at the beginning of a line. Each field has a one character name
that immediately follows the %. It is best to use only upper and lower
case letters for the names of fields. The name of the field should be
followed by exactly one space, and then by the contents of the field.
Empty fields are ignored. The conventional meaning of each field is as
follows:
A The name of an author. If the name contains a title such as Jr. at the
end, it should be separated from the last name by a comma. There can
be multiple occurrences of the A field. The order is significant. It
is a good idea always to supply an A field or a Q field.
B For an article that is part of a book, the title of the book
C The place (city) of publication.
D The date of publication. The year should be specified in full. If the
month is specified, the name rather than the number of the month
should be used, but only the first three letters are required. It is
a good idea always to supply a D field; if the date is unknown, a
value such as "in press" or "unknown" can be used.
E For an article that is part of a book, the name of an editor of the
book. Where the work has editors and no authors, the names of the
editors should be given as A fields and , (ed) or , (eds) should be
appended to the last author.
G US Government ordering number.
I The publisher (issuer).
J For an article in a journal, the name of the journal.
K Keywords to be used for searching.
L Label.
NOTE: Uniquely identifies the entry. For example, "Able94".
N Journal issue number.
O Other information. This is usually printed at the end of the reference.
P Page number. A range of pages can be specified as m-n.
Q The name of the author, if the author is not a person. This will only be
used if there are no A fields. There can only be one Q field.
NOTE: Thanks to Mike Zimmerman for clarifying this for me: it means
a "corporate" author: when the "author" is listed as an organization
such as the UN, or RAND Corporation, or whatever.
R Technical report number.
S Series name.
T Title. For an article in a book or journal, this should be the title of
the article.
V Volume number of the journal or book.
X Annotation.
NOTE: Basically, a brief abstract or description.
For all fields except A and E, if there is more than one occurrence of a
particular field in a record, only the last such field will be used.
If accent strings are used, they should follow the character to be
accented. This means that the AM macro must be used with the -ms macros.
Accent strings should not be quoted: use one \ rather than two.
Parsing records from "refer" files
You will nearly always use the `input()' constructor to create new
instances, and nearly always as shown in the the section on "SYNOPSIS".
Internally, the records are parsed by a parser object; if you invoke the
class method `Text::Refer::input()', a special default parser is used,
and this will be good enough for most tasks. However, for more complex
tasks, feel free to use the section on "class Text::Refer::Parser" to
build (and use) your own fine-tuned parser, and `input()' from that
instead.
CHANGES
Version 1.101
Initial release. Adapted from Text::Bib.
AUTHOR
Copyright (C) 1997 by Eryq,
[email protected],
http://www.enteract.com/~eryq.
