rcs(3)
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 call
ing 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 ex - tension
- 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 direc
tory. If not specified, default path is '.' (current
working directory).
$obj->workdir('/usr/local/source');- The rcsdir methods set the path of the RCS archive direc
tory. 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 locked0; - }
- 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 revi
sion. 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 num
ber. 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_date0;
$date_str = localtime($scalar_date);
print "Scalar date string = $date_str0;- # list mode
@list_date = $obj->revdate;
print "List date = @list_date0; - 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_recent0;
$most_recent_str = localtime($most_recent);
print "Most recent date string = $most_recent_str0; - 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 argu
ments. If one arguments is passed, then the argument is a
date number. If six arguments are passed, then they rep
resent 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 descrip
tion.
%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 differ
ences, 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 changed0; - }
- 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 informa
- tion
@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- $filename0;
- 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 direc
tory 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 $locker0;
- }
else {print "Head revision $head_rev is unlocked0; - }
- if (@access) {
print "0he following users are on the access listof file $filename0;
map { print "User: $_0} @access; - }
- print "0ist of all revisions of $filename0;
foreach $rev (@revisions) {print "Revision: $rev0; - }
- 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 direc
tory 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 direc
tory 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 file0;
if ($obj->rcsdiff) { # scalar contextprint $obj->rcsdiff; # list context - }
else {print "Versions are Equal0; - }
- print "0iff of revisions 1.2 and 1.10;
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 set0 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,1998,1999,2000,2001 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.