caruby-core 1.4.1

data/lib/caruby/util/controlled_value.rb

@@ -0,0 +1,35 @@
+require 'set'
+
+module CaRuby
+  class ControlledValue
+    attr_accessor :value, :parent
+
+    attr_reader :children
+
+    # Creates a new ControlledValue with the given String value and ControlledValue parent.
+    # If parent is not nil, then the new CV is added to the parent's children.
+    def initialize(value=nil, parent=nil)
+      @value = value
+      self.parent = parent
+      @children = Set.new
+    end
+
+    def descendants
+      children + children.map { |child| child.descendants.to_a }.flatten
+    end
+
+    def to_s
+      value
+    end
+
+    private
+
+    # Sets this CV's parent and adds this CV to the parent's children if necessary.
+    def parent=(parent)
+      @parent.children.delete(self) if @parent
+      @parent = parent
+      parent.children << self if parent
+      parent
+    end
+  end
+end

data/lib/caruby/util/coordinate.rb

@@ -0,0 +1,75 @@
+require 'generator'
+
+# A Coordinate is a convenience Array wrapper class with aliased #x, #y and {#z} dimensions.
+class Coordinate < Array
+  include Comparable
+
+  # @param [{Integer}] scalars the dimension coordinate values
+  # @return a new Coordinate at the given scalars
+  def initialize(*scalars)
+    super(scalars)
+  end
+
+  # @return [Integer] the first dimension
+  def x
+    self[0]
+  end
+
+  # @param [Integer] the first dimension value
+  def x=(value)
+    self[0] = value
+  end
+
+  # @return [Integer, nil] the second dimension
+  def y
+    self[1]
+  end
+
+  # @param [Integer] the second dimension value
+  def y=(value)
+    self[1] = value
+  end
+
+  # @return [Integer, nil] the third dimension
+  def z
+    self[2]
+  end
+
+  # @param [Integer] the third dimension value
+  def z=(value)
+    self[2] = value
+  end
+
+  # @return [Boolean] whether other is a Coordinate and has the same content as this Coordinate
+  def ==(other)
+    super rescue false
+  end
+
+  # Returns the comparison of the highest dimension which differs from the other
+  # coordinate, or zero if all dimensions are the same. This comparator sorts
+  # coordinates in z-y-x order.
+  # @example
+  #   Coordinate.new(2, 1) < Coordinate.new(1, 2) #=> true
+  # @return [Integer] the high-to-low dimension comparison
+  # @raise [ArgumentError] if this Coordinate dimension size Coordinate differs from that
+  #   of the other Dimension or any of the dimension values are nil
+  # @raise [TypeError] if other is not a Coordinate
+  def <=>(other)
+    return true if equal?(other)
+    raise TypeError.new("Can't compare #{self} with #{other} since it is not a Coordinate") unless Coordinate === other
+    raise ArgumentError.new("Can't compare #{self} with #{other} since it has a different dimension count") unless size == other.size
+    SyncEnumerator.new(self.reverse, other.reverse).each_with_index do |pair, index|
+      dim = pair.first
+      odim = pair.last
+      raise ArgumentError.new("Can't compare #{self} with missing dimension #{index} to #{other}") unless dim
+      raise ArgumentError.new("Can't compare #{self} to #{other} with missing dimension #{index}") unless odim
+      cmp = dim <=> odim
+      return cmp unless cmp.zero?
+    end
+    0
+  end
+
+  def to_s
+    inspect
+  end
+end

data/lib/caruby/util/domain_extent.rb

