ribbon 0.5.0 → 0.6.0

data/.gitignore

@@ -1,2 +1,3 @@
 *.lock
 doc/
+.yardoc/

data/.yardopts

@@ -0,0 +1 @@
+--protected --no-private

data/LICENSE.MPL2

@@ -0,0 +1,3 @@
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this file,
+You can obtain one at http://mozilla.org/MPL/2.0/.

data/Rakefile

@@ -1,3 +1,3 @@
 require 'rookie'
 
-Rookie::Tasks.new 'ribbon.gemspec'
+Rookie::Tasks.new('ribbon.gemspec').define_tasks!

data/lib/ribbon.rb

@@ -1,83 +1,114 @@
-require 'ribbon/version'
-require 'ribbon/wrapper'
+%w(core_extensions/basic_object options version wrapper).each do |file|
+  require file.prepend 'ribbon/'
+end
 
-# == Ruby Object Notation.
-#
-# ==== Inspired by JSON and OpenStruct.
+# Ribbons are essentially hashes that use method names as keys.
 #
-# Ribbons are essentially hashes that use method calls as keys. This is done via
-# <tt>method_missing</tt>. On top of that, one may still use it as a
-# general-purpose hash, since the <tt>[key]</tt> and <tt>[key] = value</tt>
-# methods are defined.
+#   r = Ribbon.new
+#   r.key = :value
 #
-# Ribbons support cascading references seamlessly. If you access a property that
-# hasn't been set, a new ribbon is created and returned, allowing you to
-# continue your calls:
+# If you access a property that hasn't been set, a new ribbon will be returned.
+# This allows you to easily work with nested structures:
 #
-#   r = Ribbon.new
 #   r.a.b.c = 10
 #
 # You can also assign properties by passing an argument to the method:
 #
-#   r.a.b.c 10
+#   r.a.b.c 20
 #
 # If you pass a block, the value will be yielded:
 #
-#   r.a { |a| a.b { |b| b.c 10 } }
+#   r.a do |a|
+#     a.b do |b|
+#       b.c 30
+#     end
+#   end
 #
-# If the block passed takes no arguments, it will be <tt>instance_eval</tt>ed on
-# the value instead:
+# If the block passed takes no arguments, it will be <tt>instance_eval</tt>uated
+# in the context of the value instead:
 #
-#   r.a { b { c 10 } }
+#   r.a do
+#     b do
+#       c 40
+#     end
+#   end
 #
-# Appending a <tt>!</tt> to the end of the property sets the value and returns
-# the receiver:
+# Appending a bang (<tt>!</tt>) to the end of the property sets the value and
+# returns the receiver:
 #
-#   r.x!(10).y!(20).z!(30)    # Equivalent to: r.x = 10; r.y = 20; r.z = 30
+#   Ribbon.new.x!(10).y!(20).z!(30)
 #    => {x: 10, y: 20, z: 30}
 #
-# Appending a <tt>?</tt> to the end of the property allows you to peek at the
+# Appending a question mark (<tt>?</tt>) to the end of the property returns the
 # contents of the property without creating a new ribbon if it is missing:
 #
-#   r.p?
+#   r.unknown_property?
 #    => nil
 #
-# Seamless reference cascade using arbitrary keys are also supported via the
-# <tt>[key]</tt> and <tt>[key] = value</tt> operators, which allow you to
-# directly manipulate the internal hash:
+# You can use any object as key with the <tt>[]</tt> and <tt>[]=</tt> operators:
 #
-#   r[:j][:k][:l]
+#   r['/some/path'].entries = []
 #
-# Keep in mind that the <tt>[key]</tt> operator will always create new ribbons
-# for missing properties, which is something that may not be desirable; consider
-# wrapping the ribbon with a Ribbon::Wrapper in order to have better access to
-# the underlying hash.
+# @author Matheus Afonso Martins Moreira
+# @since 0.1.0
+# @see Ribbon::Wrapper
 class Ribbon < BasicObject
 
