jinx 2.1.1

data/lib/jinx/helpers/os.rb

@@ -0,0 +1,19 @@
+require 'rbconfig'
+
+module Jinx
+  # Operating system methods.
+  module OS
+    include Config
+    
+    # @return [System] the operating system type +:windows+, +:linux+, +:mac+, +:solaris+, or +:other+
+    def self.os_type
+      case CONFIG['host_os']
+         when /mswin|windows/i then :windows
+         when /linux/i then :linux
+         when /darwin/i then :mac
+         when /sunos|solaris/i then :solaris
+         else :other
+      end
+    end
+  end
+end

data/lib/jinx/helpers/partial_order.rb

@@ -0,0 +1,37 @@
+module Jinx
+  # A PartialOrder is a Comparable which restricted scope. Classes which include PartialOrder
+  # are required to implement the <=> operator with the following semantics:
+  # *  _a_ <=> _b_ returns -1, 0, or 1 if a and b are comparable, nil otherwise
+  # A PartialOrder thus relaxes comparison symmetry, e.g.
+  #   a < b
+  # does not imply
+  #   b >= a.
+  # Example:
+  #   module Queued
+  #     attr_reader :queue
+  #     def <=>(other)
+  #       queue.index(self) <=> queue.index(other) if queue.equal?(other.queue)
+  #     end
+  #   end
+  #   q1 = [a, b] # a, b are Queued
+  #   q2 = [c]    # c is a Queued
+  #   a < b #=> true
+  #   b < c #=> nil
+  module PartialOrder
+    include Comparable
+  
+    Comparable.instance_methods(false).each do |m|
+      define_method(m.to_sym) do |other|
+         self <=> other ? super : nil
+      end
+    end
+  
+    # @return [Boolean] true if other is an instance of this object's class and other == self,
+    #   false otherwise
+    def eql?(other)
+      self.class === other and super
+    end
+
+    alias :== :eql?
+  end
+end

data/lib/jinx/helpers/pretty_print.rb

