jinx 2.1.1 → 2.1.2

data/History.md

@@ -1,6 +1,10 @@
 This history lists major release themes. See the GitHub commits (https://github.com/jinx/core)
 for change details.
 
+2.1.2 / 2012-06-12
+------------------
+* Fine-tune introspection.
+
 2.1.1 / 2012-04-13
 ------------------
 * Initial public release spun off from caruby/core.

data/lib/jinx.rb

@@ -1,3 +1,2 @@
 require 'jinx/helpers/log'
-require 'jinx/helpers/error'
 require 'jinx/resource'

data/lib/jinx/cli/application.rb

@@ -19,16 +19,16 @@ module Jinx
       # * improve the output messages
       # * print an exception to stderr as well as the log
       def start(*args, &block)
-        status = 1
+        rc = 1
         begin
-          status = run(*args, &block)
+          rc = run(*args, &block)
         rescue
           log(FATAL, "#{@appname} detected an exception: #{$!}\n#{$@.qp}")
           msg = "#{@appname} was unsuccessful: #{$!}."
           msg += "\nSee the log #{Log.instance.file} for more information." if Log.instance.file
           $stderr.puts msg
         ensure
-          log(INFO, "#{@appname} completed with status #{status}.")
+          log(INFO, "#{@appname} completed with status #{rc}.")
         end
       end
     end

data/lib/jinx/cli/command.rb

@@ -105,7 +105,7 @@ module Jinx
 
       # @param [{Symbol => Object}] opts the option => value hash
       def call_executor(opts)
-         if @executor.nil? then Jinx.fail(CommandError, "Command #{self} does not have an execution block") end
+         if @executor.nil? then raise CommandError.new("Command #{self} does not have an execution block") end
          @executor.call(opts)
       end
       

data/lib/jinx/helpers/array.rb

@@ -4,7 +4,7 @@ class Array
   # The EMPTY_ARRAY constant is an immutable empty array, used primarily as a default argument.
   class << EMPTY_ARRAY ||= Array.new
     def <<(value)
-      Jinx.fail(NotImplementedError, "Modification of the constant empty array is not supported")
+      raise NotImplementedError.new("Modification of the constant empty array is not supported")
     end
   end
 
@@ -64,7 +64,7 @@ class Array
   def to_assoc_hash
     hash = {}
     each do |item|
-      Jinx.fail(ArgumentError, "Array member must be an array: #{item.pp_s(:single_line)}") unless Array === item
+      raise ArgumentError.new("Array member must be an array: #{item.pp_s(:single_line)}") unless Array === item
       key = item.first
       if item.size < 2 then
         value = nil
@@ -100,7 +100,7 @@ class Array
     rescue NoMethodError
       raise e
     rescue
-      Jinx.fail(ArgumentError, "Can't convert #{other.class.name} to array")
+      raise ArgumentError.new("Can't convert #{other.class.name} to array")
     end
   end
 

data/lib/jinx/helpers/associative.rb

@@ -0,0 +1,41 @@
+require 'jinx/helpers/options'
+module Jinx
+  # An Associative object implements a {#[]} method. 
+  class Associative
+    # @yield [key] the associated oject
+    # @yieldparam key the key to find
+    def initialize(&accessor)
+      @accessor = accessor
+    end
+     
+    # @param key the key to find
+    # @return the associated object
+    def [](key)
+      @accessor.call(key)
+    end
+
+    # @yield [key] the associated oject
+    # @yieldparam key the key to find
+    # @return [Associative] a new Associative with a +[]=+ writer method 
+    def writer(&writer)
+      Writable.new(self, &writer)
+    end
+  end
+  
+  private
+  
+  class Writable < Associative
+    def initialize(base, &writer)
+      @base = base
+      @writer = writer
+    end
+    
+    def [](key)
+      @base[key]
+    end
+    
+    def []=(key, value)
+      @writer.call(key, value)
+    end
+  end
+end

data/lib/jinx/helpers/collections.rb

@@ -1,5 +1,4 @@
 # This file loads the definitions of useful collection mix-ins and utility classes.
-
 require 'jinx/helpers/collection'
 require 'jinx/helpers/array'
 require 'jinx/helpers/hashable'

data/lib/jinx/helpers/enumerable.rb

@@ -31,7 +31,7 @@ module Enumerable
   # @raise [ArgumentError] if the generator block is not given
   # @see #hashify
   def to_compact_hash
-    Jinx.fail(ArgumentError, "Compact hash builder is missing the value generator block") unless block_given?
+    raise ArgumentError.new("Compact hash builder is missing the value generator block") unless block_given?
     to_compact_hash_with_index { |item, index| yield item }
   end
 
@@ -159,6 +159,9 @@ module Enumerable
   # Returns an Enumerable which iterates over items in this Enumerable and the other Enumerable in sequence.
   # Unlike the Array plus (+) operator, {#union} reflects changes to the underlying enumerators.
   #
+  # @quirk Cucumber Cucumber defines it's own Enumerable union monkey-patch. Work around this in the short
+  #   term by trying to call the super first.
+  #
   # @example
   #   a = [1, 2]
   #   b = [4, 5]
@@ -170,7 +173,7 @@ module Enumerable
   # @param [Enumerable] other the Enumerable to compose with this Enumerable
   # @return [Enumerable] an enumerator over self followed by other
   def union(other)
-    Jinx::MultiEnumerator.new(self, other)
+    super rescue Jinx::MultiEnumerator.new(self, other)
   end
 
   alias :+ :union

data/lib/jinx/helpers/hash.rb

@@ -6,7 +6,7 @@ class Hash
   # The EMPTY_HASH constant is an immutable empty hash, used primarily as a default argument.
   class << EMPTY_HASH ||= Hash.new
     def []=(key, value)
-      Jinx.fail(NotImplementedError, "Modification of the constant empty hash is not supported")
+      raise NotImplementedError.new("Modification of the constant empty hash is not supported")
     end
   end
 end

data/lib/jinx/helpers/hashable.rb

@@ -392,7 +392,7 @@ module Jinx
       attr_reader :components
 
       def initialize(*hashes)
-        if hashes.include?(nil) then Jinx.fail(ArgumentError, "MultiHash is missing a component hash.") end
+        if hashes.include?(nil) then raise ArgumentError.new("MultiHash is missing a component hash.") end
         @components = hashes
       end
 
@@ -465,12 +465,6 @@ module Jinx
       @xfm = transformer
     end
 
-    # @param key the untransformed hash key
-    # @return the value for the transformed key
-    def [](key)
-      @base[@xfm.call(@base[key])]
-    end
-
     # @yield [key, value] operate on the transformed key and value
     # @yieldparam key the transformed hash key
     # @yieldparam value the hash value

data/lib/jinx/helpers/inflector.rb

@@ -7,7 +7,7 @@ class String
   #   "rose".quantify(3) #=> "roses"
   #   "rose".quantify(1 #=> "rose"
   def quantify(quantity)
-    Jinx.fail(ArgumentError, "Missing quantity argument") if quantity.nil?
+    raise ArgumentError.new("Missing quantity argument") if quantity.nil?
     "#{quantity} #{quantity == 1 ? self : pluralize}"
   end
   

data/lib/jinx/helpers/log.rb

@@ -3,15 +3,19 @@ require 'singleton'
 require 'ftools'
 require 'jinx/helpers/collections'
 require 'jinx/helpers/options'
+require 'jinx/helpers/inflector'
 
+# @param [String, IO, nil] dev the optional log file or device
 # @return [Jinx::MultilineLogger] the global logger
-def logger
-  Jinx.logger
+def logger(dev=nil, opts=nil)
+  Jinx.logger(dev, opts)
 end
 
 module Jinx
-  # @return (see Log#logger)
-  def self.logger
+  # @param [String, IO, nil] dev the optional log file or device
+  # @return [Jinx::MultilineLogger] the global logger
+  def self.logger(dev=nil, opts=nil)
+    Log.instance.open(dev, opts) if dev or opts
     Log.instance.logger
   end
   
@@ -45,17 +49,27 @@ module Jinx
   class Log
     include Singleton
     
-    # Opens the log.
+    # Opens the log. The default log location is determined from the application name.
+    # The application name is the value of the +:app+ option, or +Jinx+ by default.
+    # For an application +MyApp+, the log location is determined as follows:
+    # * +/var/log/my_app.log+ for Linux
+    # * +%LOCALAPPDATA%\MyApp\log\MyApp.log+ for Windows
+    # * +./log/MyApp.log+ otherwise
+    # The default file must be creatable or writable. If the device argument is not
+    # provided and there is no suitable default log file, then logging is disabled.
     #
-    # @param [String, IO, nil] dev the log file or device (default STDOUT)
+    # @param [String, IO, nil] dev the log file or device
     # @param [Hash, nil] opts the logger options
+    # @option opts [String] :app the application name
     # @option opts [Integer] :shift_age the number of log files retained in the rotation
     # @option opts [Integer] :shift_size the maximum size of each log file
     # @option opts [Boolean] :debug whether to include debug messages in the log file
     # @return [MultilineLogger] the global logger
     def open(dev=nil, opts=nil)
       raise RuntimeError.new("Log already open") if open?
-      if String === dev then File.makedirs(File.dirname(dev)) end
+      dev, opts = nil, dev if Hash === dev
+      dev ||= default_log_file(Options.get(:app, opts)) 
+      FileUtils.mkdir_p(File.dirname(dev)) if String === dev
       # default is 4-file rotation @ 16MB each
       shift_age = Options.get(:shift_age, opts, 4)
       shift_size = Options.get(:shift_size, opts, 16 * 1048576)
@@ -97,10 +111,48 @@ module Jinx
     private
     
     # Stream-lined log format.
-    FORMAT = %{%s [%s] %5s %s\n}   
+    FORMAT = %{%s [%s] %5s %s\n}
+               
+    # The default log file.
+    LINUX_LOG_DIR = '/var/log'
     
-    def same_file?(f1, f2)
-      f1 == f2 or (String === f2 and String === f1 and File.expand_path(f1) == File.expand_path(f2))
+    # Returns the log file, as described in {#open}.
+    #
+    # If the standard Linux log location exists, then try that.
+    # Otherwise, try the conventional Windows app data location.
+    # If all else fails, use the working directory.
+    #
+    # The file must be creatable or writable.
+    #
+    # @param [String, nil] app the application name (default +jinx+) 
+    # @return [String] the file name
+    def default_log_file(app=nil)
+      app ||= 'Jinx'
+      default_linux_log_file(app) || default_windows_log_file(app) || "log/#{app}.log"
+    end
+      
+    # @param [String] app the application name
+    # @return [String, nil] the default file name
+    def default_linux_log_file(app)
+      return unless File.exists?(LINUX_LOG_DIR)
+      base = app.underscore.gsub(' ', '_')
+      file = File.expand_path("#{base}.log", LINUX_LOG_DIR)
+      log = file if File.exists?(file) ? File.writable?(file) : File.writable?(LINUX_LOG_DIR)
+      log || '/dev/null'
+    end
+    
+    # @param [String] app the application name 
+    # @return [String, nil] the default file name
+    def default_windows_log_file(app)
+      # the conventional Windows app data location  
+      app_dir = ENV['LOCALAPPDATA'] || return
+      dir = app_dir + "/#{app}/log"
+      file = File.expand_path("#{app}.log", dir)
+      if File.exists?(file) ? File.writable?(file) : (File.directory?(dir) ? File.writable?(dir) : File.writable?(app_dir)) then
+        file
+      else
+        'NUL'
+      end
     end
   end
-end
+end

data/lib/jinx/helpers/math.rb

@@ -1,12 +1,21 @@
-# Extends the Numeric class with max and min methods. 
-class Numeric
-  # Returns the minimum of this Numeric and the other Numerics.
-  def min(*others)
-    others.inject(self) { |min, other| other < min ? other : min }
+module Jinx
+  module Math
+    # @param [<Numeric>] the numbers to compare
+    # @return [Numeric] the smallest number
+    def self.min(*args)
+      args.inject { |m, n| m < n ? m : n }
+    end
+    
+    # @param [<Numeric>] the numbers to compare
+    # @return [Numeric] the largest number
+    def self.max(*args)
+      args.inject { |m, n| m < n ? n : m }
+    end
+    
+    # @param value the value to check
+    # @return [Boolean] whether the value is a Ruby or Java number
+    def self.numeric?(value)
+      Numeric === value or Java::JavaLang::Number === value
+    end
   end
-
-  # Returns the minimum of this Numeric and the other Numerics.
-  def max(*others)
-    others.inject(self) { |max, other| other > max ? other : max }
-  end
-end
+end

data/lib/jinx/helpers/options.rb

@@ -17,7 +17,7 @@ class Options
   # If default is nil and a block is given to this method, then the default is determined
   # by calling the block with no arguments. The block can also be used to raise a missing
   # option exception, e.g.:
-  #   Options.get(:userid, options) { Jinx.fail(RuntimeError, "Missing required option: userid") }
+  #   Options.get(:userid, options) { raise RuntimeError.new("Missing required option: userid") }
   #
   # @example
   #   Options.get(:create, {:create => true}) #=> true
@@ -41,7 +41,7 @@ class Options
       when Symbol then
         option == options or default(default, &block)
       else
-        Jinx.fail(ArgumentError, "Options argument type is not supported; expected Hash or Symbol, found: #{options.class}")
+        raise ArgumentError.new("Options argument type is not supported; expected Hash or Symbol, found: #{options.class}")
     end
   end
 
@@ -64,7 +64,7 @@ class Options
       case opt
         when Symbol then hash[opt] = true
         when Hash then hash.merge!(opt)
-        else Jinx.fail(ArgumentError, "Expected a symbol or hash option, found #{opt.qp}")
+        else raise ArgumentError.new("Expected a symbol or hash option, found #{opt.qp}")
       end
     end
     hash
@@ -74,7 +74,7 @@ class Options
   # @raise [ValidationError] if the given options are not in the given allowable choices
   def self.validate(options, choices)
     to_hash(options).each_key do |opt|
-      Jinx.fail(ValidationError, "Option is not supported: #{opt}") unless choices.include?(opt)
+      raise ValidationError.new("Option is not supported: #{opt}") unless choices.include?(opt)
     end
   end
 

data/lib/jinx/helpers/pretty_print.rb

@@ -4,7 +4,6 @@ require 'pp'
 require 'stringio'
 require 'jinx/helpers/options'
 require 'jinx/helpers/collections'
-
 require 'jinx/helpers/inflector'
 
 class PrettyPrint

data/lib/jinx/helpers/transitive_closure.rb

@@ -29,7 +29,7 @@ class Object
   #   a.transitive_closure { |node| node.children }.to_a.join(", ") #=> a, b, c, d
   #   a.transitive_closure(:children).to_a.join(", ") #=> a, b, c, d
   def transitive_closure(method=nil)
-    Jinx.fail(ArgumentError, "Missing both a method argument and a block") if method.nil? and not block_given?
+    raise ArgumentError.new("Missing both a method argument and a block") if method.nil? and not block_given?
     # If there is a method argument, then the transitive closure is based on that method.
     # Otherwise, visit the closure in reverse depth-first order.
     if method then

data/lib/jinx/helpers/uniquifier.rb

@@ -24,27 +24,60 @@ module Jinx
     def initialize
       @cache = Jinx::LazyHash.new { Hash.new }
     end
-
-    # @param obj the object containing the value
-    # @param value the value to make unique
-    # @return the new unique value, or nil if the given value is nil
-    def uniquify(obj, value)
-      @cache[obj.class][value] ||= value.uniquify if value
+    
+    # Returns a relatively unique String for the given base String object or
+    # (object, String value) pair. In the former case, each call returns a distinct value.
+    # In the latter case, successive calls of the same String value for the same object
+    # class return the same unique value.
+    #
+    # This method is useful to transform a String object key to a unique value for testing
+    # purposes.
+    #
+    # The unique value is comprised of a prefix and suffix. The prefix is the base value
+    # with spaces replaced by an underscore. The suffix is a {Jinx::Uniquifier.qualifier}
+    # converted to digits and lower-case letters, excluding the digits 0, 1 and characters
+    # l, o to avoid confusion.
+    #
+    # @example
+    #   Jinx::Uniquifier.instance.uniquify('Groucho') #=> Groucho_wiafye6e
+    #   Jinx::Uniquifier.instance.uniquify('Groucho') #=> Groucho_uqafye6e
+    #   Jinx::Uniquifier.instance.uniquify('Groucho Marx') #=> Groucho_ay23ye6e
+    #   Jinx::Uniquifier.instance.uniquify(person, 'Groucho') #=> Groucho_wy874e6e
+    #   Jinx::Uniquifier.instance.uniquify(person, 'Groucho') #=> Groucho_wy87ye6e
+    #
+    # @param obj the object containing the value to uniquify
+    # @param value [String, nil] the value to make unique, or nil if the containing object is a String
+    # @return [String, nil] the new unique value, or nil if the containing object is a String
+    #   and the given value is nil
+    def uniquify(obj, value=nil)
+      if String === obj then
+        to_unique(obj)
+      elsif value then
+        @cache[obj.class][value] ||= to_unique(value)
+      end
     end
 
     def clear
       @cache.clear
     end
-  end
-end
-
-class String
-  # Returns a relatively unique value obtained from the specified base value.
-  # The suffix is generated by {Jinx::Uniquifier.qualifier}. Spaces are removed.
-  #
-  # @example
-  #   'Test Name'.uniquify #=> Test_Name_330938800614
-  def uniquify
-    gsub(' ', '_') + "_#{Jinx::Uniquifier.qualifier}"
+    
+    private
+    
+    CHARS = 'abcdefghijkmnpqrstuvwxyz23456789'
+    
+    # @param value [String, nil] the value to make unique
+    # @return [String] the new unique value, or nil if the given value is nil
+    # @raise [ArgumentError] if value is neither a String nor nil
+    def to_unique(value)
+      return if value.nil?
+      raise ArgumentError.new("#{value.qp} is not a String") unless String === value
+      s = ''
+      n = Jinx::Uniquifier.qualifier
+      while n > 0 do
+        n, m = n.divmod(32)
+        s << CHARS[m]
+      end
+      [value.gsub(' ', '_'), s].join('_')
+    end
   end
 end