-  # The internal Hash.
+  # The hash used internally.
+  #
+  # @return [Hash] the hash used by this Ribbon instance to store data
+  # @api private
   def __hash__
     @hash ||= (::Hash.new &::Ribbon.default_value_proc)
   end
 
-  # Initializes the new ribbon, merging the internal hash with the given one and
-  # converting all internal objects. See Ribbon::convert_all! for details.
+  # Initializes a new ribbon.
+  #
+  # If given a block, the ribbon will be yielded to it. If the block doesn't
+  # take any arguments, it will be evaluated in the context of the ribbon.
+  #
+  # All objects inside the hash will be converted.
+  #
+  # @param [#to_hash, Ribbon, Ribbon::Wrapper] hash the hash with the initial
+  #                                                 values
+  # @see CoreExt::BasicObject#__yield_or_eval__
+  # @see convert_all!
   def initialize(hash = {}, &block)
-    __hash__.merge! hash
-    if block.arity.zero? then instance_eval &block else block.call self end if block
+    __hash__.merge! ::Ribbon.extract_hash_from(hash)
+    __yield_or_eval__ &block
    ::Ribbon.convert_all! self
   end
 
-  # Gets a value by key.
+  # Fetches the value associated with the given key.
+  #
+  # If given a block, the value will be yielded to it. If the block doesn't take
+  # any arguments, it will be evaluated in the context of the value.
+  #
+  # @param key the key which identifies the value
+  # @return the value associated with the given key
+  # @see CoreExt::BasicObject#__yield_or_eval__
   def [](key, &block)
     value = ::Ribbon.convert __hash__[key]
-    if block.arity.zero? then value.instance_eval &block
-    else block.call value end if block
+    value.__yield_or_eval__ &block
     self[key] = value
   end
 
-  # Sets a value by key.
-  def []=(key, value)
-    __hash__[key] = value
+  # Associates the given values with the given key.
+  #
+  # @param key the key that will identify the values
+  # @param values the values that will be associated with the key
+  # @example
+  #   ribbon = Ribbon.new
+  #
+  #   ribbon[:key] = :value
+  #   ribbon[:key]
+  #   # => :value
+  #
+  #   ribbon[:key] = :multiple, :values
+  #   ribbon[:key]
+  #   # => [:multiple, :values]
+  def []=(key, *values)
+    __hash__[key] = if values.size == 1 then values.first else values end
   end
 
   # Handles the following cases:
@@ -87,181 +118,278 @@ class Ribbon < BasicObject
   #   ribbon.method          &block  =>  ribbon[method, &block]
   #   ribbon.method   value, &block  =>  ribbon[method] = value
   #                                      ribbon[method, &block]
+  #
   #   ribbon.method = value          =>  ribbon[method] = value
+  #
   #   ribbon.method!  value          =>  ribbon[method] = value
   #                                      self
+  #   ribbon.method!         &block  =>  ribbon[method, &block]
+  #                                      self
+  #   ribbon.method!  value, &block  =>  ribbon[method] = value
+  #                                      ribbon[method, &block]
+  #                                      self
+  #
   #   ribbon.method?                 =>  ribbon.__hash__.fetch method
   #   ribbon.method?  value          =>  ribbon.__hash__.fetch method, value
   #   ribbon.method?         &block  =>  ribbon.__hash__.fetch method, &block
+  #   ribbon.method?  value, &block  =>  ribbon.__hash__.fetch method, value, &block
   def method_missing(method, *args, &block)
