.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Rcs 3pm"
.TH Rcs 3pm "2021-01-04" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Rcs \- Perl Object Class for Revision Control System (RCS).
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    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);
.Ve
.PP
The default behavior is to run rcs programs with the \-q (quiet) flag,
and to die if any rcs program returns an error.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This Perl module provides an object oriented interface to access 
\&\fBRevision Control System (\s-1RCS\s0)\fR utilities.  \s-1RCS\s0 must be installed on
the system prior to using this module.  This module should simplify
the creation of an \s-1RCS\s0 front-end.
.SS "\s-1OBJECT CONSTRUCTOR\s0"
.IX Subsection "OBJECT CONSTRUCTOR"
The \fBnew\fR method may be used as either a class method or an object
method to create a new object.
.PP
.Vb 2
\&    # called as class method
\&    $obj = Rcs\->new;
\&
\&    # called as object method
\&    $newobj = $obj\->new;
.Ve
.PP
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.
.PP
Thus
.PP
.Vb 1
\&    $obj = Rcs\->new($pathname);
.Ve
.PP
is the same as
.PP
.Vb 2
\&    $obj = Rcs\->new;
\&    $obj\->pathname($pathname);
.Ve
.PP
See \fBpathname\fR method for additional details.
.SS "\s-1CLASS METHODS\s0"
.IX Subsection "CLASS METHODS"
Besides the object constructor, there are three class methods provided
which effect any newly created objects.
.PP
The \fBarcext\fR method sets the \s-1RCS\s0 archive extension, which is ',v' by
default.
.PP
.Vb 4
\&    # set/unset RCS archive extension
\&    Rcs\->arcext(\*(Aq\*(Aq);            # set no archive extension
\&    Rcs\->arcext(\*(Aq,v\*(Aq);          # set archive extension to \*(Aq,v\*(Aq
\&    $arc_ext = Rcs\->arcext();   # get current archive extension
.Ve
.PP
The \fBbindir\fR method sets the directory path where the \s-1RCS\s0 executables
(i.e. rcs, ci, co) are located.  The default location is '/usr/local/bin'.
.PP
.Vb 2
\&    # set RCS bin directory
\&    Rcs\->bindir(\*(Aq/usr/bin\*(Aq);
\&
\&    # access RCS bin directory
\&    $bin_dir = Rcs\->bindir;
.Ve
.PP
The \fBquiet\fR method sets/unsets the quiet mode for the \s-1RCS\s0 executables.
Quiet mode is set by default.
.PP
.Vb 3
\&    # 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;
.Ve
.PP
These methods may also be called as object methods.
.PP
.Vb 3
\&    $obj\->arcext(\*(Aq\*(Aq);
\&    $obj\->bindir(\*(Aq/usr/bin\*(Aq);
\&    $obj\->quiet(0);
.Ve
.SS "\s-1OBJECT ATTRIBUTE METHODS\s0"
.IX Subsection "OBJECT ATTRIBUTE METHODS"
These methods set the attributes of the \s-1RCS\s0 object.
.PP
The \fBfile\fR method is used to set the name of the \s-1RCS\s0 working file.  The
filename must be set before invoking any access of modifier methods on the
object.
.PP
.Vb 1
\&    $obj\->file(\*(Aqmr_anderson.pl\*(Aq);
.Ve
.PP
The \fBarcfile\fR method is used to set the name of the \s-1RCS\s0 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
\&\s-1RCS\s0 archive extension (default ',v') is automatically added to the filename.
.PP
.Vb 1
\&    $obj\->arcfile(\*(Aqprinciple_mcvicker.pl\*(Aq);
.Ve
.PP
The \fBworkdir\fR methods set the path of the \s-1RCS\s0 working directory.  If not
specified, default path is '.' (current working directory).
.PP
.Vb 1
\&    $obj\->workdir(\*(Aq/usr/local/source\*(Aq);
.Ve
.PP
The \fBrcsdir\fR methods set the path of the \s-1RCS\s0 archive directory.  If not
specified, default path is './RCS'.
.PP
.Vb 1
\&    $obj\->rcsdir(\*(Aq/usr/local/archive\*(Aq);
.Ve
.PP
The \fBpathname\fR method will set both the working filename and archive
directory.
.PP
.Vb 3
\&    $obj\->pathname($RCS_DIR . \*(Aq/\*(Aq . \*(Aqbutthead.c\*(Aq);
\&and
\&    $obj\->pathname($RCS_DIR . \*(Aq/\*(Aq . \*(Aqbutthead.c,v\*(Aq);
.Ve
.PP
are the same as
.PP
.Vb 2
\&    $obj\->rcsdir($RCS_DIR);
\&    $obj\->file(\*(Aqbutthead.c\*(Aq);
.Ve
.SS "\s-1RCS PARSE METHODS\s0"
.IX Subsection "RCS PARSE METHODS"
This class provides methods to directly parse the \s-1RCS\s0 archive file.
.PP
The \fBaccess\fR method returns a list of all user on the access list.
.PP
.Vb 1
\&    @access_list = $obj\->access;
.Ve
.PP
The \fBauthor\fR method returns the author of the revision.  The head revision
is used if no revision argument is passed to method.
.PP
.Vb 2
\&    # returns the author of revision \*(Aq1.3\*(Aq
\&    $author = $obj\->author(\*(Aq1.3\*(Aq);
\&
\&    # returns the authos of the head revision
\&    $author = $obj\->author;
.Ve
.PP
The \fBhead\fR method returns the head revision.
.PP
.Vb 1
\&    $head = $obj\->head;
.Ve
.PP
The \fBlock\fR 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.
.PP
.Vb 2
\&    # returns locker of revision \*(Aq1.3\*(Aq
\&    $locker = $obj\->lock(\*(Aq1.3\*(Aq);
\&
\&    # 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\en";
\&    }
.Ve
.PP
The \fBrevisions\fR method returns a list of all revisions of archive file.
.PP
.Vb 1
\&    @revisions = $obj\->revisions;
.Ve
.PP
The \fBstate\fR method returns the state of the revision. The head revision
is used if no revision argument is passed to method.
.PP
.Vb 2
\&    # returns state of revision \*(Aq1.3\*(Aq
\&    $state = $obj\->state(\*(Aq1.3\*(Aq);
\&
\&    # returns state of head revision
\&    $state = $obj\->state;
.Ve
.PP
The \fBsymbol\fR 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.
.PP
.Vb 2
\&    # list context, returns all symbols associated with revision 1.3
\&    @symbols = $obj\->symbol(\*(Aq1.3\*(Aq);
\&
\&    # 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(\*(Aq1.3\*(Aq);
\&
\&    # scalar context, returns last symbol associated with head revision
\&    $symbol = $obj\->symbol;
.Ve
.PP
The \fBsymbols\fR method returns a hash, keyed by symbol, of all of the revisions
associated with the file.
.PP
.Vb 4
\&    %symbols = $obj\->symbols;
\&    foreach $sym (keys %symbols) {
\&        $rev = $symbols{$sym};
\&    }
.Ve
.PP
The \fBrevdate\fR 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.
.PP
.Vb 5
\&    # scalar mode
\&    $scalar_date = $obj\->revdate;
\&    print "Scalar date number = $scalar_date\en";
\&    $date_str = localtime($scalar_date);
\&    print "Scalar date string = $date_str\en";
\&
\&    # list mode
\&    @list_date = $obj\->revdate;
\&    print "List date = @list_date\en";
.Ve
.PP
The \fBdates\fR 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.
.PP
.Vb 4
\&    # 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\en";
\&    $most_recent_str = localtime($most_recent);
\&    print "Most recent date string = $most_recent_str\en";
.Ve
.PP
The \fBsymrev\fR 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.
.PP
.Vb 2
\&    # gets revision that has \*(AqMY_SYMBOL\*(Aq defined against it
\&    $rev = $obj\->symrev(\*(AqMY_SYMBOL\*(Aq);
.Ve
.PP
The \fBdaterev\fR 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.
.PP
.Vb 3
\&    # 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);
.Ve
.PP
The \fBcomments\fR method returns a hash of revision comments, keyed on revision.
A key value of 0 returns the description.
.PP
.Vb 3
\&    %comments = $obj\->comments;
\&    $description = $comments{0};
\&    $comment_1_3 = $comments{\*(Aq1.3\*(Aq};
.Ve
.SS "\s-1RCS SYSTEM METHODS\s0"
.IX Subsection "RCS SYSTEM METHODS"
These methods invoke the \s-1RCS\s0 system utilities.
.PP
The \fBci\fR method calls the \s-1RCS\s0 ci program.
.PP
.Vb 2
\&    # check in, and then check out in unlocked state
\&    $obj\->ci(\*(Aq\-u\*(Aq);
.Ve
.PP
The \fBco\fR method calls the \s-1RCS\s0 co program.
.PP
.Vb 2
\&    # check out in locked state
\&    $obj\->co(\*(Aq\-l\*(Aq);
.Ve
.PP
The \fBrcs\fR method calls the \s-1RCS\s0 rcs program.
.PP
.Vb 2
\&    # lock file
\&    $obj\->rcs(\*(Aq\-l\*(Aq);
.Ve
.PP
The \fBrcsdiff\fR method calls the \s-1RCS\s0 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.
.PP
When called without parameters, rcsdiff does a diff between the current
working file, and the last revision checked in.
.PP
.Vb 2
\&    # call in list context
\&    @diff_output = $obj\->rcsdiff;
\&
\&    # call in scalar context
\&    $changed = $obj\->rcsdiff;
\&    if ($changed) {
\&        print "Working file has changed\en";
\&    }
.Ve
.PP
Call rcsdiff with parameters to do a diff between any two revisions.
.PP
.Vb 1
\&    @diff_output = $obj\->rcsdiff(\*(Aq\-r1.2\*(Aq, \*(Aq\-r1.1\*(Aq);
.Ve
.PP
The \fBrlog\fR method calls the \s-1RCS\s0 rlog program.  This method returns the
output of the rlog program.
.PP
.Vb 2
\&    # get complete log output
\&    @rlog_complete = $obj\->rlog;
\&
\&    # called with \*(Aq\-h\*(Aq switch outputs only header information
\&    @rlog_header = $obj\->rlog(\*(Aq\-h\*(Aq);
\&    print @rlog_header;
.Ve
.PP
The \fBrcsclean\fR method calls the \s-1RCS\s0 rcsclean program.
.PP
.Vb 2
\&    # remove working file
\&    $obj\->rcsclean;
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "\s-1CREATE ACCESS LIST\s0"
.IX Subsection "CREATE ACCESS LIST"
Using method \fBrcs\fR with the \fB\-a\fR switch allows you to add users to
the access list of an \s-1RCS\s0 archive file.
.PP
.Vb 2
\&    use Rcs;
\&    $obj = Rcs\->new;
\&
\&    $obj\->rcsdir("./project_tree/archive");
\&    $obj\->workdir("./project_tree/src");
\&    $obj\->file("cornholio.pl");
.Ve
.PP
Methos \fBrcs\fR invokes the \s-1RCS\s0 utility rcs with the same parameters.
.PP
.Vb 2
\&    @users = qw(beavis butthead);
\&    $obj\->rcs("\-a@users");
.Ve
.PP
Calling method \fBaccess\fR returns list of users on access list.
.PP
.Vb 3
\&    $filename = $obj\->file;
\&    @access_list = $obj\->access;
\&    print "Users @access_list are on the access list of $filename\en";
.Ve
.SS "\s-1PARSE RCS ARCHIVE FILE\s0"
.IX Subsection "PARSE RCS ARCHIVE FILE"
Set class variables and create '\s-1RCS\s0' object.
Set bin directory where \s-1RCS\s0 programs (e.g. rcs, ci, co) reside.  The
default is '/usr/local/bin'.  This sets the bin directory for all objects.
.PP
.Vb 3
\&    use Rcs;
\&    Rcs\->bindir(\*(Aq/usr/bin\*(Aq);
\&    $obj = Rcs\->new;
.Ve
.PP
Set information regarding \s-1RCS\s0 object.  This information includes name of the
working file, directory of working file ('.' by default), and \s-1RCS\s0 archive
directory ('./RCS' by default).
.PP
.Vb 3
\&    $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\en";
\&    }
\&    else {
\&        print "Head revision $head_rev is unlocked\en";
\&    }
\&
\&    if (@access) {
\&        print "\enThe following users are on the access list of file $filename\en";
\&        map { print "User: $_\en"} @access;
\&    }
\&
\&    print "\enList of all revisions of $filename\en";
\&    foreach $rev (@revisions) {
\&        print "Revision: $rev\en";
\&    }
.Ve
.SS "CHECK-IN \s-1FILE\s0"
.IX Subsection "CHECK-IN FILE"
Set class variables and create '\s-1RCS\s0' object.
Set bin directory where \s-1RCS\s0 programs (e.g. rcs, ci, co) reside.  The
default is '/usr/local/bin'.  This sets the bin directory for all objects.
.PP
.Vb 4
\&    use Rcs;
\&    Rcs\->bindir(\*(Aq/usr/bin\*(Aq);
\&    Rcs\->quiet(0);      # turn off quiet mode
\&    $obj = Rcs\->new;
.Ve
.PP
Set information regarding \s-1RCS\s0 object.  This information includes name of
working file, directory of working file ('.' by default), and \s-1RCS\s0 archive
directory ('./RCS' by default).
.PP
.Vb 1
\&    $obj\->file(\*(Aqcornholio.pl\*(Aq);
\&
\&    # Set RCS archive directory, is \*(Aq./RCS\*(Aq by default
\&    $obj\->rcsdir("./project_tree/archive");
\&
\&    # Set working directory, is \*(Aq.\*(Aq by default
\&    $obj\->workdir("./project_tree/src");
.Ve
.PP
Check in file using \fB\-u\fR switch.  This will check in the file, and will then
check out the file in an unlocked state.  The \fB\-m\fR switch is used to set the
revision comment.
.PP
Command:
.PP
.Vb 1
\&    $obj\->ci(\*(Aq\-u\*(Aq, \*(Aq\-mRevision Comment\*(Aq);
.Ve
.PP
is equivalent to commands:
.PP
.Vb 2
\&    $obj\->ci(\*(Aq\-mRevision Comment\*(Aq);
\&    $obj\->co;
.Ve
.SS "CHECK-OUT \s-1FILE\s0"
.IX Subsection "CHECK-OUT FILE"
Set class variables and create '\s-1RCS\s0' object.
Set bin directory where \s-1RCS\s0 programs (e.g. rcs, ci, co) reside.  The
default is '/usr/local/bin'.  This sets the bin directory for all objects.
.PP
.Vb 4
\&    use Rcs;
\&    Rcs\->bindir(\*(Aq/usr/bin\*(Aq);
\&    Rcs\->quiet(0);      # turn off quiet mode
\&    $obj = Rcs\->new;
.Ve
.PP
Set information regarding \s-1RCS\s0 object.  This information includes name of
working file, directory of working file ('.' by default), and \s-1RCS\s0 archive
directory ('./RCS' by default).
.PP
.Vb 1
\&    $obj\->file(\*(Aqcornholio.pl\*(Aq);
\&
\&    # Set RCS archive directory, is \*(Aq./RCS\*(Aq by default
\&    $obj\->rcsdir("./project_tree/archive");
\&
\&    # Set working directory, is \*(Aq.\*(Aq by default
\&    $obj\->workdir("./project_tree/src");
.Ve
.PP
Check out file read-only:
.PP
.Vb 1
\&    $obj\->co;
.Ve
.PP
or check out and lock file:
.PP
.Vb 1
\&    $obj\->co(\*(Aq\-l\*(Aq);
.Ve
.SS "\s-1RCSDIFF\s0"
.IX Subsection "RCSDIFF"
Method \fBrcsdiff\fR does an diff between revisions.
.PP
.Vb 2
\&    $obj = Rcs\->new;
\&    $obj\->bindir(\*(Aq/usr/bin\*(Aq);
\&
\&    $obj\->rcsdir("./project_tree/archive");
\&    $obj\->workdir("./project_tree/src");
\&    $obj\->file("cornholio.pl");
\&
\&    print "Diff of current working file\en";
\&    if ($obj\->rcsdiff) {       # scalar context
\&        print $obj\->rcsdiff;   # list context
\&    }
\&    else {
\&       print "Versions are Equal\en";
\&    }
\&
\&    print "\en\enDiff of revisions 1.2 and 1.1\en";
\&    print $obj\->rcsdiff(\*(Aq\-r1.2\*(Aq, \*(Aq\-r1.1\*(Aq);
.Ve
.SS "\s-1RCSCLEAN\s0"
.IX Subsection "RCSCLEAN"
Method \fBrcsclean\fR will remove an unlocked working file.
.PP
.Vb 4
\&    use Rcs;
\&    Rcs\->bindir(\*(Aq/usr/bin\*(Aq);
\&    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\en" unless Rcs\->quiet;
\&
\&    $obj\->rcsclean;
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Craig Freter, <\fIcraig@freter.com\fR>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
David Green, <\fIgreendjf@cvhp152.gpt.marconicomms.com\fR>
.PP
Jamie O'Shaughnessy, <\fIjamie@thanatar.demon.co.uk\fR>
.PP
Raju Krishnamurthy, <\fIraju_k@iname.com\fR>
.SH "COPYRIGHT"
.IX Header "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.