s4t-utils 1.0.0

data/data/make-s4t-project/sub-lib-skeleton

@@ -0,0 +1,3 @@
+module !REPLACE_ME_MODULE!
+  # Your code here
+end

data/data/make-s4t-project/test-skeleton

@@ -0,0 +1,28 @@
+# This file should be copied into a test ending in 'tests.rb' so that
+# the Rakefile knows it's a test.
+
+require "set-standalone-test-paths.rb" unless $started_from_rakefile
+require 'test/unit'
+require 's4t-utils'
+include S4tUtils
+
+## Require either the particular file under test like this:
+# require '!REPLACE_ME_FILE!/my-file'
+## or the entire package:
+# require '!REPLACE_ME_FILE!'
+
+class TestName < Test::Unit::TestCase
+  ## You probably want to include your library so that you don't have
+  ## to tack !REPLACE_ME_MODULE!:: onto every name, but I won't assume
+  ## that.
+  # include !REPLACE_ME_MODULE!
+
+  def setup
+  end
+
+  def teardown
+  end
+
+  def test_something
+  end
+end

data/data/make-s4t-project/version-skeleton

@@ -0,0 +1,3 @@
+module !REPLACE_ME_MODULE!
+  Version = '0.1.0'
+end

data/lib/s4t-utils.rb

@@ -0,0 +1,23 @@
+require 's4t-utils/capturing-globals'
+require 's4t-utils/error-handling'
+require 's4t-utils/more-assertions'
+require 's4t-utils/claims'
+require 's4t-utils/friendly-format'
+require 's4t-utils/rake-task-helpers'
+require 's4t-utils/svn-file-movement'
+require 's4t-utils/hacks'
+require 's4t-utils/command-line'
+require 's4t-utils/test-util'
+require 's4t-utils/os'
+
+require 'pp'
+
+# Tolerate typos
+S4TUtils=S4tUtils   
+S4tUtil=S4tUtils   
+S4TUtil=S4tUtils   
+
+# Note, unless otherwise noted, all methods defined in S4tUtils 
+# are both module functions and instance functions.
+module S4tUtils
+end

data/lib/s4t-utils/capturing-globals.rb

@@ -0,0 +1,93 @@
+require 'stringio'
+
+module S4tUtils
+
+  module_function
+
+  # Run the block, capturing output to $stderr in a string.
+  # That string is the method's return value.
+  def capturing_stderr
+    old_stderr = $stderr
+    new_stderr = StringIO.new
+    begin
+      $stderr = new_stderr
+      yield
+    ensure
+      $stderr = old_stderr
+    end
+    new_stderr.string
+  end
+
+  # Run the block, replacing the values of environment variables
+  # with the values given in the hash _settings_. The environment
+  # variables are restored when the method returns.
+  def with_environment_vars(settings)
+    begin
+      old = {}
+      settings.each { | key, value |
+        old[key] = ENV[key]
+        ENV[key] = value
+      }
+      yield
+    ensure
+      settings.each_key { | key |
+        ENV[key] = old[key]
+      }
+    end
+  end
+
+  # Run the block with the _HOME_ environment variable set to the 
+  # current working directory.
+  def with_home_right_here
+    begin
+      old_home = ENV['HOME']
+      ENV['HOME'] = '.'
+      yield
+    ensure
+      ENV['HOME'] = @old_home
+    end
+  end
+
+  # Run the block with the given _file_ (named by a string) deleted before
+  # and after.
+  def erasing_local_config_file(file)
+    with_home_right_here { 
+      begin
+        File.delete(file) if File.exist?(file)
+        yield
+      ensure
+        File.delete(file) if File.exist?(file)
+      end
+    }
+  end
+
+  # Run the block. During the execution, the contents of _file_ (named by 
+  # a string) is replaced with _contents_.
+  def with_local_config_file(file, contents)
+    erasing_local_config_file(file) do
+      File.open(file, 'w') do | io |
+        io.puts(contents.to_s)
+      end
+      yield
+    end
+  end
+
+  # Run the block. During execution, _ARGV_'s is set as if the 
+  # script had been executed with _string_ as its argument list.
+  # If the block tries to exit, with_command_args will instead throw
+  # a StandardError.
+  def with_command_args(string)
+    begin
+      old_argv = ARGV.dup
+      ARGV.replace(string.split)
+      yield
+    rescue SystemExit => ex
+      replacement = StandardError.new(ex.message)
+      replacement.set_backtrace(ex.backtrace)
+      raise replacement
+    ensure
+      ARGV.replace(old_argv)
+    end
+  end
+
+end

data/lib/s4t-utils/claims.rb

@@ -0,0 +1,20 @@
+module S4tUtils
+
+  module_function
+
+  # A StandardError is thrown if the _fact_ the user claims is true
+  # is actually false. The _block_ is called to provide the exception
+  # message.
+  def user_claims(fact, &block)
+    raise StandardError.new(block.call) unless fact
+  end
+
+  # A StandardError is thrown if the _fact_ the user disputes is
+  # nevertheless true. The _block_ is called to provide the exception
+  # message.
+  def user_disputes(fact, &block)
+    user_claims(!fact, &block)
+  end
+end
+
+

