ribbon 0.5.0 → 0.6.0

data/lib/ribbon/core_extensions.rb

@@ -0,0 +1,13 @@
+class Ribbon < BasicObject
+
+  # Extensions to the standard library.
+  #
+  # @author Matheus Afonso Martins Moreira
+  # @since 0.6.0
+  module CoreExtensions; end
+
+end
+
+%w(array basic_object hash object).each do |file|
+  require file.prepend 'ribbon/core_extensions/'
+end

data/lib/ribbon/{core_ext → core_extensions}/array.rb

@@ -1,13 +1,18 @@
 require 'ribbon'
 
 class Ribbon < BasicObject
-  module CoreExt
+  module CoreExtensions
 
     # Methods to work with ribbons in arrays.
+    #
+    # @author Matheus Afonso Martins Moreira
+    # @since 0.6.0
     module Array
 
       # If the last argument is a hash, removes and converts it to a ribbon,
       # otherwise returns an empty ribbon.
+      #
+      # @return [Ribbon] the Ribbon at the end of this array
       def extract_ribbon!
         case last
           when Hash then Ribbon.new pop
@@ -19,19 +24,26 @@ class Ribbon < BasicObject
 
       # Extracts the last argument as a wrapped ribbon, or returns an empty one.
       # See #extract_ribbon! for details.
+      #
+      # @return [Ribbon::Wrapper] the wrapped Ribbon at the end of this array
       def extract_wrapped_ribbon!
-        Ribbon.wrap extract_options_as_ribbon!
+        Ribbon.wrap extract_ribbon!
       end
 
       # Same as #extract_ribbon!
+      #
+      #
+      # @return [Ribbon] the Ribbon at the end of this array
       alias extract_options_as_ribbon! extract_ribbon!
 
       # Same as #extract_wrapped_ribbon!
+      #
+      # @return [Ribbon::Wrapper] the wrapped Ribbon at the end of this array
       alias extract_options_as_wrapped_ribbon! extract_wrapped_ribbon!
 
     end
 
-    ::Array.send :include, ::Ribbon::CoreExt::Array
+    ::Array.send :include, ::Ribbon::CoreExtensions::Array
 
   end
 end

data/lib/ribbon/core_extensions/basic_object.rb

@@ -0,0 +1,24 @@
+class Ribbon < BasicObject
+  module CoreExtensions
+
+    # Some useful methods.
+    #
+    # @author Matheus Afonso Martins Moreira
+    # @since 0.6.0
+    module BasicObject
+
+      # Evaluates the block using +instance_eval+ if it takes no arguments;
+      # yields +self+ to it otherwise.
+      #
+      # @yieldparam [self] object this instance
+      # @return [Object, nil] the result of the block or nil if not given one
+      def __yield_or_eval__(&block)
+        if block.arity.zero? then instance_eval &block else block.call self end if block
+      end
+
+    end
+
+    ::BasicObject.send :include, ::Ribbon::CoreExtensions::BasicObject
+
+  end
+end

data/lib/ribbon/core_extensions/hash.rb

@@ -0,0 +1,41 @@
+require 'ribbon'
+
+class Ribbon < BasicObject
+  module CoreExtensions
+
+    # Includes methods to convert hashes to ribbons.
+    #
+    # @author Matheus Afonso Martins Moreira
+    # @since 0.6.0
+    module Hash
+
+      # Converts this hash to a Ribbon.
+      #
+      # @return a new Ribbon with the contents of this hash
+      def to_ribbon
+        Ribbon.new self
+      end
+
+      # Converts this hash to a Ribbon::Wrapper.
+      #
+      # @return a new wrapped Ribbon with the contents of this hash
+      def to_ribbon_wrapper
+        Ribbon.wrap self
+      end
+
+      # Same as #to_ribbon.
+      #
+      # @return a new Ribbon with the contents of this hash
+      alias to_rbon to_ribbon
+
+      # Same as #to_ribbon_wrapper.
+      #
+      # @return a new wrapped Ribbon with the contents of this hash
+      alias to_wrapped_ribbon to_ribbon_wrapper
+
+    end
+
+    ::Hash.send :include, ::Ribbon::CoreExtensions::Hash
+
+  end
+end

data/lib/ribbon/core_extensions/object.rb

