jinx 2.1.1

data/lib/jinx/helpers/inflector.rb

@@ -0,0 +1,36 @@
+require 'jinx/active_support/inflector'
+
+class String
+  # @param [Numeric] quantity the amount qualifier
+  # @return [String] this String qualified by a plural if the quantity is not 1
+  # @example
+  #   "rose".quantify(3) #=> "roses"
+  #   "rose".quantify(1 #=> "rose"
+  def quantify(quantity)
+    Jinx.fail(ArgumentError, "Missing quantity argument") if quantity.nil?
+    "#{quantity} #{quantity == 1 ? self : pluralize}"
+  end
+  
+  # @return [String] this String with the first letter capitalized and other letters preserved
+  # @example
+  #   "rosesAreRed".capitalize_first #=> "RosesAreRed"
+  def capitalize_first
+    sub(/(?:^)(.)/) { $1.upcase }
+  end
+  
+  # @return [String] this String with a leading indefinite article
+  # @example
+  #   "rose".indefinitize #=> "a rose"
+  #   "eagle".indefinitize #=> "an eagle"
+  def indefinitize
+    article = self =~ /^[aeiou]/i ? 'an' : 'a'
+    "#{article} #{self}"
+  end
+  
+  # @return [String] this String with the first letter decapitalized and other letters preserved
+  # @example
+  #   "RosesAreRed".decapitalize #=> "rosesAreRed"
+  def decapitalize
+    sub(/(?:^)(.)/) { $1.downcase }
+  end
+end

data/lib/jinx/helpers/key_transformer_hash.rb

@@ -0,0 +1,43 @@
+require 'jinx/helpers/hashable'
+
+module Jinx
+  # The KeyTransformerHash class pipes the key access argument into a transformer block before
+  # accessing a base Hashable, e.g.:
+  #   hash = KeyTransformerHash.new { |key| key % 2 }
+  #   hash[1] = :a
+  #   hash[3] #=> :a
+  class KeyTransformerHash
+    include Hashable
+
+    # Creates a KeyTransformerHash on the optional base hash and required key transformer block.
+    #
+    # @param [Hash, nil] base the hash to transform
+    # @yield [key] transforms the base key
+    # @yieldparam key the base key to transform
+    def initialize(base={}, &transformer)
+      @base = base
+      @xfm = transformer
+    end
+
+    # Returns the value at key after this KeyTransformerHash's transformer block is applied to the key,
+    # or nil if the base hash does not contain an association for the transformed key.
+    def [](key)
+      @base[@xfm.call(key)]
+    end
+
+    # Sets the value at key after this KeyTransformerHash's transformer block is applied, or nil
+    # if this hash does not contain an association for the transformed key.
+    def []=(key, value)
+      @base[@xfm.call(key)] = value
+    end
+
+    # Delegates to the base hash.
+    # Note that this breaks the standard Hash contract, since
+    #   all? { |k, v| self[k] }
+    # is not necessarily true because the key is transformed on access.
+    # @see Accessor for a KeyTransformerHash variant that restores this contract
+    def each(&block)
+      @base.each(&block)
+    end
+  end
+end

data/lib/jinx/helpers/lazy_hash.rb

@@ -0,0 +1,44 @@
+require 'jinx/helpers/options'
+
+module Jinx
+  # A Hash that creates a new entry on demand.
+  class LazyHash < Hash
+    # Creates a new Hash with the specified value factory proc.
+    # The factory proc has one argument, the key.
+    # If access by key fails, then a new association is created
+    # from the key to the result of calling the factory proc.
+    #
+    # Example:
+    #   hash = LazyHash.new { |key| key.to_s }
+    #   hash[1] = "1"
+    #   hash[1] #=> "1"
+    #   hash[2] #=> "2"
+    #
+    # If a block is not provided, then the default association value is nil, e.g.:
+    #   hash = LazyHash.new
+    #   hash.has_key?(1) #=> false
+    #   hash[1] #=> nil
+    #   hash.has_key?(1) #=> true
+    #
+    # A nil key always returns nil. There is no hash entry for nil, e.g.:
+    #   hash = LazyHash.new { |key| key }
+    #   hash[nil] #=> nil
+    #   hash.has_key?(nil) #=> false
+    #
+    # If the :compact option is set, then an entry is not created
+    # if the value initializer result is nil or empty, e.g.:
+    #   hash = LazyHash.new { |n| 10.div(n) unless n.zero? }
+    #   hash[0] #=> nil
+    #   hash.has_key?(0) #=> false
+    def initialize(options=nil)
+      reject_flag = Options.get(:compact, options)
+      # Make the hash with the factory block
+      super() do |hash, key|
+        if key then
+          value = yield key if block_given?
+          hash[key] = value unless reject_flag and value.nil_or_empty?
+        end
+      end
+    end
+  end
+end

data/lib/jinx/helpers/log.rb

