jsonify 0.0.2 → 0.0.3

data/README.md

@@ -1,4 +1,4 @@
-# Jsonify
+# Jsonify -- a builder for JSON <a href="http://travis-ci.org/bsiggelkow/jsonify"><img src="https://secure.travis-ci.org/bsiggelkow/jsonify.png" alt=""></a>
 
 [Jsonify](https://github.com/bsiggelkow/jsonify) is to JSON as [Builder](https://github.com/jimweirich/builder) is to XML.
 
@@ -19,18 +19,15 @@ Nevertheless, this forces the developer to place this code into the model when i
 
 When someone asks "Where are the model representations defined?", I don't want to have to say "Well, look in the views folder for XML, but you have to look at the code in the model for the JSON format."
 
-There are other good libraries available that help solve this problem, such as Tokamak and RABL, that allow the developer to specify the representation in one format that is then interpreted into the wanted format at runtime.
-Please take a look at these projects when you consider alternatives; however, its my opinion that they are substantial and inherent differences between XML and JSON.
+There are a number of <a href='#related'>other libraries</a> available that try to solve this problem. Some take a similar approach to Jsonify and provide a builder-style interface.
+Others allow the developer to specify the representation using a common DSL that can generate both JSON and XML.
+Please take a look at these projects when you consider alternatives. It's my opinion that there are substantial and inherent differences between XML and JSON; and that these differences may force the developer to make concessions in one format or the other.
 
-These differences may force the developer make concessions in one format to make the other format correct.
-
-But an even greater motivation for me was emulating the simplicity of Builder. I have not found a single framework for JSON that provides the simplicity and elegance of Builder. Jsonify is my attempt at remedying that situation.
-
-___more coming soon___
+But an even greater motivation for me was emulating the simplicity of [Builder](https://github.com/jimweirich/builder). I have not found a single framework for JSON that provides the simplicity and elegance of Builder. Jsonify is my attempt at remedying that situation.
 
 ## Installation
 
-gem install jsonify
+`gem install jsonify`
 
 ## Usage
 
@@ -82,7 +79,7 @@ Results in ...
 
 ### View Templates
 
-Jsonify includes Rails 3 template handler. Rails will handle any template with a ___.jsonify___ extension with Jsonify.
+Jsonify includes Rails 3 template handler. Rails will handle any template with a `.jsonify` extension with Jsonify.
 The Jsonify template handler exposes the `Jsonify::Builder` instance to your template with the `json` variable as in the following example:
 
     json.hello do
@@ -91,15 +88,18 @@ The Jsonify template handler exposes the `Jsonify::Builder` instance to your tem
 
 ## Documentation
 
-[Jsonify Yard Docs](http://rubydoc.info/github/bsiggelkow/jsonify/master/frames)
-
-## Build Status
+[Yard Docs](http://rubydoc.info/github/bsiggelkow/jsonify/master/frames)
 
-[Compliments of Travis](http://travis-ci.org/bsiggelkow/jsonify)
+<a name='related'/>
+<h2>Related Projects</h2>
+- [Argonaut](https://github.com/jbr/argonaut)
+- [JSON Builder](https://github.com/dewski/json_builder)
+- [RABL](https://github.com/nesquena/rabl)
+- [Tokamak](https://github.com/abril/tokamak)
 
 ## TODOs
-1. Consider simplified means of creating arrays (e.g. json.links(@links) {|link| ...})
 1. Benchmark performance
+1. Document how partials can be used
 
 ## Roadmap
 

data/lib/jsonify/builder.rb

@@ -40,43 +40,93 @@ module Jsonify
       @pretty ? JSON.pretty_generate(JSON.parse(result)) : result
     end
     
-    # Adds the value(s) to the current JSON object in the builder's stack.
-    # @param *args values
-    def add!(*args)
-      __current.add *args
+    # Stores the key and value into a JSON object
+    # @param key the key for the pair
+    # @param value the value for the pair
+    # @return self to allow for chaining
+    def store!(key, value=nil)
+      (@stack[@level] ||= JsonObject.new).add(key,value)
+      self
     end
+
+    alias_method :[]=, :store!
     
-    alias_method :<<, :add!
+    # Append -- pushes the given object on the end of a JsonArray.
+    def <<(val)
+      __append(val)
+      self
+    end
+
+    # Append -- pushes the given variable list objects on to the end of the JsonArray 
+    def append!(*args)
+      args.each do |arg| 
+        __append( arg )
+      end
+      self
+    end
 
-    # Adds a new JsonPair to the builder. 
-    # This method will be called if the name does not match an existing method name.
+    # Adds a new JsonPair to the builder where the key of the pair is set to the method name
+    # (`sym`).
+    # When passed a block, the value of the pair is set to the result of that 
+    # block; otherwise, the value is set to the argument(s) (`args`).
+    #
+    # @example Create an object literal
+    #     json.person do
+    #       json.first_name @person.given_name
+    #       json.last_name @person.surname
+    #     end
+    # 
+    # @example compiles to something like ...
+    #     "person": {
+    #       "first_name": "George",
+    #       "last_name": "Burdell"
+    #     }
+    # 
+    # If a block is given and an argument is passed, the argument it is assumed to be an 
+    # Array (more specifically, an object that responds to `each`). 
+    # The argument is iterated over and each item is yielded to the block.
+    # The result of the block becomes an array item of a JsonArray.
+    #
+    # @example Map an of array of links to an array of JSON objects
+    #     json.links(@links) do |link|
+    #       {:rel => link.first, :href => link.last}
+    #     end
+    # 
+    # @example compiles to something like ...
+    #     "links": [
+    #        {
+    #          "rel": "self",
+    #          "href": "http://example.com/people/123"
+    #        },
+    #        {
+    #          "rel": "school",
+    #          "href": "http://gatech.edu"
+    #        }
+    #     ]
     #
     # @param *args [Array] iterates over the given array yielding each array item to the block; the result of which is added to a JsonArray
     def method_missing(sym, *args, &block)
       
       # When no block given, simply add the symbol and arg as key - value for a JsonPair to current
-      return __current.add( sym, args.length > 1 ? args : args.first ) unless block
+      return __store( sym, args.length > 1 ? args : args.first ) unless block
 
-      # Create a JSON pair and add it to the current object
-      pair = Generate.pair_value(sym) 
-      __current.add(pair)
+      # In a block; create a JSON pair (with no value) and add it to the current object
+      pair = Generate.pair_value(sym)
+      __store pair
 
       # Now process the block
       @level += 1
 
-      unless args.empty?
-        # Argument was given, iterate over it and add result to a JsonArray
-        __set_current JsonArray.new
+      if args.empty?
+        block.call
+      else
         args.first.each do |arg|
-          __current.add block.call(arg)
+          __append block.call(arg)
         end
-      else
-        # No argument was given; ordinary JsonObject is expected
-        block.call(self)
       end
 
-      # Set the value on the pair to current
-      pair.value = __current
+      # Set the value on the pair to the object at the top of the stack
+      pair.value = @stack[@level]
 
       # Pop current off the top of the stack; we are done with it at this point
       @stack.pop
@@ -84,69 +134,17 @@ module Jsonify
       @level -= 1
     end
     
-    # Sets the object at the top of the stack to a new JsonObject, which is yielded to the block.
-    def object!
-      __set_current JsonObject.new
-      yield __current
-    end
-    
-    # Sets the object at the top of the stack to a new JsonArray, which is yielded to the block.
-    def array!
-      __set_current JsonArray.new
-      @level += 1
-        yield @stack[@level-1]
-      @level -= 1
-      __current
-    end
-
-    # Maps each element in the given array to a JsonArray. The result of the block becomes an array item of the JsonArray.
-    # @param array array of objects to iterate over.
-    #
-    # @example Map an of array of links to an array of JSON objects
-    #    json.links do
-    #      json.map!(links) do |link|
-    #        {:rel => link.first, :href => link.last}
-    #      end
-    #    end
-    # 
-    # @example compiles to something  like ...
-    #    "links": [
-    #      {
-    #        "rel": "self",
-    #        "href": "http://example.com/people/123"
-    #      },
-    #      {
-    #        "rel": "school",
-    #        "href": "http://gatech.edu"
-    #      }
-    #    ]
-    def map!(array)
-      __set_current JsonArray.new
-      array.each do |item|
-        __current << (yield item)
-      end
-      __current
-    end
-    
-    alias_method :collect!, :map!
-    
     private
     
-    # Inheriting from BlankSlate requires these funky (aka non-idiomatic) method names
+    # BlankSlate requires the __<method> names
 
-    # Current object at the top of the stack. If there is no object there; initializes to a new JsonObject
-    # 
-    # @return [JsonValue] object at the top of the stack
-    def __current
-      @stack[@level] ||= JsonObject.new
-    end
+    def __store(key,value=nil)
+      (@stack[@level] ||= JsonObject.new).add(key,value)
+    end  
 
-    # Sets the current object at the top of the stack
-    #
-    # @param val object to set at the top of the stack
-    def __set_current(val)
-      @stack[@level] = val
+    def __append(value)
+      (@stack[@level] ||= JsonArray.new).add value
     end
-    
+
   end
 end

data/lib/jsonify/version.rb

@@ -1,3 +1,3 @@
 module Jsonify
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/spec/builder_spec.rb

@@ -63,46 +63,59 @@ PRETTY_JSON
         json.compile!.should == pretty_results.chomp
       end
     end
+    
+    describe 'array creation' do
+      it 'with the append operator (<<)' do
+        json << 1 << 2
+        json.compile!.should == "[1,2]"
+      end
+      it 'with the append! method' do
+        json.append!( 1,2 )
+            .append! 3
+        json.compile!.should == "[1,2,3]"
+      end
+    end
+    describe 'object creation' do
+      it 'should support the element assignment operator( []= )' do
+        json["foo"] = 'bar'
+        json.compile!.should == '{"foo":"bar"}'
+      end
+      it 'should support the store! message' do
+        json.store!( "foo", "bar" )
+            .store!( 'no',  "whar" )
+        json.compile!.should == '{"foo":"bar","no":"whar"}'
+      end
+    end
   end
   
   describe 'arrays' do
     it 'simple array should work' do
-      json.array! do |ary|
-        ary << 1
-        ary << 2
-      end
+      json << 1
+      json << 2
       json.compile!.should == "[1,2]"
     end
     it 'array of arrays should work' do
-      json.array! do |ary|
-        ary << json.array! {|a| a << 1}
-        ary << json.array! {|b| b << 2}
-        ary << 3
-      end
-      json.compile!.should == "[[1],[2],3]"
+      json << [1]
+      json << [2]
+      json << [3]
+      json.compile!.should == "[[1],[2],[3]]"
     end
     it 'array of hashes should work' do
-      json.array! do |ary|
-        ary << {:foo => :bar}
-        ary << {:go  => :far}
-      end
+      json << {:foo => :bar}
+      json << {:go  => :far}
       json.compile!.should == "[{\"foo\":\"bar\"},{\"go\":\"far\"}]"
     end
   end
   
   describe 'objects' do
     it 'simple object should work' do
-      json.object! do |obj|
-        obj.add :foo,:bar
-        obj.add :go, :far
-      end
+      json.foo :bar
+      json.go :far
       json.compile!.should ==  "{\"foo\":\"bar\",\"go\":\"far\"}"
     end
     it 'should handle arrays' do
-      json.object! do |obj|
-        obj.add 1, [2, 3]
-        obj.add 4, 5
-      end
+      json[1] = [2, 3]
+      json[4] = 5
       json.compile!.should ==  '{"1":[2,3],"4":5}'
     end
   end
@@ -136,10 +149,8 @@ PRETTY_JSON
 
     it 'hash with array' do
       json.foo do
-        json.array! do |ary|
-          ary << 1
-          ary << 2
-        end
+        json << 1
+        json << 2
       end
       json.compile!.should == "{\"foo\":[1,2]}"
     end
@@ -153,10 +164,8 @@ PRETTY_JSON
     end
     
     it 'simple array with object' do
-      json.array! do |ary|
-        ary << 1
-        ary << (json.foo 'bar')
-      end
+      json << 1
+      json << {:foo => :bar}
       json.compile!.should == "[1,{\"foo\":\"bar\"}]"
     end
 
@@ -165,10 +174,8 @@ PRETTY_JSON
         json.bar do
           json.baz 'goo'
           json.years do
-            json.array! do |ary|
-              ary << 2011
-              ary << 2012
-            end
+            json << 2011
+            json << 2012
           end
         end
       end
@@ -203,7 +210,7 @@ PRETTY_JSON
         link_class.new('foo.com',     'parent')
       ]
     }
-    it 'should work using array!' do
+    it 'should work using arrays' do
       json.result do
         json.person do
           json.fname 'George'
@@ -216,23 +223,5 @@ PRETTY_JSON
       expected = "{\"result\":{\"person\":{\"fname\":\"George\",\"lname\":\"Burdell\"},\"links\":[{\"href\":\"example.com\",\"rel\":\"self\"},{\"href\":\"foo.com\",\"rel\":\"parent\"}]}}"
       JSON.parse(json.compile!).should == JSON.parse(expected)
     end
-
-    it "should work using map! with argument" do
-      json.result do
-        json.person do
-          json.fname 'George'
-          json.lname 'Burdell'
-        end
-        json.links do
-          json.map!(links) do |link|
-            { :href => link.url, :rel => link.type}
-          end
-        end
-      end
-      expected = "{\"result\":{\"person\":{\"fname\":\"George\",\"lname\":\"Burdell\"},\"links\":[{\"href\":\"example.com\",\"rel\":\"self\"},{\"href\":\"foo.com\",\"rel\":\"parent\"}]}}"
-      JSON.parse(json.compile!).should == JSON.parse(expected)
-    end
   end
-  
-  
 end

metadata

@@ -2,7 +2,7 @@
 name: jsonify
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors: 
 - Bill Siggelkow
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-25 00:00:00 -04:00
+date: 2011-07-27 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -144,7 +144,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -2236513269003945627
+      hash: 2505547202778738501
       segments: 
       - 0
       version: "0"
@@ -153,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -2236513269003945627
+      hash: 2505547202778738501
       segments: 
       - 0
       version: "0"