Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Agent(3)	      User Contributed Perl Documentation	      Agent(3)

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).

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 1441:
	   You forgot a	'=back'	before '=head1'

perl v5.24.1			  2007-08-20			      Agent(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | BUGS | WARRANTY AND LIABILITY | COPYRIGHT | SEE ALSO | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Rcs::Agent&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help