NAME

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

SYNOPSIS

 use File::Spec::PublicationPage;

 ($volume, $basepath, $directory, 
  $startdate, $enddate, $publication, 
  $publication_title_head, $publication_subtitles, $publication_annotations,
  $startpage, $endpage, 
  $page_title_head, $page_subtitles, $page_annotations, 
  @extensions)               = $obj->splitpath ($filepath);

 $publication_title_section  = $obj->publication_title_section;
 $publication                = $obj->publication;
 $publication_title_head     = $obj->publication_title_head;
 $publication_subtitles      = $obj->publication_subtitles;
 $publication_annotations    = $obj->publication_annotations;
 $page_title_head            = $obj->page_title_head;
 $page_subtitles             = $obj->page_subtitles;
 $page_annotations           = $obj->page_annotations;
 $page_title_section         = $obj->fulltitle;
 $pagename                   = $obj->pagename;
 $issuename                  = $obj->issuename;

 $obj = $obj->set_publication             ($publication);
 $obj = $obj->set_publication_title_head  ($publication_title_head);
 $obj = $obj->set_publication_subtitles   ($publication_subtitles);
 $obj = $obj->set_publication_annotations ($publication_annotations);
 $obj = $obj->set_page_title_head         ($page_title_head);
 $obj = $obj->set_page_subtitles          ($page_subtitles);
 $obj = $obj->set_page_annotations        ($page_annotations);

 $publication_title_sections = $obj->reset_document_title_section;
 $page_title_sections        = $obj->reset_page_title_section;

Inheritance

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

Description

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

 publication:               XMAS
 publication_title_head:    Title
 publication_subtitles:     Subtitle
 publication_annotations:   note
 page_title_head:           undef
 page_subtitles:            undef
 page_annotations:          undef

Ordering is used in this parsing. The first "-" delimited element in the name_body is the publication name; the second is the main title of the article; the third and remaining items are subtitles of the article unless the first character is lower case, in which case it is taken to be a local annotation.

Such annotations are useful for adding key words to the file name so that Unix locate and find will be more useful. One might have added "-iranStudentRebellion" if the publication or page title did not mention Iran and one wished to be able to locate all files with information about Iran.

Examples

 use File::Spec::PublicationPage;

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

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

 my $startpage   = $foo->startpage;
 my $endpage     = $foo->endpage;
 my $pages       = $foo->pages;
 my $pagename    = $foo->pagename;
 my $publication = $foo->publication;
 my $pubsection  = $foo->publication_title_section;
 my $dtitle_head = $foo->publication_title_head;
 my $dsubtitle   = $foo->publication_subtitles;
 my $dnotes      = $foo->publication_annotations;
 my $pgsection   = $foo->fulltitle;
 my $ptitle_head = $foo->page_title_head;
 my $psubtitle   = $foo->page_subtitles;
 my $pnotes      = $foo->page_annotations;

 $foo->set_publication             ("JournalOfIrreproduceableResults");
 $foo->set_publication_title_head  ("QuantumBubbling" );
 $foo->set_publication_subtitles   ("ThePintEffect");
 $foo->set_publication_annotations ("allTheTimeInTheworldInAGuinness");

 $foo->set_page_title_head         ("TheCat );
 $foo->set_page_subtitles          ("DeadOrAlive");
 $foo->set_page_annotations        ("whatWillPetaSay");

 my $docsection  = $foo->reset_document_title_section;
 my $pgsection   = $foo->reset_page_title_section;
 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

 publication               Name of the publication
 publication_title_head    The primary title of the whole document.
 publication_subtitles     Subtitles of the whole document.
 publication_annotations   Annotations on the whole document.
 page_title_head           The primary title of the page.
 page_subtitles            Subtitles of the page.
 page_annotations          Annotations on the page.

Class Methods

 None.

Instance Methods

$page_title_section = $obj->fulltitle

Return a $page_full_title string , eg "MainTitle", "MainTitle-SubtitleOne-SubtitleTwo". "MainTitle-OnlySubtitle-firstNote" or perhaps "MainTitle-firstNote-secondNote".

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

$issuename = $obj->issuename

Return a $issuename string , eg "20021225-NewScientist".

undef if there the date string or publication name is unavailable. Both are required.

$page_annotations = $obj->page_annotations

Return the page annotations string.

$page_subtitles = $obj->page_subtitles

Return the page subtitles string.

$page_title_head = $obj->page_title_head

Return the page main title string.

$pagename = $obj->pagename

Return the page name string, eg "20021225-NewScientist-p010" or undef if the date string, publication name or pageid string is unavailable. All are required.

$publication = $obj->publication

Return the publication name string.

$publication_annotations = $obj->publication_annotations

Return the publication annotations string.

$publication_subtitles = $obj->publication_subtitles

Return the publication subtitles string.

$publication_title_head = $obj->publication_title_head

Return the publication main title string.

$publication_title_section = $obj->publication_title_section

Return the publication_title_section string:

    "publication-title-head publication-subtitles publications-annotations"

or whatever portion is available. Return undef if there is none.

$publication_title_sections = $obj->reset_document_title_section

Regenerate the document_title_section from pieces:

     publication + publication_title_head + publication_subtitles + 
     publication_annotations -> document_title_section

$page_title_sections = $obj->reset_page_title_section

Regenerate the page_title_section from pieces:

  page_title_head + page_subtitles + page_annotations -> page_title_section

$obj = $obj->set_publication ($publication)

Unconditionally set the publication name.

$obj = $obj->set_publication_annotations ($publication_annotations)

Unconditionally set the publication annotations.

$obj = $obj->set_publication_subtitles ($publication_subtitles)

Unconditionally set the publication subtitles.

$obj = $obj->set_publication_title_head ($publication_title_head)

Unconditionally set the publication_title_head.

$obj = $obj->set_page_annotations ($page_annotations)

Unconditionally set the page annotations.

$obj = $obj->set_page_subtitles ($page_subtitles)

Unconditionally set the page subtitles.

$obj = $obj->set_page_title_head ($page_title_head)

Unconditionally set the page_title_head.

($volume, $basepath, $directory, $startdate, $enddate, $publication, $publication_title_head, $publication_subtitles, $publication_annotations, $startpage, $endpage, $page_title_head, $page_subtitles, $page_annotations, @extensions) = $obj->splitpath ($filepath)

Override and chain the parent method. Parses the filename into:

  {firstdate{-lastdate}}{-publication
  {-publication_title_head}{-publication_subtitles}{-publication_annotations}}
  {-startpage{-endpage}}
  {-page_title_head}{-page_subtitles}{-page_annotations}}{.extensions}

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

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

DMA::FSM, Fault::DebugPrinter, File::Spec::DatedPage

AUTHOR

Dale Amon <amon@vnl.com>

cpanm Document::Toc

perl -MCPAN -e shell
install Document::Toc