File::Version.pm - Simple File Versioning Class
use File::Version;
my %args = ( FILE => 'foo.txt', SEARCH_PATHS => ['/projects'], RECURSION_DEPTH => 10, FOLLOW_SYMBOLIC => 0 );
my $foo = File::Version->new(%args);
$foo->locate_ancestors; # recursively search /project 10 directories deep for all 'foo.txt' ancestors
$foo->locate_descendants; # recursively search /project 10 directories deep for all 'foo.txt' descendants
$foo->next_version; # next version of 'foo.txt'
$foo->search_paths( SEARCH_PATHS => [ '/home' ] ); # now search all home directories
$foo->recursion_depth( RECURSION_DEPTH => 5 ); # now seach only 5 directories deep
$foo->follow_symbolic( FOLLOW_SYMBOLIC => 1 ); # follow symbolic links (not recommended)
This module is useful for creating and locating different versions of a file. For example, let's say you're working with a first generation file named foo.txt. Before proceeding, we gather some information about the foo.txt family tree:
my %args = ( FILE => '/path/foo.txt', SEARCH_PATHS => ['/home'], RECURSION_DEPTH => 10, FOLLOW_SYMBOLIC => 0 );
$foo->locate_descendants might return the following reference :
$ref = { '1' => { '/home/bill/1__foo.txt' => '1', '/home/mary/foobar/test/2__foo.txt' => '2' }, '2' => { '/home/bill/2_1__foo.txt' => '1', '/home/john/project/2_2__foo.txt' => '2', '/home/fred/mystuff/1_1__foo.txt' => '1' }, '3' => { '/home/jill/2_2_1__foo.txt' => '1' } };
meaning that foo.txt has :
2 children, 3 grandchildren, 1 great grandchild
$foo->locate_ancestors has the opposite effect, returning undef in this case because foo.txt is an original file.
$foo->next_version returns '3__foo.txt', meaning the third child of foo.txt. A file named '3_1__foo.txt' would mean the first child of foo.txt's third child.
Use the Algorithm::Diff module to compare different versions.
The cp_version.pl script (provided with this module) takes filenames as arguments from the command line and spits out the next version of each file. Alias this script for your convenience.
This module was written and tested using Perl 5.6.0 under Linux. If you want this module to work with Windows, at minimum you'll need to change the directory separator to a backslash. Comments and suggestions welcome.
Nathaniel J. Graham <broom@pincer.org>
Copyright 2003, Nathaniel J. Graham. All Rights Reserved. This program is free software. You may copy or redistribute it under the same terms as Perl itself.
2 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head1'
To install File::Version, copy and paste the appropriate command in to your terminal.
cpanm
cpanm File::Version
CPAN shell
perl -MCPAN -e shell install File::Version
For more information on module installation, please visit the detailed CPAN module installation guide.