data/lib/s4t-utils/command-line.rb

@@ -0,0 +1,18 @@
+module S4tUtils
+
+  module_function
+
+  # Ask the question contained in the _question_lines_, prompt, and
+  # wait for an answer. If the stripped value read from STDIN is 
+  # empty, use the _default_answer_.
+  def ask(default_answer, *question_lines)
+    puts question_lines
+    print "[#{default_answer}] => "
+    answer = STDIN.readline.strip
+    answer = default_answer.to_s if answer == ''
+    answer
+  end
+
+end
+
+

data/lib/s4t-utils/error-handling.rb

@@ -0,0 +1,26 @@
+module S4tUtils
+
+  module_function
+
+  # Typically used to wrap the execution of an entire script. 
+  # If an exception is thrown, a terse message is printed (to $stderr)
+  # instead of a stack dump. The message printed is gotten from the 
+  # exception.
+  def with_pleasant_exceptions
+    yield
+  rescue SystemExit
+    raise
+  rescue Exception => ex
+    $stderr.puts(ex.message)
+  end
+
+  # with_pleasant_exceptions swallows the stack trace, which you
+  # want to see during debugging. The easy way to see it is to add
+  # 'out' to that message, producing this one. To reduce the chance
+  # you'll forget to make exceptions pleasant again, a note that 
+  # exceptions are turned off is always printed to $stderr.
+  def without_pleasant_exceptions
+    $stderr.puts "Note: exception handling turned off."
+    yield
+  end
+end

data/lib/s4t-utils/friendly-format.rb

@@ -0,0 +1,35 @@
+#--
+# Note: see also <http://englishext.rubyforge.org/>
+#++
+
+module S4tUtils
+
+  module_function
+
+  # Use _connector_ to join _array_ into a human-friendly list.
+  #
+  #
+  #    friendly_list("or", [1])   => "'1'"
+  #    friendly_list("or"), [1, 2]  => "'1' or '2'"
+  #    friendly_list("or"), [1, 2, 3] => "'1', '2', or '3'"
+  def friendly_list(connector, array)
+    quoted = array.collect { | elt | "'" + elt.to_s + "'" }
+    case array.length
+    when 0
+      ""
+    when 1
+      quoted[0]
+    when 2
+      quoted[0] + " #{connector} " + quoted[1]
+    else
+      quoted[0...-1].join(", ") + ", #{connector} #{quoted.last}"
+    end
+  end
+
+  # Produces a version of a string that can be typed after a :
+  # (Can also be safely given at a command-line prompt.)
+  def symbol_safe_name(name)
+    name.to_s.gsub(/\W/, '')
+  end
+end
+

data/lib/s4t-utils/hacks.rb

@@ -0,0 +1,55 @@
+module S4tUtils
+
+  module_function
+
+  # The return value of prog1 is the _retval_. Before that's returned,
+  # though, the _retval_ is yielded to the block. This method is an 
+  # alternative to stashing a value in a temporary, fiddling around, then
+  # returning the temporary. Here's an example:
+  #
+  #     prog1(1+1) { | s | puts "Sum is #{s}."}   # => 2
+  #
+  # The name "prog1" is ancient Lisp jargon.
+  def prog1(retval)
+    yield(retval)
+    retval
+  end
+  
+  # A way of putting debugging statements in code that requires less
+  # typing than +puts+.
+  #
+  #     pi [1, 2, 3], 'input'    # => 'input: [1, 2, 3]
+  #
+  # The _arg_ is printed using +inspect+. If _leader_ isn't given, 
+  # nothing is printed before _arg_.
+  #
+  # pi returns its _arg_, which is occasionally useful for sticking
+  # debugging into the middle of complicated expressions.
+  def pi(arg, leader=nil)
+     leader = (leader == nil) ? '' : leader + ': '
+     prog1(arg) { puts leader + arg.inspect }
+   end
+  
+
+
+  # An ArgForwarder is associated with a _target_. It forwards messages
+  # sent to it to the target, passing along any arguments to the method. 
+  # So far, so boring. But an ArgForwarder is also created with some 
+  # _added_args_. When the ArgForwarder forwards, it prepends those
+  # _added_args_ to the message's given arguments.
+  #
+  #   array = []
+  #   forwarder = ArgForwarder.new(array, 5)
+  #   forwarder.push
+  #   assert_equal([5], array)
+  class ArgForwarder
+    def initialize(target, *added_args)
+      @target = target
+      @added_args = added_args
+    end
+
+    def method_missing(method, *args) # :nodoc:
+      @target.send(method, *(@added_args + args))
+    end
+  end
+end

data/lib/s4t-utils/load-path-auto-adjuster.rb

