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