@@ -0,0 +1,49 @@
+require 'caruby/util/collection'
+require 'caruby/util/validation'
+
+# A DomainExtent contains class-specific key => object associations.
+# The objects are created on demand and accessed by the get method.
+#
+# @example
+#   DomainExtent.new { |klass, key| key.to_s + klass.name }.get(String, 'a') #=> aString
+class DomainExtent < LazyHash
+  include Validation
+
+  # Creates a new DomainExtent. The block passed to the constructor
+  # is a factory to create an object on demand, with arguments
+  # the target class and the target key. The default block is empty.
+  def initialize
+    return initialize {} unless block_given?
+    super { |klass| LazyHash.new { |key| yield klass, key } }
+  end
+
+  # Sets the factory used to create an instance of the specified class.
+  # The factory is called to create a new instance when a get operation
+  # does not yet have a key => instance association.
+  #
+  # The factory accepts a single argument, the instance key, e.g.
+  #   set_factory(MyClass) { |key| MyClass.new(key) }
+  def set_factory(klass, &factory)
+    validate_type(klass => Class)
+    # the current instances, if any
+    instances = fetch(klass) if has_key?(klass)
+    # make the key => instance class extent map
+    # the instance creation factory is
+    class_extent = LazyHash.new { |key| yield key }
+    # copy existing instances if necessary
+    class_extent.merge!(instances) if instances
+    # add the class => class extent association
+    self[klass] = class_extent
+  end
+
+  # Returns the domain instance of the given class for the given key.
+  # If there is nois no entry for key and the factory is set for the class,
+  # then a new object is created on demand.
+  def get(klass, key)
+    raise RuntimeError.new("Invalid target class: #{klass}") unless klass.is_a?(Class)
+    raise RuntimeError.new("Missing target key value") if key.nil?
+    # the class extent hash is created on demand if necessary.
+    # the instance is created on demand if there is a factory for the class.
+    self[klass][key]
+  end
+end

data/lib/caruby/util/file_separator.rb

@@ -0,0 +1,65 @@
+require 'caruby/util/class'
+
+class File
+  [:gets, :readline, :readlines].each do |attr|
+    # Overrides the standard method to infer a line separator from the input
+    # if the separator argument is the default.
+    redefine_method(attr) do |original|
+      lambda do |*params|
+        sep = params.first || default_line_separator
+        send(original, sep)
+      end
+    end
+
+    # Overrides the standard {#each} method to infer a line separator from the input
+    # if the separator argument is not given.
+    def each(separator=nil)
+      while (line = gets(separator)) do
+        yield line
+      end
+    end
+  end
+
+  private
+
+  # Returns the default line separator. The logic is borrowed from the FasterCVS gem.
+  def default_line_separator
+    @def_line_sep ||= infer_line_separator
+  end
+
+  def infer_line_separator
+    type_line_separator or content_line_separator or $/
+  end
+
+  def type_line_separator
+    if [ARGF, STDIN, STDOUT, STDERR].include?(self) or
+      (defined?(Zlib) and self.class == Zlib::GzipWriter) then
+      return $/
+    end
+  end
+
+  def content_line_separator
+    begin
+      saved_pos = pos  # remember where we were
+      # read a chunk until a separator is discovered
+      sep = discover_line_separator
+      # tricky seek() clone to work around GzipReader's lack of seek()
+      rewind
+      # reset back to the remembered position
+      chunks, residual = saved_pos.divmod(1024)
+      chunks.times { read(1024) }
+      read(residual)
+    rescue IOError  # stream not opened for reading
+    end
+    sep
+  end
+
+  def discover_line_separator
+    # read a chunk until a separator is discovered
+    while (sample = read(1024)) do
+      sample += read(1) if sample[-1, 1] == "\r" and not eof?
+      # try to find a standard separator
+      return $& if sample =~ /\r\n?|\n/
+    end
+  end
+end

data/lib/caruby/util/inflector.rb

@@ -0,0 +1,20 @@
+require 'caruby/active_support/inflector'
+
+class String
+  # @param [Numeric] quantity the amount qualifier
+  # @return this String qualified by a plural if the quantity is not 1
+  # @example
+  #   "rose".quantify(3) #=> "roses"
+  #   "rose".quantify(1 #=> "rose"
+  def quantify(quantity)
+    raise ArgumentError.new("Missing quantity argument") if quantity.nil?
+    "#{quantity} #{quantity == 1 ? self : pluralize}"
+  end
+  
+  # @return this String with the first letter capitalized and other letters preserved.
+  # @example
+  #   "rosesAreRed".capitalize_first #=> "RosesAreRed"
+  def capitalize_first
+    sub(/(?:^)(.)/) { $1.upcase }
+  end
+end

