caruby-core 1.4.1

data/lib/caruby/util/options.rb

@@ -0,0 +1,92 @@
+require 'caruby/util/collection'
+require 'caruby/util/validation'
+require 'caruby/util/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) { raise RuntimeError.new("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]
+  def self.get(option, options, default=nil, &block)
+    return default(default, &block) if options.nil?
+    case options
+    when Hash then
+      value = options[option]
+      value.nil? ? default(default, &block) : value
+    when Enumerable then
+      options.include?(option) ? true : default(default, &block)
+    when Symbol then
+      option == options ? true : default(default, &block)
+    else
+      raise ArgumentError.new("Options argument type is not supported; expected Hash or Symbol, found: #{options.class}")
+    end
+  end
+
+  # Merges the others options with options and returns the new merged option hash.
+  #
+  # @example
+  #   Options.merge(nil, :create) #=> {:create => :true}
+  #   Options.merge(:create, :optional => :a, :required => :b) #=> {:create => :true, :optional => :a, :required => :b}
+  #   Options.merge({:required => [:b]}, :required => [:c]) #=> {:required => [:b, :c]}
+  def self.merge(options, others)
+    options = options.dup if Hash === options
+    self.merge!(options, others)
+  end
+
+  # Merges the others options into the given options and returns the created or modified option hash.
+  # This method differs from {Options.merge} by modifying an existing options hash.
+  def self.merge!(options, others)
+    to_hash(options).merge!(to_hash(others)) { |key, oldval, newval| oldval.respond_to?(:merge) ? oldval.merge(newval) : newval }
+  end
+
+  # Returns the options as a hash. If options is already a hash, then this method returns hash.
+  # * If options is a Symbol _s_, then this method returns +{+_s_+=>true}+.
+  # * An Array of Symbols is enumerated as individual Symbol options.
+  # * If options is nil, then this method returns a new empty hash.
+  def self.to_hash(options)
+    return Hash.new if options.nil?
+    case options
+    when Hash then
+      options
+    when Array then
+      options.to_hash { |item| Symbol === item or raise ArgumentError.new("Option is not supported; expected Symbol, found: #{options.class}") }
+    when Symbol then
+      {options => true}
+    else
+      raise ArgumentError.new("Options argument type is not supported; expected Hash or Symbol, found: #{options.class}")
+    end
+  end
+
+  # Raises a ValidationError if the given options are not in the given allowable choices.
+  def self.validate(options, choices)
+    to_hash(options).each_key do |opt|
+      raise ValidationError.new("Option is not supported: #{opt}") unless choices.include?(opt)
+    end
+  end
+
+  private
+
+  def self.default(value)
+    value.nil? && block_given? ? yield : value
+  end
+end

data/lib/caruby/util/partial_order.rb

@@ -0,0 +1,36 @@
+# A PartialOrder is a Comparable which restricted scope. Classes wich 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)
+#       raise TypeError.new("Comparison argument is not another Queued item") unless Queued == 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
+
+    # Returns 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/caruby/util/person.rb

