jsonify 0.0.3 → 0.0.4

data/Gemfile

@@ -1,4 +1,4 @@
 source "http://rubygems.org"
 
-# Specify your gem's dependencies in jsonify.gemspec
+# Gem dependencies are in jsonify.gemspec
 gemspec

data/README.md

@@ -1,4 +1,4 @@
-# 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 &mdash; a builder for JSON [![Build Status](http://travis-ci.org/bsiggelkow/jsonify.png)](http://travis-ci.org/bsiggelkow/jsonify)
 
 [Jsonify](https://github.com/bsiggelkow/jsonify) is to JSON as [Builder](https://github.com/jimweirich/builder) is to XML.
 
@@ -31,6 +31,12 @@ But an even greater motivation for me was emulating the simplicity of [Builder](
 
 ## Usage
 
+In the examples that follow, the JSON output is usually shown "prettified". Is this only
+for illustration purposes, as the default behavior for Jsonify is not to prettify the output.
+You can enable prettification by passing `:pretty => true` to the Jsonify::Builder constructor; however,
+pretty printing is a relatively costly operation and should not be used in production (unless, of course, you explicitly
+want to show this format).
+
 ### Standalone
     # Create some objects that represent a person and associated hyperlinks
     @person = Struct.new(:first_name,:last_name).new('George','Burdell')
@@ -86,6 +92,242 @@ The Jsonify template handler exposes the `Jsonify::Builder` instance to your tem
       json.world "Jsonify is Working!"
     end
 
+#### Partials
+
+You can use partials with Jsonify view templates, but how you use them will 
+depend on how the information they return is structured. An important to keep in
+mind is that a partial, no matter what kind it is, always a returns a string.
+
+##### Jsonify partials
+
+Any Jsonify partial &mdash; that is, the file has a `.jsonify` extension &mdash;
+will return, by design, a string that is valid JSON. It will represent either a JSON object,
+and be wrapped in curly braces ({}), or a JSON array, and be wrapped in square brackets ([]).
+
+To incorporate such a value into a Jsonify template, Jsonify provides the `ingest!` method. 
+
+You can use this method to add JSON, rendered by a partial, to the builder.
+Let's assume this our main template, `index.jsonify`:
+
+    json << 1
+    json.ingest! (render :partial=>'my_partial')
+
+From the first line, you can tell that an array will be created so this line uses the append operator.
+On the second line, a partial is being added to the builder. Note that you cannot simply place `render :parial ...`
+on a line by itself as you can do with other templates like `erb` and `haml`; you have to explicitly tell Jsonify
+to add it.
+
+Let's say that the partial file, `_my_partial.jsonify`, is as follows:
+
+    json << 3
+    json << 4
+
+This `json` variable is a separate instance of the Jsonify::Builder, distinct from the builder instance,
+in the main template. This partial will end up generating the following string:
+
+    "[3,4]"
+
+The `ingest!` method will actually parse this string back into a Jsonify-based object, and add it
+to the builder's current state. The resulting output will be:
+
+    "[1,[3,4]]"
+
+##### Other partials
+
+You can also use output from non-Jsonify templates (e.g. erb); just remember that the output from a template
+is always a string and that you have to tell the builder how to include the result of the partial.
+For example, suppose I have the partial `_today.erb` with the following content:
+
+    <%= Date.today %>
+
+You can then incorporate this partial into your Jsonify template just as you would any other string value:
+
+    json << 1
+    json.ingest! (render :partial=>'my_partial')
+    json << {:date => (render :partial => 'today')}
+
+  renders ...
+  
+    [1,[3,4],{"date":"2011-07-30"}]
+
+### Usage Patterns
+
+Jsonify is designed to support construction of an valid JSON representation and
+is entirely based on the [JSON specification](http://json.org).
+
+JSON is built on two fundamental structures:
+
+  * __object__: a collection of name-value pairs -- in Jsonify this is a `JsonObject`
+  * __array__: an ordered list of values -- in Jsonify this is a `JsonArray`
+  
+Jsonify adheres to the JSON specification and provides explicit support 
+for working with these primary structures. At the top most level, a JSON string
+must be one of these structures and Jsonify ensures that this condition is met.
+
+#### JSON Objects
+
+A JSON object, sometimes
+referred to as an ___object literal___, is a common structure familiar
+to most developers. Its analogous to the nested element structured common
+in XML. The [JSON RFC](http://www.ietf.org/rfc/rfc4627.txt) states that 
+"the names within an object SHOULD be unique". Jsonify elevates this recommendation
+by backing the JsonObject with a `Hash`; an object must have unique keys and the last one in, wins.
+
+    json = Jsonify::Builder.new
+    json.person do # start a new JsonObject where the key is 'foo'
+      json.name 'George Burdell' # add a pair to this object
+      json.skills ['engineering','bombing'] # adds a pair with an array value
+      json.name 'George P. Burdell'
+    end
+
+compiles to ...
+
+    {
+      "person": {
+        "name": "George P. Burdell",
+        "skills": [
+          "engineering",
+          "bombing"
+        ]
+      }
+    }
+
+It's perfectly legitimate for a JSON representation to simply be a collection
+of name-value pairs without a ___root___ element. Jsonify supports this by
+simply allowing you to specify the pairs that make up the object.
+
+    json = Jsonify::Builder.new
+    json.location 'Library Coffeehouse'
+    json.neighborhood 'Brookhaven'
+
+  compiles to ...
+
+    {
+      "location": "Library Coffeehouse",
+      "neighborhood": "Brookhaven"
+    }
+
+If the ___name___ you want contains whitespace or other characters not allowed in a Ruby method name, use `tag!`.
+
+    json.tag!("my location", 'Library Coffeehouse')
+    json.neighborhood 'Brookhaven'
+
+    {
+      "my location": "Library Coffeehouse",
+      "neighborhood": "Brookhaven"
+    }
+
+Jsonify also supports a hash-style interface for creating JSON objects.
+
+    json = Jsonify::Builder.new
+    
+    json[:foo] = :bar
+    json[:go]  = :far
+    
+  compiles to ...
+
+    {
+      "foo": "bar",
+      "go": "far"
+    }
+
+You can these hash-style methods within a block as well ...
+
+    json.homer do
+      json[:beer] = "Duffs"
+      json[:spouse] = "Marge"
+    end
+
+  compiles to ...
+
+    {
+      "homer": {
+        "beer": "Duffs",
+        "spouse": "Marge"
+      }
+    }
+
+If you prefer a more method-based approach, you can use the `store!` method passing it the key and value.
+
+    json.store!(:foo, :bar)
+    json.store!(:go, :far)
+
+#### JSON Arrays
+
+A JSON array is an ordered list of JSON values. A JSON value can be a simple value,
+like a string or a number, or a supported JavaScript primitive like true, false, or null.
+A JSON value can also be a JSON object or another JSON array. Jsonify strives to make
+this kind of construction possible in a buider-style.
+
+Jsonify supports JSON array construction through two approaches: `method_missing` and `append!`.
+
+##### method_missing
+
+Pass an array and a block to `method_missing` (or `tag!`), and Jsonify will iterate
+over that array, and create a JSON array where each array item is the result of the block.
+If you pass an array that has a length of 5, you will end up with a JSON array that has 5 items.
+That JSON array is then set as the value of the name-value pair, where the name comes from the method name (for `method_missing`)
+or symbol (for `tag!`).
+
+So this construct is really doing two things -- creating a JSON pair, and creating a JSON array as the value of the pair.
+
+    json = Jsonify::Builder.new(:pretty => true)
+    json.letters('a'..'c') do |letter|
+      letter.upcase
+    end
+    
+compiles to ...
+
+    {
+      "letters": [
+        "A",
+        "B",
+        "C"
+      ]
+    }
+
+Another way to handle this particular example is to get rid of the block entirely. 
+Simply pass the array directly &mdash; the result will be the same.
+
+    json.letters ('a'..'c').map(&:upcase)
+
+##### append!
+
+But what if we don't want to start with an object? How do we tell Jsonify to start with an array instead?
+
+You can use `append!` (passing one or more values), or `<<` (which accepts only a single value) to
+the builder and it will assume you are adding values to a JSON array.
+
+    json = Jsonify::Builder.new
+    json.append! 'a'.upcase, 'b'.upcase, 'c'.upcase
+
+    [
+      "A",
+      "B",
+      "C"
+    ]
+
+or more idiomatically ...
+
+    json.append! *('a'..'c').map(&:upcase)
+
+The append ___operator___, `<<`, can be used to push a single value into the array:
+
+    json << 'a'.upcase
+    json << 'b'.upcase
+    json << 'c'.upcase
+    
+Of course, standard iteration works here as well ...
+
+    json = Jsonify::Builder.new
+    ('a'..'c').each do |letter|
+      json << letter.upcase
+    end
+
+#### Mixing JSON Arrays and Objects
+
+___coming soon___
+
 ## Documentation
 
 [Yard Docs](http://rubydoc.info/github/bsiggelkow/jsonify/master/frames)
@@ -95,16 +337,18 @@ The Jsonify template handler exposes the `Jsonify::Builder` instance to your tem
 - [Argonaut](https://github.com/jbr/argonaut)
 - [JSON Builder](https://github.com/dewski/json_builder)
 - [RABL](https://github.com/nesquena/rabl)
+- [Representative](https://github.com/mdub/representative)
 - [Tokamak](https://github.com/abril/tokamak)
 
 ## TODOs
 1. Benchmark performance
 1. Document how partials can be used
+1. Clean up specs
 
 ## Roadmap
 
 1. Split Rails template handling into separate gem
-1. Add support for Sinatra and Padrino (maybe separate gems)
+1. Add support for Sinatra and Padrino (Tilt integration?)
 
 ## License
 

data/lib/jsonify/builder.rb

@@ -134,12 +134,35 @@ module Jsonify
       @level -= 1
     end
     
+    # Ingest a full JSON representation (either an oject or array)
+    # into the builder. The value is parsed, objectified, and added to the
+    # current value at the top of the stack.
+    #
+    # @param [String] json_string a full JSON string (e.g. from a rendered partial)
+    def ingest!(json_string)
+      return if json_string.empty?
+      res = Jsonify::Generate.value(JSON.parse(json_string))
+      current = @stack[@level]
+      if current.nil?
+        @stack[@level] = res
+      elsif JsonObject === current
+        if JsonObject === res
+          @stack[@level].merge res
+        else 
+          raise ArgumentError.new("Cannot add JSON array to JSON Object")
+        end
+      else # current is JsonArray
+        @stack[@level].add res
+      end
+    end
+
     private
     
     # BlankSlate requires the __<method> names
 
     def __store(key,value=nil)
-      (@stack[@level] ||= JsonObject.new).add(key,value)
+      pair = (JsonPair === key ? key : JsonPair.new(key, value))
+      (@stack[@level] ||= JsonObject.new).add(pair)
     end  
 
     def __append(value)

data/lib/jsonify/json_value.rb

@@ -30,9 +30,15 @@ module Jsonify
     end
 
     def add(key, val=nil)
-      pair = (JsonPair === key) ? key : JsonPair.new(key, val)
+      pair = ( JsonPair === key ? key : JsonPair.new(key, val) )
       @values.store(pair.key, pair)
     end
+    
+    def merge(json_object)
+      json_object.values.each do |pair|
+        @values.store(pair.key, pair)
+      end
+    end
 
     alias_method :<<, :add
     alias_method :add!, :add # for consistency with the Builder api

data/lib/jsonify/version.rb

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

data/spec/builder_spec.rb

@@ -70,8 +70,7 @@ PRETTY_JSON
         json.compile!.should == "[1,2]"
       end
       it 'with the append! method' do
-        json.append!( 1,2 )
-            .append! 3
+        json.append!( 1,2 ).append! 3
         json.compile!.should == "[1,2,3]"
       end
     end
@@ -81,9 +80,8 @@ PRETTY_JSON
         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"}'
+        json.store!( "foo", "bar" ).store!( 'no',  "whar" )
+        JSON.parse(json.compile!).should == JSON.parse('{"foo":"bar","no":"whar"}')
       end
     end
   end
@@ -103,7 +101,7 @@ PRETTY_JSON
     it 'array of hashes should work' do
       json << {:foo => :bar}
       json << {:go  => :far}
-      json.compile!.should == "[{\"foo\":\"bar\"},{\"go\":\"far\"}]"
+      json.compile!.should == '[{"foo":"bar"},{"go":"far"}]'
     end
   end
   
@@ -111,7 +109,8 @@ PRETTY_JSON
     it 'simple object should work' do
       json.foo :bar
       json.go :far
-      json.compile!.should ==  "{\"foo\":\"bar\",\"go\":\"far\"}"
+      expected = '{"foo":"bar","go":"far"}'
+      JSON.parse(json.compile!).should ==  JSON.parse(expected)
     end
     it 'should handle arrays' do
       json[1] = [2, 3]
@@ -128,7 +127,8 @@ PRETTY_JSON
           json.tag!('buzz buzz','goo goo')
         end
       end
-      json.compile!.should == "{\"foo foo\":{\"bar bar\":{\"buzz buzz\":\"goo goo\"}}}"
+      expected = '{"foo foo":{"bar bar":{"buzz buzz":"goo goo"}}}'
+      JSON.parse(json.compile!).should == JSON.parse(expected)
     end
 
     it 'complex hash' do
@@ -137,14 +137,14 @@ PRETTY_JSON
           json.baz 'goo'
         end
       end
-      json.compile!.should == "{\"foo\":{\"bar\":{\"baz\":\"goo\"}}}"
+      json.compile!.should == '{"foo":{"bar":{"baz":"goo"}}}'
     end
 
     it 'simple hash' do
       json.foo do
         json.baz :goo
       end
-      json.compile!.should == "{\"foo\":{\"baz\":\"goo\"}}"
+      json.compile!.should == '{"foo":{"baz":"goo"}}'
     end
 
     it 'hash with array' do
@@ -152,7 +152,7 @@ PRETTY_JSON
         json << 1
         json << 2
       end
-      json.compile!.should == "{\"foo\":[1,2]}"
+      json.compile!.should == '{"foo":[1,2]}'
     end
     
     it 'hash with array by iteration' do
@@ -160,13 +160,20 @@ PRETTY_JSON
       json.foo(ary) do |n|
         n * 2
       end 
-      json.compile!.should ==  "{\"foo\":[2,4,6]}"
+      json.compile!.should ==  '{"foo":[2,4,6]}'
     end
     
     it 'simple array with object' do
       json << 1
       json << {:foo => :bar}
-      json.compile!.should == "[1,{\"foo\":\"bar\"}]"
+      json.compile!.should == '[1,{"foo":"bar"}]'
+    end
+    
+    it 'simple array with object via method_missing' do
+      json << 1
+      json << 2
+      json.foo :bar
+      json.compile!.should == "[1,2,{\"foo\":\"bar\"}]"
     end
 
     it 'complex hash with array' do
@@ -224,4 +231,49 @@ PRETTY_JSON
       JSON.parse(json.compile!).should == JSON.parse(expected)
     end
   end
+  
+  describe 'ingest!' do
+    context 'a json object' do
+      let(:json_string) { '{"my girl":"Friday","my daughter":"Wednesday"}' }
+      context 'into' do
+        it 'nothing -- should replace it' do
+          json.ingest! json_string
+          JSON.parse(json.compile!).should == JSON.parse(json_string)
+        end
+        it 'json object -- should merge' do
+          json["my boy"] = "Monday"
+          json["my girl"] = "Sunday"
+          json.ingest! json_string
+          expected = '{"my boy":"Monday","my girl":"Friday","my daughter":"Wednesday"}'
+          JSON.parse(json.compile!).should == JSON.parse(expected)
+        end
+        it 'json array -- should add' do
+          json << 1 << 2
+          json.ingest! json_string
+          expected = '[1,2,{"my girl":"Friday","my daughter":"Wednesday"}]'
+          JSON.parse(json.compile!).should == JSON.parse(expected)
+        end
+      end
+    end
+    context 'a json array' do
+      let(:json_string) { '[1,2,3]' }
+      context 'into' do
+        it 'nothing -- should replace it' do
+          json.ingest! json_string
+          JSON.parse(json.compile!).should == JSON.parse(json_string)
+        end
+        it 'json object -- should raise error' do
+          json["my boy"] = "Monday"
+          json["my girl"] = "Sunday"
+          lambda{ json.ingest! json_string }.should raise_error( ArgumentError )
+        end
+        it 'json array -- should add' do
+          json << 1 << 2
+          json.ingest! json_string
+          expected = '[1,2,[1,2,3]]'
+          JSON.parse(json.compile!).should == JSON.parse(expected)
+        end
+      end
+    end
+  end
 end

metadata

@@ -2,7 +2,7 @@
 name: jsonify
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors: 
 - Bill Siggelkow
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-27 00:00:00 -04:00
+date: 2011-07-30 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: 2505547202778738501
+      hash: -1768495453963674133
       segments: 
       - 0
       version: "0"
@@ -153,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 2505547202778738501
+      hash: -1768495453963674133
       segments: 
       - 0
       version: "0"