NAME

 Document::TocFile - Manage a Table of contents file.

SYNOPSIS

 use Document::TocFile;

 $obj      = Document:TocFile->open ($path, $date, $title)
 $obj      = $obj->flush
 $toc      = $obj->merge     ($toc)
 $toc      = $obj->putFrom   ($toc)
 $toc      = $obj->mergeFrom ($toc)
 $version  = $obj->version
 $major    = $obj->major
 $minor    = $obj->minor
 $title    = $obj->title
 $dates    = $obj->dates
 $filepath = $obj->filepath
 $title    = $obj->document
 $dates    = $obj->documentdates

Inheritance

 UNIVERSAL

Description

This Class manages a table of contents file. The file is always named .toc and contains formatted records of the following syntax (TocFile Format Version 0.02):

        0.02
        <dates>-<document_title_section>
        <pageid> <pagetitle_section> <categorylist>

where the first two lines are required. There may be zero or more occurrences of the page lines. A category list is just a list of keywords:

        015  TheCatCameBack-ANewLook   Physics Cosmology Space

The Toc format version number will allow us to cleanly upgrade to more sophisticated file structuring designs in the future. It is the first item in the .toc file, on a line by itself so a parser may immediately decide if it will be able to parse the remainder of the file. The minor version number is to be incremented if changes are such that a previous parser will simply not see the additions or changes (changes are upward compatible); if a change affects the ability of the previous parser to keep on keepin' on, the major version number is incremented (changes are not upward compatible). Parsers for a new major version should be able to read and upgrade all previous versions of the .toc file, perhaps by selection off the major version number.

To Do

There is absolutely no protection against more than one application working with the same .toc file at the same time. This is an area for future improvement. The same is true of .log and .config files.

Examples

 use Document::Toc;
 use Document::TocFile;

 my ($path,$date,$title)  = ("~/test","20040902","LinuxJournal-i126");
 my $toc                  = Document::Toc->new ();
 my $foo                  = Document:TocFile->open ($path,$date,$title);

 my $docname_string       = $foo->title;
 my $date_string          = $foo->dates;
 my $version_string       = $foo->version;
 my $major_version_number = $foo->major;
 my $minor_version_number = $foo->minor;
 my $filepath             = $foo->filepath
 my $doctitle             = $foo->document
 my $docdates             = $foo->documentdates
 my $merged_toc           = $foo->merge     ($toc);
 my $flg                  = $foo->flush
    $toc                  = $foo->putFrom   ($merged_toc);
    $toc                  = $foo->merge     ($toc)
    $toc                  = $foo->mergeFrom ($toc)

Class Variables

 None.

Instance Variables

 filepath                Full pathname of the .toc file suitable for open and
                         close.
 document_dates          Document date string taken from the filepath.
 document_title_section  Document name string taken from the filepath..
 contents                Array of arrays to hold all the lines of the table of
                         contents data read from the .toc.
 toc_version             Version string taken from the  .toc file.
 toc_major               First element of version string from .toc
 toc_minor               Second element of version string from .toc.
 toc_dates               Document date string taken from the .toc file.
 toc_title_section       Document name string taken from the  .toc file.

Class Methods

$obj = Document:TocFile->open ($path, $date, $title)

Generate an object to manage the interface with a .toc file in a directory named /$path/$date-$title/. The arguments are:

        path to document directory, eg. /home/mypubs/thisdocument/
        document dates              eg. 20040813 
        document-title-section      eg. LinuxManual-PenguinsRule

If there is no .toc file, an 'empty' with just:

        0.02
        $date-$title

in it.. If the file already exists, it is read and if it has a version number this object knows about, the data is parsed into an internal format. When the .toc file is next updated, it will be re-written in the Toc File Format Version used by this object.

The open method returns undef if it is unable to build a valid document path name from the input argument list.

Instance Methods

$dates = $obj->dates

Return the date string from the .toc file document name, eg "19991225"

$title = $obj->document

Return the document title from the input args eg:

 "ReportOnInternationalSecurity-TheThreatModel"

