NAME

Rcs::Agent - an RCS archive manipulation method library

SYNOPSIS

use Rcs::Agent;

DESCRIPTION

Rcs::Agent is a perl module for manipulating RCS archives. It provides an object-oriented interface to the RCS commands rcs(1), rcsdiff(1), ci(1) and co(1), in addition to providing easy access to revision information contained in the RCS archive file. A description of how RCS works is beyond the scope of this document, or to put it simply, you need to learn how to use RCS before using this perl interface to it.

METHODS

new

The new() method is the Rcs::Agent constructor, and is used both to create new RCS archives files if they do not already exist, or manipulate existing ones if they already exist in the specified location.

Typically, new() would be called using the following parameters:

$rcs = new Rcs::Agent (	file => "/data/src/foobar.c");

The file parameter tells the module what the name of the work file is. This is the only parameter which is absolutely necessary: if it is not supplied, then new() will return undef and all subsequent method calls using the $rcs handle will fail.

The workdir parameter can be used to specify the working directory of the file, if for some reason the programmer decides not to specify it using the file parameter. The example above could easily have been written:

$rcs = new Rcs::Agent (	file => "foobar.c", 
				workdir => "/data/src");

The rcsdir parameter specifies the location of the RCS archive. This is normally designated as the "RCS/" directory off the working directory, but there is no reason why rcsdir cannot be placed somewhere else if so desired. If this parameter is not specified, then the module uses some simplistic heuristics to determine the location of the RCS directory automatically. If there is a directory off the working directory called "RCS/" then the module will use that. If there is not, then it will use the working directory.

The suffix parameter specifies the RCS archive file suffix to use. On a Unix or a Unix-lookalike system, this is usually ",v". There is normally no need to change this parameter.

The tmpdir parameter specifies the location of a directory which is writable and which can by used by the Rcs::Agent library to create temporary files when necessary. While this defaults to "/tmp", it is strongly suggested for security reasons that a different, application-specific temporary directory be used.

err

The err() method returns whatever is currently in the error buffer. Whenever any method in this library fails for some reason, the method will put a message into the error buffer and then return undef to the calling function. This method is used to access the error message. It takes no parameters and returns a scalar text string, which may be zero length if there is no current error.

head

The head() method returns the revision number of the top of the RCS tree.

timestamp

The timestamp() method returns the mtime timestamp of the RCS archive file in C time format (i.e. seconds since the epoch). For convenience, this value can also be accessed by referring to $rcs->{mtime}.

archived

The archived() method indicates whether the file in question is already in RCS control. It is a quick and dirty function which simply tests whether the file has a readable RCS archive file. It returns 1 or 0, depending on whether this test is found to be true or not.

diff

The diff() method returns a list of differences between one version of the RCS archive and another. If neither the revision1 nor revision2 parameters are passed to this method, then it will return the list of diffs between the current working file and the head version. If revision1 alone is specified, then it will return a list of diffs between the current working file and the specified version, and if both parameters are supplied, then it will provide a list of diffs between the version specified in revision1 and revision2. The method will return undef if either of the revisions specified don't exist.

It is also possible to specify the revisions using symbolic names or tags instead of version numbers.

The format of the diff output can be controlled using the format parameter. If this is set to context, then it will produce context diffs; if it is set to unified, then unified diffs will be returned if the system's version of diff(1) supports unified diffs. If the format is not specified, or if it is set to old, then diff() will return a list of diffs in classic format.

checkin

The checkin() method allows the programmer to check a version of the file into the RCS archive. By default, the revision will be inserted at the head of the revision tree, unless the revision is specified using the revision parameter.

A comment can be added to the revision's log using the log parameter. If no comment or a blank comment is specified, then the revision is logged with the text "*** empty log message ***", as happens when using the RCS ci program.

The revision may be tagged with a symbolic name using the tag parameter. If the force parameter is set to "yes" then the symbolic name will override any previous assignment of the symbolic name.

If the programmer wishes to check the version out after check-in, then the checkout parameter should be set to "yes". This is useful if the programmer wishes to keep a working copy of the file outside the archive. If checkout is disabled, then the working copy of the file is deleted on check-in, which may not suit all purposes. By default, this option is turned on.

In addition, the programmer may wish to check out and lock the revision immediately after checkin. This can be accomplished setting the lock parameter to "yes".

These last two options correspond to the -u and -l options in ci respectively.

The checkin() method will return the numeric value 1 on success and undef on failure. As with all of these methods, in the event of the method returning undef, a failure message will be logged into the error buffer.

checkout

The checkout() method allows the programmer to check a version of the file out of the RCS archive. By default, if no revision is specified using the revision parameter, then the head revision will be checked out. It is possible to specify the revisions using symbolic names or tags instead of version numbers when checking out revisions.

The programmer may put a lock on the revision being checked out by setting the lock parameter to be "yes".

If there is a version of the archive already locked, or if the working file is writable, the check-out procedure will normally fail. This behaviour is to prevent the programmer from accidentally over-writing the work of another user who may also be editing a revision of the file. Checkouts can be forced by setting the force parameter to be "yes"; this option should not be used unless the operator is certain that no damage will be done.

