NAME
VcsTools::File - Perl class to manage a VCS file.
SYNOPSIS
my %dbhash; # may be tied to a MLDBM
use VcsTools::LogParser ;
use VcsTools::DataSpec::HpTnd qw($description readHook);
use Puppet::Storage ;
use VcsTools::HmsAgent ; # could be also RcsAgent
my $ds = new VcsTools::DataSpec::HpTnd ;
my $ds = new VcsTools::LogParser
(
description => $description,
readHook => \&readHook
) ;
Puppet::Storage->dbHash(\%dbhash);
Puppet::Storage->keyRoot('root');
my $storage= new Puppet::Storage(name => 'dummy.txt') ;
VcsTools::HmsAgent->hmsBase('test');
VcsTools::HmsAgent->hmsHost('a_host');
my $agent = VcsTools::HmsAgent->new
(
name => 'dummy.txt',
workDir => cwd().'/'.$dir
);
my $vf = new VcsTools::File
(
storage => $storage ,
vcsAgent => $agent,
name => 'dummy.txt',
workDir => $some_dir,
dataScanner => $ds
);
$vf -> createArchive();
$vf -> checkOut(revision => '1.1', lock => 1) ;
$vf -> archiveFile(info =>{log => 'dummy log for 1.2'});
$vf -> showDiff(rev1 => '1.1', rev2 => '1.2');
$vf -> setUpMerge(ancestor => '1.1', below => '1.2', other => '1.1.1.1');DESCRIPTION
This class represents a VCS file. It holds all the interfaces to the "real" world and the history object (See VcsTools::History)).
Firthermore, this class will store the file and archive properties (like s the file readable, does the archive exists, is it locked...) in a Storable file (within a .store directory)
CAVEATS
The file must contain the $Revision: 1.5 $ VCS keyword.
The VCS agent (hmsAgent) creation is clumsy. I should use translucent attributes or stuff like that like Tom Christiansen described. In other words, let the user create its agent object and clone it for File usage. This part is subject to change sooner of later. Only the constructors should be impacted.
CONVENTION
The following words may be non ambiguous for native english speakers, but it is not so with us french people. So I prefer clarify these words:
Log: Refers to the information stored with one version.
History: Refers to a collection of all logs of all versions stored in the VCS base.
Constructor
new(...)
Will create a new File object.
Parameters are those of "new(...)" in Puppet::Body plus :
dataScanner : VcsTools::LogParser (or equivalent) object reference.
workDir : Absolute directory where the file is.
vcsAgent : VCS interface object (e.g. VcsTools::HmsAgent).
Generic methods
check()
See ""check()" in VcsTools::Source
History handling methods
createHistory()
Will returns the VcsTools::History object for this file and create it if necessary.
updateHistory()
Extract the history information from the VCS base and update the VcsTools::History objbect (by calling "update(...)" in VcsTools::History).
This function must be called to re-synchronize your application if the VCS base was changed by someone else.
Handling the real file
createLocalAgent()
Create the file Agent class.
getTimeStamp()
Returns the last modification time of the file. (See stat function in perlfunc)
edit()
Will launch a window editor though the file agent ("edit()" in VcsTools::FileAgent)
getRevision()
See ""getRevision()" in VcsTools::Source
checkWritable()
Will return 1 if the file is writable, 0 if not. Will return undef in case of problems.
checkExist()
Will return 1 if the file exists, 0 if not. Will return undef in case of problems.
chmodFile(...)
Will change the file mode to writable or not.
Parameters are :
writable: 1 or 0
Returns 1 if chmod was done and undef in case of problems.
writeFile(...)
Write the passed content into the actual VCS file..
Parameters are :
content: String or hash ref (See "writeFile(...)" in VcsTools::FileAgent) that will be written.
Returns 1 if the file was written and undef in case of problems.
writeRevContent(...)
Write the content of a specific version of the VCS file in the passed file name. This method is handy when you want to compare several revisions of a VCS file with a tool which does not support directly your VCS system.
For instance to compare 2 versions of foo.c you may call:
# creates a v1.2_foo.c file
$foo->writeRevContent(revision => 1.2);
# creates a v1.3_foo.c file
$foo->writeRevContent(revision => 1.3);Then you may call xdiff on v1.2_foo.c and v1.3_foo.c.
Parameters are :
revision: writeFile will retrieve this revision of the VCS file and write it to the passed file name.
fileName: file name to write to (default to "v<rev>_<VCS_file_name>", e.g. v1.13_bar.c for version 1.13 of the bar.c VCS file)
Returns the name of the written file if the file was actually written and undef in case of problems.
remove()
Unlink the VCS file.
Handling the VCS part
Before invoking any VCS functions, the File object will check whether the function can be performed. (For instance, it will not try to perform a check out if the local file is writable.)
createVcsAgent()
Create the VCS interface class.
checkArchive()
Calls checkArchive of the VCS interface class. (E.g. "checkArchive()" in VcsTools::HmsAgent) with the working revision as the revision parameter..
changeLock(...)
Delegated to the VCS interface class. E.g. "changeLock(...)" in VcsTools::HmsAgent
checkOut(...)
Delegated to the VCS interface class. E.g. "checkOut(...)" in VcsTools::HmsAgent
getContent(...)
Delegated to the VCS interface class. E.g. "getContent(...)" in VcsTools::HmsAgent
archiveLog(...)
See "archiveLog()" in VcsTools::Source
getHistory()
Delegated to the VCS interface class. E.g. "getHistory()" in VcsTools::HmsAgent
showDiff(...)
Delegated to the VCS interface class. E.g. "showDiff(...)" in VcsTools::HmsAgent
archiveFile(...)
Will archive the current file.
Parameters are:
revision: revision number for this new version of the file. Defaults to a number computed by "guessNewRev(revision)" in VcsTools::History,
info: Hash ref holding relevant informations for this new archive. (See VcsTools::LogParser for the hash content). Defaults to a hash containing 'auto archive' as log information, the current date and the name of the user performing the archive.
Note that before performing the archive, the program will check the timestamp of the archive base and will upload its history informations if the archive has been changed since the last upload. This way the archive number decided by the history object will always be correct.
TO DO
A merge() method which will find the common ancestor of the passed revisions, perform a merge using merge(1) and write the result in the local file.
A patch() method which will report the modif made from one revision to an other revision on a branch. This can be handy to report a bug fix on a branch under change control.
AUTHOR
Dominique Dumont, Dominique_Dumont@grenoble.hp.com
Copyright (c) 1998-1999 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
perl(1), Tk(3), Puppet::Any(3), VcsTools::DataSpec::HpTnd(3), VcsTools::Version(3), VcsTools::File(3)