@@ -0,0 +1,120 @@
+# This is loaded by an executable script in one of two cases:
+#
+# It's a development version living in the bin part of this directory
+# structure (but it can invoked from any place).
+#
+#   project/
+#     bin/
+#     lib/
+#        project/
+#           third-party/
+#              s4t-utils/
+#                 this file
+#
+# It's a deployed version living in some random place, with 
+# the site_ruby directory in the page.
+#
+#   site_ruby/1.8/
+#      project/
+#        third-party/
+#           s4t-utils/
+#              this file
+#
+#
+# In order for this file to have been required in both cases, the following
+# code is executed in the caller:
+#
+#
+# $:.unshift((Pathname.new(__FILE__).parent.parent + 'lib').to_s)
+# require 'package/third-party/s4t-utils/load-path-auto-adjuster'
+#
+# In the first case, that will put something like "../lib" on the load
+# path.  In the second case, it will put harmless garbage on the path
+# (harmless because it won't contain this file, which will still be
+# found somewhere later in the load path). 
+#
+# The first thing this file does is pop that off, it having done its job.
+# In the first (development) case, it puts the following on the load path:
+#        project/lib & project/lib/project/third-party & project
+# ('project' is added so that <require 'test/util-file'> works.)
+#
+#    In the second, it adds only the third-party library and takes care
+#    to add it just after whatever component in the path contains this
+#    file. (It will thus not interfere with clashing packages earlier
+#    in the path.) 
+#        site_ruby/1.8/project/third-party
+#    since site_ruby/1.8 (or the equivalent) is already on there.
+
+require 'rubygems'
+require 'pathname'
+
+module S4tUtils
+  module Hidden  # :nodoc: all
+
+    class Arranger
+      def initialize(third_party)
+        @third_party_lib = third_party
+        @project_lib = third_party.parent.parent
+        @test_util_root = @project_lib.parent
+      end
+
+      def self.arrange_path_around(third_party)
+        new(third_party).arrange
+      end
+
+      def arrange
+        add_third_party_gems
+        if project_lib_already_in_path?
+          just_add_third_party_after_project_lib
+        else
+          add_everything_at_front
+        end
+      end
+        
+
+      def add_third_party_gems
+        # When RubyGems 0.8.11 gets clear_paths, it does not clear the
+        # cache used by Gem's overriding version of require(), so if
+        # this is loaded after the first Gem is required, it will have
+        # no effect on later uses of require(). (But it does affect
+        # require_gem.)
+        # 
+        ENV['GEM_PATH']=(@third_party_lib+'gems').to_s
+        Gem.clear_paths
+      end
+
+      def project_lib_already_in_path?
+        $:.include?(@project_lib.to_s)
+      end
+
+      def just_add_third_party_after_project_lib
+        $:.each_with_index do | path_element, index |
+          if path_element == @project_lib.to_s
+            $:[index+1,0] = @third_party_lib.to_s
+            return
+          end
+        end
+        fail "No place to put third_party library."
+      end
+
+      def add_everything_at_front
+        $:.unshift(@test_util_root.to_s)  
+        $:.unshift(@third_party_lib.to_s)
+        $:.unshift(@project_lib.to_s)  # This is now first
+      end
+    end
+
+    def self.auto_adjust_load_path
+      $:.shift   # Remove extra element used to find this file.
+      
+      # Having loaded us, __FILE__ is something like this:
+      # ...lib.../package/third-party/s4t-utils/load-path-auto-adjuster.rb
+      relative_third_party = Pathname.new(__FILE__).parent.parent
+      # Pathname#real_path doesn't work on Windows (1.8.2). Grr.
+      third_party = Pathname.new(File.expand_path(relative_third_party.to_s))
+      Arranger.arrange_path_around(third_party)
+    end
+
+    auto_adjust_load_path
+  end
+end

data/lib/s4t-utils/more-assertions.rb

@@ -0,0 +1,35 @@
+module Test
+  module Unit
+
+    # Some additional Test::Unit assertions.
+    module Assertions
+      # Same as +assert+. I just like it better.
+      def assert_true(boolean, message = nil)
+        assert(boolean, message)
+      end
+
+      # Assert that the _boolean_ is false.
+      def assert_false(boolean, message = nil)
+        _wrap_assertion do
+          assert_block(build_message(message, "<?> should be false or nil.", boolean)) { !boolean }
+        end
+      end
+
+      # Like +assert_raise+, but the raised exception must contain a
+      # +message+ matching (as in +assert_match+) the _message_ argument.
+      def assert_raise_with_matching_message(exception_class, message, &block)
+        exception = assert_raise(exception_class, &block)
+        assert_match(message, exception.message)
+      end
+      alias_method :assert_raises_with_matching_message,
+                   :assert_raise_with_matching_message
+
+      # Assert that the block tried to +exit+. 
+      def assert_wants_to_exit
+        assert_raise(SystemExit) do
+          yield
+        end
+      end
+    end
+  end
+end