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, eryq@enteract.com,
    http://www.enteract.com/~eryq.

