NAME

 File::Spec::Dated - Object to parse dated archive filenames.

SYNOPSIS

 use File::Spec::Dated;

 ($volume, $basepath, $directory, $startdate, $enddate, $name_body, @extensions) = $self->splitpath ($filepath);

 $startdate = $self->startdate;
 $enddate   = $self->enddate;
 $dates     = $self->dates;
 $undated   = $self->undated_filename;
 $name_body = $self->name_body;
 $self      = $self->set_startdate ($startdate);
 $self      = $self->set_enddate ($enddate);
 $self      = $self->set_name_body ($name_body);
 $name      = $self->reset_name;

Inheritance

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

Description

Split a filename path into segments used by virtually all archiver applications. This includes the segmentation done by the File::Spec:Archivist plus a further breakdown of the filename part it returns.

For example, if the filename were 19901225-XMAS-Title-Subtitle-note.tar.gz would be further split as:

 startdate:         19991225
 enddate:           undef
 name_body:         XMAS-Title-Subtitle-note
 extensions:        (tar gz)
 extension:         gz

Extensions are re-parsed here with more constraints on what is considered an extension. It must not only be dot delimited, but also be left of the last - i the filename. Eve so, there is still an ambiguity problem to be dealt with here and in child classes. We cannot always be certain that an extension really is an extension. For example, if the filename were DATE-XYZ.ABC, it could be parsed in a number of ways:

          name_body:         XYZ
          extension:         ABC

or name_body: XYZ.ABC

The later may seem unlikely, but here are examples showing that it isn't:

 19991225-XMAS-CardGenerator-V1.1
 19991225-XMAS-ACarol-p100.1a

Examples

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

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

 my $startdate  = $foo->startdate;
 my $enddate    = $foo->enddate;
 my $dates      = $foo->dates;
 my $undated    = $obj->undated_filename;
 my $name_body  = $foo->name_body;
 my @extensions = $foo->extensions;
 my $extensions = $foo->extensions;
 my $extension  = $foo->extension;

 $foo->set_startdate  ("19901225120000");
 $foo->set_enddate    ("20001225120000");
 $foo->set_name_body  ("XMAS-Title-Subtitle-note");
 $foo->set_extensions ("jpeg" );
 my $name       = $foo->reset_name;
 my $filename   = $foo->reset_filename;
 my $filepath   = $foo->reset_pathname;
 my @parts      = $foo->reparse;

 $foo->set_extensions ("tar","gz");
 $filename      = $foo->reset_filename;
 $filepath      = $foo->reset_pathname;
 @parts         = $foo->reparse;

Class Variables

 None.

Instance Variables

 startdate         The starting date string.
 enddate           The ending date string.
 name_body         The "body" portion of the filename.
 extensions        A list, left to right, of all file extensions found.
 extension         Last or rightmost of the file extensions found.

Class Methods

 None.

Instance Methods

$dates = $obj->dates

Return a $dates string suitable for use in an index or table of contents, eg "19991225", "19991225103015", "19991225-20000101" or "19991225103000-19991225113000".

Returns undef if there is no date information associated with this filespec.

$enddate = $obj->enddate

Return the end date string or undef if none.

$name_body = $obj->name_body

Return the name_body or undef if none.

$name = $obj->reset_name

Regenerate name from parts:

        startdate + enddate + name_body -> name

$obj = $obj->set_enddate ($enddate)

Unconditionally set the end date of the filename.

$obj = $obj->set_name_body ($name_body)

Unconditionally set the name_body of the filename.

$obj = $obj->set_startdate ($startdate)

Unconditionally set the start date of the filename.

($volume, $basepath, $directory, $startdate, $enddate, $name_body, @extensions) = $obj->splitpath ($filepath)

Parses the filename into:

        firstdate{-lastdate}{-name_body}{.extensions}

and returns all the elements of the pathname and filename as a list. Completely reinitializes the object for the name $filepath. Chains to parent class method.

$startdate = $obj->startdate

Return the start date string or undef if none.

$undated = $obj->undated_filename

If a filename has dates on the left, return the remainder; if there is no date part do nothing.

For example, whether the original filename is 20040817-filename.tar.gz or just filename.tar.gz it will return filename.tar.gz. This is useful in applications which deal with both Archivist and non-Archivist filenames and which may need to shift a file back and forth between the two universes.

Private Class Methods

 None.

Private Instance Methods

$obj = $obj->_init

Internal initializer. Chains to parent class method.

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

KNOWN BUGS

 See TODO.

SEE ALSO

Fault::ErrorHandler, Fault::DebugPrinter, DMA::ISODate, DMA::FSM, File::Spec::BaseParse

AUTHOR

Dale Amon <amon@vnl.com>

cpanm Document::Toc

perl -MCPAN -e shell
install Document::Toc