@@ -0,0 +1,207 @@
+require 'set'
+require 'date'
+require 'pp'
+require 'stringio'
+require 'jinx/helpers/options'
+require 'jinx/helpers/collections'
+
+require 'jinx/helpers/inflector'
+
+class PrettyPrint
+  # The standard +prettyprint+ gem SingleLine is adjusted to add an output accessor and an optional output argument to {#initialize}.
+  class SingleLine
+    # @return [String] the print target
+    attr_reader :output
+
+    alias :base__initialize :initialize
+    private :base__initialize
+
+    # Overrides the standard SingleLine initializer to supply an output parameter default.
+    def initialize(output='', maxwidth=nil, newline=nil)
+      base__initialize(output, maxwidth, newline)
+    end
+  end
+end
+
+# A PrintWrapper prints arguments by calling a printer proc.
+class PrintWrapper < Proc
+  # Creates a new PrintWrapper on the given arguments.
+  def initialize(*args)
+    super()
+    @args = args
+  end
+
+  # @param args this wrapper's print block parameters
+  # @return [PrintWrapper] self
+  def wrap(*args)
+    @args = args
+    self
+  end
+
+  # Calls this PrintWrapper's print procedure on the arguments set in the initializer.
+  def to_s
+    @args.empty? ? 'nil' : call(*@args)
+  end
+
+  alias :inspect :to_s
+end
+
+class Object
+  # @return [String] this object's class demodulized name and object id
+  def print_class_and_id
+    "#{self.class.qp}@#{object_id}"
+  end
+
+  # qp, an abbreviation for quick-print, calls {#print_class_and_id} in this base implementation.
+  alias :qp :print_class_and_id
+
+  # Formats this object with the standard {PrettyPrint}.
+  #
+  # @param [Hash, Symbol, nil] opts the print options
+  # @option opts [Boolean] :single_line print the output on a single line
+  # @return [String] the formatted print result
+  def pp_s(opts=nil)
+    s = StringIO.new
+    if Options.get(:single_line, opts) then
+      PP.singleline_pp(self, s)
+    else
+      PP.pp(self, s)
+    end
+    s.rewind
+    s.read.chomp
+  end
+end
+
+class Numeric
+  # Alias #{Object#qp} to {#to_s} in this primitive class.
+  alias :qp :to_s
+end
+
+class String
+  # Alias #{Object#qp} to {#to_s} in this primitive class.
+  alias :qp :to_s
+end
+
+class TrueClass
+  # Alias #{Object#qp} to {#to_s} in this primitive class.
+  alias :qp :to_s
+end
+
+class FalseClass
+  # Alias #{Object#qp} to {#to_s} in this primitive class.
+  alias :qp :to_s
+end
+
+class NilClass
+  # Alias #{Object#qp} to {#to_s} in this primitive class.
+  alias :qp :inspect
+end
+
+class Symbol
+  # Alias #{Object#qp} to {#to_s} in this primitive class.
+  alias :qp :inspect
+end
+
+class Module
+  # @return [String ] the demodulized name
+  def qp
+    name[/\w+$/]
+  end
+end
+
+module Enumerable
+  # Prints this Enumerable with a filter that calls qp on each item.
+  # Non-collection Enumerable classes override this method to delegate to {Object#qp}.
+  #
+  # Unlike {Object#qp}, this implementation accepts the {Object#pp_s} options.
+  # The options are used to format this Enumerable, but are not propagated to the
+  # enumerated items.
+  #
+  # @param (see Object#pp_s)
+  # @return [String] the formatted result
+  def qp(opts=nil)
+    wrap { |item| item.qp }.pp_s(opts)
+  end
+
+  # If a transformer block is given to this method, then the block is applied to each
+  # enumerated item before pretty-printing the result.
+  #
+  # @param (see Object#pp_s)
+  # @yield [item] transforms the item to print
+  # @yieldparam item the item to print
+  # @return (see Oblect#pp_s)
+  def pp_s(opts=nil)
+    # delegate to Object if no block
+    return super unless block_given?
+    # make a print wrapper
+    wrapper = PrintWrapper.new { |item| yield item }
+    # print using the wrapper on each item
+    wrap { |item| wrapper.wrap(item) }.pp_s(opts)
+  end
+
+  # Pretty-prints the content within brackets, as is done by the Array pretty printer.
+  def pretty_print(q)
+    q.group(1, '[', ']') {
+      q.seplist(self) { |v|
+        q.pp v
+      }
+    }
+  end
+
+  # Pretty-prints the cycle within brackets, as is done by the Array pretty printer.
+  def pretty_print_cycle(q)
+    q.text(empty? ? '[]' : '[...]')
+  end
+end
+
+module Jinx
+  module Hashable
+    # qp, short for quick-print, prints this Hashable with a filter that calls qp on each key and value.
+    #
+    # @return [String] the quick-print result
+    def qp
+      qph = {}
+      each { |k, v| qph[k.qp] = v.qp }
+      qph.pp_s
+    end
+
+    def pretty_print(q)
+      Hash === self ? q.pp_hash(self) : q.pp_hash(to_hash)
+    end
+
+    def pretty_print_cycle(q)
+      q.text(empty? ? '{}' : '{...}')
+    end
+  end
+end
+
+class String
+  # Pretty-prints this String using the Object pretty_print rather than Enumerable pretty_print.
+  def pretty_print(q)
+    q.text self
+  end
+end
+
+class DateTime
+  # @return [String] the formatted +strftime+
+  def pretty_print(q)
+    q.text(strftime)
+  end
+  
+  # qp, an abbreviation for quick-print, is an alias for {#to_s} in this primitive class.
+  alias :qp :to_s
+end
+
+class Set
+  # Formats this set using {Enumerable#pretty_print}.
+  def pretty_print(q)
+    # mark this object as visited; this fragment is inferred from pp.rb and is necessary to detect a cycle
+    Thread.current[:__inspect_key__] << __id__
+    to_a.pretty_print(q)
+  end
+
+  # The pp.rb default pretty printing method for general objects that are detected as part of a cycle.
+  def pretty_print_cycle(q)
+    to_a.pretty_print_cycle(q)
+  end
+end

data/lib/jinx/helpers/set.rb

@@ -0,0 +1,8 @@
+require 'set'
+
+class Set
+  # The standard Set {#merge} is an anomaly among Ruby collections, since merge modifies the called Set in-place rather
+  # than return a new Set containing the merged contents. Preserve this unfortunate behavior, but partially address
+  # the anomaly by adding the merge! alias to make it clear that this is an in-place merge.
+  alias :merge! :merge
+end

data/lib/jinx/helpers/stopwatch.rb

