NAME

File::VMSVersions - Perl extension for opening files in a directory with VMS like versioning

SYNOPSIS

  use File::VMSVersions;

  my $vdir = File::VMSVersions->new(
     -name  => "./mydir",
     -mode  => 'versions',
     -limit => 3,
  );

  foreach my $i (1..6) {
     my($fh, $fn) = $vdir->open('bla.dat', '>');
     die $fn unless $fh;
     print $fh "file number $i\n";
     print "created $fn\n";
     $fh->close;
  }

Now you should have the following files in ./mydir:

  .vcntl
  bla.dat;lck
  bla.dat;4
  bla.dat;5
  bla.dat;6

DESCRIPTION

The File::VMSVersions module was developed for maintaining automatic versioning of files in a directory. When you are using the module's routines for opening files, it will keep a configurable amount of old versions. The versions will be identified by a number that is added at the end of the filename after a semicolon (i. e. 'myfile.dat;7').

The configured options for a directory are saved in the file '.vcntl'. They are read each time the open method is called and written when the new constructor or the config method are called with according options.

'.vcntl' consists of only one line with limit and mode separated by an '#'. For example:

  20#days

  10#versions

It is ok to edit '.vcntl' manually

CONSTRUCTOR

To create a new File::VMSVersions call the new contructor

   $obj = File::VMSVersions->new(
        -name  => <directory name>,
      [ -mode  => <'versions'|'days'>,
        -limit => <version limit>, ]
   );

You have to specify both -limit and -mode or none of them. If both evaluate to false the file .vcntl is read. Otherwise it will be replaced with the new values. If the file doesn't exist when the configuration is read, there is no version limit at all.

METHODS

$obj->open(<filename> [, <mode:'<|>|>>']> [, <version>])

Opens a version of a file. The default mode is '<' (read).

If version is not specified when reading, the last version will be opened.

If mode equals '>' (write) or '>>' (append), the specified version of the desired file will be created or appended (append will create a new file if the version doesn't exist).

If there is no version specified, the highest existing version will be incremented by 1.

If the specified version is negative the nth last version will be opened.

open returns a list with an indirect filehandle and the filename. On errors the filehandle is undefined and the filename contains an error message.

$obj->purge(<filename>, [-mode => <mode>, -limit => <limit>]

purges the versions of a file to the specified limit. When limit and mode are not specified all but the last versions are purged. There is no need to call purge for normal versioning.

$obj->config([-mode => <mode>, -limit => <limit>])

Sets and/or returns limit and mode of the directory

$obj->info(<filename>)

returns a hashref with version information for <filename>

AUTHOR

Thomas Kratz, <ThomasKratz@web.de>

COPYRIGHT AND LICENSE

Copyright 2003 by Thomas Kratz

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.