-    m = method.to_s.strip.gsub(/[=?!]$/, '').strip.to_sym
-    case method.to_s[-1]
-      when '='
-        self[m] = args.first
-      when '!'
-        self[m] = args.first; self
-      when '?'
-        begin self.__hash__.fetch m, *args, &block
+    method_string = method.to_s
+    key = method_string.strip.gsub(/[=?!]$/, '').strip.intern
+    case method_string[-1]
+      when ?=
+        __send__ :[]=, key, *args
+      when ?!
+        __send__ :[]=, key, *args unless args.empty?
+        self[key, &block]
+        self
+      when ??
+        begin self.__hash__.fetch key, *args, &block
         rescue ::KeyError; nil end
       else
-        self[method] = args.first unless args.empty?
-        self[method, &block]
+        __send__ :[]=, key, *args unless args.empty?
+        self[key, &block]
     end
   end
 
-  # Computes a simple key: value string for easy visualization of this ribbon.
+  # Generates a simple <tt>key: value</tt> string representation of this ribbon.
   #
-  # In +opts+ can be specified several options that customize how the string
-  # is generated. Among those options:
-  #
-  # [:separator]  Used to separate a key/value pair. Default is <tt>': '</tt>.
-  # [:key]        Symbol that will be sent to the key in order to obtain its
-  #               string representation. Defaults to <tt>:to_s</tt>.
-  # [:value]      Symbol that will be sent to the value in order to obtain its
-  #               string representation. Defaults to <tt>:inspect</tt>.
+  # @option opts [String] :separator Separates the key/value pair.
+  #                                  Default is <tt>': '</tt>.
+  # @option opts [Symbol] :key       Will be sent to the key in order to convert
+  #                                  it to a string. Default is <tt>:to_s</tt>.
+  # @option opts [Symbol] :value     Will be sent to the value in order to
+  #                                  convert it to a string. Default is
+  #                                  <tt>:inspect</tt>.
+  # @return [String] the string representation of this ribbon
   def to_s(opts = {})
-    to_s_recursive opts
+    __to_s_recursive__ ::Ribbon.extract_hash_from(opts)
   end
 
-  # Same as #to_s.
   alias inspect to_s
 
-  # The class methods.
-  class << self
+  private
 
-    # A Proc which returns a new ribbon as the default value for the given hash
-    # key.
-    def default_value_proc
-      @default_value_proc ||= (proc { |hash, key| hash[key] = Ribbon.new })
-    end
+  # Computes a string value recursively for the given ribbon, and all ribbons
+  # inside it, using the given options.
+  #
+  # @since 0.3.0
+  # @see #to_s
+  def __to_s_recursive__(opts = {}, ribbon = self)
+    ksym = opts.fetch(:key,   :to_s).to_sym
+    vsym = opts.fetch(:value, :inspect).to_sym
+    separator = opts.fetch(:separator, ': ').to_s
+    values = ribbon.__hash__.map do |k, v|
+      k = k.ribbon if ::Ribbon.wrapped? k
+      v = v.ribbon if ::Ribbon.wrapped? v
+      k = if ::Ribbon.instance? k then __to_s_recursive__ opts, k else k.__send__ ksym end
+      v = if ::Ribbon.instance? v then __to_s_recursive__ opts, v else v.__send__ vsym end
+      "#{k}#{separator}#{v}"
+    end.join ', '
+    "{#{values}}"
+  end
 
-    # If <tt>object</tt> is a hash, converts it to a ribbon. If it is an array,
-    # converts any hashes inside.
-    def convert(object)
-      case object
-        when Hash then Ribbon.new object
-        when Array then object.map { |element| convert element }
-        else object
-      end
-    end
+end
 
-    # Converts all values in the given ribbon.
-    def convert_all!(ribbon)
-      ribbon.__hash__.each do |key, value|
-        ribbon[key] = case value
-          when Ribbon then convert_all! value
-          else convert value
-        end
-      end
-      ribbon
-    end
+class << Ribbon
 
