rscm 0.3.16 → 0.4.0

data/CHANGES

@@ -1,5 +1,19 @@
 = RSCM Changelog
 
+== Version 0.4.0
+
+This release of RSCM modifies mosts API methods to take an options Hash (or alternatively, setting
+the default_options attribute), allowing better capturing of the underlying SCM's IO (stdout/stderr)
+
+* Introduced named parameters for several API methods.
+* Added RSCM::VERSION
+* Fixed incorrect arguments to poll_new_revisions in revision_poller.rb
+* Added Base.to_identifier(raw_identifier) for type conversion to the native revision type.
+* Removed support for directory listings (No use case for it anymore, keep things simpler)
+* checkout no longer yields new files, only returns an array (primarily used for testing)
+* Better.popen removed in favour of RSCM::CommandLine.
+* Stdout and stderr logs are now written to disk.
+
 == Version 0.3.16
 
 Bugfix release

data/README

@@ -1,4 +1,4 @@
-= RSCM - Ruby Source Control Management (0.3.16)
+= RSCM - Ruby Source Control Management (0.4.0)
 
 RSCM is to SCM what DBI/JDBC/ODBC are to databases - an SCM-independent API for accessing different SCMs. The high level features are roughly:
 
@@ -8,8 +8,9 @@ RSCM is to SCM what DBI/JDBC/ODBC are to databases - an SCM-independent API for
 * Add and commit files
 * Manipluate triggers
 
-Although RSCM's main focus is operations on a working copy of an SCM repository, the API also allows some level of interaction
-with the SCM repository itself, like creating new repositories.
+Although RSCM's main focus is operations on a working copy of an SCM repository, 
+the API also allows some level of interaction with the SCM repository itself, 
+like creating new repositories.
 
 == Download
 
@@ -17,10 +18,14 @@ RSCM is available as a RubyGem, and can be installed like this:
 
   gem install rscm
 
-(You may need administer access to do this on a POSIX system).
-If you want the latest and greatest, you can get the sources, which live alongside DamageControl's sources:
+(You may need administrator access to do this on a POSIX system).
+If you want the latest and greatest, you can get the sources:
 
-* See the DamageControl Developer Guide at http://hieraki.lavalamp.ca/
+Anonymous:
+  svn co svn://svn.damagecontrol.codehaus.org/damagecontrol/scm/trunk/rscm
+
+Developers:
+  svn co svn+ssh://developer@beaver.codehaus.org/home/projects/damagecontrol/scm/trunk/rscm
 
 == Contributors
 
@@ -33,10 +38,10 @@ If you want the latest and greatest, you can get the sources, which live alongsi
 
 * CVS - http://www.nongnu.org/cvs (stable)
 * Subversion - http://subversion.tigris.org (stable)
-* ClearCase - http://www-306.ibm.com/software/awdtools/clearcase (not thoroughly tested)
 
 In progress:
 
+* ClearCase - http://www-306.ibm.com/software/awdtools/clearcase (not thoroughly tested)
 * Darcs - http://www.abridgegame.org/darcs (very incomplete)
 * Monotone - http://www.venge.net/monotone (half complete)
 * Perforce - http://www.perforce.com (nearly complete - a little out of date with recent API)
@@ -48,7 +53,8 @@ Loads! All of them! How to add support for a new one is described further down i
 
 == Related projects
 
-* DamageControl - http://damagecontrol.codehaus.org. DamageControl adds a web interface to RSCM and tons of other features for continuous integration.
+* DamageControl - http://damagecontrol.buildpatterns.com. DamageControl is a Continuous Integration system
+built around RSCM and Ruby on Rails.
 
 == Sample usage
 