The checkout() method will return the numeric value 1 on success and undef on failure.

lock

The lock() method permits the operator to lock a specific revision in the RCS archive without actually checking it out. By default, if no revision is specified using the revision parameter, then the head revisision will be locked. It is possible to specify the revisions using symbolic names or tags instead of version numbers when checking out revisions.

If the specified revision in the archive is already locked, then this method will fail.

The checkout() method will return the numeric value 1 on success and undef on failure.

unlock

The unlock() method performs the exact opposite as the lock() method: it unlocks the specified revision in the archive.

If the specified revision in the archive is already unlocked, then this method will fail.

The unlock() method will return the numeric value 1 on success and undef on failure.

initialize

The initialize() method is used to create and initialize an RCS archive for the working file if none existed previously.

The archive description can be specified using the "description" parameter.

If RCS version 5.7 or higher is installed on the system, the archive can be initialized to be binary safe by setting the "binary" parameter. Note that rcsmerge may not work properly on archives with binary data, and also that if there is a string in the binary file which matches an RCS keyword (i.e. \$Id\$, \$Log\$, etc), RCS may attempt to replace it with the its corresponding expanded value on checkout which may corrupt your binary file. See co for more details both of these issues.

The initialize() method returns the numeric value 1 on success and undef on failure.

rexists

The rexists() method checks to make sure that the revision specified in the parameter list actually exists in the RCS archive. If this is the case, then the revision number will be returned. If it does not exist, or some other error is detected, then undef is returned, and an error is left in the error buffer.

parent

The parent() method returns the previous revision relative to the revision specified in the parameter list, or undef if it does not exist:

In the following example, $parent might be assigned the value '1.1'.

my $parent = $rcs->parent (revision => '1.2');

When dealing with branches, the real parent branch is returned, and not the virtual branch fork revision. So, for example, the following code sets the value of $parent to be '1.5' rather than '1.5.3':

my $parent = $rcs->parent (revision => '1.5.3.1');

If the revision parameter is omitted, the revision defaults to the head revision.

child

Similar to parent(), child() returns the next revision relative to the revision specified in the parameter list, or undef if it does not exist.

revisions

The revisions() method returns a reference to an array containing the names of all of the revisions listed in the RCS archive.

symbols

The symbols() method returns a reference to an array containing the names of all of the symbolic names listed in the RCS archive.

access

The access() method returns a reference to an array containing the names of all of the logins who have access to lock the RCS file, or undef if it is an empty list.

description

description() is used to read or write the archive description. This is the text which is logged in the RCS archive using the "-t-" parameter. If the "description" parameter is set in the argument list, then the description in the archive file is set to the value specified.

my $description = $rcs->description ();

In this code, the $description variable will be set to the archive's description field, if it exists.

$rcs->description (description => 'Main source file');

In this code snippet, the RCS archive description is set to be be the value "Main source file".

locked, locker, state, author, date, log

These methods return the RCS archive data specified by the method name. If the "revision" parameter is given, then the method will return data relevant to the specified revision. Otherwise, the method will return data relevant to the head revision. All of the methods except for "log" return a scalar value. "log" returns a reference to an array of scalars, each of which corresponds to a line of the log message for the specified revision.

The locked() method is the same as locker(), and is included to allow more readable code such as

if ($rcs->locked(revision => "1.3")) {
    <code if version is locked>
} else {
    <code if version is unlocked>
}

As another example, the following line of code will return the author of revision 1.2 of the current RCS object:

my $author = $rcs->author(revision => "1.3");

If the data for the specified revision does not exist, then the method will return undef.

BUGS

o

unfortunately, it was all but impossible to call this module RCS::Agent, which is probably the more natural name. The reason for this is left as an exercise for the reader.

o

the code hasn't been tested on non-unix operating systems like the Windows family, MacOS, VMS and so forth. It will almost certainly not work on them.

o

"Merge is Hard!". Rcs::Agent does not support merging branches because this is something which often requires manual intervention. On the grounds that providing broken functionality along these lines would just encourage a bad habit, it's been left out completely. There are no plans to change this policy - at least not until the code develops self awareness.

o

Rcs::Agent does not yet grok CVS's magic branch tags.

o

revisions() and symbols() both contain references to branch revisions. This needs to be changed.

Please mail rcs-agent-lib@netability.ie if you find any more bugs. Patches should be sent in unified diff format (i.e. diff -u), or context diff format (diff -c) if your version of diff doesn't support unified diffs.

WARRANTY AND LIABILITY

THIS SOFTWARE IS PROVIDED BY NETWORK ABILITY LIMITED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NETWORK ABILITY LIMITED OR ANY CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

COPYRIGHT

Copyright (C) 2001 - 2007 Network Ability Ltd. All rights reserved. This software may be redistributed under the terms of the license included in this software distribution. Please see the file "LICENSE" for further details.

SEE ALSO

perl(1), rcsintro(1), rcsfile(5), rcs(1), rcsdiff(1), ci(1), co(1), rlog(1).

cpanm Rcs::Agent

perl -MCPAN -e shell
install Rcs::Agent