-    # Merges the hash of +new_ribbon+ with the hash of +old_ribbon+, creating a
-    # new ribbon in the process.
-    def merge(old_ribbon, new_ribbon, &block)
-      old_hash = extract_hash_from old_ribbon
-      new_hash = extract_hash_from new_ribbon
-      merged_hash = old_hash.merge new_hash, &block
-      Ribbon.new merged_hash
-    end
+  alias [] new
 
-    # Merges the hash of +new_ribbon+ with the hash of +old_ribbon+, modifying
-    # +old_ribbon+'s hash in the process.
-    def merge!(old_ribbon, new_ribbon, &block)
-      old_hash = extract_hash_from old_ribbon
-      new_hash = extract_hash_from new_ribbon
-      old_hash.merge! new_hash, &block
-      old_ribbon
-    end
+  # Proc used to store a new Ribbon instance as the value of a missing key.
+  #
+  # @return [Proc] the proc used when constructing new hashes
+  # @since 0.4.6
+  def default_value_proc
+    @default_value_proc ||= (proc { |hash, key| hash[key] = Ribbon.new })
+  end
 
-    # Merges the +new_ribbon+ and all nested ribbons with the +old_ribbon+
-    # recursively, returning a new ribbon.
-    def deep_merge(old_ribbon, new_ribbon, &block)
-      deep :merge, old_ribbon, new_ribbon, &block
+  # Converts hashes to ribbons. Will look inside arrays.
+  #
+  # @param object the object to convert
+  # @return the converted value
+  # @since 0.2.0
+  def convert(object)
+    case object
+      when Hash then Ribbon.new object
+      when Array then object.map { |element| convert element }
+      else object
     end
+  end
 
-    # Merges the +new_ribbon+ and all nested ribbons with the +old_ribbon+
-    # recursively, modifying all ribbons in place.
-    def deep_merge!(old_ribbon, new_ribbon, &block)
-      deep :merge!, old_ribbon, new_ribbon, &block
+  # Converts all values inside the given ribbon.
+  #
+  # @param [Ribbon, Ribbon::Wrapper] ribbon the ribbon whose values are to be
+  #                                         converted
+  # @return [Ribbon, Ribbon::Wrapper] the ribbon with all values converted
+  # @since 0.2.0
+  # @see convert
+  def convert_all!(ribbon)
+    ribbon.__hash__.each do |key, value|
+      ribbon[key] = case value
+        when Ribbon then convert_all! value
+        when Ribbon::Wrapper then convert_all! value.ribbon
+        else convert value
+      end
     end
+    ribbon
+  end
 
-    # Returns +true+ if the given +object+ is a ribbon.
-    def instance?(object)
-      Ribbon === object
-    end
+  # Merges the hashes of the given ribbons.
+  #
+  # @param [Ribbon, Ribbon::Wrapper, #to_hash] old_ribbon the ribbon with old
+  #                                                       values
+  # @param [Ribbon, Ribbon::Wrapper, #to_hash] new_ribbon the ribbon with new
+  #                                                       values
+  # @return [Ribbon] a new ribbon containing the results of the merge
+  # @yieldparam key the key which identifies both values
+  # @yieldparam old_value the value from old_ribbon
+  # @yieldparam new_value the value from new_ribbon
+  # @yieldreturn the object that will be used as the new value
+  # @since 0.3.0
+  # @see merge!
+  # @see extract_hash_from
+  def merge(old_ribbon, new_ribbon, &block)
+    old_hash = extract_hash_from old_ribbon
+    new_hash = extract_hash_from new_ribbon
+    merged_hash = old_hash.merge new_hash, &block
+    Ribbon.new merged_hash
+  end
 