data/lib/caruby/util/log.rb

@@ -0,0 +1,95 @@
+require 'logger'
+require 'singleton'
+require 'ftools'
+require 'caruby/util/collection'
+
+# @return [CaRuby::Logger] the global logger
+def logger
+  CaRuby::Log::instance.logger
+end
+
+module CaRuby
+  # Extends the standard Logger to format multi-line messages on separate lines.
+  class MultilineLogger < Logger
+    # @see Logger#initialize
+    def initialize(*args)
+      super
+    end
+  
+    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] file_or_dev the log file or device (default STDOUT)
+    # @param [Hash, nil] the Logger::LogDevice options
+    # @return [Logger] the logger
+    def open(file_or_dev=nil, options=nil)
+      dev = file_or_dev || default_log_file
+      return @logger if same_file?(dev, @dev)
+      # close the previous log file, if necessary
+      @logger.close if @logger
+      if String === dev then File.makedirs(File.dirname(dev)) end
+      # default is 4-file rotation @ 16MB each
+      shift_age = Options.get(:shift_age, options, 4)
+      shift_size = Options.get(:shift_size, options, 16 * 1048576)
+      @logger = MultilineLogger.new(dev, shift_age, shift_size)
+      @logger.level = Options.get(:debug, options) ? Logger::DEBUG : Logger::INFO
+      @logger.info('============================================')
+      @logger.info('Logging started.')
+      @dev = dev
+      @logger
+    end
+  
+    def close
+      @logger.close
+      @logger = nil
+    end
+  
+    # Returns the logger.
+    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
+    
+    def same_file?(f1, f2)
+      f1 == f2 or (String === f2 and String === f1 and File.expand_path(f1) == File.expand_path(f2))
+    end
+    
+    def default_log_file
+      log_ndx = ARGV.index("--log") || ARGV.index("-l")
+      if log_ndx then
+        ARGV[log_ndx + 1]
+      elsif ENV.has_key?("CA_LOG") then
+        ENV["CA_LOG"]
+      elsif defined?(DEF_LOG_FILE)
+        DEF_LOG_FILE
+      else
+        'log/caruby.log'
+      end
+    end
+  end
+end

data/lib/caruby/util/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/caruby/util/merge.rb

@@ -0,0 +1,59 @@
+require 'caruby/util/options'
+require 'caruby/util/collection'
+
+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/caruby/util/module.rb

@@ -0,0 +1,34 @@
+class Module
+  # Returns the class or module with name in the parent module.
+  # If parent is nil, then name is looked up in the global context.
+  # Otherwise, this method returns {#module_with_name}.
+  def self.module_with_name(parent, name)
+    return parent.module_with_name(name) if parent
+    begin
+      constant = eval(name)
+    rescue Exception
+      return
+    end
+    constant if constant.is_a?(Module)
+  end
+
+  # Returns the class or module with name in this module.
+  # name can qualified by parent modules, e.g. +MyApp::Person+.
+  # If name cannot be resolved as a Module, then this method returns nil.
+  def module_with_name(name)
+    begin
+      constant = name.split('::').inject(parent) { |parent, name| parent.const_get(name) }
+    rescue Exception
+      return
+    end
+    constant if constant.is_a?(Module)
+  end
+
+  # Returns the class with name in this module.
+  # name can qualified by parent modules, e.g. +MyApp::Person+.
+  # If name cannot be resolved as a Class, then this method returns nil.
+  def class_with_name
+    mod = module_with_name
+    mod if mod.is_a?(Class)
+  end
+end