@@ -57,6 +63,7 @@ Here is an example of how to use RSCM to get a list of revisions (aka changesets
   require 'rscm'
   
   scm = RSCM::Subversion.new("svn://some.server/some/path/trunk")
+  scm.default_options = {:stdout => "stdout.log", :stderr => "stderr.log"}
   # What follows would look the same for any supported SCM
   revisions = scm.revisions(Time.utc(2004, 11, 10, 12, 34, 22)) # For Subversion, you can also pass a revision number (int)
   revisions.each do |revision|

data/Rakefile

@@ -7,10 +7,11 @@ require 'rake/gempackagetask'
 require 'rake/contrib/sshpublisher'
 require 'rake/contrib/rubyforgepublisher'
 require 'meta_project'
+require 'lib/rscm/version'
 
 PKG_BUILD     = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
 PKG_NAME      = 'rscm'
-PKG_VERSION   = '0.3.16' + PKG_BUILD
+PKG_VERSION   = RSCM::VERSION::STRING + PKG_BUILD
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 
 desc "Default Task"
@@ -32,6 +33,9 @@ Rake::TestTask.new { |t|
   t.libs << "test"
   t.test_files = fl
   t.verbose = true
+  
+  # turn on code coverage
+  #t.ruby_opts << "-rcoverage/coverage"
 }
 
 rd = Rake::RDocTask.new { |rdoc|

data/lib/rscm.rb

@@ -1,6 +1,7 @@
 require 'rscm/path_converter'
 require 'rscm/difftool'
-require 'rscm/better'
+require 'rscm/platform'
+require 'rscm/command_line'
 require 'rscm/base'
 require 'rscm/revision'
 require 'rscm/revision_poller'

data/lib/rscm/base.rb

@@ -3,48 +3,20 @@ require 'rscm/revision'
 require 'rscm/path_converter'
 
 module RSCM
-  # This class defines the RSCM API. The documentation of the various methods
-  # uses CVS and Subversion's terminology. (For example, checkout means 'get working copy',
-  # not 'lock for private edit' as in ClearCase or VSS terminology).
+  # This class defines the RSCM API, which offers access to an SCM working copy
+  # as well as a 'central' repository.
   #
-  # Concrete subclasses of this class provide an API to manage a local working copy
-  # as well as an associated 'central' repository. The main responsibility is working
-  # copy operations:
+  # Concrete subclasses of this class (concrete adapters) implement the integration
+  # with the respective SCMs.
   #
-  # * add
-  # * checkout
-  # * checked_out?
-  # * diff
-  # * edit
-  # * ls
-  # * move
-  # * revisions
-  # * uptodate?
-  # * file
-  # * destroy_working_copy
+  # Most of the methods take an optional +options+ Hash (named parameters), allowing
+  # the following options:
   #
-  # In addition to operations related to working copies, the same instance should provide
-  # methods to administer the working copy's associated 'central' repository. These are:
+  # * <tt>:stdout</tt>: Path to file name where stdout of SCM operations are written.
+  # * <tt>:stdout</tt>: Path to file name where stderr of SCM operations are written.
   #
-  # * central_exists?
-  # * create_central
-  # * can_create_central?
-  # * import_central
-  # * install_trigger
-  # * supports_trigger? / can_install_trigger?
-  # * trigger_installed?
-  # * trigger_mechanism
-  # * uninstall_trigger
-  #
-  # Some methods are a bit fuzzy with respect to their relevance to the working copy or
-  # the associated central repository, as it depends on the nature of the individual underlying 
-  # SCMs. These methods are:
-  #
-  # * checkout_command_line
-  # * label
-  # * name
-  # * transactional? / atomic?
-  # * update_command_line
+  # In stead of specifying the +options+ parameters for every API method, it's possible
+  # to assign default options via the +default_options+ attribute.
   #
   # Some of the methods in this API use +from_identifier+ and +to_identifier+.
   # These identifiers can be either a UTC Time (according to the SCM's clock)
@@ -54,29 +26,30 @@ module RSCM
   # If +from_identifier+ or +to_identifier+ are +nil+ they should respectively default to
   # Time.epoch or Time.infinite.
   #
-  # TODO: rename this superclass to 'Base'
-  #
   class Base
 
-# TODO: Make revisions yield revisions as they are determined, to avoid
-# having to load them all into memory before the method exits. Careful not to
-# use yielded revisions to do another scm hit - like get diffs. Some SCMs
-# might dead lock on this. Implement a guard for that.
-# TODO: Add some visitor support here too?
-
-  public
+    attr_accessor :default_options
   
+    # Transforms +raw_identifier+ into the native rype used for revisions.
+    def to_identifier(raw_identifier)
+      raw_identifier.to_s
+    end
+  
+    # Sets the checkout dir (working copy). Should be set prior to most other method
+    # invocations (depending on the implementation).
     def checkout_dir=(dir)
       @checkout_dir = PathConverter.filepath_to_nativepath(dir, false)
     end
   
+    # Gets the working copy directory.
     def checkout_dir
       @checkout_dir
     end
 
-    def to_yaml_properties
+    def to_yaml_properties #:nodoc:
       props = instance_variables
       props.delete("@checkout_dir")
+      props.delete("@default_options")
       props.sort!
     end
 
@@ -85,8 +58,7 @@ module RSCM
       FileUtils.rm_rf(checkout_dir) unless checkout_dir.nil?
     end
 
-    # Whether the physical SCM represented by this instance exists.
-    #
+    # Whether or not the SCM represented by this instance exists.
     def central_exists?
       # The default implementation assumes yes - override if it can be
       # determined programmatically.
@@ -94,7 +66,6 @@ module RSCM
     end
     
     # Whether or not this SCM is transactional (atomic).
-    #
     def transactional?
       false
     end
@@ -103,12 +74,12 @@ module RSCM
     # Creates a new 'central' repository. This is intended only for creation of 'central'
     # repositories (not for working copies). You shouldn't have to call this method if a central repository
     # already exists. This method is used primarily for testing of RSCM, but can also
-    # be used if you *really* want to create a central repository. 
+    # be used if you *really* want to use RSCM to create a central repository. 
     # 
     # This method should throw an exception if the repository cannot be created (for
     # example if the repository is 'remote' or if it already exists).
     #
-    def create_central
+    def create_central(options={})
       raise NotImplementedError
     end
     
@@ -125,28 +96,29 @@ module RSCM
     end
 
     # Adds +relative_filename+ to the working copy.
-    def add(relative_filename)
+    def add(relative_filename, options={})
       raise NotImplementedError
     end
 
     # Schedules a move of +relative_src+ to +relative_dest+
     # Should not take effect in the central repository until
     # +commit+ is invoked.
-    def move(relative_src, relative_dest)
+    def move(relative_src, relative_dest, options={})
       raise NotImplementedError
     end
 
-    # Recursively imports files from a +dir+ into the central scm
-    def import_central(dir, message)
-      raise "Not implemented"
+    # Recursively imports files from <tt>:dir</tt> into the central scm,
+    # using commit message <tt>:message</tt>
+    def import_central(options)
+      raise NotImplementedError
     end
 
     # Open a file for edit - required by scms that check out files in read-only mode e.g. perforce
-    def edit(file)
+    def edit(file, options={})
     end
     
     # Commit (check in) modified files.
-    def commit(message)
+    def commit(message, options={})
       raise NotImplementedError
     end
     
@@ -166,12 +138,14 @@ module RSCM
     # For some SCMs this is not possible, or at least very hard. In that case, just override
     # the checkout_silent method instead of this method (should be protected).
     #
-    def checkout(to_identifier=Time.infinity) # :yield: file
+    def checkout(to_identifier=Time.infinity, options={}) # :yield: file
+      to_identifier=Time.infinity if to_identifier.nil?
+
       # the OS doesn't store file timestamps with fractions.
       before_checkout_time = Time.now.utc - 1
 
       # We expect subclasses to implement this as a protected method (unless this whole method is overridden).
-      checkout_silent(to_identifier)
+      checkout_silent(to_identifier, options)
       files = Dir["#{@checkout_dir}/**/*"]
       added = []
       files.each do |file|
@@ -184,9 +158,6 @@ module RSCM
         File.file?(path)
       end
       relative_added_file_paths = to_relative(checkout_dir, added_file_paths)
-      relative_added_file_paths.each do |path|
-        yield path if block_given?
-      end
       relative_added_file_paths
     end
   
@@ -194,7 +165,7 @@ module RSCM
     # and +to_identifier+ (inclusive). If +relative_path+ is specified, the result will only contain
     # revisions pertaining to that path.
     #
-    def revisions(from_identifier, to_identifier=Time.infinity, relative_path=nil)
+    def revisions(from_identifier, options={})
       raise NotImplementedError
     end
     
@@ -208,11 +179,6 @@ module RSCM
       HistoricFile.new(relative_path, dir, self)
     end
     
-    # Returns an Array of the children under +relative_path+
-    def ls(relative_path)
-      raise NotImplementedError
-    end
-    
     # Opens a revision_file
     def open(revision_file, &block) #:yield: io
       raise NotImplementedError
@@ -222,12 +188,8 @@ module RSCM
     # repository's revision/time identified by +identifier+. 
     # If +identifier+ is nil, 'HEAD' of repository should be assumed.
     #
-    # TODO: rename to in_synch?
     def uptodate?(identifier)
-      # Suboptimal algorithm that works for all SCMs.
-      # Subclasses can override this to improve efficiency.
-      
-      revisions(identifier).empty?
+      raise NotImplementedError
     end
 
     # Whether the project is checked out from the central repository or not.
@@ -300,6 +262,19 @@ module RSCM
     end
 
   protected
+  
+    # Wrapper for CommandLine.execute that provides default values for 
+    # dir plus any options set in default_options (typically stdout and stderr).
+    def execute(cmd, options={}, &proc)
+      default_dir = @checkout_dir.nil? ? Dir.pwd : @checkout_dir
+      options = {:dir => default_dir}.merge(default_options).merge(options)
+      begin
+        CommandLine.execute(cmd, options, &proc)
+      rescue CommandLine::OptionError => e
+        e.message += "\nEither specify default_options on the scm object, or pass the required options to the method"
+        raise e
+      end
+    end
 
     # Takes an array of +absolute_paths+ and turns it into an array
     # of paths relative to +dir+

data/lib/rscm/command_line.rb

@@ -0,0 +1,66 @@
+module RSCM
+  # Utility for running a +cmd+ in a +dir+ with a specified +env+.
+  # If a block is passed, the standard out stream is passed to that block (and returns)
+  # the result from the block. Otherwise, if a block is not passed, standard output
+  # is redirected to +stdout_file+. The standard error stream is always redirected
+  # to +stderr_file+. Note that both +stdout_file+ and +stderr_file+ must always
+  # be specified with non-nil values, as both of them will always have the command lines
+  # written to them.
+  module CommandLine
+    class OptionError < StandardError; end
+    class ExecutionError < StandardError
+      attr_reader :cmd, :dir, :exitstatus, :stderr      
+      def initialize(cmd, dir, exitstatus, stderr); @cmd, @dir, @exitstatus, @stderr = cmd, dir, exitstatus, stderr; end
+      def to_s
+        "\ndir       : #{@dir}\n" +
+        "command   : #{@cmd}\n" +
+        "exitstatus: #{@exitstatus}\n" +
+        "stderr    : #{@stderr}\n"
+      end
+    end
+    
+    def execute(cmd, options={}, &proc)
+      options = {
+        :dir => Dir.pwd,
+        :env => {},
+        :exitstatus => 0
+      }.merge(options)
+      
+      raise OptionError.new(":stdout can't be nil") if options[:stdout].nil?
+      raise OptionError.new(":stderr can't be nil") if options[:stderr].nil?
+      options[:stdout] = File.expand_path(options[:stdout])
+      options[:stderr] = File.expand_path(options[:stderr])
+
+      commands = cmd.split("&&").collect{|c| c.strip}
+      Dir.chdir(options[:dir]) do
+        redirected_cmd = commands.collect do |c|
+          redirection = block_given? ? "#{c} 2>> #{options[:stderr]}" : "#{c} >> #{options[:stdout]} 2>> #{options[:stderr]}"
+
+          "echo #{RSCM::Platform.prompt} #{c} >> #{options[:stdout]} && " +
+          "echo #{RSCM::Platform.prompt} #{c} >> #{options[:stderr]} && " +
+          redirection
+        end.join(" && ")
+
+        options[:env].each{|k,v| ENV[k]=v}
+        begin
+          IO.popen(redirected_cmd) do |io|
+            if(block_given?)
+              return(proc.call(io))
+            else
+              io.read
+            end
+          end
+        rescue Errno::ENOENT => e
+          File.open(options[:stderr], "a") {|io| io.write(e.message)}
+        ensure
+          if($?.exitstatus != options[:exitstatus])
+            error_message = File.exist?(options[:stderr]) ? File.read(options[:stderr]) : "#{options[:stderr]} doesn't exist"
+            raise ExecutionError.new(cmd, options[:dir], $?.exitstatus, error_message)
+          end
+        end
+      end
+      $?.exitstatus
+    end
+    module_function :execute
+  end
+end

data/lib/rscm/historic_file.rb

@@ -13,8 +13,8 @@ module RSCM
     end
     
     # Returns an Array of RevisionFile - from Time.epoch until Time.infinity (now)
-    def revision_files
-      @scm.revisions(Time.epoch, Time.infinity, @relative_path).collect do |revision|
+    def revision_files(options={})
+      @scm.revisions(Time.epoch, options.dup.merge({:to_identifier => Time.infinity, :relative_path => @relative_path})).collect do |revision|
         if revision.files.length != 1
           files_s = revision.files.collect{|f| f.to_s}.join("\n")
           raise "The file-specific revision didn't have exactly one file, but #{revision.files.length}:\n#{files_s}"
@@ -26,9 +26,5 @@ module RSCM
       end
     end
     
-    def children
-      raise "Not a directory" unless directory?
-      @scm.ls(@relative_path)
-    end
   end
 end