-    # Returns +true+ if the given ribbon is wrapped.
-    def wrapped?(ribbon)
-      Ribbon::Wrapper === ribbon
-    end
+  # Merges the hashes of the given ribbons in place.
+  #
+  # @param [Ribbon, Ribbon::Wrapper, #to_hash] old_ribbon the ribbon with old
+  #                                                       values
+  # @param [Ribbon, Ribbon::Wrapper, #to_hash] new_ribbon the ribbon with new
+  #                                                       values
+  # @return [Ribbon, Ribbon::Wrapper, Hash] old_ribbon, which will contain the
+  #                                         results of the merge
+  # @yieldparam key the key which identifies both values
+  # @yieldparam old_value the value from old_ribbon
+  # @yieldparam new_value the value from new_ribbon
+  # @yieldreturn the object that will be used as the new value
+  # @since 0.3.0
+  # @see merge
+  # @see extract_hash_from
+  def merge!(old_ribbon, new_ribbon, &block)
+    old_hash = extract_hash_from old_ribbon
+    new_hash = extract_hash_from new_ribbon
+    old_hash.merge! new_hash, &block
+    old_ribbon
+  end
 
-    # Wraps a ribbon instance in a Ribbon::Wrapper.
-    def wrap(ribbon = ::Ribbon.new)
-      Ribbon::Wrapper.new ribbon
-    end
+  # Merges everything inside the given ribbons.
+  #
+  # @param [Ribbon, Ribbon::Wrapper, #to_hash] old_ribbon the ribbon with old
+  #                                                       values
+  # @param [Ribbon, Ribbon::Wrapper, #to_hash] new_ribbon the ribbon with new
+  #                                                       values
+  # @return [Ribbon] a new ribbon containing the results of the merge
+  # @yieldparam key the key which identifies both values
+  # @yieldparam old_value the value from old_ribbon
+  # @yieldparam new_value the value from new_ribbon
+  # @yieldreturn the object that will be used as the new value
+  # @since 0.4.5
+  # @see merge
+  # @see deep_merge!
+  # @see extract_hash_from
+  def deep_merge(old_ribbon, new_ribbon, &block)
+    deep :merge, old_ribbon, new_ribbon, &block
+  end
 
-    # Unwraps the +ribbon+ if it is wrapped and returns its hash. Returns +nil+
-    # in any other case.
-    def extract_hash_from(ribbon)
-      case ribbon
-        when Ribbon::Wrapper then ribbon.internal_hash
-        when Ribbon then ribbon.__hash__
-        when Hash then ribbon
-        else nil
-      end
-    end
+  # Merges everything inside the given ribbons in place.
+  #
+  # @param [Ribbon, Ribbon::Wrapper, #to_hash] old_ribbon the ribbon with old
+  #                                                       values
+  # @param [Ribbon, Ribbon::Wrapper, #to_hash] new_ribbon the ribbon with new
+  #                                                       values
+  # @return [Ribbon, Ribbon::Wrapper, Hash] old_ribbon, which will contain the
+  #                                         results of the merge
+  # @yieldparam key the key which identifies both values
+  # @yieldparam old_value the value from old_ribbon
+  # @yieldparam new_value the value from new_ribbon
+  # @yieldreturn the object that will be used as the new value
+  # @since 0.4.5
+  # @see merge!
+  # @see deep_merge
+  # @see extract_hash_from
+  def deep_merge!(old_ribbon, new_ribbon, &block)
+    deep :merge!, old_ribbon, new_ribbon, &block
+  end
 
-    # Deserializes the hash from the +string+ using YAML and uses it to
-    # construct a new ribbon.
-    def from_yaml(string)
-      Ribbon.new YAML.load(string)
-    end
+  # Tests whether the given object is an instance of Ribbon.
+  #
+  # @param object the object to be tested
+  # @return [true, false] whether the object is an instance of Ribbon
+  # @since 0.2.0
+  def instance?(object)
+    Ribbon === object
+  end
 
-    # Creates a new instance.
-    #
-    #   Ribbon[a: :a, b: :b, c: :c]
-    alias [] new
+  # Tests whether the given object is an instance of {Ribbon::Wrapper}.
+  #
+  # @param object the object to be tested
+  # @return [true, false] whether the object is an instance of {Ribbon::Wrapper}
+  # @since 0.2.0
+  def wrapped?(ribbon)
+    Ribbon::Wrapper === ribbon
+  end
 
