ribbon 0.2.4 → 0.3.0

data/lib/ribbon.rb

@@ -10,10 +10,35 @@ require 'ribbon/wrapper'
 # general-purpose hash, since the <tt>[key]</tt> and <tt>[key] = value</tt>
 # methods are defined.
 #
-# In order to make room for as many method names as possible, Ribbon inherits
-# from BasicObject and doesn't implement any methods. Ribbons are designed to be
-# used together with Ribbon::Wrapper, which provides the methods useful for
-# computation.
+# 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:
+#
+#   r = Ribbon.new
+#   r.a.b.c = 10
+#
+# Appending a <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
+#    => {x: 10, y: 20, z: 30}
+#
+# Appending a <tt>?</tt> to the end of the property allows you to peek at the
+# contents of the property without creating a new ribbon if it is missing:
+#
+#   r.p?
+#    => 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:
+#
+#   r[:j][:k][:l]
+#
+# 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.
 class Ribbon < BasicObject
 
   # The internal Hash.
@@ -21,7 +46,7 @@ class Ribbon < BasicObject
     @hash ||= {}
   end
 
-  # Initializes the new Ribbon, merging the internal hash with the given one and
+  # Initializes the new ribbon, merging the internal hash with the given one and
   # converting all internal objects. See Ribbon::convert_all! for details.
   def initialize(hash = {}, &block)
     __hash__.merge! hash, &block
@@ -44,23 +69,25 @@ class Ribbon < BasicObject
 
   # Handles the following cases:
   #
-  #   ribbon.method = value  =>  ribbon[method] = value
-  #   ribbon.method!  value  =>  ribbon[method] = value
-  #   ribbon.method?         =>  ribbon[method] ? true : false
   #   ribbon.method          =>  ribbon[method]
+  #   ribbon.method = value  =>  ribbon[method] = value
+  #   ribbon.method!  value  =>  ribbon[method] = value; self
+  #   ribbon.method?         =>  ribbon.__hash__[method]
   def method_missing(method, *args, &block)
-    m = method.to_s.strip.chop.strip.to_sym
+    m = method.to_s.strip.gsub(/[=?!]$/, '').strip.to_sym
     case method.to_s[-1]
-      when '=', '!'
+      when '='
         self[m] = args.first
+      when '!'
+        self[m] = args.first; self
       when '?'
-        __hash__[m] ? true : false
+        self.__hash__[m]
       else
         self[method]
     end
   end
 
-  # If <tt>object</tt> is a Hash, converts it to a Ribbon. If it is an Array,
+  # If <tt>object</tt> is a hash, converts it to a ribbon. If it is an array,
   # converts any hashes inside.
   def self.convert(object)
     case object
@@ -70,7 +97,7 @@ class Ribbon < BasicObject
     end
   end
 
-  # Converts all values in the given Ribbon.
+  # Converts all values in the given ribbon.
   def self.convert_all!(ribbon)
     ribbon.__hash__.each do |key, value|
       ribbon[key] = case value
@@ -81,22 +108,51 @@ class Ribbon < BasicObject
     ribbon
   end
 
-  # Returns +true+ if the given +object+ is a Ribbon.
+  # Computes a simple key: value string for easy visualization 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>.
+  def to_s(opts = {})
+    to_s_recursive opts
+  end
+
+  # Same as #to_s.
+  alias inspect to_s
+
+  # Merges the hash of +new+ with the hash of +old+, creating a new ribbon in
+  # the process.
+  def self.merge(old, new, &block)
+    new extract_hash_from(old).merge(extract_hash_from(ribbon), &block)
+  end
+
+  # Merges the hash of +new+ with the hash of +old+, modifying +old+'s hash in
+  # the process.
+  def self.merge!(old, new, &block)
+    extract_hash_from(old).merge! extract_hash_from(ribbon), &block
+  end
+
+  # Returns +true+ if the given +object+ is a ribbon.
   def self.instance?(object)
     self === object
   end
 
-  # Returns +true+ if the given Ribbon is wrapped.
+  # Returns +true+ if the given ribbon is wrapped.
   def self.wrapped?(ribbon)
     Wrapper === ribbon
   end
 
-  # Wraps a Ribbon instance in a Ribbon::Wrapper.
+  # Wraps a ribbon instance in a Ribbon::Wrapper.
   def self.wrap(ribbon)
     Wrapper.new ribbon
   end
 
-  # Unwraps the +ribbon+ if it is wrapped and returns its hash. Returns nil in
+  # Unwraps the +ribbon+ if it is wrapped and returns its hash. Returns +nil+ in
   # any other case.
   def self.extract_hash_from(ribbon)
     ribbon = ribbon.ribbon if ::Ribbon.wrapped? ribbon
@@ -105,11 +161,30 @@ class Ribbon < BasicObject
 
   class << self
 
-    # Wraps a Ribbon instance in a Ribbon::Wrapper.
+    # Wraps a ribbon instance in a Ribbon::Wrapper.
     #
     #   Ribbon[ribbon].keys
     alias [] wrap
 
   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}}"
+  end
+
 end

data/lib/ribbon/version.rb

@@ -11,12 +11,12 @@ class Ribbon < BasicObject
     # Minor version.
     #
     # Increments denote backward-compatible changes and additions.
-    MINOR = 2
+    MINOR = 3
 
     # Patch version.
     #
     # Increments denote changes in implementation.
-    PATCH = 4
+    PATCH = 0
 
     # Build version.
     #

data/lib/ribbon/wrapper.rb

@@ -5,18 +5,37 @@ class Ribbon < BasicObject
   # Wraps around a Ribbon in order to provide general-purpose methods.
   #
   # Ribbons are designed to use methods as hash keys. In order to maximize
