Path::Class::Versioned - A simple module for managing versioned file names
use Path::Class::Versioned; # typical usage for files ... my $v = Path::Class::Versioned->new( name_pattern => [ 'MyBackups-v', undef, '.zip' ], parent => [ $FindBin::Bin, 'backups' ] # coerced into Path::Class::Dir ); # create the next filename in the # sequence as specified by the # name pattern above. my $next_file_name = $v->next_name; # defaults to files ... # create an instance of Path::Class::File # that represents that next file name my $file = $v->next_file; # typical usage for directories ... my $v = Path::Class::Versioned->new( name_pattern => [ 'MyBackupDirectory-v', undef ], parent => Path::Class::Dir->new() # will use current dir ); # just like the file example, but # tell it to match against directories # instead of files my $next_dir_name = $v->next_name(dir => 1); # create an instance of Path::Class::Dir # that represents that next directory name my $subdir = $v->next_dir;
C'mon, you know you have done this too, so why bother writing it over and over again, just use this module.
This module aims to provide a simple, yet sophisticated way of creating and managing versioned files by name. It is a poor substitute for using a real VCS (version control system) or some more sophisticated versioning module that utilizes diffs, etc. However, there are some times when you just don't need that level of control, and just need to back stuff up in a simple way, so here it is.
These attributes should be set through the constructor, all are required except for the
version_format which will default to just printing the number.
This is expected to be an ArrayRef made up of strings, stringify-able objects and exactly one
undefvalue will serve as the placeholder for the version number. Here are some example formats and the names they create.
For a simple sequentially named file set, with no extra version formatting you might do something like this:
[ 'Foo-v', undef, '.txt' ] # Foo-v1.txt, Foo-v2.txt, etc ...
For a simple date-stamped directory set with a version_format of
%02dyou might do something like this:
[ 'Baz-', $datetime, '-v', undef ] # Baz-2008-05-12-v01/, Baz-2008-05-12-v02/
It is assumed that your
$datetimeinstance already has the formatter set to produce the specified string. Something like this has the benefit of making it very simple to create dated files/directories, but not have to worry about overwriting something in the same day.
This is a format string which will be passed to
sprintfin order to format the version number. It defaults to just returning the number itself.
This is a Path::Class::Dir object representing the parent directory, it is the contents of this directory which will be inspected to determine the next name to be created.
Alternately you can specify an ArrayRef of strings, or a string itself and those will be coerced into a Path::Class::Dir object. We use the type created by the MooseX::Types::Path::Class module, please refer that for more details.
- next_name (dir = Bool, file => Bool)>
Returns the next file name (if the
fileboolean argument is true) or the next directory name (if the
dirboolean argument is true). It defaults to the a file name.
Returns a Path::Class::File object for the value of
Returns a Path::Class::Dir object for the value of
All complex software has bugs lurking in it, and this module is no exception. If you find a bug please either email me, or add the bug to cpan-RT.
NO ONE IS INNOCENT! Here are the names of those who are especially guilty.
- Thanks to perigrin for holding back the snide comments when I suggested this module.
- Thanks to rjbs for the module name (although he may deny any involvment).
Stevan Little <firstname.lastname@example.org>
COPYRIGHT AND LICENSE
Copyright 2008-2010 Infinity Interactive, Inc.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.