@@ -0,0 +1,76 @@
+require 'benchmark'
+
+module Jinx
+  # Stopwatch is a simple execution time accumulator.
+  class Stopwatch
+    # Time accumulates elapsed real time and total CPU time.
+    class Time
+      # @return [Benchmark::Tms] the Tms wrapped by this Time
+      attr_reader :tms
+
+      # @param [Benchmark::Tms, nil] the starting time (default is now)
+      def initialize(tms=nil)
+        @tms = tms || Benchmark::Tms.new
+      end
+
+      # @return [Numeric] the cumulative elapsed real clock time
+      def elapsed
+        @tms.real
+      end
+
+      #  @return [Numeric] the cumulative CPU total time
+      def cpu
+        @tms.total
+      end
+
+      # Adds the time to execute the given block to this time.
+      #
+      #  @return [Numeric] the split execution Time
+      def split(&block)
+        stms = Benchmark.measure(&block)
+        @tms += stms
+        Time.new(stms)
+      end
+
+      # Sets this benchmark timer to zero.
+      def reset
+        @tms = Benchmark::Tms.new
+      end
+    end
+  
+    # Executes the given block
+    #
+    # @return [Numeric] the execution Time
+    def self.measure(&block)
+      new.run(&block)
+    end
+
+    # Creates a new idle Stopwatch.
+    def initialize
+      @time = Time.new
+    end
+
+    # Executes the given block. Accumulates the execution time in this Stopwatch. 
+    #
+    #  @return [Numeric] the execution run Time
+    def run(&block)
+      @time.split(&block)
+    end
+
+    # @return [Numeric] the cumulative elapsed real clock time spent in {#run} executions
+    def elapsed
+      @time.elapsed
+    end
+
+    # @return [Numeric] the cumulative CPU total time spent in {#run} executions for the
+    #  current process and its children
+    def cpu
+      @time.cpu
+    end
+
+    # Resets this Stopwatch's cumulative time to zero.
+    def reset
+      @time.reset
+    end
+  end
+end

data/lib/jinx/helpers/transformer.rb

@@ -0,0 +1,24 @@
+module Jinx
+  # This Transformer helper class applies a transformer block to a base enumeration.
+  class Transformer
+    include Collection
+
+    def initialize(enum=[], &transformer)
+      @base = enum
+      @xfm = transformer
+    end
+
+    # Sets the base Enumerable on which this Transformer operates and returns this transformer, e.g.:
+    #  transformer = Transformer.new { |n| n * 2 }
+    #  transformer.on([1, 2, 3]).to_a #=> [2, 4, 6]
+    def on(enum)
+      @base = enum
+      self
+    end
+
+    # Calls the block on each item after this Transformer's transformer block is applied.
+    def each
+      @base.each { |item| yield(item.nil? ? nil : @xfm.call(item)) }
+    end
+  end
+end

data/lib/jinx/helpers/transitive_closure.rb

@@ -0,0 +1,55 @@
+require 'jinx/helpers/visitor'
+
+class Object
+  # Returns the transitive closure over a method or block. This method returns an array partially ordered
+  # by the children method or block, i.e. each node occurs before all other nodes referenced directly or
+  # indirectly by the children.
+  #
+  # If a method symbol or name is provided, then that method is called. Otherwise, the block is called.
+  # In either case, the call is expected to return an object or Enumerable of objects which also respond
+  # to the method or block.
+  #
+  # @param [Symbol, nil] method the child reference, or nil if a block is given
+  # @yield [node] the parent node's children
+  # @yieldparam node the parent node
+  # @example
+  #   class Node
+  #     attr_reader :parent, :children
+  #     def initialize(name, parent=nil)
+  #       super()
+  #       @name = name
+  #       @parent = parent
+  #       @children = []
+  #       parent.children << self if parent
+  #     end
+  #
+  #     def to_s;
+  #   end
+  #   a = Node.new('a'); b = Node.new('b', a), c = Node.new('c', a); d = Node.new('d', c)
+  #   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?
+    # 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
+      transitive_closure() { |node| node.send(method) }
+    else
+      Jinx::Visitor.new(:depth_first) { |node| yield node }.to_enum(self).to_a.reverse
+    end
+  end
+end
+
+module Enumerable
+  # Returns the transitive closure over all items in this Enumerable.
+  #
+  # @see Object#transitive_closure
+  def transitive_closure(method=nil)
+    # delegate to Object if there is a method argument
+    return super(method) if method
+    # this Enumerable's children are this Enumerable's contents
+    closure = super() { |node| node.equal?(self) ? self : yield(node) }
+    # remove this collection from the closure
+    closure[1..-1]
+  end
+end

data/lib/jinx/helpers/uniquifier.rb

@@ -0,0 +1,50 @@
+require 'singleton'
+require 'jinx/helpers/lazy_hash'
+
+module Jinx
+  # A utility class to generate value qualifiers.
+  class Uniquifier
+    include Singleton
+
+    # Returns a relatively unique integral qualifier. Successive calls to this method
+    # within the same time zone spaced more than a millisecond apart return different
+    # integers. Each generated qualifier is greater than the previous by an unspecified
+    # amount.
+    def self.qualifier
+      # the first date that this method could be called
+      @first ||= Date.new(2011, 12, 01)
+      # days as integer + milliseconds as fraction since the first date
+      diff = DateTime.now - @first
+      # shift a tenth of a milli up into the integer portion
+      decimillis = diff * 24 * 60 * 60 * 10000
+      # truncate the fraction
+      decimillis.truncate
+    end
+
+    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
+    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}"
+  end
+end