@@ -0,0 +1,18 @@
+class Ribbon < BasicObject
+  module CoreExtensions
+
+    # Methods available to all objects.
+    #
+    # @author Matheus Afonso Martins Moreira
+    # @since 0.6.0
+    module Object
+    end
+
+    ::Object.send :include, ::Ribbon::CoreExtensions::Object
+
+  end
+end
+
+%w(option_scope yield_or_eval).each do |file|
+  require file.prepend 'ribbon/core_extensions/object/'
+end

data/lib/ribbon/core_extensions/object/option_scope.rb

@@ -0,0 +1,21 @@
+require 'ribbon/options'
+
+class Ribbon < BasicObject
+  module CoreExtensions
+
+    module Object
+
+      # Applies an option scope to this object, where all methods called in the
+      # block receive the specified options.
+      #
+      # @see Ribbon::Options
+      def option_scope(options = {}, &block)
+        Ribbon::Options.apply_to self, options, &block
+      end
+
+    end
+
+    ::Object.send :include, ::Ribbon::CoreExtensions::Object
+
+  end
+end

data/lib/ribbon/core_extensions/object/yield_or_eval.rb

@@ -0,0 +1,15 @@
+require 'ribbon/core_extensions/basic_object'
+
+class Ribbon < BasicObject
+  module CoreExtensions
+
+    module Object
+
+      alias yield_or_eval __yield_or_eval__
+
+    end
+
+    ::Object.send :include, ::Ribbon::CoreExtensions::Object
+
+  end
+end

data/lib/ribbon/options.rb

@@ -0,0 +1,54 @@
+require 'ribbon'
+require 'ribbon/core_extensions/array'
+
+class Ribbon < BasicObject
+
+  # Applies options to all method calls.
+  #
+  #   Ribbon::Options.new(object, option: :value) do
+  #     method_with some: :settings  # equivalent to { some: :settings, option: :value }
+  #     overrides option: { with: :another_value }
+  #   end
+  #
+  #   Ribbon::Options.apply_to(Ribbon.new, separator: '->') do |ribbon|
+  #     ribbon.to_s
+  #     ribbon.inspect
+  #   end
+  #
+  # @author Matheus Afonso Martins Moreira
+  # @since 0.6.0
+  class Options < BasicObject
+
+    # Applies the given options to all methods sent to the receiver. Will apply
+    # the block immediately, if given one.
+    #
+    # @param receiver the object that will be receiving the methods
+    # @param [Ribbon, Ribbon::Wrapper, #to_hash] options the options that will
+    #                                                    be applied to all
+    #                                                    methods
+    # @see CoreExt::BasicObject#__yield_or_eval__
+    def initialize(receiver, options = {}, &block)
+      @receiver, @options = receiver, options
+      __yield_or_eval__ &block
+    end
+
+    # Merges the options given to the method with the options associated with
+    # this instance and sends the method to the receiver as normal.
+    def method_missing(method, *arguments, &block)
+      options = arguments.extract_options_as_ribbon!
+      arguments << ::Ribbon.deep_merge(@options, options)
+      @receiver.__send__ method, *arguments, &block
+    end
+
+  end
+
+  class << Options
+
+    # Applies options to all method calls.
+    #
+    # @see #initialize
+    alias apply_to new
+
+  end
+
+end

data/lib/ribbon/version.rb

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

data/lib/ribbon/wrapper.rb

@@ -2,68 +2,75 @@ require 'ribbon'
 
 class Ribbon < BasicObject
 
-  # Wraps around a Ribbon in order to provide general-purpose methods.
+  # Wraps 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.
+  # Ribbons are designed to use methods as hash keys. In order to maximize the
+  # number of possibilities, many useful methods, including methods from Object,
+  # were left out and included in this class instead.
   #
-  # 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.
+  # You can use wrapped ribbons like an ordinary hash. Any undefined methods
+  # will be sent to the ribbon's hash. If the hash doesn't respond to the
+  # method, it will be sent to the ribbon itself.
   #
-  #   r = Ribbon.new
-  #   w = Ribbon::Wrapper.new r
+  #   wrapper = Ribbon::Wrapper.new
   #
-  #   w.a.b.c
-  #   w[:a][:b][:c]
+  #   wrapper.a.b.c
+  #    => {}
+  #   wrapper.keys
+  #    => [:a]
   #
