/ 
VCS-SCCS-0.06
River stage zero No dependents
/ VCS::SCCS

NAME

VCS::SCCS - OO Interface to SCCS files

SYNOPSIS

use VCS::SCCS;

my $sccs = VCS::SCCS->new ("SCCS/s.file.pl");   # Read and parse

# Meta info
my $fn = $sccs->file ();            # s.file.pl
my $cs = $sccs->checksum ();        # 52534
my @us = $sccs->users ();           # qw( merijn user )
my $fl = $sccs->flags ();           # { q => "Test applic", v => undef }
my $cm = $sccs->comment ();         # ""
my $cr = $sccs->current ();         # 70
my @cr = $sccs->current ();         # ( 70, "5.39", 5, 39 )

# Delta related
my $xx = $sccs->delta (...);   -- NYI --
my $vs = $sccs->version ();         # "5.39"
my $vs = $sccs->version (69);       # "5.38"
my $rv = $sccs->revision ();        # 70
my $rv = $sccs->revision ("5.37");  # 68
my $rm = $sccs->revision_map ();    # [ [ 1, "4.1" ], ... [ 70, "5.39" ]]

# Content related
my $body_70 = $sccs->body ();       # file.pl @70 incl NL's
my @body_70 = $sccs->body ();       # file.pl @70 list of chomped lines
my @body_69 = $sccs->body (69);     # same for file.pl @96
my @body_69 = $sccs->body ("5.38"); # same
-- NYI --
my $diff = $sccs->diff (67);        # unified diff between rev 67 and 70
my $diff = $sccs->diff (63, "5.37");# unified diff between rev 63 and 68

DESCRIPTION

SCCS was the dominant version control system until the release of the Revision Control System. Today, SCCS is generally considered obsolete. However, its file format is still used internally by a few other revision control programs, including BitKeeper and TeamWare. Sablime[1] also allows the use of SCCS files. The SCCS file format uses a storage technique called interleaved deltas (or the weave). This storage technique is now considered by many revision control system developers as key to some advanced merging techniques, such as the "Precise Codeville" ("pcdv") merge.

This interface aims at the possibility to read those files, without the need of the sccs utility set, and open up to the possibility of scripts that use it to convert to more modern VCSs like git, Mercurial, CVS, or subversion.

FUNCTIONS

Meta function

new (<file>)

The constructor only accepts a single argument: the SCCS file. this will typically be something like SCCS/s.file.c.

If anything in that file makes new () believe that it is not a SCCS file, it will return undef. In this stage, there is no way yet to tell why new () failed.

file

Returns the name of the parsed file. Useful if you have more than a single $sccs object.

checksum

Returns the checksum that was stored in the file. This module does not check if it is valid, nor does it have functionality to calculate a new checksum.

users

Returns the list of users that was recorded in this file as authorized to make deltas/changes.

flags

Returns a hash of the flags set for this file (if set at all). VCS::SCCS does not do anything with these flags. They are here for the end-user only.

Note that not all flags are supported by all versions of admin, like x is supported on HP-UX, but not in CSSC.

t <type of program>

File has a user defined value for the %Y% keyword.

v [<program name>]

File was flagged to prompt for MR (using <program name> for validation).

i <keyword string>

File was flagged to require id keywords.

b

File was allowed to pass -b to get to create branch deltas.

m <module name>

File has a user defined value for the %M% keyword.

f <floor>

File was given a floor: the lowest release, a number from 1 to 9998, which may be get for editing.

c <ceiling>

File was given a ceiling: a number less than or equal to 9999, which can be retrieved by a get command.

d <default sid>

File was given a default delta number SID.

n

File created null deltas for skipped major versions.

j

File was flagged to allow concurrent edits on the same SID.

l <lock releases>

File was given a list of releases to which deltas can no longer be made.

q <user defined text>

File has a user defined value for the %Q% keyword.

x

File was flagged to set execution bit on get.

z <reserved for use in interfaces>

File was flagged to set execution bit on get.

comment

The comment that was added when the file was created.

current

In scalar context returns the current revision number. That is the number of the file that would be restored by get with no arguments.

In list context, it returns the current revision, version and parts of the version, something like (70, "5.39", 5, 39, undef, undef). The last 4 numbers are the equivalent of the keywords %R%, %L%, %B%, and %S% for that release.

Delta functions

delta

NYI

version =item version (<revision>)

If called without argument, it returns the last version, just as the second return value of current () in list context.

If called with a revision argument, it returns you the version that matches that revision. It returns undef if no matching version is found.

revision =item revision (<version>)

If called without argument, it returns the last revision, just as current () returns in scalar context.

If called with a version argument, it returns you the revision that matches that version. It returns undef if no matching revision is found.

revision_map

Returns an anonymous list of revision - version pairs (in anonymous lists).

Content function

body =item body (<revision>) =item body (<version>)

In scalar context returns the full body for the given revision. If no revision is passed, the current (most recent) revision is used. If a version is passed, the matching revision will be used. If the is no matching version or revision, body () returns undef.

In list context, body () returns the list of chomped lines for the given revision.

diff

NYI

translate_keywords

NYI

plan is to accept either a single string, like "CVS", or "RCS" and translate the SCCS keywords to the corresponding CVS or RCS keywords (if possible), or to accept a hash that defines a translation table and have VCS::SCCS fill in the missing entries with defaults.

SPECIFICATION

SCCS file format is reasonable well documented. I have included a manual page for sccsfile for HP-UX in doc/

EXAMPLES

See the files in examples/ for my attempts to start convertors to other VCSs

LIMITATIONS

As this module is created as a base for conversion to more useful and robust VCSs, it is a read-only interface to the SCCS files.

BUGS

Tested on our own repositories with perl-5.8.x-dor and perl-5.10.0.

TODO

* improve documentation * implement delta () and diff () * more tests * sccs2rcs * sccs2cvs * sccs2git * sccs2hg * sccs2svn * errors and warnings * provide hooks to VCS::

DIAGNOSTICS

First errors, than diagnostics ...

SEE ALSO

SCCS - http://en.wikipedia.org/wiki/Source_Code_Control_System

CSSC - https://sourceforge.net/projects/cssc A GNU project that aims to be a drop-in replacement for SCCS. It is written in c++ and therefor disqualifies to be used at any older OS that does support SCCS but has no C++ compiler. And even if you have one, there is a good chance it won't build or does not bass the basic tests. I didn't get it to work.

VCS - http://search.cpan.org/dist/VCS

AUTHOR

H.Merijn Brand <h.m.brand@xs4all.nl>

COPYRIGHT AND LICENSE

Copyright (C) 2007-2007 H.Merijn Brand

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.