$dates = $obj->documentdates

Return the date string from the input args, eg "19991225"

$filepath = $obj->filepath

Return the full pathname of the .toc file, suitable for file open, close, etc, eg:

 "/archive/19991225-ReportOnInternationalSecurity-TheThreatModel/.toc"

$obj = $obj->flush

Write a new .toc file from the stored data. Writes to a .toc.tmp first then moves it to .toc. Any error at any point terminates the close before overwriting the .toc. Only if the system 'mv' itself fails in a race could .toc be damaged.

flush can be issued any number of times, but will do nothing unless the contents has changed.

If the version of this class is different from the version on the .toc, a rewrite is forced.

If there is no .toc file, a write is forced so that at the very least there will always be a file with version and document title records in any directory for which a Document::TocFile object is created.

Flush is called by the DESTROY method, so if our contents have changed in any of the ways noted above, the .toc file will be rewritten.

[If a reason is found that requires prevention of this behavior, a simple code modification is to add a method to clear the internal _init flag ivar.]

$major = $obj->major

Return the major version part of the .toc files' format version number.

$toc = $obj->merge ($toc)

Merge the internally stored contents of the .toc file into the supplied Document::Toc object. Undef on failure.

$toc = $obj->mergeFrom ($toc)

Overwrite page records in the contents array by merging the current contents with those from the supplied Document::Toc object. Does not rewrite the .toc file itself.

$minor = $obj->minor

Return the minor version part of the .toc files' format version number.

$toc = $obj->putFrom ($toc)

Replace the internally stored contents of the .toc file with the data from the supplied Document::Toc object. Does not rewrite the .toc file itself.

Returns undef on failure.

$title = $obj->title

Return the document title from the associated .toc file eg:

 "ReportOnInternationalSecurity-TheThreatModel"

$version = $obj->version

Return the .toc files' format version number string.

Private Class Methods

 None.

Private Instance Methods

$obj->_err ($msg)

Print a warning message.

$flg = $obj->_read

Read the and parse the .toc file from a publication directory. Return true on success; undef if the major version stored in the file is greater than the major version of this Class or other problems are found with the file format.

($path, $pathname, $dates, $title) = $obj->_setdirobj ($path, $dates, $title )

Subclass may override. Shuffles the input argument list and returns them in a list along with a $pathname of $dir/$date-$name. Why? This is a tricky way to let subclasses override the open method's input argument list.

Open's entire argument list is passed to this method, uninterpreted. So whether open takes one argument or three is entirely dependent what this method looks for.

($toc_title, $toc_dates) = $obj->_split_documentname ($toc_title)

This method customizes the behavior of the the .toc file read operation in the open method. Subclass may override. The first output value is just a copy of the input argument; the second, the date, is a null string. This might change if I decided to do some low level parsing here. Yes, it could use a File::Spec, but it is intentionally staying as simple an independent as possible. Child classes will use File::Spec::* when they override this method.

$documentname = $obj->_validate_documentname ($documentname)

This method customizes the behavior of the the .toc file read operation in the open method. Subclass may override. Just moves the input arg to the output.

$flg = $obj->_validate_pagetitle ($document_title, $stargpage, $endpage, $document_title)

This method customizes the behavior of the the .toc file read operation in the open method. Subclass may override. Always returns true.

$flg = $obj->_write

Write an updated .toc file to a publication directory with extreme care and paranoia. First write a temp file, then copy it over top of the old .toc once we're sure all is cool.

If object has not been initialized, fail.

If it has not changed, succeed immediately. Otherwise flush it to disk and clear _dirty flag.

Returns true on success, false if *all* data does not end up in .toc

KNOWN BUGS

 See TODO.

SEE ALSO

Fault::Logger, Fault::DebugPrinter, Fault::ErrorHandler, DMA::Version, DMA::FSM, Document::Toc, Document::PageId, DMA::ISODate

AUTHOR

Dale Amon <amon@vnl.com>

cpanm Document::Toc

perl -MCPAN -e shell
install Document::Toc