cvs2svn_lib/revision_manager.py

   1 # (Be in -*- python -*- mode.)
   2 #
   3 # ====================================================================
   4 # Copyright (c) 2000-2008 CollabNet.  All rights reserved.
   5 #
   6 # This software is licensed as described in the file COPYING, which
   7 # you should have received as part of this distribution.  The terms
   8 # are also available at http://subversion.tigris.org/license-1.html.
   9 # If newer versions of this license are posted there, you may use a
  10 # newer version instead, at your option.
  11 #
  12 # This software consists of voluntary contributions made by many
  13 # individuals.  For exact contribution history, see the revision
  14 # history and logs, available at http://cvs2svn.tigris.org/.
  15 # ====================================================================
  16
  17 """This module describes the interface to the CVS repository."""
  18
  19
  20 class RevisionCollector(object):
  21   """Optionally collect revision information for CVS files."""
  22
  23   def __init__(self):
  24     """Initialize the RevisionCollector.
  25
  26     Please note that a RevisionCollector is instantiated in every
  27     program run, even if the data-collection pass will not be
  28     executed.  (This is to allow it to register the artifacts that it
  29     produces.)  Therefore, the __init__() method should not do much,
  30     and more substantial preparation for use (like actually creating
  31     the artifacts) should be done in start()."""
  32
  33     pass
  34
  35   def register_artifacts(self, which_pass):
  36     """Register artifacts that will be needed while collecting data.
  37
  38     WHICH_PASS is the pass that will call our callbacks, so it should
  39     be used to do the registering (e.g., call
  40     WHICH_PASS.register_temp_file() and/or
  41     WHICH_PASS.register_temp_file_needed())."""
  42
  43     pass
  44
  45   def start(self):
  46     """Data will soon start being collected.
  47
  48     Any non-idempotent initialization should be done here."""
  49
  50     pass
  51
  52   def process_file(self, cvs_file_items):
  53     """Collect data for the file described by CVS_FILE_ITEMS.
  54
  55     CVS_FILE_ITEMS has already been transformed into the logical
  56     representation of the file's history as it should be output.
  57     Therefore it is not necessarily identical to the history as
  58     recorded in the RCS file.
  59
  60     This method is allowed to store a pickleable object to the
  61     CVSItem.revision_reader_token member of CVSItems in
  62     CVS_FILE_ITEMS.  These data are stored with the items and
  63     available for the use of the RevisionReader."""
  64
  65     raise NotImplementedError()
  66
  67   def finish(self):
  68     """All recording is done; clean up."""
  69
  70     pass
  71
  72
  73 class NullRevisionCollector(RevisionCollector):
  74   """A do-nothing variety of RevisionCollector."""
  75
  76   def process_file(self, cvs_file_items):
  77     pass
  78
  79
  80 class RevisionReader(object):
  81   """An object that can read the contents of CVSRevisions."""
  82
  83   def register_artifacts(self, which_pass):
  84     """Register artifacts that will be needed during branch exclusion.
  85
  86     WHICH_PASS is the pass that will call our callbacks, so it should
  87     be used to do the registering (e.g., call
  88     WHICH_PASS.register_temp_file() and/or
  89     WHICH_PASS.register_temp_file_needed())."""
  90
  91     pass
  92
  93   def start(self):
  94     """Prepare for calls to get_content()."""
  95
  96     pass
  97
  98   def get_content(self, cvs_rev):
  99     """Return the contents of CVS_REV.
 100
 101     CVS_REV is a CVSRevision.  The way that the contents are extracted
 102     is influenced by properties that are set on CVS_REV:
 103
 104     * The CVS_REV property _keyword_handling specifies how RCS/CVS
 105       keywords should be handled:
 106
 107       * 'collapsed' -- collapse RCS/CVS keywords in the output; e.g.,
 108         '$Author: jrandom $' -> '$Author$'.
 109
 110       * 'expanded' -- expand RCS/CVS keywords in the output; e.g.,
 111         '$Author$' -> '$Author: jrandom $'.
 112
 113       * 'untouched' -- leave RCS/CVS keywords untouched.  For a file
 114         that had keyword expansion enabled in CVS, this typically
 115         means that the keyword comes out expanded as for the
 116         *previous* revision, because CVS expands keywords on checkout,
 117         not checkin.
 118
 119       * unset -- undefined behavior; depends on which revision manager
 120         is being used.
 121
 122     * The CVS_REV property _eol_fix specifies how EOL sequences should
 123       be handled in the output.  If the property is unset or empty,
 124       then leave EOL sequences untouched.  If it is non-empty, then
 125       convert all end-of-line sequences to the value of that property
 126       (typically '\n' or '\r\n').
 127
 128     See doc/properties.txt and doc/text-transformations.txt for more
 129     information.
 130
 131     If Ctx().decode_apple_single is set, then extract the data fork
 132     from any content that looks like AppleSingle format."""
 133
 134     raise NotImplementedError()
 135
 136   def finish(self):
 137     """Inform the reader that all calls to get_content() are done.
 138
 139     Start may be called again at a later point."""
 140
 141     pass
 142
 143