rewritten and documented
diff --git a/Demo/pdist/rcslib.py b/Demo/pdist/rcslib.py
index 5e4ecc0..7c68543 100755
--- a/Demo/pdist/rcslib.py
+++ b/Demo/pdist/rcslib.py
@@ -1,168 +1,82 @@
-"""Base local RCS interface module.
+"""RCS interface module.
-Provides simplified interface to RCS controlled files. Unabashedly
-ripped most of this from RCSProxy.py which had in some respects, more
-than I needed, and in others, not enough. I think RCSProxy.py could
-be rewritten using this module as a base.
+Defines the class RCS, which represents a directory with rcs version
+files and (possibly) corresponding work files.
+
"""
-__version__ = "guido's, based on: rcs.py,v 1.2 1995/06/22 21:11:37 bwarsaw Exp"
-
-import string
+import fnmatch
import os
+import regsub
+import string
import tempfile
-okchars = string.letters + string.digits + '-_=+.'
+class RCS:
-class RCSDirectory:
+ """RCS interface class (local filesystem version).
- def __init__(self, directory=None):
- self._dirstack = []
- if directory:
- self.cd(directory)
+ An instance of this class represents a directory with rcs version
+ files and (possible) corresponding work files.
- def _close(self):
- while self._dirstack:
- self.back()
+ Methods provide access to most rcs operations such as
+ checkin/checkout, access to the rcs metadata (revisions, logs,
+ branches etc.) as well as some filesystem operations such as
+ listing all rcs version files.
- def pwd(self):
- return os.getcwd()
+ XXX BUGS / PROBLEMS
- def cd(self, name):
- save = os.getcwd()
- os.chdir(name)
- self._dirstack.append(save)
+ - The instance always represents the current directory so it's not
+ very useful to have more than one instance around simultaneously
- def back(self):
- if not self._dirstack:
- raise os.error, "empty directory stack"
- dir = self._dirstack[-1]
- os.chdir(dir)
- del self._dirstack[-1]
+ """
- def _filter(self, files, pat = None):
- if pat:
- def keep(name, pat = pat):
- return fnmatch.fnmatch(name, pat)
- files = filter(keep, files)
- files.sort()
- return files
+ # Characters allowed in work file names
+ okchars = string.letters + string.digits + '-_=+.'
- def isfile(self, name):
- namev = self.rcsname(name)
- return namev and (os.path.isfile(namev) or \
- os.path.isfile(os.path.join('RCS', namev)))
+ def __init__(self):
+ """Constructor."""
+ pass
- def isrcs(self, name):
- return name[-2:] == ',v'
+ def __del__(self):
+ """Destructor."""
+ pass
- def rcsname(self, name):
- if self.isrcs(name): namev = name
- else: namev = name + ',v'
- if os.path.isfile(namev): return namev
- namev = os.path.join('RCS', namev)
- if os.path.isfile(namev): return namev
- return None
+ # --- Informational methods about a single file/revision ---
- def realname(self, namev):
- if self.isrcs(namev): name = namev[:-2]
- else: name = namev
- if os.path.isfile(name): return name
- name = os.path.basename(name)
- if os.path.isfile(name): return name
- return None
+ def log(self, name_rev, otherflags = ''):
+ """Print the full log text for NAME_REV on stdout.
- def islocked(self, name):
- f = self._open(name, 'rlog -L -R')
- line = f.readline()
- self._closepipe(f)
- if not line: return None
- return not self.realname(name) == self.realname(line)
+ Optional OTHERFLAGS are passed to rlog.
- def _unmangle(self, name):
- if type(name) == type(''):
- rev = ''
- else:
- name, rev = name
- return name, rev
+ """
+ name, rev = self.checkfile(name_rev)
+ cmd = "rlog -r%s %s %s" % (rev, name, otherflags)
+ return self._system(cmd)
- def checkfile(self, name):
- name, rev = self._unmangle(name)
- if not self.isfile(name):
- raise os.error, 'not an rcs file %s' % `name`
- for c in rev:
- if c not in okchars:
- raise ValueError, "bad char in rev"
- return name, rev
+ def head(self, name_rev):
+ """Return the head revision for NAME_REV"""
+ dict = self.info(name_rev)
+ return dict['head']
- def listfiles(self, pat = None):
- files = os.listdir(os.curdir)
- files = filter(self.isrcs, files)
- if os.path.isdir('RCS'):
- files2 = os.listdir('RCS')
- files2 = filter(self.isrcs, files2)
- files = files + files2
- files = map(self.realname, files)
- return self._filter(files, pat)
+ def info(self, name_rev):
+ """Return a dictionary of info (from rlog -h) for NAME_REV
- def listsubdirs(self, pat = None):
- files = os.listdir(os.curdir)
- files = filter(os.path.isdir, files)
- return self._filter(files, pat)
+ The dictionary's keys are the keywords that rlog prints
+ (e.g. 'head' and its values are the corresponding data
+ (e.g. '1.3').
- def isdir(self, name):
- return os.path.isdir(name)
+ XXX symbolic names and locks are not returned
- def _open(self, name, cmd = 'co -p'):
- name, rev = self.checkfile(name)
- namev = self.rcsname(name)
- if rev:
- cmd = cmd + ' -r' + rev
- return os.popen('%s %s' % (cmd, `namev`))
-
- def _closepipe(self, f):
- sts = f.close()
- if sts:
- raise IOError, "Exit status %d" % sts
-
- def _remove(self, fn):
- try:
- os.unlink(fn)
- except os.error:
- pass
-
- def _list(self, function, list):
- if list is None:
- list = self.listfiles()
- res = []
- for name in list:
- try:
- res.append((name, function(name)))
- except (os.error, IOError):
- res.append((name, None))
- return res
-
- def _dict(self, function, list):
- if list is None:
- list = self.listfiles()
- dict = {}
- for name in list:
- try:
- dict[name] = function(name)
- except (os.error, IOError):
- pass
- return dict
-
- def info(self, name):
- f = self._open(name, 'rlog -h')
+ """
+ f = self._open(name_rev, 'rlog -h')
dict = {}
while 1:
line = f.readline()
if not line: break
if line[0] == '\t':
- # TBD: could be a lock or symbolic name
+ # XXX could be a lock or symbolic name
# Anything else?
continue
i = string.find(line, ':')
@@ -172,59 +86,233 @@
self._closepipe(f)
return dict
- def head(self, name):
- dict = self.info(name)
- return dict['head']
+ # --- Methods that change files ---
- def log(self, name, flags = ''):
- f = self._open(name, 'rlog %s 2>&1' % flags)
- log = f.read()
- self._closepipe(f)
- return log
+ def lock(self, name_rev):
+ """Set an rcs lock on NAME_REV."""
+ name, rev = self.checkfile(name_rev)
+ cmd = "rcs -l%s %s" % (rev, name)
+ return self._system(cmd)
- def get(self, name, withlock=None, otherflags=""):
- """a.k.a. co"""
- name, rev = self._unmangle(name)
- if not self.isfile(name):
- raise os.error, 'not an rcs file %s' % `name`
+ def unlock(self, name_rev):
+ """Clear an rcs lock on NAME_REV."""
+ name, rev = self.checkfile(name_rev)
+ cmd = "rcs -u%s %s" % (rev, name)
+ return self._system(cmd)
+
+ def checkout(self, name_rev, withlock=0, otherflags=""):
+ """Check out NAME_REV to its work file.
+
+ If optional WITHLOCK is set, check out locked, else unlocked.
+
+ The optional OTHERFLAGS is passed to co without
+ interpretation.
+
+ Any output from co goes to directly to stdout.
+
+ """
+ name, rev = self.checkfile(name_rev)
if withlock: lockflag = "-l"
else: lockflag = "-u"
- cmd = 'co %s%s %s %s 2>&1' % (lockflag, rev, otherflags, name)
- sts = os.system(cmd)
- if sts: raise IOError, "bad co exit status %d" % sts
+ cmd = 'co %s%s %s %s' % (lockflag, rev, otherflags, name)
+ return self._system(cmd)
- def put(self, name, message=None, otherflags=""):
- """a.k.a. ci"""
+ def checkin(self, name_rev, message=None, otherflags=""):
+ """Check in NAME_REV from its work file.
+
+ The optional MESSAGE argument becomes the checkin message
+ (default "<none>" if None); or the file description if this is
+ a new file.
+
+ The optional OTHERFLAGS argument is passed to ci without
+ interpretation.
+
+ Any output from ci goes to directly to stdout.
+
+ """
+ name, rev = self._unmangle(name_rev)
+ new = not self.isvalid(name)
if not message: message = "<none>"
if message and message[-1] != '\n':
message = message + '\n'
- name, rev = self._unmangle(name)
- new = not self.isfile(name)
- # by default, check it in -u so we get an unlocked copy back
- # in the current directory
+ lockflag = "-u"
textfile = None
try:
if new:
- for c in name:
- if c not in okchars:
- raise ValueError, "bad char in name"
textfile = tempfile.mktemp()
f = open(textfile, 'w')
f.write(message)
f.close()
- cmd = 'ci -u%s -t%s %s %s 2>&1' % \
- (rev, textfile, otherflags, name)
+ cmd = 'ci %s%s -t%s %s %s' % \
+ (lockflag, rev, textfile, otherflags, name)
else:
- cmd = 'ci -u%s -m"%s" %s %s 2>&1' % \
- (rev, message, otherflags, name)
-
- sts = os.system(cmd)
- if sts: raise IOError, "bad ci exit status %d" % sts
+ message = regsub.gsub('\([\\"$`]\)', '\\\\\\1', message)
+ cmd = 'ci %s%s -m"%s" %s %s' % \
+ (lockflag, rev, message, otherflags, name)
+ return self._system(cmd)
finally:
if textfile: self._remove(textfile)
- def mkdir(self, name):
- os.mkdir(name, 0777)
+ # --- Exported support methods ---
- def rmdir(self, name):
- os.rmdir(name)
+ def listfiles(self, pat = None):
+ """Return a list of all version files matching optional PATTERN."""
+ files = os.listdir(os.curdir)
+ files = filter(self._isrcs, files)
+ if os.path.isdir('RCS'):
+ files2 = os.listdir('RCS')
+ files2 = filter(self._isrcs, files2)
+ files = files + files2
+ files = map(self.realname, files)
+ return self._filter(files, pat)
+
+ def isvalid(self, name):
+ """Test whether NAME has a version file associated."""
+ namev = self.rcsname(name)
+ return (os.path.isfile(namev) or
+ os.path.isfile(os.path.join('RCS', namev)))
+
+ def rcsname(self, name):
+ """Return the pathname of the version file for NAME.
+
+ The argument can be a work file name or a version file name.
+ If the version file does not exist, the name of the version
+ file that would be created by "ci" is returned.
+
+ """
+ if self._isrcs(name): namev = name
+ else: namev = name + ',v'
+ if os.path.isfile(namev): return namev
+ namev = os.path.join('RCS', os.path.basename(namev))
+ if os.path.isfile(namev): return namev
+ if os.path.isdir('RCS'):
+ return os.path.join('RCS', namev)
+ else:
+ return namev
+
+ def realname(self, namev):
+ """Return the pathname of the work file for NAME.
+
+ The argument can be a work file name or a version file name.
+ If the work file does not exist, the name of the work file
+ that would be created by "co" is returned.
+
+ """
+ if self._isrcs(namev): name = namev[:-2]
+ else: name = namev
+ if os.path.isfile(name): return name
+ name = os.path.basename(name)
+ return name
+
+ def islocked(self, name_rev):
+ """Test whether FILE (which must have a version file) is locked.
+
+ XXX This does not tell you which revision number is locked and
+ ignores any revision you may pass in (by virtue of using rlog
+ -L -R).
+
+ """
+ f = self._open(name_rev, 'rlog -L -R')
+ line = f.readline()
+ self._closepipe(f)
+ if not line: return None
+ return self.realname(name_rev) == self.realname(line)
+
+ def checkfile(self, name_rev):
+ """Normalize NAME_REV into a (NAME, REV) tuple.
+
+ Raise an exception if there is no corresponding version file.
+
+ """
+ name, rev = self._unmangle(name_rev)
+ if not self.isvalid(name):
+ raise os.error, 'not an rcs file %s' % `name`
+ return name, rev
+
+ # --- Internal methods ---
+
+ def _open(self, name_rev, cmd = 'co -p', rflag = '-r'):
+ """INTERNAL: open a read pipe to NAME_REV using optional COMMAND.
+
+ Optional FLAG is used to indicate the revision (default -r).
+
+ Default COMMAND is "co -p".
+
+ Return a file object connected by a pipe to the command's
+ output.
+
+ """
+ name, rev = self.checkfile(name_rev)
+ namev = self.rcsname(name)
+ if rev:
+ cmd = cmd + ' ' + rflag + rev
+ return os.popen('%s %s' % (cmd, `namev`))
+
+ def _unmangle(self, name_rev):
+ """INTERNAL: Normalize NAME_REV argument to (NAME, REV) tuple.
+
+ Raise an exception if NAME contains invalid characters.
+
+ A NAME_REV argument is either NAME string (implying REV='') or
+ a tuple of the form (NAME, REV).
+
+ """
+ if type(name_rev) == type(''):
+ name_rev = name, rev = name_rev, ''
+ else:
+ name, rev = name_rev
+ for c in rev:
+ if c not in self.okchars:
+ raise ValueError, "bad char in rev"
+ return name_rev
+
+ def _closepipe(self, f):
+ """INTERNAL: Close PIPE and print its exit status if nonzero."""
+ sts = f.close()
+ if sts:
+ raise IOError, "Exit status %d" % sts
+
+ def _system(self, cmd):
+ """INTERNAL: run COMMAND in a subshell.
+
+ Standard input for the command is taken fron /dev/null.
+
+ Raise IOError when the exit status is not zero.
+
+ Return whatever the calling method should return; normally
+ None.
+
+ A derived class may override this method and redefine it to
+ capture stdout/stderr of the command and return it.
+
+ """
+ cmd = cmd + " </dev/null"
+ sts = os.system(cmd)
+ if sts: raise IOError, "command exit status %d" % sts
+
+ def _filter(self, files, pat = None):
+ """INTERNAL: Return a sorted copy of the given list of FILES.
+
+ If a second PATTERN argument is given, only files matching it
+ are kept. No check for valid filenames is made.
+
+ """
+ if pat:
+ def keep(name, pat = pat):
+ return fnmatch.fnmatch(name, pat)
+ files = filter(keep, files)
+ else:
+ files = files[:]
+ files.sort()
+ return files
+
+ def _remove(self, fn):
+ """INTERNAL: remove FILE without complaints."""
+ try:
+ os.unlink(fn)
+ except os.error:
+ pass
+
+ def _isrcs(self, name):
+ """INTERNAL: Test whether NAME ends in ',v'."""
+ return name[-2:] == ',v'