@@ -0,0 +1,119 @@
+require 'caruby/util/validation'
+
+# Mix-in for standard Person attributes.
+module CaRuby
+  module Person
+    class Name
+      include Validation
+
+      attr_accessor :salutation, :qualifier, :credentials
+      attr_reader :first, :last, :middle
+
+      # Creates a new Name with the required last and optional first and middle components.
+      def initialize(last, first=nil, middle=nil)
+        # replace empty with nil
+        @first = first unless first == ''
+        @last = last unless last == ''
+        @middle = middle unless middle == ''
+      end
+
+      # Returns this Name as an array consisting of the first, middle and last fields.
+      #
+      # @example
+      #  Person.parse("Abe Lincoln").to_a #=> ["Abe", nil, "Lincoln"]
+      def to_a
+        [@first, @middle, @last]
+      end
+
+      # Returns this Name in the format [Salutation] First [Middle] Last[, Credentials].
+      def to_s
+        name_s = [salutation, first, middle, last, qualifier].reject { |part| part.nil? }.join(' ')
+        name_s << ', ' << credentials if credentials
+        name_s
+      end
+
+      # Returns whether this Person's first, middle and last name components equal the other Person's.
+      def ==(other)
+        self.class == other.class and first == other.first and middle == other.middle and last == other.last
+      end
+
+      alias :inspect :to_s
+
+      # Parses the name_s String into a Name. The name can be in one of the following formats:
+      # * last, first middle
+      # * [salutation] [first [middle]] last [qualifier] [, credentials]
+      # where _salutation_ ends in a period.
+      #
+      # Examples:
+      # * Longfellow, Henry Wadsworth
+      # * Longfellow, Henry Gallifant Wadsworth
+      # * Henry Longfellow
+      # * Longfellow
+      # * Mr. Henry Wadsworth Longfellow III, MD, Ph.D.
+      def self.parse(name_s)
+        return if name_s.blank?
+        # the name component variables
+        first = middle = last = salutation = qualifier = credentials = nil
+        # split into comma-delimited tokens
+        tokens = name_s.split(',')
+        # the word(s) before the first comma
+        before_comma = tokens[0].split(' ')
+        # if this is a last, first middle format, then parse it that way.
+        # otherwise the format is [salutation] [first [middle]] last [qualifier] [credentials]
+        if before_comma.size == 1 then
+          last = before_comma[0]
+          if tokens.size > 1 then
+            after_comma = tokens[1].split(' ')
+            first = after_comma.shift
+            middle = after_comma.join(' ')
+          end
+        else
+          # extract the salutation from the front, if any
+          salutation = before_comma.shift if salutation?(before_comma[0])
+          # extract the qualifier from the end, if any
+          qualifier = before_comma.pop if qualifier?(before_comma[-1])
+          # extract the last name from the end
+          last = before_comma.pop
+          # extract the first name from the front
+          first = before_comma.shift
+          # the middle name is whatever is left before the comma
+          middle = before_comma.join(' ')
+          # the credentials are the comma-delimited words after the first comma
+          credentials = tokens[1..-1].join(',').strip
+        end
+        # if there is only one name field, then it is the last name
+        if last.nil? then
+          last = first
+          first = nil
+        end
+        # make the name
+        name = self.new(last, first, middle)
+        name.salutation = salutation
+        name.qualifier = qualifier
+        name.credentials = credentials
+        name
+      end
+
+      # Raises ValidationError if there is neither a first nor a last name
+      # or if there is a middle name but no first name.
+      def validate
+        if last.nil? and first.nil? then
+          raise ValidationError.new("Name is missing both the first and last fields")
+        end
+        if !middle.nil? and first.nil? then
+          raise ValidationError.new("Name with middle field #{middle} is missing the first field")
+        end
+      end
+
+      # Returns whether s ends in a period.
+      def self.salutation?(s)
+        s =~ /\.$/
+      end
+
+      # Returns whether s is Jr., Sr., II, III, etc.
+      def self.qualifier?(s)
+        s and (s =~ /[J|S]r[.]?/ or s =~ /\AI+\Z/)
+      end
+    end
+  end
+end

data/lib/caruby/util/pretty_print.rb

@@ -0,0 +1,184 @@
+require 'set'
+require 'date'
+require 'pp'
+require 'stringio'
+require 'caruby/util/options'
+require 'caruby/util/collection'
+require 'caruby/util/inflector'
+
+class PrettyPrint
+  # Fixes the standard prettyprint gem SingleLine to add an output accessor and an optional output argument to {#initialize}.
+  class SingleLine
+    attr_reader :output
+
+    alias :base__initialize :initialize
+    private :base__initialize
+
+    # Allow output to be optional, defaulting to ''
+    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
+
+  # Sets the arguments to wrap with this wrapper's print block and returns self.
+  def wrap(*args)
+    @args = args
+    self
+  end
+
+  # Calls this PrintWrapper's print procedure on its arguments.
+  def to_s
+    @args.empty? ? 'nil' : call(*@args)
+  end
+
+  alias :inspect :to_s
+end
+
+class Object
+  # Prints 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 as a String with PrettyPrint.
+  # If the :single_line option is set, then the output is printed to a single line.
+  def pp_s(options=nil)
+    s = StringIO.new
+    if Options.get(:single_line, options) then
+      PP.singleline_pp(self, s)
+    else
+      PP.pp(self, s)
+    end
+    s.rewind
+    s.read.chomp
+  end
+end
+
+class Numeric
+  # qp, an abbreviation for quick-print, is an alias for {#to_s} in this primitive class.
+  alias :qp :to_s
+end
+
+class String
+  # qp, an abbreviation for quick-print, is an alias for {#to_s} in this primitive class.
+  alias :qp :to_s
+end
+
+class TrueClass
+  # qp, an abbreviation for quick-print, is an alias for {#to_s} in this primitive class.
+  alias :qp :to_s
+end
+
+class FalseClass
+  # qp, an abbreviation for quick-print, is an alias for {#to_s} in this primitive class.
+  alias :qp :to_s
+end
+
+class NilClass
+  # qp, an abbreviation for quick-print, is an alias for {#inspect} in this NilClass.
+  alias :qp :inspect
+end
+
+class Symbol
+  # qp, an abbreviation for quick-print, is an alias for {#inspect} in this Symbol class.
+  alias :qp :inspect
+end
+
+class Module
+  # qp, an abbreviation for quick-print, prints this module's name unqualified by a parent module prefix.
+  def qp
+    name[/\w+$/]
+  end
+end
+
+module Enumerable
+  # qp, short for quick-print, prints a collection Enumerable with a filter that calls qp on each item.
+  # Non-collection Enumerables delegate to the superclass method.
+  def qp
+    wrap { |item| item.qp }.pp_s
+  end
+
+  # If the transformer block is given to this method, then the transformer block to each
+  # enumerated item before pretty-printing the result.
+  def pp_s(options=nil, &transformer)
+    # delegate to Object if no block
+    return super(options) 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(options)
+  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 Hashable
+  # qp, short for quick-print, prints this Hashable with a filter that calls qp on each key and value.
+  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
+
+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
+  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/caruby/util/properties.rb