-  # Wrapped ribbons talk directly to their ribbon's hash:
+  # Keep in mind that nested ribbons may or may not be wrapped:
   #
-  #   w[:k]
-  #   => nil
+  #   wrapper.a.b.c.keys
+  #    => {}
+  #   wrapper
+  #    => {a: {b: {c: {keys: {}}}}}
   #
-  # However, keep in mind that the wrapped hash may contain other ribbons,
-  # which may not be wrapped:
+  # You can wrap and unwrap all ribbons inside:
   #
-  #   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.x = 10
-  #   w.ribbon.x
-  #   => 10
+  #   wrapper.wrap_all!
+  #   wrapper.unwrap_all!
+  # @author Matheus Afonso Martins Moreira
+  # @since 0.2.0
+  # @see Ribbon
   class Wrapper
 
-    # The wrapped Ribbon object.
-    attr :ribbon
+    # The wrapped Ribbon.
+    #
+    # @return [Ribbon] the ribbon wrapped by this instance
+    def ribbon
+      @ribbon ||= Ribbon.new
+    end
 
-    # Wraps +ribbon+. If it is already wrapped, uses the wrapped ribbon as this
-    # wrapper's ribbon. If it is a hash, creates a new Ribbon with its data. If
-    # it is something else, an ArgumentError will be raised.
+    # Wraps a Ribbon, another Wrapper's Ribbon or a hash.
+    #
+    # @param [Ribbon, Ribbon::Wrapper, #to_hash] ribbon the ribbon that will be
+    #                                                   wrapped
+    # @return [Ribbon] the wrapped Ribbon
     def ribbon=(ribbon)
       @ribbon = case ribbon
         when Wrapper then ribbon.ribbon
-        when Hash then Ribbon.new ribbon
         when Ribbon then ribbon
-        else raise ArgumentError, "Can't wrap #{ribbon.class}"
+        else Ribbon.new ribbon.to_hash
       end
     end
 
-    # Wraps a Ribbon object, providing many general-purpose methods that were
-    # not defined in the Ribbon itself.
+    # Wraps the given Ribbon, another Wrapper's Ribbon or a hash.
+    #
+    # If given a block, the wrapper will be yielded to it. If the block doesn't
+    # take any arguments, it will be evaluated in the context of the wrapper.
+    #
+    # @see #ribbon=
+    # @see Ribbon#initialize
     def initialize(ribbon = Ribbon.new, &block)
       self.ribbon = ribbon
-      if block.arity.zero? then instance_eval &block else block.call self end if block
+      __yield_or_eval__ &block
     end
 
-    # Returns the hash of the wrapped ribbon.
+    # The hash used by the wrapped Ribbon.
+    #
+    # @return [Hash] the internal hash of the Ribbon wrapped by this instance
+    # @since 0.5.0
     def internal_hash
       ribbon.__hash__
     end
@@ -75,67 +82,85 @@ class Ribbon < BasicObject
       else ribbon end.__send__ method, *args, &block
     end
 
-    def deep_merge(ribbon)
-      Ribbon.deep_merge self, ribbon
+    # Merges the contents of this wrapped Ribbon with the contents of the given
+    # Ribbon into a new Ribbon::Wrapper instance.
+    #
+    # @param [Ribbon, Ribbon::Wrapper, #to_hash] ribbon the ribbon with new
+    #                                                   values
+    # @return [Ribbon::Wrapper] a new wrapped ribbon containing the results of
+    #                           the merge
+    # @yieldparam key the key which identifies both values
+    # @yieldparam old_value the value from this wrapped Ribbon
+    # @yieldparam new_value the value from the given ribbon
+    # @yieldreturn the object that will be used as the new value
+    # @since 0.4.5
+    # @see #deep_merge!
+    # @see Ribbon.deep_merge
+    def deep_merge(ribbon, &block)
+      Ribbon.wrap Ribbon.deep_merge(self, ribbon, &block)
     end
 
