ribbon 0.1.0 → 0.2.0

data/lib/ribbon.rb

@@ -1,26 +1,28 @@
-require 'ribbon/methods'
 require 'ribbon/version'
+require 'ribbon/wrapper'
 
-# Ruby Object Notation.
+# == Ruby Object Notation.
 #
-# Inspired by JSON and OpenStruct.
+# ==== Inspired by JSON and OpenStruct.
 #
-# Contains a hash whose keys that are symbols can be accessed via method calls.
-# This is done via <tt>method_missing</tt>.
+# 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.
 #
 # In order to make room for as many method names as possible, Ribbon inherits
-# from BasicObject and implements as many methods as possible at the class
-# level.
+# 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.
 class Ribbon < BasicObject
 
-  extend Methods
-
   # The internal Hash.
   def __hash__
     @hash ||= {}
   end
 
-  # Merges the internal hash with the given one.
+  # 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
    ::Ribbon.convert_all! self
@@ -58,31 +60,49 @@ class Ribbon < BasicObject
     end
   end
 
-  # Computes a simple key:value string for easy visualization.
-  #
-  # 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>.
-  #
-  # No matter what is given as the key or value of a
-  def to_s(opts = {})
-    ksym = opts.fetch(:key,   :to_s).to_sym
-    vsym = opts.fetch(:value, :inspect).to_sym
-    separator = opts.fetch(:separator, ': ').to_s
-    values = ::Ribbon.map(self) do |k, v|
-      k = if ::Ribbon.instance? k then k.to_s opts else k.send ksym end
-      v = if ::Ribbon.instance? v then v.to_s opts else v.send vsym end
-      "#{k}#{separator}#{v}"
-    end.join ', '
-    "{Ribbon #{values}}"
+  # 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
+      when ::Hash then self.new object
+      when ::Array then object.map { |element| convert element }
+      else object
+    end
   end
 
-  # Same as #to_s.
-  alias :inspect :to_s
+  # Converts all values in the given Ribbon.
+  def self.convert_all!(ribbon)
+    ribbon.__hash__.each do |key, value|
+      ribbon[key] = case value
+        when self then convert_all! value
+        else convert value
+      end
+    end
+    ribbon
+  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.
+  def self.wrapped?(ribbon)
+    Wrapper === ribbon
+  end
+
+  # Wraps a Ribbon instance in a Ribbon::Wrapper.
+  def self.wrap(ribbon)
+    Wrapper.new ribbon
+  end
+
+  class << self
+
+    # Wraps a Ribbon instance in a Ribbon::Wrapper.
+    #
+    #   Ribbon[ribbon].keys
+    alias [] wrap
+
+  end
 
 end

data/lib/ribbon/core_ext/hash.rb

@@ -6,7 +6,7 @@ class Ribbon < BasicObject
     # Includes a method to convert hashes to ribbons.
     module Hash
 
-      # Converts this hash to a Ribbon::Object.
+      # Converts this hash to a Ribbon.
       def to_ribbon
         Ribbon.new self
       end

data/lib/ribbon/version.rb

@@ -11,7 +11,7 @@ class Ribbon < BasicObject
     # Minor version.
     #
     # Increments denote backward-compatible changes and additions.
-    MINOR = 1
+    MINOR = 2
 
     # Patch version.
     #

data/lib/ribbon/wrapper.rb

