NAME

PBib::Document - Abstract Base and Factory class for Documents

SYNOPSIS

        use PBib::Document;
        my $doc = new PBib::Document(
                'filename' => $filename,
                'mode' => 'r',
                'verbose' => 1,
                );
        print $doc->filename();
        my @paragraphs = $doc->paragraphs();
        $doc->close();

DESCRIPTION

Factory class to create documents that are processed by PBib.

CONSTRUCTOR

$doc = new PBib::Document('filename' => $filename);

Arguments are passed as hash:

filename => string for filename

class => document class to use, e.g. 'RTF' or 'MSWord'

If class is not defined, it is tried to be guessed by looking at the file. (Currently, the filename's extension only.)

formatOptions => hash with options passed to ReferenceFormator

OBSOLETE??

bibitemOptions => hash with options passed to BibItemFormator

OBSOLETE??

converter => string for ReferenceConverter class

OBSOLETE??

formator => string for ReferenceFormator class

OBSOLETE??

mode => "r" | "w"

Mode for this document, used to open the file. "r" = Read, "w" = Write

verbose => If true, produce more verbose output.

File Handling Methods

$filename = $doc->filename();

Return the document's filename.

$handle = $doc->handle();

Return the document's Perl FileHandle.

Caution: This method might not be used by all subclasses of PBib::Document.

$doc->encoding();

Return the document's encoding.

Returns undef if not specified.

$doc->close();

Close the file.

$doc->read()

Read the document from disk. Return the content of the document in a format internal to the document class. (Per default a ref to an array of the lines.)

$doc->write()

Write the document back to disk, if the document has been opened and it contains paragraphs().

$boolean = $doc->exists()

Check, if this document is exists, independent of being accessable. (Perl's -f test)

$boolean = $doc->isValid()

Check, if this document is ok, e.g. if the file exists and can be accessed. (Perl's -w or -r, depending on $doc->mode()

Text Access Methods

Methods used by PBib to access the document.

$inDoc->processParagraphs($func, $rc, $outDoc, @_)

Process all paragraphs of the $inDoc by calling $func. If $outDoc is defined, the result of the function call is added to $outDoc.

The default implementation assumes a linear sequence of paragraphs, using $inDoc's paragraphCount() and getParagraph().

$func is called on $rc with the current paragraph, its index and @_ as parameters:

        $par = $rc->$func($par, $i, @_);

$int = $doc->paragraphCount();

Return the number of paragraphs in document.

$string = $doc->getParagraph($int);

Return the paragraph with index $int

@strings = $doc->paragraphs()

Return all paragraphs in document as an array with all paragraphs as plain (ascii) strings.

Calles $doc->read() if the file has not been read before.

$doc->addParagraph($str1, $str2, ...), $doc->addParagraphs($str1, $str2, ...)

Append paragraphs to document.

Converting Methods

Methods used by PBib::ReferenceConverter::convert().

$doc->prepareConvert($conv)

Do anything you want to before being converted. (Hook for subclasses.) The document object that is returned is used for conversion.

This is called by PBib::ReferenceConverter::convert() on the input document with $conv as the current converter.

$doc->finalizeConvert($conv)

Do anything you want to after being converted. (Hook for subclasses.) The object that is returned is used for further processing.

This is called by PBib::ReferenceConverter::convert() on the output document with $conv as the current converter.

Formatting Methods

Methods used by PBib to create formatted text.

Interactive Editing Methods

Methods used by PBib for interactive editing of documents, e.g. open in editor.

Class Methods

PBib::Document::openFile($filename);

Open the file with it's associated default application.