-    def deep_merge!(ribbon)
-      Ribbon.deep_merge! self, ribbon
+    # Merges this wrapped Ribbon with the given Ribbon.
+    #
+    # @param [Ribbon, Ribbon::Wrapper, #to_hash] ribbon the ribbon with new
+    #                                                   values
+    # @return [self] this Ribbon::Wrapper instance
+    # @yieldparam key the key which identifies both values
+    # @yieldparam old_value the value from this wrapped Ribbon
+    # @yieldparam new_value the value from the given ribbon
+    # @yieldreturn the object that will be used as the new value
+    # @since 0.4.5
+    # @see #deep_merge
+    # @see Ribbon.deep_merge!
+    def deep_merge!(ribbon, &block)
+      Ribbon.deep_merge! self, ribbon, &block
     end
 
     # Wraps all ribbons contained by this wrapper's ribbon.
+    #
+    # @return [self] this Ribbon::Wrapper instance
+    # @since 0.3.0
     def wrap_all!
       wrap_all_recursive!
     end
 
     # Unwraps all ribbons contained by this wrapper's ribbon.
+    #
+    # @return [Ribbon] the Ribbon wrapped by this instance
+    # @since 0.3.0
     def unwrap_all!
       unwrap_all_recursive!
     end
 
     # Converts the wrapped Ribbon and all ribbons inside into hashes.
+    #
+    # @return [Hash] the converted contents of this wrapped Ribbon
     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:
+    # Converts the wrapped ribbon to a hash and serializes it with YAML.
     #
-    #   ribbon = Ribbon.new YAML.load(str)
-    #
-    # Alternatively, you can pass a YAML string to the Wrapper::from_yaml
-    # method.
+    # @return [String] the YAML string that represents this Ribbon
+    # @see from_yaml
     def to_yaml
       to_hash.to_yaml
     end
 
-    # Delegates to Ribbon#to_s.
+    # Delegates to the wrapped Ribbon.
+    #
+    # @return [String] the string representation of this Ribbon::Wrapper
+    # @see Ribbon#to_s
     def to_s
       ribbon.to_s
     end
 
-    # The class methods.
-    class << self
-
-      # Wraps a Ribbon instance.
-      #
-      #   Ribbon::Wrapper[ribbon]
-      alias [] new
-
-      # Deserializes the hash from the +string+ using YAML and uses it to
-      # construct a new wrapped ribbon.
-      def from_yaml(string)
-        Ribbon::Wrapper.new YAML.load(string)
-      end
-
-    end
-
     private
 
     # Converts the wrapped ribbon and all ribbons inside into hashes using
-    # recursion. This implementation avoids the creation of additional ribbon or
-    # wrapper objects.
+    # recursion.
+    #
+    # @return [Hash] the converted contents of the wrapped Ribbon
     def to_hash_recursive(ribbon = self.ribbon)
       {}.tap do |hash|
         ribbon.__hash__.each do |key, value|
@@ -148,21 +173,25 @@ class Ribbon < BasicObject
       end
     end
 
-    # Recursively wraps all ribbons inside. This implementation avoids the
-    # creation of additional ribbon or wrapper objects.
+    # Recursively wraps all ribbons and hashes inside.
+    #
+    # @return [self] this Ribbon::Wrapper instance
+    # @since 0.3.0
     def wrap_all_recursive!(wrapper = self)
-      wrapper.internal_hash.each do |key, value|
-        wrapper.internal_hash[key] = case value
-          when Ribbon then wrap_all_recursive! Ribbon::Wrapper[value]
+      (hash = wrapper.internal_hash).each do |key, value|
+        hash[key] = case value
+          when Ribbon, Hash 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)
+    # Recursively unwraps all wrapped ribbons inside.
+    #
+    # @return [Ribbon] the Ribbon wrapped by this instance
+    # @since 0.3.0
+    def unwrap_all_recursive!(ribbon = self.ribbon)
       ribbon.__hash__.each do |key, value|
         ribbon[key] = case value
           when Ribbon::Wrapper then unwrap_all_recursive! value.ribbon
@@ -173,4 +202,23 @@ class Ribbon < BasicObject
     end
 
   end
+
+  class << Wrapper
+
+    # Wraps a Ribbon instance.
+    #
+    # @see #initialize
+    alias [] new
+
+    # Deserializes the hash from the +string+ using YAML and uses it to
+    # construct a new wrapped ribbon.
+    #
+    # @return [Ribbon::Wrapper] a new wrapped Ribbon
+    # @since 0.4.4
+    # @see #to_yaml
+    def from_yaml(string)
+      ::Ribbon::Wrapper.new YAML.load(string)
+    end
+
+  end
 end