@@ -0,0 +1,112 @@
+require 'yaml'
+require 'set'
+require 'caruby/util/log'
+require 'caruby/util/pretty_print'
+require 'caruby/util/collection'
+require 'caruby/util/merge'
+
+module CaRuby
+  # Exception raised if a configuration property is missing or invalid.
+  class ConfigurationError < RuntimeError; end
+
+  # A Properties instance encapsulates a properties file accessor. The properties are stored
+  # in YAML format.
+  class Properties < Hash
+    # Creates a new Properties object. If the file argument is given, then the properties are loaded from
+    # that file.
+    #
+    # Supported options include the following:
+    # * :merge - the properties which are merged rather than replaced when loaded from the property files
+    # * :required - the properties which must be set when the property files are loaded
+    # * :array - the properties whose comma-separated String input value is converted to an array value
+    def initialize(file=nil, options=nil)
+      super()
+      @merge_properties = Options.get(:merge, options, []).to_set
+      @required_properties = Options.get(:required, options, []).to_set
+      @array_properties = Options.get(:array, options, []).to_set
+      load_properties(file) if file
+    end
+
+    # Returns a new Hash which associates this Properties' keys converted to symbols to the respective values.
+    def symbolize
+      Hash.new
+    end
+
+    # Returns whether the property key or its alternate is defined.
+    def has_property?(key)
+      has_key?(key) or has_key?(alternate_key(key))
+    end
+
+    # Returns the property value for the key. If there is no String key entry but there is a
+    # alternate key entry, then this method returns the alternate key value.
+     def [](key)
+      super(key) or super(alternate_key(key))
+    end
+
+    # Returns the property value for the key. If there is no key entry but there is an
+    # alternate key entry, then alternate key entry is set.
+    def []=(key, value)
+      return super if has_key?(key)
+      alt = alternate_key(key)
+      has_key?(alt) ? super(alt, value) : super
+    end
+
+    # Deletes the entry for the given property key or its alternate.
+    def delete(key)
+      key = alternate_key(key) unless has_key?(key)
+      super
+    end
+
+    # Loads the specified properties file, replacing any existing properties.
+    #
+    # If a key is included in this Properties merge_properties array, then the
+    # old value for that key will be merged with the new value for that key
+    # rather than replaced.
+    #
+    # This method reloads a property file that has already been loaded.
+    #
+    # Raises ConfigurationError if file doesn't exist or couldn't be parsed.
+    def load_properties(file)
+      raise ConfigurationError.new("Properties file not found: #{File.expand_path(file)}") unless File.exists?(file)
+      logger.debug { "Loading properties file #{file}..." }
+      properties = {}
+      begin
+        YAML::load_file(file).each { |key, value| properties[key.to_sym] = value }
+      rescue
+        raise ConfigurationError.new("Could not read properties file #{file}: " + $!)
+      end
+     # Uncomment the following line to print detail properties.
+      #logger.debug { "#{file} properties:\n#{properties.pp_s}" }
+      # parse comma-delimited string values of array properties into arrays
+      @array_properties.each do |key|
+        value = properties[key]
+        if String === value then
+          properties[key] = value.split(/,\s*/)
+        end
+      end
+      # if the key is a merge property key, then perform a deep merge.
+      # otherwise, do a shallow merge of the property value into this property hash.
+      deep, shallow = properties.partition { |key, value| @merge_properties.include?(key) }
+      merge!(deep, :deep)
+      merge!(shallow)
+    end
+
+    private
+
+    # Returns key as a Symbol if key is a String, key as a String if key is a Symbol,
+    # or nil if key is neither a String nor a Symbol.
+    def alternate_key(key)
+      case key
+      when String then key.to_sym
+      when Symbol then key.to_s
+      end
+    end
+
+    # Validates that the required properties exist.
+    def validate_properties
+      @required_properties.each do |key|
+        raise CaRuby::ConfigurationError.new("A required #{@application} property was not found: #{key}") unless has_property?(key)
+      end
+    end
+  end
+end