@@ -0,0 +1,106 @@
+require 'logger'
+require 'singleton'
+require 'ftools'
+require 'jinx/helpers/collections'
+require 'jinx/helpers/options'
+
+# @return [Jinx::MultilineLogger] the global logger
+def logger
+  Jinx.logger
+end
+
+module Jinx
+  # @return (see Log#logger)
+  def self.logger
+    Log.instance.logger
+  end
+  
+  # Extends the standard Logger to format multi-line messages on separate lines.
+  class MultilineLogger < ::Logger
+    # @see Logger#initialize
+    def initialize(*args)
+      super
+    end
+    
+    # Rackify the logger with a write method, in conformance with
+    # the [Rack spec](http://rack.rubyforge.org/doc/SPEC.html).
+    alias :write :<<
+  
+    private
+  
+    # Writes msg to the log device. Each line in msg is formatted separately.
+    #
+    # @param (see Logger#format_message)
+    # @return (see Logger#format_message)
+    def format_message(severity, datetime, progname, msg)
+      if String === msg then
+        msg.inject('') { |s, line| s << super(severity, datetime, progname, line.chomp) }
+      else
+        super
+      end
+    end
+  end
+  
+  # Wraps a standard global Logger.
+  class Log
+    include Singleton
+    
+    # Opens the log.
+    #
+    # @param [String, IO, nil] dev the log file or device (default STDOUT)
+    # @param [Hash, nil] opts the logger options
+    # @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
+      # default is 4-file rotation @ 16MB each
+      shift_age = Options.get(:shift_age, opts, 4)
+      shift_size = Options.get(:shift_size, opts, 16 * 1048576)
+      @logger = MultilineLogger.new(dev, shift_age, shift_size)
+      @logger.level = Options.get(:debug, opts) ? Logger::DEBUG : Logger::INFO
+      @logger.formatter = lambda do |severity, time, progname, msg|
+        FORMAT % [
+          progname || 'I',
+          DateTime.now.strftime("%d/%b/%Y %H:%M:%S"),
+          severity,
+          msg]
+      end
+      @dev = dev
+      @logger
+    end
+    
+    # @return [Boolean] whether the logger is open 
+    def open?
+      !!@logger
+    end
+    
+    # Closes and releases the {#logger}.
+    def close
+      @logger.close
+      @logger = nil
+    end
+  
+    # @return (see #open)
+    def logger
+      @logger ||= open
+    end
+    
+    # @return [String, nil] the log file, or nil if the log was opened on an IO rather
+    #   than a String
+    def file
+      @dev if String === @dev
+    end
+    
+    private
+    
+    # Stream-lined log format.
+    FORMAT = %{%s [%s] %5s %s\n}   
+    
+    def same_file?(f1, f2)
+      f1 == f2 or (String === f2 and String === f1 and File.expand_path(f1) == File.expand_path(f2))
+    end
+  end
+end

data/lib/jinx/helpers/math.rb

@@ -0,0 +1,12 @@
+# 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 }
+  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

data/lib/jinx/helpers/merge.rb

@@ -0,0 +1,60 @@
+require 'jinx/helpers/options'
+require 'jinx/helpers/collections'
+
+
+class Hash
+  # Returns a new hash which merges the other hash with this hash.
+  #
+  # Supported options include the following:
+  # * :deep - merge values which match on the key.
+  # If the :deep option is set, and a key matches both this hash and the other hash
+  # on hash values, then the other hash's value is recursively merged into this Hash's
+  # value using the non-destructive {#merge} method with the deep option set.
+  # If a block is given to this method, then the block is passed to the value merge.
+  #
+  # @example
+  #   {:a => [1], :b => [2]}.merge({:b => [3]}, :deep) #=> {:a => [1], :b => [2, 3]}
+  #   {:a => {:b => [1]}}.merge({:a => {:b => [2]}, :c => 3}, :deep) #=> {:a => {:b => [1, 2]}, :c => 3}
+  def merge(other, options=nil, &block)
+    dup.merge!(other, options, &block)
+  end
+
+  alias :base__merge! :merge!
+  private :base__merge!
+
+  # Merges the other hash into this hash and returns this modified hash.
+  #
+  # @see #merge the options and block description
+  def merge!(other, options=nil, &block)
+    # use the standard Hash merge unless the :deep option is set
+    return base__merge!(other, &block) unless Options.get(:deep, options)
+    # merge the other entries:
+    # if the hash value is a hash, then call merge on that hash value.
+    # otherwise, if the hash value understands merge, then call that method.
+    # otherwise, if there is a block, then call the block.
+    # otherwise, set the the hash value to the other value.
+    base__merge!(other) do |key, oldval, newval|
+      if Hash === oldval then
+        oldval.merge(newval, options, &block)
+      elsif oldval.respond_to?(:merge)
+        oldval.merge(newval, &block)
+      elsif block_given? then
+        yield(key, oldval, newval)
+      else
+        newval
+      end
+    end
+  end
+end
+
+class Array
+  # Adds the elements in the other Enumerable which are not already included in this Array.
+  # Returns this modified Array.
+  def merge(other)
+    # incompatible merge argument is allowed but ignored
+    self unless Enumerable === other
+    # concatenate the members of other not in self
+    unique = other.to_a - self
+    concat(unique)
+  end
+end

