NAME

File::Spec::DatedPage - Parse a dated and page numbered file name in a system independant way.

SYNOPSIS

 use File::Spec::DatedPage;

($volume, $basepath, $directory, 
 $startdate, $enddate, $document_title_section,
 $startpage, $endpage, $page_title_section,
 @extensions)           = $obj->splitpath ($filepath);

$document_title_section = $obj->document_title_section;

$startpage = $obj->startpage;
$endpage   = $obj->endpage;
$pages     = $obj->pages;

$page_title_section = $obj->page_title_section;

$flag      = $obj->ambiguous;
$obj      = $obj->set_document_title_section ($document_title_section);
$obj      = $obj->set_startpage              ($startpage);
$obj      = $obj->set_endpage                ($endpage);
$obj      = $obj->set_page_title_section     ($page_title_section);

$name_body = $obj->reset_name_body;

Inheritance

UNIVERSAL
  File::Spec::Unix
    File::Spec::BaseParse
      File::Spec::Dated
        File::Spec::DatedPage

Description

Further splits a pathname string from what it's parent classes have already done. Using the example name_body string, XMAS-Title-Subtitle-note, it will be broken down further as:

document_title_section:    XMAS-Title-Subtitle-note
startpage:
endpage
page_title_section:

The 'ambiguous' flag is not implemented yet: it is only talked about.. It should mark cases where a file extension might really be part of a filename as shown in File::Spec::Dated. This is the first semantic level at which it seems to matter. I have now made sure it does not exist outside this module so as to make it easy to purge if I decide it is an unworkable idea.

Examples

use File::Spec::DatedPage;
my $baz        = File::Spec::DatedPage->new;
my @list       = $baz->splitpath
                 ("/my/base/Cards/19901225-XMAS-Title-Subtitle-note.tar.gz");

my $foo        = File::Spec::DatedPage->new
                 ("/my/base/Cards/19901225-XMAS-Title-Subtitle-note.tar.gz");

my $startpage  = $foo->startpage;
my $endpage    = $foo->endpage;
my $pages      = $foo->pages;
my $dtitle     = $foo->document_title_section;
my $ptitle     = $foo->page_title_section;

$foo->set_startpage  ("100");
$foo->set_endpage    ("101");
$foo->set_document_title_section 
                     ("JournalOfIrreproduceableResults-QuantumBubbling" );
$foo->set_page_title_section ("ThePintEffect-allTheTimeInTheworldInAGuinness");
my $name_body  = $foo->reset_name_body;
my $name       = $foo->reset_name;
my $filename   = $foo->reset_filename;
my $filepath   = $foo->reset_pathname;
my @parts      = $foo->reparse;

Class Variables

None.

Instance Variables

document_title_section   Title of the whole document.
startpage                Starting page string.
endpage                  Ending page string.
page_title_section       Title specifically associated with the page.
ambiguous                Set if it is ambiguous whether  the leftmost file
                         extension really is a file extension.

Class Methods

None.

Instance Methods

$flag = $obj->ambiguous

Return true if it is ambiguous whether the rightmost file extension is really a file extension.

$document_title_section = $obj->document_title_section

Return the document title section string.

$endpage = $obj->endpage

Return the ending pageid object or undef if there is none.

$pages = $obj->pages

Return a $pages string suitable for use in an index or table of contents, eg "100", "100-101" or "42.1-42.2".

Return undef if there is no page information associated with this filespec.

$page_title_section = $obj->page_title_section

Return the title string.

$obj = $obj->set_endpage ($endpage)

Unconditionally set the end page.

$obj = $obj->set_document_title_section ($document_title_section)

Unconditionally set the document_title_section string.

$obj = $obj->set_startpage ($startpage)

Unconditionally set the start page.

$obj = $obj->set_page_title_section ($page_title_section)

Unconditionally set the page_title_section.

($volume, $basepath, $directory, $startdate, $enddate, $document_title_section, $startpage, $endpage, $page_title_section, @extensions) = $obj->splitpath ($filepath)

Parses the filename into:

{firstdate{-lastdate}}{-title}{-startpage{-endpage}}{-subtitle}{.extensions}

and returns all the elements of the pathname and filename as a list. Completely reinitializes the object for the name $filepath.

$startpage = $obj->startpage

Return the starting pageid object.

$name_body = $obj->reset_name_body

Rebuild the name_body ivar from parts:

document_title_section + startpage + endpage + page_title_section -> name_body

Private Class Methods

None.

Private Instance Methods

$obj = $obj->_init

Internal initializer.

This method is for the subclass initializer chaining and should not be used otherwise.

KNOWN BUGS

See TODO.

SEE ALSO

Fault::DebugPrinter, DMA::FSM, Document::PageId, File::Spec::Dated

AUTHOR

Dale Amon <amon@vnl.com>

cpanm Document::Toc

perl -MCPAN -e shell
install Document::Toc