-  # possibilities, many useful methods were left out of the Ribbon class and
+  # possibilities, many useful methods were left out of the ribbon class and
   # implemented in this wrapper class instead.
   #
-  # One usually wraps a Ribbon on the fly in order to work with it:
+  # This class enables you to use ribbons like an ordinary hash. Any undefined
+  # methods called on a wrapped ribbon will be sent to its hash, or to the
+  # ribbon itself if the hash doesn't respond to the method.
   #
   #   r = Ribbon.new
-  #   Ribbon[r].each { |k, v| p [k,v] }
+  #   w = Ribbon::Wrapper.new r
   #
-  # If a method the wrapper doesn't respond to is called, it will simply be
-  # forwarded to the wrapped Ribbon:
+  #   w.a.b.c
+  #   w[:a][:b][:c]
+  #
+  # Wrapped ribbons talk directly to their ribbon's hash:
+  #
+  #   w[:k]
+  #   => nil
+  #
+  # However, keep in mind that the wrapped hash may contain other ribbons,
+  # which may not be wrapped:
+  #
+  #   w.a.b.c[:d]
+  #   => {}
+  #
+  # You can automatically wrap and unwrap all ribbons inside the wrapped one:
+  #
+  #   w.wrap_all!
+  #   w.unwrap_all!
+  #
+  # The wrapped ribbon receives all undefined methods that hashes won't take:
   #
-  #   w = Ribbon[r]
   #   w.x = 10
   #   w.ribbon.x
   #   => 10
@@ -52,7 +71,7 @@ class Ribbon < BasicObject
       self.ribbon = ribbon
     end
 
-    # Returns the hash of the wrapped Ribbon.
+    # Returns the hash of the wrapped ribbon.
     def hash
       ribbon.__hash__
     end
@@ -64,28 +83,22 @@ class Ribbon < BasicObject
       else ribbon end.__send__ method, *args, &block
     end
 
-    # Merges the hash of this wrapped Ribbon with the given +ribbon+, which can
-    # be a Ribbon::Wrapper, a Ribbon or a hash.
-    #
-    # This method returns a new hash.
-    def merge(ribbon, &block)
-      hash.merge Ribbon.extract_hash_from(ribbon), &block
+    # Wraps all ribbons contained by this wrapper's ribbon.
+    def wrap_all!
+      wrap_all_recursive!
     end
 
-    # Merges the hash of this wrapped Ribbon with the given +ribbon+, which can
-    # be a Ribbon::Wrapper, a Ribbon or a hash.
-    #
-    # This method modifies the hash of this wrapped Ribbon.
-    def merge!(ribbon, &block)
-      hash.merge! Ribbon.extract_hash_from(ribbon), &block
+    # Unwraps all ribbons contained by this wrapper's ribbon.
+    def unwrap_all!
+      unwrap_all_recursive!
     end
 
-    # Converts the wrapped Ribbon and all Ribbons inside into hashes.
+    # Converts the wrapped Ribbon and all ribbons inside into hashes.
     def to_hash
       to_hash_recursive
     end
 
-    # Converts the wrapped Ribbon to a hash and serializes it with YAML. To get
+    # Converts the wrapped ribbon to a hash and serializes it with YAML. To get
     # a Ribbon back from the serialized hash, you can simply load the hash and
     # pass it to the Ribbon constructor:
     #
@@ -94,46 +107,16 @@ class Ribbon < BasicObject
       to_hash.to_yaml
     end
 
-    # Computes a simple key: value string for easy visualization of the wrapped
-    # 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>.
-    def to_s(opts = {})
-      to_s_recursive opts, ribbon
+    # Delegates to Ribbon#to_s.
+    def to_s
+      ribbon.to_s
     end
 
-    # Same as #to_s.
-    alias :inspect :to_s
-
     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)
-      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
-
-    # Converts the wrapped Ribbon and all Ribbons inside into hashes using
-    # recursion. This implementation avoids the creation of additional Ribbon or
-    # Ribbon::Wrapper objects.
+    # Converts the wrapped ribbon and all ribbons inside into hashes using
+    # recursion. This implementation avoids the creation of additional ribbon or
+    # wrapper objects.
     def to_hash_recursive(ribbon = self.ribbon)
       {}.tap do |hash|
         ribbon.__hash__.each do |key, value|
@@ -146,5 +129,29 @@ class Ribbon < BasicObject
       end
     end
 
+    # Recursively wraps all ribbons inside. This implementation avoids the
+    # creation of additional ribbon or wrapper objects.
+    def wrap_all_recursive!(wrapper = self)
+      wrapper.hash.each do |key, value|
+        wrapper.hash[key] = case value
+          when ::Ribbon then wrap_all_recursive! ::Ribbon::Wrapper[value]
+          else value
+        end
+      end
+      wrapper
+    end
+
+    # Recursively unwraps all ribbons inside. This implementation avoids the
+    # creation of additional ribbon or wrapper objects.
+    def unwrap_all_recursive!(ribbon = self)
+      ribbon.__hash__.each do |key, value|
+        ribbon[key] = case value
+          when ::Ribbon::Wrapper then unwrap_all_recursive! value.ribbon
+          else value
+        end
+      end
+      ribbon
+    end
+
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ribbon
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2011-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rookie
-  requirement: &8171640 !ruby/object:Gem::Requirement
+  requirement: &15659380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *8171640
+  version_requirements: *15659380
 description: Ruby Object Notation. Inspired by JSON and OpenStruct.
 email: matheus.a.m.moreira@gmail.com
 executables: []
@@ -54,7 +54,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1602149804169223736
+      hash: 2946347091620539582
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -63,7 +63,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1602149804169223736
+      hash: 2946347091620539582
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.10