NAME¶
Rcs - Perl Object Class for Revision Control System (RCS).
SYNOPSIS¶
use Rcs;
# Use tags to control how the rcs programs handle errors
# and the use of the rcs -q (quiet) flag.
use Rcs qw(nonFatal Verbose);
The default behavior is to run rcs programs with the -q (quiet) flag, and to die
if any rcs program returns an error.
DESCRIPTION¶
This Perl module provides an object oriented interface to access
Revision
Control System (RCS) utilities. RCS must be installed on the system prior
to using this module. This module should simplify the creation of an RCS
front-end.
OBJECT CONSTRUCTOR
The
new method may be used as either a class method or an object method
to create a new object.
# called as class method
$obj = Rcs->new;
# called as object method
$newobj = $obj->new;
Note: You may now set the pathname of the working file through the object
constructor. This is the same as calling the pathname method after calling the
new method.
Thus
$obj = Rcs->new($pathname);
is the same as
$obj = Rcs->new;
$obj->pathname($pathname);
See
pathname method for additional details.
CLASS METHODS
Besides the object constructor, there are three class methods provided which
effect any newly created objects.
The
arcext method sets the RCS archive extension, which is ',v' by
default.
# set/unset RCS archive extension
Rcs->arcext(''); # set no archive extension
Rcs->arcext(',v'); # set archive extension to ',v'
$arc_ext = Rcs->arcext(); # get current archive extension
The
bindir method sets the directory path where the RCS executables (i.e.
rcs, ci, co) are located. The default location is '/usr/local/bin'.
# set RCS bin directory
Rcs->bindir('/usr/bin');
# access RCS bin directory
$bin_dir = Rcs->bindir;
The
quiet method sets/unsets the quiet mode for the RCS executables.
Quiet mode is set by default.
# set/unset RCS quiet mode
Rcs->quiet(0); # unset quiet mode
Rcs->quiet(1); # set quiet mode
# access RCS quiet mode
$quiet_mode = Rcs->quiet;
These methods may also be called as object methods.
$obj->arcext('');
$obj->bindir('/usr/bin');
$obj->quiet(0);
OBJECT ATTRIBUTE METHODS
These methods set the attributes of the RCS object.
The
file method is used to set the name of the RCS working file. The
filename must be set before invoking any access of modifier methods on the
object.
$obj->file('mr_anderson.pl');
The
arcfile method is used to set the name of the RCS archive file. Using
this method is optional, as the other methods will assume the archive filename
is the same as the working file unless specified otherwise. The RCS archive
extension (default ',v') is automatically added to the filename.
$obj->arcfile('principle_mcvicker.pl');
The
workdir methods set the path of the RCS working directory. If not
specified, default path is '.' (current working directory).
$obj->workdir('/usr/local/source');
The
rcsdir methods set the path of the RCS archive directory. If not
specified, default path is './RCS'.
$obj->rcsdir('/usr/local/archive');
The
pathname method will set both the working filename and archive
directory.
$obj->pathname($RCS_DIR . '/' . 'butthead.c');
and
$obj->pathname($RCS_DIR . '/' . 'butthead.c,v');
are the same as
$obj->rcsdir($RCS_DIR);
$obj->file('butthead.c');
RCS PARSE METHODS
This class provides methods to directly parse the RCS archive file.
The
access method returns a list of all user on the access list.
@access_list = $obj->access;
The
author method returns the author of the revision. The head revision
is used if no revision argument is passed to method.
# returns the author of revision '1.3'
$author = $obj->author('1.3');
# returns the authos of the head revision
$author = $obj->author;
The
head method returns the head revision.
$head = $obj->head;
The
lock method returns the locker of the revision. The method returns
null if the revision is unlocked. The head revision is used if no revision
argument is passed to method. When called in list context the lock method
returns a hash of all locks.
# returns locker of revision '1.3'
$locker = $obj->lock('1.3');
# returns locker of head revision
$locker = $obj->lock;
# return hash of all locks
%locks = $obj->lock; # called in list context
foreach $rev (keys %locks) {
$locker = $locks{$rev};
print "User $locker has revision $rev locked\n";
}
The
revisions method returns a list of all revisions of archive file.
@revisions = $obj->revisions;
The
state method returns the state of the revision. The head revision is
used if no revision argument is passed to method.
# returns state of revision '1.3'
$state = $obj->state('1.3');
# returns state of head revision
$state = $obj->state;
The
symbol method returns the symbol(s) associated with a revision. If
called in list context, method returns all symbols associated with revision.
If called in scalar context, method returns last symbol assciated with a
revision. The head revision is used if no revision argument is passed to
method.
# list context, returns all symbols associated with revision 1.3
@symbols = $obj->symbol('1.3');
# list context, returns all symbols associated with head revision
@symbols = $obj->symbol;
# scalar context, returns last symbol associated with revision 1.3
$symbol = $obj->symbol('1.3');
# scalar context, returns last symbol associated with head revision
$symbol = $obj->symbol;
The
symbols method returns a hash, keyed by symbol, of all of the
revisions associated with the file.
%symbols = $obj->symbols;
foreach $sym (keys %symbols) {
$rev = $symbols{$sym};
}
The
revdate method returns the date of a revision. The returned date
format is the same as the localtime format. When called as a scalar, it
returns the system date number. If called is list context, the list
($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) is returned.
# scalar mode
$scalar_date = $obj->revdate;
print "Scalar date number = $scalar_date\n";
$date_str = localtime($scalar_date);
print "Scalar date string = $date_str\n";
# list mode
@list_date = $obj->revdate;
print "List date = @list_date\n";
The
dates method returns a hash of revision dates, keyed on revision. The
hash values are system date numbers. When called in scalar mode, the method
returns the most recent revision date.
# list mode
%DatesHash = obj->dates;
@dates_list = sort {$b<=>$a} values %DatesHash;
$MostRecent = $dates_list[0];
# scalar mode
$most_recent = $obj->dates;
print "Most recent date = $most_recent\n";
$most_recent_str = localtime($most_recent);
print "Most recent date string = $most_recent_str\n";
The
symrev method returns the revision against which a specified symbol
was defined. If the symbol was not defined against any version of this file, 0
is returned.
# gets revision that has 'MY_SYMBOL' defined against it
$rev = $obj->symrev('MY_SYMBOL');
The
daterev method returns revisions which were created before a
specified date. Method may take one or six arguments. If one arguments is
passed, then the argument is a date number. If six arguments are passed, then
they represent a date string.
# one argument, date number
# gets revisions created before Sun Sep 6 22:23:47 1998
@revs = $obj->daterev(841436420);
# six argument
# gets revisions created before 25th June 1998 16:45:30
@revs = $obj->daterev(1998, 6, 25, 16, 45, 30);
The
comments method returns a hash of revision comments, keyed on
revision. A key value of 0 returns the description.
%comments = $obj->comments;
$description = $comments{0};
$comment_1_3 = $comments{'1.3'};
RCS SYSTEM METHODS
These methods invoke the RCS system utilities.
The
ci method calls the RCS ci program.
# check in, and then check out in unlocked state
$obj->ci('-u');
The
co method calls the RCS co program.
# check out in locked state
$obj->co('-l');
The
rcs method calls the RCS rcs program.
# lock file
$obj->rcs('-l');
The
rcsdiff method calls the RCS rcsdiff program. When called in list
context, this method returns the outpout of the rcsdiff program. When called
in scalar context, this method returns the return status of the rcsdiff
program. The return status is 0 for the same, 1 for some differences, and 2
for error condition.
When called without parameters, rcsdiff does a diff between the current working
file, and the last revision checked in.
# call in list context
@diff_output = $obj->rcsdiff;
# call in scalar context
$changed = $obj->rcsdiff;
if ($changed) {
print "Working file has changed\n";
}
Call rcsdiff with parameters to do a diff between any two revisions.
@diff_output = $obj->rcsdiff('-r1.2', '-r1.1');
The
rlog method calls the RCS rlog program. This method returns the
output of the rlog program.
# get complete log output
@rlog_complete = $obj->rlog;
# called with '-h' switch outputs only header information
@rlog_header = $obj->rlog('-h');
print @rlog_header;
The
rcsclean method calls the RCS rcsclean program.
# remove working file
$obj->rcsclean;
EXAMPLES¶
CREATE ACCESS LIST
Using method
rcs with the
-a switch allows you to add users to the
access list of an RCS archive file.
use Rcs;
$obj = Rcs->new;
$obj->rcsdir("./project_tree/archive");
$obj->workdir("./project_tree/src");
$obj->file("cornholio.pl");
Methos
rcs invokes the RCS utility rcs with the same parameters.
@users = qw(beavis butthead);
$obj->rcs("-a@users");
Calling method
access returns list of users on access list.
$filename = $obj->file;
@access_list = $obj->access;
print "Users @access_list are on the access list of $filename\n";
PARSE RCS ARCHIVE FILE
Set class variables and create 'RCS' object. Set bin directory where RCS
programs (e.g. rcs, ci, co) reside. The default is '/usr/local/bin'. This sets
the bin directory for all objects.
use Rcs;
Rcs->bindir('/usr/bin');
$obj = Rcs->new;
Set information regarding RCS object. This information includes name of the
working file, directory of working file ('.' by default), and RCS archive
directory ('./RCS' by default).
$obj->rcsdir("./project_tree/archive");
$obj->workdir("./project_tree/src");
$obj->file("cornholio.pl");
$head_rev = $obj->head;
$locker = $obj->lock;
$author = $obj->author;
@access = $obj->access;
@revisions = $obj->revisions;
$filename = $obj->file;
if ($locker) {
print "Head revision $head_rev is locked by $locker\n";
}
else {
print "Head revision $head_rev is unlocked\n";
}
if (@access) {
print "\nThe following users are on the access list of file $filename\n";
map { print "User: $_\n"} @access;
}
print "\nList of all revisions of $filename\n";
foreach $rev (@revisions) {
print "Revision: $rev\n";
}
CHECK-IN FILE
Set class variables and create 'RCS' object. Set bin directory where RCS
programs (e.g. rcs, ci, co) reside. The default is '/usr/local/bin'. This sets
the bin directory for all objects.
use Rcs;
Rcs->bindir('/usr/bin');
Rcs->quiet(0); # turn off quiet mode
$obj = Rcs->new;
Set information regarding RCS object. This information includes name of working
file, directory of working file ('.' by default), and RCS archive directory
('./RCS' by default).
$obj->file('cornholio.pl');
# Set RCS archive directory, is './RCS' by default
$obj->rcsdir("./project_tree/archive");
# Set working directory, is '.' by default
$obj->workdir("./project_tree/src");
Check in file using
-u switch. This will check in the file, and will then
check out the file in an unlocked state. The
-m switch is used to set
the revision comment.
Command:
$obj->ci('-u', '-mRevision Comment');
is equivalent to commands:
$obj->ci('-mRevision Comment');
$obj->co;
CHECK-OUT FILE
Set class variables and create 'RCS' object. Set bin directory where RCS
programs (e.g. rcs, ci, co) reside. The default is '/usr/local/bin'. This sets
the bin directory for all objects.
use Rcs;
Rcs->bindir('/usr/bin');
Rcs->quiet(0); # turn off quiet mode
$obj = Rcs->new;
Set information regarding RCS object. This information includes name of working
file, directory of working file ('.' by default), and RCS archive directory
('./RCS' by default).
$obj->file('cornholio.pl');
# Set RCS archive directory, is './RCS' by default
$obj->rcsdir("./project_tree/archive");
# Set working directory, is '.' by default
$obj->workdir("./project_tree/src");
Check out file read-only:
$obj->co;
or check out and lock file:
$obj->co('-l');
RCSDIFF
Method
rcsdiff does an diff between revisions.
$obj = Rcs->new;
$obj->bindir('/usr/bin');
$obj->rcsdir("./project_tree/archive");
$obj->workdir("./project_tree/src");
$obj->file("cornholio.pl");
print "Diff of current working file\n";
if ($obj->rcsdiff) { # scalar context
print $obj->rcsdiff; # list context
}
else {
print "Versions are Equal\n";
}
print "\n\nDiff of revisions 1.2 and 1.1\n";
print $obj->rcsdiff('-r1.2', '-r1.1');
RCSCLEAN
Method
rcsclean will remove an unlocked working file.
use Rcs;
Rcs->bindir('/usr/bin');
Rcs->quiet(0); # turn off quiet mode
$obj = Rcs->new;
$obj->rcsdir("./project_tree/archive");
$obj->workdir("./project_tree/src");
$obj->file("cornholio.pl");
print "Quiet mode NOT set\n" unless Rcs->quiet;
$obj->rcsclean;
AUTHOR¶
Craig Freter, <
craig@freter.com>
CONTRIBUTORS¶
David Green, <
greendjf@cvhp152.gpt.marconicomms.com>
Jamie O'Shaughnessy, <
jamie@thanatar.demon.co.uk>
Raju Krishnamurthy, <
raju_k@iname.com>
COPYRIGHT¶
Copyright (C) 1997,2003 Craig Freter. All rights reserved. This program is free
software; you can redistribute it and/or modify it under the same terms as
Perl itself.