1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
|
<HTML>
<HEAD>
<TITLE>Rcs - Perl Object Class for Revision Control System.</TITLE>
<LINK REV="made" HREF="mailto:freter@postal.pcy.mci.net">
</HEAD>
<BODY>
<!-- INDEX BEGIN -->
<UL>
<LI><A HREF="#NAME">NAME</A>
<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
<UL>
<LI><A HREF="#OBJECT_CONSTRUCTOR">OBJECT CONSTRUCTOR</A>
<LI><A HREF="#CLASS_METHODS">CLASS METHODS</A>
<LI><A HREF="#OBJECT_ATTRIBUTE_METHODS">OBJECT ATTRIBUTE METHODS</A>
<LI><A HREF="#RCS_PARSE_METHODS">RCS PARSE METHODS</A>
<LI><A HREF="#RCS_SYSTEM_METHODS">RCS SYSTEM METHODS</A>
</UL>
<LI><A HREF="#EXAMPLES">EXAMPLES</A>
<UL>
<LI><A HREF="#CREATE_ACCESS_LIST">CREATE ACCESS LIST</A>
<LI><A HREF="#PARSE_RCS_ARCHIVE_FILE">PARSE RCS ARCHIVE FILE</A>
<LI><A HREF="#CHECK_IN_FILE">CHECK-IN FILE</A>
<LI><A HREF="#CHECK_OUT_FILE">CHECK-OUT FILE</A>
<LI><A HREF="#RCSDIFF">RCSDIFF</A>
<LI><A HREF="#RCSCLEAN">RCSCLEAN</A>
</UL>
<LI><A HREF="#AUTHOR">AUTHOR</A>
<LI><A HREF="#CONTRIBUTORS">CONTRIBUTORS</A>
<LI><A HREF="#COPYRIGHT">COPYRIGHT</A>
</UL>
<!-- INDEX END -->
<HR>
<P>
<H1><A NAME="NAME">NAME</A></H1>
<P>
Rcs - Perl Object Class for Revision Control System (RCS).
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<P>
<PRE> use Rcs;
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
This Perl module provides an object oriented interface to access
<STRONG>Revision Control System (RCS)</STRONG> utilities. RCS must be installed on the system prior to using this module.
This module should simplify the creation of an RCS front-end.
<P>
<HR>
<H2><A NAME="OBJECT_CONSTRUCTOR">OBJECT CONSTRUCTOR</A></H2>
<P>
The <STRONG>new</STRONG> method may be used as either a class method or an object method to create a
new object.
<P>
<PRE> # called as class method
$obj = Rcs->new;
</PRE>
<P>
<PRE> # called as object method
$newobj = $obj->new;
</PRE>
<P>
<HR>
<H2><A NAME="CLASS_METHODS">CLASS METHODS</A></H2>
<P>
Besides the object constructor, there are three class methods provided
which effect any newly created objects.
<P>
The <STRONG>arcext</STRONG> method sets the RCS archive extension, which is ',v' by default.
<P>
<PRE> # 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
</PRE>
<P>
The <STRONG>bindir</STRONG> method sets the directory path where the RCS executables (i.e. rcs, ci, co)
are located. The default location is '/usr/local/bin'.
<P>
<PRE> # set RCS bin directory
Rcs->bindir('/usr/bin');
</PRE>
<P>
<PRE> # access RCS bin directory
$bin_dir = Rcs->bindir;
</PRE>
<P>
The <STRONG>quiet</STRONG> method sets/unsets the quiet mode for the RCS executables. Quiet mode is
set by default.
<P>
<PRE> # set/unset RCS quiet mode
Rcs->quiet(0); # unset quiet mode
Rcs->quiet(1); # set quiet mode
</PRE>
<P>
<PRE> # access RCS quiet mode
$quiet_mode = Rcs->quiet;
</PRE>
<P>
These methods may also be called as object methods.
<P>
<PRE> $obj->arcext('');
$obj->bindir('/usr/bin');
$obj->quiet(0);
</PRE>
<P>
<HR>
<H2><A NAME="OBJECT_ATTRIBUTE_METHODS">OBJECT ATTRIBUTE METHODS</A></H2>
<P>
These methods set the attributes of the RCS object.
<P>
The <STRONG>file</STRONG> 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.
<P>
<PRE> $obj->file('mr_anderson.pl');
</PRE>
<P>
The <STRONG>arcfile</STRONG> 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.
<P>
<PRE> $obj->arcfile('principle_mcvicker.pl');
</PRE>
<P>
The <STRONG>workdir</STRONG> methods set the path of the RCS working directory. If not specified,
default path is '.' (current working directory).
<P>
<PRE> $obj->workdir('/usr/local/source');
</PRE>
<P>
The <STRONG>rcsdir</STRONG> methods set the path of the RCS archive directory. If not specified,
default path is './RCS'.
<P>
<PRE> $obj->rcsdir('/usr/local/archive');
</PRE>
<P>
<HR>
<H2><A NAME="RCS_PARSE_METHODS">RCS PARSE METHODS</A></H2>
<P>
This class provides methods to directly parse the RCS archive file.
<P>
The <STRONG>access</STRONG> method returns a list of all user on the access list.
<P>
<PRE> @access_list = $obj->access;
</PRE>
<P>
The <STRONG>author</STRONG> method returns the author of the revision. The head revision is used if no
revision argument is passed to method.
<P>
<PRE> # returns the author of revision '1.3'
$author = $obj->author('1.3');
</PRE>
<P>
<PRE> # returns the authos of the head revision
$author = $obj->author;
</PRE>
<P>
The <STRONG>head</STRONG> method returns the head revision.
<P>
<PRE> $head = $obj->head;
</PRE>
<P>
The <STRONG>lock</STRONG> 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.
<P>
<PRE> # returns locker of revision '1.3'
$locker = $obj->lock('1.3');
</PRE>
<P>
<PRE> # returns locker of head revision
$locker = $obj->lock;
</PRE>
<P>
The <STRONG>revisions</STRONG> method returns a list of all revisions of archive file.
<P>
<PRE> @revisions = $obj->revisions;
</PRE>
<P>
The <STRONG>state</STRONG> method returns the state of the revision. The head revision is used if no
revision argument is passed to method.
<P>
<PRE> # returns state of revision '1.3'
$state = $obj->state('1.3');
</PRE>
<P>
<PRE> # returns state of head revision
$state = $obj->state;
</PRE>
<P>
The <STRONG>symbol</STRONG> method returns the <CODE>symbol(s)</CODE> 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.
<P>
<PRE> # list context, returns all symbols associated with revision 1.3
@symbols = $obj->symbol('1.3');
</PRE>
<P>
<PRE> # list context, returns all symbols associated with head revision
@symbols = $obj->symbol;
</PRE>
<P>
<PRE> # scalar context, returns last symbol associated with revision 1.3
$symbol = $obj->symbol('1.3');
</PRE>
<P>
<PRE> # scalar context, returns last symbol associated with head revision
$symbol = $obj->symbol;
</PRE>
<P>
The <STRONG>symbols</STRONG> method returns a hash, keyed by symbol, of all of the revisions associated
with the file.
<P>
<PRE> %symbols = $obj->symbols;
foreach $sym (keys %symbols) {
$rev = $symbols{$sym};
}
</PRE>
<P>
The <STRONG>revdate</STRONG> 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.
<P>
<PRE> # 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";
</PRE>
<P>
<PRE> # list mode
@list_date = $obj->revdate;
print "List date = @list_date\n";
</PRE>
<P>
The <STRONG>dates</STRONG> 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.
<P>
<PRE> # list mode
%DatesHash = obj->dates;
@dates_list = sort {$b<=>$a} values %DatesHash;
$MostRecent = $dates_list[0];
</PRE>
<P>
<PRE> # 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";
</PRE>
<P>
The <STRONG>symrev</STRONG> 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.
<P>
<PRE> # gets revision that has 'MY_SYMBOL' defined against it
$rev = $obj->symrev('MY_SYMBOL');
</PRE>
<P>
The <STRONG>daterev</STRONG> 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.
<P>
<PRE> # one argument, date number
# gets revisions created before Sun Sep 6 22:23:47 1998
@revs = $obj->daterev(841436420);
</PRE>
<P>
<PRE> # six argument
# gets revisions created before 25th June 1998 16:45:30
@revs = $obj->daterev(1998, 6, 25, 16, 45, 30);
</PRE>
<P>
The <STRONG>comments</STRONG> method returns a hash of revision comments, keyed on revision. A key value
of 0 returns the description.
<P>
<PRE> %comments = $obj->comments;
$description = $comments{0};
$comment_1_3 = $comments{'1.3'};
</PRE>
<P>
<HR>
<H2><A NAME="RCS_SYSTEM_METHODS">RCS SYSTEM METHODS</A></H2>
<P>
These methods invoke the RCS system utilities.
<P>
The <STRONG>ci</STRONG> method calls the RCS ci program.
<P>
<PRE> # check in, and then check out in unlocked state
$obj->ci('-u');
</PRE>
<P>
The <STRONG>co</STRONG> method calls the RCS co program.
<P>
<PRE> # check out in locked state
$obj->co('-l');
</PRE>
<P>
The <STRONG>rcs</STRONG> method calls the RCS rcs program.
<P>
<PRE> # lock file
$obj->rcs('-l');
</PRE>
<P>
The <STRONG>rcsdiff</STRONG> 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.
<P>
When called without parameters, rcsdiff does a diff between the current
working file, and the last revision checked in.
<P>
<PRE> # call in list context
@diff_output = $obj->rcsdiff;
</PRE>
<P>
<PRE> # call in scalar context
$changed = $obj->rcsdiff;
if ($changed) {
print "Working file has changed\n";
}
</PRE>
<P>
Call rcsdiff with parameters to do a diff between any two revisions.
<P>
<PRE> @diff_output = $obj->rcsdiff('-r1.2', '-r1.1');
</PRE>
<P>
The <STRONG>rlog</STRONG> method calls the RCS rlog program. This method returns the output of the
rlog program.
<P>
<PRE> # get complete log output
@rlog_complete = $obj->rlog;
</PRE>
<P>
<PRE> # called with '-h' switch outputs only header information
@rlog_header = $obj->rlog('-h');
print @rlog_header;
</PRE>
<P>
The <STRONG>rcsclean</STRONG> method calls the RCS rcsclean program.
<P>
<PRE> # remove working file
$obj->rcsclean;
</PRE>
<P>
<HR>
<H1><A NAME="EXAMPLES">EXAMPLES</A></H1>
<P>
<HR>
<H2><A NAME="CREATE_ACCESS_LIST">CREATE ACCESS LIST</A></H2>
<P>
Using method <STRONG>rcs</STRONG> with the <STRONG>-a</STRONG> switch allows you to add users to the access list of an RCS archive file.
<P>
<PRE> use Rcs;
$obj = Rcs->new;
</PRE>
<P>
<PRE> $obj->rcsdir("./project_tree/archive");
$obj->workdir("./project_tree/src");
$obj->file("cornholio.pl");
</PRE>
<P>
Methos <STRONG>rcs</STRONG> invokes the RCS utility rcs with the same parameters.
<P>
<PRE> @users = qw(beavis butthead);
$obj->rcs("-a@users");
</PRE>
<P>
Calling method <STRONG>access</STRONG> returns list of users on access list.
<P>
<PRE> $filename = $obj->file;
@access_list = $obj->access;
print "Users @access_list are on the access list of $filename\n";
</PRE>
<P>
<HR>
<H2><A NAME="PARSE_RCS_ARCHIVE_FILE">PARSE RCS ARCHIVE FILE</A></H2>
<P>
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.
<P>
<PRE> use Rcs;
Rcs->bindir('/usr/bin');
$obj = Rcs->new;
</PRE>
<P>
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).
<P>
<PRE> $obj->rcsdir("./project_tree/archive");
$obj->workdir("./project_tree/src");
$obj->file("cornholio.pl");
</PRE>
<P>
<PRE> $head_rev = $obj->head;
$locker = $obj->lock;
$author = $obj->author;
@access = $obj->access;
@revisions = $obj->revisions;
</PRE>
<P>
<PRE> $filename = $obj->file;
</PRE>
<P>
<PRE> if ($locker) {
print "Head revision $head_rev is locked by $locker\n";
}
else {
print "Head revision $head_rev is unlocked\n";
}
</PRE>
<P>
<PRE> if (@access) {
print "\nThe following users are on the access list of file $filename\n";
map { print "User: $_\n"} @access;
}
</PRE>
<P>
<PRE> print "\nList of all revisions of $filename\n";
foreach $rev (@revisions) {
print "Revision: $rev\n";
}
</PRE>
<P>
<HR>
<H2><A NAME="CHECK_IN_FILE">CHECK-IN FILE</A></H2>
<P>
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.
<P>
<PRE> use Rcs;
Rcs->bindir('/usr/bin');
Rcs->quiet(0); # turn off quiet mode
$obj = Rcs->new;
</PRE>
<P>
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).
<P>
<PRE> $obj->file('cornholio.pl');
</PRE>
<P>
<PRE> # Set RCS archive directory, is './RCS' by default
$obj->rcsdir("./project_tree/archive");
</PRE>
<P>
<PRE> # Set working directory, is '.' by default
$obj->workdir("./project_tree/src");
</PRE>
<P>
Check in file using <STRONG>-u</STRONG> switch. This will check in the file, and will then check out the file in an
unlocked state. The <STRONG>-m</STRONG> switch is used to set the revision comment.
<P>
Command:
<P>
<PRE> $obj->ci('-u', '-mRevision Comment');
</PRE>
<P>
is equivalent to commands:
<P>
<PRE> $obj->ci('-mRevision Comment');
$obj->co;
</PRE>
<P>
<HR>
<H2><A NAME="CHECK_OUT_FILE">CHECK-OUT FILE</A></H2>
<P>
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.
<P>
<PRE> use Rcs;
Rcs->bindir('/usr/bin');
Rcs->quiet(0); # turn off quiet mode
$obj = Rcs->new;
</PRE>
<P>
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).
<P>
<PRE> $obj->file('cornholio.pl');
</PRE>
<P>
<PRE> # Set RCS archive directory, is './RCS' by default
$obj->rcsdir("./project_tree/archive");
</PRE>
<P>
<PRE> # Set working directory, is '.' by default
$obj->workdir("./project_tree/src");
</PRE>
<P>
Check out file read-only:
<P>
<PRE> $obj->co;
</PRE>
<P>
or check out and lock file:
<P>
<PRE> $obj->co('-l');
</PRE>
<P>
<HR>
<H2><A NAME="RCSDIFF">RCSDIFF</A></H2>
<P>
Method <STRONG>rcsdiff</STRONG> does an diff between revisions.
<P>
<PRE> $obj = Rcs->new;
$obj->bindir('/usr/bin');
</PRE>
<P>
<PRE> $obj->rcsdir("./project_tree/archive");
$obj->workdir("./project_tree/src");
$obj->file("cornholio.pl");
</PRE>
<P>
<PRE> print "Diff of current working file\n";
if ($obj->rcsdiff) { # scalar context
print $obj->rcsdiff; # list context
}
else {
print "Versions are Equal\n";
}
</PRE>
<P>
<PRE> print "\n\nDiff of revisions 1.2 and 1.1\n";
print $obj->rcsdiff('-r1.2', '-r1.1');
</PRE>
<P>
<HR>
<H2><A NAME="RCSCLEAN">RCSCLEAN</A></H2>
<P>
Method <STRONG>rcsclean</STRONG> will remove an unlocked working file.
<P>
<PRE> use Rcs;
Rcs->bindir('/usr/bin');
Rcs->quiet(0); # turn off quiet mode
$obj = Rcs->new;
</PRE>
<P>
<PRE> $obj->rcsdir("./project_tree/archive");
$obj->workdir("./project_tree/src");
$obj->file("cornholio.pl");
</PRE>
<P>
<PRE> print "Quiet mode NOT set\n" unless Rcs->quiet;
</PRE>
<P>
<PRE> $obj->rcsclean;
</PRE>
<P>
<HR>
<H1><A NAME="AUTHOR">AUTHOR</A></H1>
<P>
Craig Freter, <<EM>craig@freter.com</EM>>
<P>
<HR>
<H1><A NAME="CONTRIBUTORS">CONTRIBUTORS</A></H1>
<P>
David Green, <<EM>greendjf@cvhp152.gpt.co.uk</EM>>
<P>
Jamie O'Shaughnessy, <<EM>jamie@thanatar.demon.co.uk</EM>>
<P>
<HR>
<H1><A NAME="COPYRIGHT">COPYRIGHT</A></H1>
<P>
Copyright (C) 1997,1998 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.
</BODY>
</HTML>
|
