ribbon 0.3.1 → 0.4.0

data/README.markdown

@@ -1,9 +1,121 @@
 # Ribbon
 
-RibBON - RuBy Object Notation
+RuBy Object Notation
 
 Inspired by JSON and OpenStruct.
 
+## Quick Start
+
+A Ribbon is a simple but powerful associative data structure designed to be easy
+and natural to use. It allows the dynamic definition of arbitrary attributes,
+which can easily be nested.
+
+    > r = Ribbon.new
+    > r.a.b.c = :d
+     => {}
+    > r
+     => {a: {b: {c: :d}}}
+
+If a property hasn't been set, an empty Ribbon will be used as its value. This
+allows you to easily and seamlessly nest any number of Ribbons. If the property
+_has_ been set, its value will be returned instead.
+
+    > r.a.b.c
+     => :d
+
+You can also set the property if you give an argument to the method.
+
+    > r.a.b.c :e
+     => :e
+    > r
+     => {a: {b: {c: :e}}}
+
+If you give it a block, the value of the option will be yielded to it.
+
+    > Ribbon.new.tap do |config|
+        config.music do |music|
+          music.file do |file|
+            file.extensions %w(flac mp3 ogg wma)
+          end
+        end
+      end
+     => {music: {file: {extensions: ["flac", "mp3", "ogg", "wma"]}}}
+
+If the block takes no arguments (arity of zero), it will be evaluated in the
+context of the value instance. The above example could be rewritten as:
+
+    > Ribbon.new.tap do |config|
+        config.music do
+          music.file do
+            file.extensions %w(flac mp3 ogg wma)
+          end
+        end
+      end
+     => {music: {file: {extensions: ["flac", "mp3", "ogg", "wma"]}}}
+
+If you wish to check if a property has a value, you can simply append a `?` to
+its name. If the property isn't there, `nil` will be returned and no Ribbon will
+be created and stored in its place.
+
+    > r.z?
+     => nil
+    > r
+     => {}
+
+If you append a `!` to the name of the property and give it an argument, the
+value of the property will be set to it and the receiver will be returned,
+allowing you to chain multiple assignments in a single line.
+
+    > r.a!(:z).s!(:x).d!(:c)
+     => {a: :z, s: :x, d: :c}
+
+You can also access the properties by key using the `[]` and `[]=` operators.
+They work just like the regular method calls, which means you can chain them.
+
+    > r[:these_properties][:do_not][:exist]
+    > r[:they][:will_be] = :created
+
+### Ribbon Wrappers
+
+Since Ribbons inherit from BasicObject, they don't include many general-purpose
+methods. In order to solve that problem, `Ribbon::Wrapper` is provided. With a
+wrapped Ribbon instance, you can treat it as if it were an ordinary hash.
+
+    > w = Ribbon::Wrapper.new
+    > w[:x]
+     => nil
+    > w.fetch :x, 10
+     => 10
+
+All undefined methods will be forwarded to the Ribbon's internal hash. However,
+if the hash doesn't respond to the method, it will be forwarded to the Ribbon
+itself. In other words, you can use wrapped ribbons as if they weren't wrapped,
+too.
+
+    > w.x?
+     => nil
+    > w.x.y.z = 10
+     => 10
+
+One big difference to be aware of is that dynamic property creation and access
+via square brackets isn't available with wrapped ribbons, because hashes respond
+to `[]`.
+
+    > w[:undefined][:property]
+     => NoMethodError: undefined method `[]' for nil:NilClass
+
+Also noteworthy is the fact that wrapping a ribbon will not modify it; nested
+ribbons will not be wrapped. However, the are the methods `wrap_all!` and
+`unwrap_all!`, which will recursively wrap and unwrap every ribbon,
+respectively, are available.
+
+In addition to that, many other useful methods are implemented, such as
+`to_hash`, which recursively converts the ribbon and all nested ribbons to pure
+hashes, and `to_yaml`, which serializes the ribbon in YAML format.
+
+Finally, you may access the wrapped ribbon's internal hash using the `hash`
+attribute, and access the wrapped ribbon itself using the `ribbon` attribute.
+
 ---
 
-Extracted from [Acclaim](https://github.com/matheusmoreira/acclaim).
+Originally part of [Acclaim](https://github.com/matheusmoreira/acclaim).

data/lib/ribbon.rb

@@ -17,6 +17,19 @@ require 'ribbon/wrapper'
 #   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
+#
+# If you pass a block, the value will be yielded:
+#
+#   r.a { |a| a.b { |b| b.c 10 } }
+#
+# If the block passed takes no arguments, it will be <tt>instance_eval</tt>ed on
+# the value instead:
+#
+#   r.a { b { c 10 } }
+#
 # Appending a <tt>!</tt> to the end of the property sets the value and returns
 # the receiver:
 #
@@ -54,12 +67,12 @@ class Ribbon < BasicObject
   end
 
   # Gets a value by key.
-  def [](key)
-    __hash__[key] = if __hash__.has_key? key
-      ::Ribbon.convert __hash__[key]
-    else
-      ::Ribbon.new
-    end
+  def [](key, &block)
+    value = if __hash__.has_key? key then ::Ribbon.convert __hash__[key]
+    else ::Ribbon.new end
+    if block.arity.zero? then value.instance_eval &block
+    else block.call value end if block
+    self[key] = value
   end
 
   # Sets a value by key.
@@ -70,6 +83,8 @@ class Ribbon < BasicObject
   # Handles the following cases:
   #
   #   ribbon.method          =>  ribbon[method]
+  #   ribbon.method   value  =>  ribbon[method] = value; ribbon[method]
+  #   ribbon.method  &block  =>  ribbon[method, &block]
   #   ribbon.method = value  =>  ribbon[method] = value
   #   ribbon.method!  value  =>  ribbon[method] = value; self
   #   ribbon.method?         =>  ribbon.__hash__[method]
@@ -83,7 +98,8 @@ class Ribbon < BasicObject
       when '?'
         self.__hash__[m]
       else
-        self[method]
+        self[method] = args.first unless args.empty?
+        self[method, &block]
     end
   end
 
@@ -148,7 +164,7 @@ class Ribbon < BasicObject
   end
 
   # Wraps a ribbon instance in a Ribbon::Wrapper.
-  def self.wrap(ribbon)
+  def self.wrap(ribbon = Ribbon.new)
     ::Ribbon::Wrapper.new ribbon
   end
 

data/lib/ribbon/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ribbon
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-30 00:00:00.000000000 Z
+date: 2012-01-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rookie
-  requirement: &18538300 !ruby/object:Gem::Requirement
+  requirement: &18324900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *18538300
+  version_requirements: *18324900
 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: 63380645992066073
+      hash: 1159963088107678730
 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: 63380645992066073
+      hash: 1159963088107678730
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.10