data/lib/jinx/helpers/module.rb

@@ -0,0 +1,18 @@
+class Module
+  # Returns the class or module with the given name defined in this module.
+  # The name can qualified by parent modules, e.g. +MyApp::Person+.
+  # If name cannot be resolved as a Module, then this method returns nil.
+  #
+  # @param [String] the class name
+  # @return [Module, nil] the class or module defined in this module, or nil if none 
+  def module_with_name(name)
+    name.split('::').inject(self) { |parent, part| parent.const_get(part) } rescue nil
+  end
+  
+  # @example
+  #   A::B.parent_module #=> A
+  # @return [Module] this module's definition context
+  def parent_module
+    Kernel.module_with_name(name.split('::')[0..-2].join('::'))
+  end
+end

data/lib/jinx/helpers/multi_enumerator.rb

@@ -0,0 +1,31 @@
+module Jinx
+  # A MultiEnumerator iterates over several Enumerators in sequence. Unlike Array#+, MultiEnumerator reflects changes to the
+  # underlying enumerators.
+  #
+  # @example
+  #   a = [1, 2]
+  #   b = [4, 5]
+  #   ab = MultiEnumerator.new(a, b)
+  #   ab.to_a #=> [1, 2, 4, 5]
+  #   a << 3; b << 6; ab.to_a #=> [1, 2, 3, 4, 5, 6]
+  class MultiEnumerator
+    include Collection
+
+    # @return [<Enumerable>] the enumerated collections
+    attr_reader :components
+
+    # Initializes a new {MultiEnumerator} on the given components.
+    #
+    # @param [<Enumerable>] the component enumerators to compose
+    def initialize(*enums)
+      super()
+      @components = enums
+      @components.compact!
+    end
+
+    # Iterates over each of this MultiEnumerator's Enumerators in sequence.
+    def each
+      @components.each { |enum| enum.each { |item| yield item  } }
+    end
+  end
+end

data/lib/jinx/helpers/options.rb

@@ -0,0 +1,92 @@
+require 'jinx/helpers/collections'
+
+require 'jinx/helpers/validation'
+require 'jinx/helpers/merge'
+
+# Options is a utility class to support method options.
+class Options
+  # Returns the value of option in options as follows:
+  # * If options is a hash which contains the option key, then this method returns
+  #   the option value. A non-collection options[option] value is wrapped as a singleton
+  #   collection to conform to a collection default type, as shown in the example below.
+  # * If options equals the option symbol, then this method returns +true+.
+  # * If options is an Array of symbols which includes the given option, then this method
+  #   returns +true+.
+  # * Otherwise, this method returns the default.
+  #
+  # 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") }
+  #
+  # @example
+  #   Options.get(:create, {:create => true}) #=> true
+  #   Options.get(:create, :create) #=> true
+  #   Options.get(:create, [:create, :compress]) #=> true
+  #   Options.get(:create, nil) #=> nil
+  #   Options.get(:create, nil, :false) #=> false
+  #   Options.get(:create, nil, :true) #=> true
+  #   Options.get(:values, nil, []) #=> []
+  #   Options.get(:values, {:values => :a}, []) #=> [:a]
+  #   Options.get(:values, [:create, {:values => :a}], []) #=> [:a]
+  def self.get(option, options, default=nil, &block)
+    return default(default, &block) if options.nil?
+    case options
+      when Hash then
+        value = options[option]
+        if String === value then value.strip! end
+        value.nil_or_empty? ? default(default, &block) : value
+      when Enumerable then
+        detect_in_enumerable(option, options) or default(default, &block)
+      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}")
+    end
+  end
+
+  # Returns the given option list as a hash, determined as follows:
+  # * If an item is a hash, then that hash is included in the result
+  # * If an item is a symbol _s_, then {_s_ => true} is included in the result
+  #
+  # @example
+  #   Options.to_hash() #=> {}
+  #   Options.to_hash(nil) #=> {}
+  #   Options.to_hash(:a => 1) #=> {:a => 1}
+  #   Options.to_hash(:a) #=> {:a => true}
+  #   Options.to_hash(:a, :b => 2) #=> {:a => true, :b => 2}
+  # @param [<[Symbol, Hash]>] opts the option list
+  # @return [Hash] the option hash
+  def self.to_hash(*opts)
+    hash = {}
+    opts.compact!
+    opts.each do |opt|
+      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}")
+      end
+    end
+    hash
+  end
+
+  # @param [Hash, Symbol, nil] opts the options to validate
+  # @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)
+    end
+  end
+
+  private
+  
+  def self.detect_in_enumerable(key, options)
+    options.detect_value do |opt|
+      Hash === opt ? opt[key] : opt == key
+    end
+  end
+
+  def self.default(value)
+    value.nil? && block_given? ? yield : value
+  end
+end