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