-    private
+  # Wraps an object in a {Ribbon::Wrapper}.
+  #
+  # @param [Ribbon, Ribbon::Wrapper, #to_hash] object the object to be wrapped
+  # @return [Ribbon::Wrapper] a new wrapped ribbon
+  # @since 0.2.0
+  def wrap(object = ::Ribbon.new)
+    Ribbon::Wrapper.new object
+  end
 
-    # Common logic for deep merge functions. +merge_func+ should be either
-    # +merge+ or +merge!+, and denotes which function will be used to merge
-    # recursively. +args+ will be forwarded to the merge function.
-    #
-    # If given a block, it will be called with the key, the old value and the
-    # new value as parameters and its return value will be used. The value of
-    # the new hash will be used, otherwise.
-    def deep(merge_method, old_ribbon, new_ribbon, &block)
-      send merge_method, old_ribbon, new_ribbon do |key, old_value, new_value|
-        if instance?(old_value) and instance?(new_value)
-          deep merge_method, old_value, new_value, &block
-        else
-          if block.respond_to? :call then block.call key, old_value, new_value
-          else new_value end
-        end
-      end
+  # Returns the hash of a Ribbon. Will attempt to convert other objects.
+  #
+  # @param [Ribbon, Ribbon::Wrapper, #to_hash] parameter the object to convert
+  # @return [Hash] the resulting hash
+  # @since 0.2.1
+  def extract_hash_from(parameter)
+    case parameter
+      when Ribbon::Wrapper then parameter.internal_hash
+      when Ribbon then parameter.__hash__
+      else parameter.to_hash
     end
+  end
 
+  # Deserializes the hash from the string using YAML and uses it to construct a
+  # new ribbon.
+  #
+  # @param [String] string a valid YAML string
+  # @return [Ribbon] a new Ribbon
+  # @since 0.4.7
+  def from_yaml(string)
+    Ribbon.new YAML.load(string)
   end
 
   private
 
-  # Computes a string value recursively for the given ribbon and all ribbons
-  # inside it. This implementation avoids creating additional ribbon or
-  # Ribbon::Wrapper objects.
-  def to_s_recursive(opts, ribbon = self)
-    ksym = opts.fetch(:key,   :to_s).to_sym
-    vsym = opts.fetch(:value, :inspect).to_sym
-    separator = opts.fetch(:separator, ': ').to_s
-    values = ribbon.__hash__.map do |k, v|
-      k = k.ribbon if ::Ribbon.wrapped? k
-      v = v.ribbon if ::Ribbon.wrapped? v
-      k = if ::Ribbon.instance? k then to_s_recursive opts, k else k.send ksym end
-      v = if ::Ribbon.instance? v then to_s_recursive opts, v else v.send vsym end
-      "#{k}#{separator}#{v}"
-    end.join ', '
-    "{#{values}}"
+  # Common logic for deep merge methods. +merge_method+ should be either
+  # +:merge+ or +:merge!+, and denotes which method will be used to merge
+  # recursively.
+  #
+  # @yieldparam key the key which identifies both values
+  # @yieldparam old_value the value from old_ribbon
+  # @yieldparam new_value the value from new_ribbon
+  # @yieldreturn the object that will be used as the new value
+  # @since 0.4.5
+  # @see merge!
+  # @see merge
+  # @see deep_merge
+  # @see deep_merge!
+  def deep(merge_method, old_ribbon, new_ribbon, &block)
+    send merge_method, old_ribbon, new_ribbon do |key, old_value, new_value|
+      if instance?(old_value) and instance?(new_value)
+        deep merge_method, old_value, new_value, &block
+      else
+        if block then block.call key, old_value, new_value
+        else new_value end
+      end
+    end
   end
 
 end