@@ -0,0 +1,122 @@
+require 'ribbon'
+
+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
+  # implemented in this wrapper class instead.
+  #
+  # One usually wraps a Ribbon on the fly in order to work with it:
+  #
+  #   r = Ribbon.new
+  #   Ribbon[r].each { |k, v| p [k,v] }
+  #
+  # If a method the wrapper doesn't respond to is called, it will simply be
+  # forwarded to the wrapped Ribbon:
+  #
+  #   w = Ribbon[r]
+  #   w.x = 10
+  #   w.ribbon.x
+  #   => 10
+  class Wrapper
+
+    class << self
+
+      # Wraps a Ribbon instance.
+      #
+      #   Ribbon::Wrapper[ribbon]
+      alias [] new
+
+    end
+
+    # The wrapped Ribbon object.
+    attr_accessor :ribbon
+
+    # Wraps a Ribbon object, providing many general-purpose methods that were
+    # not defined in the Ribbon itself.
+    def initialize(ribbon = Ribbon.new)
+      self.ribbon = ribbon
+    end
+
+    # Returns the hash of the wrapped Ribbon.
+    def hash
+      ribbon.__hash__
+    end
+
+    # Forwards the method, arguments and block to the wrapped Ribbon's hash, if
+    # it responds to the method, or to the ribbon itself otherwise.
+    def method_missing(method, *args, &block)
+      if hash.respond_to? method then hash
+      else ribbon end.__send__ method, *args, &block
+    end
+
+    # 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
+    # a Ribbon back from the serialized hash, you can simply load the hash and
+    # pass it to the Ribbon constructor:
+    #
+    #   ribbon = Ribbon.new YAML.load(str)
+    def to_yaml
+      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
+    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.
+    def to_hash_recursive(ribbon = self.ribbon)
+      {}.tap do |hash|
+        ribbon.__hash__.each do |key, value|
+          hash[key] = case value
+            when ::Ribbon then to_hash_recursive value
+            when ::Ribbon::Wrapper then to_hash_recursive value.ribbon
+            else value
+          end
+        end
+      end
+    end
+
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ribbon
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-29 00:00:00.000000000 Z
+date: 2011-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rookie
-  requirement: &15229760 !ruby/object:Gem::Requirement
+  requirement: &19808560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *15229760
+  version_requirements: *19808560
 description: Ruby Object Notation. Inspired by JSON and OpenStruct.
 email: matheus.a.m.moreira@gmail.com
 executables: []
@@ -37,8 +37,8 @@ files:
 - lib/ribbon.rb
 - lib/ribbon/core_ext.rb
 - lib/ribbon/core_ext/hash.rb
-- lib/ribbon/methods.rb
 - lib/ribbon/version.rb
+- lib/ribbon/wrapper.rb
 - ribbon.gemspec
 homepage: https://github.com/matheusmoreira/ribbon
 licenses: []
@@ -52,12 +52,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 1132984077947899198
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 1132984077947899198
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.10

data/lib/ribbon/methods.rb

@@ -1,82 +0,0 @@
-class Ribbon < BasicObject
-
-  # Methods that operate on Ribbons. These should be included at the class level
-  # in order to keep as many names available for use with ribbons as possible.
-  module Methods
-
-    # Returns the hash keys of the given ribbon.
-    def keys(ribbon)
-      ribbon.__hash__.keys
-    end
-
-    # Yields a key, value pair to the given block.
-    def each(ribbon, &block)
-      ribbon.__hash__.each &block
-    end
-
-    # Yields a key, value pair to the given block and returns an array
-    # containing the values returned by the block on each iteration.
-    def map(ribbon, &block)
-      ribbon.__hash__.map &block
-    end
-
-    # Merges +old+'s hash with +new+'s. This is equivalent to calling
-    # <tt>merge!</tt> on +old+'s hash and passing it +new+'s hash and the given
-    # block.
-    def merge!(old, new, &block)
-      old_hash, new_hash = old.__hash__, new.__hash__
-      old_hash.merge! new_hash, &block
-    end
-
-    # Converts +ribbon+ and all Ribbons inside into hashes.
-    def to_hash(ribbon)
-      {}.tap do |hash|
-        each(ribbon) do |key, value|
-          hash[key] = case value
-            when Ribbon then to_hash value
-            else value
-          end
-        end
-      end
-    end
-
-    # If <tt>object</tt> is a Hash, converts it to a Ribbon::Object. 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
-
-    # Converts all values in the given ribbon.
-    def convert_all!(ribbon)
-      each(ribbon) do |key, value|
-        ribbon[key] = case value
-          when Ribbon then convert_all! value
-          else convert value
-        end
-      end
-      ribbon
-    end
-
-    # Returns +true+ if the given +object+ is a Ribbon.
-    def instance?(object)
-      Ribbon === object
-    end
-
-    # Converts the 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::Object constructor:
-    #
-    #   ribbon = Ribbon::Object.new YAML.load(str)
-    def to_yaml(ribbon)
-      to_hash(ribbon).to_yaml
-    end
-
-  end
-
-end
-
-require 'ribbon'