jsonify 0.0.1 → 0.0.2

data/.gitignore

@@ -2,3 +2,5 @@
 .bundle
 Gemfile.lock
 pkg/*
+.yardoc/
+doc/

data/.travis.yml

@@ -0,0 +1,3 @@
+rvm:
+  - 1.9.2
+  - 1.8.7

data/README.md

@@ -1,6 +1,6 @@
 # Jsonify
 
-[Jsonify](https://github.com/bsiggelkow/jsonify) Jsonify is to JSON as [Builder](https://github.com/jimweirich/builder) is to XML.
+[Jsonify](https://github.com/bsiggelkow/jsonify) is to JSON as [Builder](https://github.com/jimweirich/builder) is to XML.
 
 ## Goal
 
@@ -13,6 +13,19 @@ Jsonify hooks into Rails ActionView to allow you to create JSON view templates i
 JSON and XML are without a doubt the most common representations used by RESTful applications. Jsonify was built around the notion that these representations belong in the ___view___ layer of the application.
 For XML representations, Rails makes this easy through its support of Builder templates, but, when it comes to JSON, there is no clear approach.
 
+For many applications, particularly those based on legacy database, its not uncommon to expose the data in more client-friendly representations than would be presented by the default Rails `to_json` method.
+Rails does provide control of the emitted via a custom implementation of `as_json`.
+Nevertheless, this forces the developer to place this code into the model when it more rightly belongs in the view.
+
+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.
+
+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___
 
 ## Installation
@@ -22,10 +35,9 @@ gem install jsonify
 ## Usage
 
 ### Standalone
-
     # Create some objects that represent a person and associated hyperlinks
-    person = Struct.new(:first_name,:last_name).new('George','Burdell')
-    links = [
+    @person = Struct.new(:first_name,:last_name).new('George','Burdell')
+    @links = [
       ['self',   'http://example.com/people/123'],
       ['school', 'http://gatech.edu'],
     ]
@@ -33,16 +45,14 @@ gem install jsonify
     # Build this information as JSON
     require 'jsonify'
     json = Jsonify::Builder.new(:pretty => true)
-  
+
     json.result do
       json.alumnus do
-        json.fname person.first_name
-        json.lname person.last_name
+        json.fname @person.first_name
+        json.lname @person.last_name
       end
-      json.links do
-        json.map!(links) do |link|
-          {:rel => link.first, :href => link.last}
-        end
+      json.links(@links) do |link|
+        {:rel => link.first, :href => link.last}
       end
     end
 
@@ -70,10 +80,31 @@ Results in ...
       }
     }
 
-
 ### View Templates
 
-___coming soon___
+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
+      json.world "Jsonify is Working!"
+    end
+
+## Documentation
+
+[Jsonify Yard Docs](http://rubydoc.info/github/bsiggelkow/jsonify/master/frames)
+
+## Build Status
+
+[Compliments of Travis](http://travis-ci.org/bsiggelkow/jsonify)
+
+## TODOs
+1. Consider simplified means of creating arrays (e.g. json.links(@links) {|link| ...})
+1. Benchmark performance
+
+## Roadmap
+
+1. Split Rails template handling into separate gem
+1. Add support for Sinatra and Padrino (maybe separate gems)
 
 ## License
 

data/jsonify.gemspec

@@ -25,4 +25,6 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rake'
   s.add_development_dependency 'rspec'
   s.add_development_dependency 'autotest'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'rdiscount'
 end

data/lib/jsonify/builder.rb

@@ -1,53 +1,96 @@
 module Jsonify
   class Builder < BlankSlate
 
+    # Initializes a new builder. The Jsonify::Builder works by keeping a stack of +JsonValue+s.
+    #
+    # @param [Hash] options the options to create with
+    # @option options [boolean] :verify Builder will verify that the compiled JSON string is parseable;  this option does incur a performance penalty and generally should only be used in development
+    # @option options [pretty] :pretty Builder will output the JSON string in a prettier format with new lines and indentation; this option does incur a performance penalty and generally should only be used in development
     def initialize(options={})
       @verify = options[:verify].nil? ? false : options[:verify] 
       @pretty = options[:pretty].nil? ? false : options[:pretty] 
       reset!
     end
     
+    # Clears the builder data
     def reset!
       @level = 0
       @stack = []
     end
 
-    # Builder-style methods
+    # Adds a new JsonPair to the builder. Use this method if the pair "key" has spaces or other characters that prohibit creation via method_missing.
+    #
+    # @param sym [String] the key for the pair
+    # @param *args [arguments] If a block is passed, the first argument will be iterated over and the subsequent result will be added to a JSON array; otherwise, the arguments set value for the `JsonPair`
+    # @param &block a code block the result of which will be used to populate the value for the JSON pair
     def tag!(sym, *args, &block)
       method_missing(sym, *args, &block)
     end
     
+    # Compiles the JSON objects into a string representation. 
+    # If initialized with +:verify => true+, the compiled result will be verified by attempting to re-parse it using +JSON.parse+.
+    # If initialized with +:pretty => true+, the compiled result will be parsed and regenerated via +JSON.pretty_generate+.
+    # This method can be called without any side effects. You can call +compile!+ at any time, and multiple times if desired.
+    #
+    # @raise [TypeError] only if +:verify+ is set to true
+    # @raise [JSON::ParseError] only if +:verify+ is set to true
     def compile!
       result = (@stack[0] ? @stack[0].evaluate : {}.to_json)
       JSON.parse(result) if @verify
       @pretty ? JSON.pretty_generate(JSON.parse(result)) : result
     end
     
-    def add!(value)
-      __current.add Generate.value(value)
+    # Adds the value(s) to the current JSON object in the builder's stack.
+    # @param *args values
+    def add!(*args)
+      __current.add *args
     end
     
+    alias_method :<<, :add!
+
+    # Adds a new JsonPair to the builder. 
+    # This method will be called if the name does not match an existing method name.
+    #
+    # @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)
-      if block        
-        pair = Generate.pair_value(sym)
-        __current.add(pair)
-        @level += 1
-          block.call(self)
-          pair.value = __current
-        @level -= 1
-      else
-        if sym && args && args.length > 0
-          __current.add Generate.pair_value(sym, args.length > 1 ? args : args.first)
+      
+      # 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
+
+      # Create a JSON pair and add it to the current object
+      pair = Generate.pair_value(sym) 
+      __current.add(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
+        args.first.each do |arg|
+          __current.add block.call(arg)
         end
-        __current
+      else
+        # No argument was given; ordinary JsonObject is expected
+        block.call(self)
       end
+
+      # Set the value on the pair to current
+      pair.value = __current
+
+      # Pop current off the top of the stack; we are done with it at this point
+      @stack.pop
+
+      @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
@@ -56,6 +99,27 @@ module Jsonify
       __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|
@@ -70,10 +134,16 @@ module Jsonify
     
     # Inheriting from BlankSlate requires these funky (aka non-idiomatic) 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
 
+    # 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
     end

data/lib/jsonify/generate.rb

@@ -1,8 +1,23 @@
 module Jsonify
+  
+  # Provides a set of functions for creating JsonValues from Ruby objects.
   module Generate
 
     class << self
-      
+
+      # Coerces the given value into a JsonValue.
+      #
+      # The coercion rules are based on the type (class) of the value as follows:
+      # - +JsonValue+ => no coercion
+      # - +String+    => JsonString ( \"foo\" )
+      # - +Numeric+   => JsonNumber ( 1 )
+      # - +TrueClass+ => JsonTrue   ( true )
+      # - +FalseClass+=> JsonFalse  ( false )
+      # - +NilClass+  => JsonNull   ( null )
+      # - +Array+     => JsonArray  ( [1,2,3] )
+      # - +Hash+      => JsonObject ( <code>{"\a":1,\"b\":2}</code> )
+      # 
+      # @param val value to coerce into a JsonValue.
       def value(val)
         case val
           when JsonValue; val

data/lib/jsonify/json_value.rb

@@ -29,13 +29,13 @@ module Jsonify
       @values.values
     end
 
-    def add(val)
-      raise ArgumentError.new("Cannot add #{val} to JsonOject") unless (Array === val || JsonPair === val)       
-      val = JsonPair.new(val.shift, val.length <= 1 ? val.first : val) if Array === val
-      @values.store(val.key, val)
+    def add(key, val=nil)
+      pair = (JsonPair === key) ? key : JsonPair.new(key, val)
+      @values.store(pair.key, pair)
     end
 
     alias_method :<<, :add
+    alias_method :add!, :add # for consistency with the Builder api
 
   end
 
@@ -55,6 +55,7 @@ module Jsonify
     end
 
     alias_method :<<, :add
+    alias_method :add!, :add # for consistency with the Builder api
     
   end
   

data/lib/jsonify/version.rb

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

data/spec/builder_spec.rb

@@ -17,14 +17,19 @@ describe Jsonify::Builder do
     end
     describe 'with verify set' do
       it 'should report a parse error if the result is not parseable' do
-        json = Jsonify::Builder.new(:verify => true)
+
         # Hackery to come up with a failing case
+        class TestBuilder < Jsonify::Builder
+          attr_accessor :stack
+        end
         class FooBar
           def evaluate
             "foobar"
           end
         end
-        json.instance_variable_set(:@stack, [FooBar.new])
+
+        json = TestBuilder.new(:verify => true)
+        json.stack << FooBar.new
         lambda{ json.compile! }.should raise_error(JSON::ParserError)
       end
     end
@@ -78,8 +83,8 @@ PRETTY_JSON
     end
     it 'array of hashes should work' do
       json.array! do |ary|
-        ary << {foo: :bar}
-        ary << {go:  :far}
+        ary << {:foo => :bar}
+        ary << {:go  => :far}
       end
       json.compile!.should == "[{\"foo\":\"bar\"},{\"go\":\"far\"}]"
     end
@@ -88,22 +93,31 @@ PRETTY_JSON
   describe 'objects' do
     it 'simple object should work' do
       json.object! do |obj|
-        obj << [:foo,:bar]
-        obj << [:go, :far]
+        obj.add :foo,:bar
+        obj.add :go, :far
       end
       json.compile!.should ==  "{\"foo\":\"bar\",\"go\":\"far\"}"
     end
-    it 'should treat the first element of an array as a key' do
+    it 'should handle arrays' do
       json.object! do |obj|
-        obj << [1, 2, 3]
-        obj << [4, 5]
+        obj.add 1, [2, 3]
+        obj.add 4, 5
       end
       json.compile!.should ==  '{"1":[2,3],"4":5}'
     end
   end
   
   describe 'using blocks' do
-    
+
+    it 'should allow names with spaces using tag!' do
+      json.tag!("foo foo") do
+        json.tag!("bar bar") do
+          json.tag!('buzz buzz','goo goo')
+        end
+      end
+      json.compile!.should == "{\"foo foo\":{\"bar bar\":{\"buzz buzz\":\"goo goo\"}}}"
+    end
+
     it 'complex hash' do
       json.foo do
         json.bar do
@@ -112,12 +126,14 @@ PRETTY_JSON
       end
       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\"}}"
     end
+
     it 'hash with array' do
       json.foo do
         json.array! do |ary|
@@ -128,6 +144,14 @@ PRETTY_JSON
       json.compile!.should == "{\"foo\":[1,2]}"
     end
     
+    it 'hash with array by iteration' do
+      ary = [1,2,3]
+      json.foo(ary) do |n|
+        n * 2
+      end 
+      json.compile!.should ==  "{\"foo\":[2,4,6]}"
+    end
+    
     it 'simple array with object' do
       json.array! do |ary|
         ary << 1
@@ -148,17 +172,27 @@ PRETTY_JSON
           end
         end
       end
-      json.compile!.should == "{\"foo\":{\"bar\":{\"baz\":\"goo\",\"years\":[2011,2012]}}}"
+      expected = "{\"foo\":{\"bar\":{\"baz\":\"goo\",\"years\":[2011,2012]}}}"
+      JSON.parse(json.compile!).should == JSON.parse(expected)
     end
   end
   
   describe 'without blocks' do
+
     describe 'complex array' do
       it 'should work' do
         json.bar [1,2,{:foo => 'goo'}]
         json.compile!.should == "{\"bar\":[1,2,{\"foo\":\"goo\"}]}"
       end
     end
+
+    describe 'object with null' do
+      it 'should handle missing argument' do
+        json.foo
+        json.compile!.should == '{"foo":null}'
+      end
+    end
+    
   end
   
   describe 'super complex example' do
@@ -175,34 +209,28 @@ PRETTY_JSON
           json.fname 'George'
           json.lname 'Burdell'
         end
-        json.links do
-          json.array! do |ary|
-            links.each do |link|
-              ary << { href: link.url, rel: link.type}
-            end
-          end
+        json.links(links) do |link|
+          { :href => link.url, :rel => link.type}
         end
       end
       expected = "{\"result\":{\"person\":{\"fname\":\"George\",\"lname\":\"Burdell\"},\"links\":[{\"href\":\"example.com\",\"rel\":\"self\"},{\"href\":\"foo.com\",\"rel\":\"parent\"}]}}"
-      json.compile!.should == expected
+      JSON.parse(json.compile!).should == JSON.parse(expected)
     end
 
-    [:map!, :collect!].each do |method|
-      it "should work using #{method} with argument" do
-        json.result do
-          json.person do
-            json.fname 'George'
-            json.lname 'Burdell'
-          end
-          json.links do
-            json.send(method,links) do |link|
-              { href: link.url, rel: link.type}
-            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
-        expected = "{\"result\":{\"person\":{\"fname\":\"George\",\"lname\":\"Burdell\"},\"links\":[{\"href\":\"example.com\",\"rel\":\"self\"},{\"href\":\"foo.com\",\"rel\":\"parent\"}]}}"
-        json.compile!.should == expected
       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
   

data/spec/generate_spec.rb

@@ -12,7 +12,8 @@ describe Jsonify::Generate do
   it 'should build json' do
     json = Jsonify::Generate
     result = json.value links
-    result.evaluate.should == '{"links":[{"rel":"foo","href":"goo"},{"rel":"bar","href":"baz"}]}'
+    expected = '{"links":[{"rel":"foo","href":"goo"},{"rel":"bar","href":"baz"}]}'
+    JSON.parse(result.evaluate).should == JSON.parse(expected)
   end
 
   describe 'complex example' do
@@ -27,7 +28,8 @@ describe Jsonify::Generate do
           ])
         }
       )
-      json.evaluate.should == "{\"links\":[{\"rel\":\"foo\",\"href\":\"goo\"},{\"rel\":\"bar\",\"href\":\"baz\"}]}"
+      expected = "{\"links\":[{\"rel\":\"foo\",\"href\":\"goo\"},{\"rel\":\"bar\",\"href\":\"baz\"}]}"
+      JSON.parse(json.evaluate).should == JSON.parse(expected)
     end
   end
 end

data/spec/json_value_spec.rb

@@ -1,15 +1,53 @@
 require 'spec_helper'
 
 describe Jsonify::JsonValue do
+
   describe Jsonify::JsonPair do
     let(:pair) { Jsonify::JsonPair.new('key',Jsonify::JsonString.new('value')) }
     it 'should be constructed of a key and value' do
       pair.key.should == 'key'
-      # pair.value.should == 
     end
     it 'should evaluate to key:value' do
       pair.evaluate.should == "\"key\":\"value\""
     end
   end
-  
+
+  describe Jsonify::JsonTrue do
+    it 'should have a value of true' do
+      Jsonify::JsonTrue.new.evaluate.should == 'true'
+    end
+  end
+
+  describe Jsonify::JsonFalse do
+    it 'should have a value of false' do
+      Jsonify::JsonFalse.new.evaluate.should == 'false'
+    end
+  end
+
+  describe Jsonify::JsonNull do
+    it 'should have a value of true' do
+      Jsonify::JsonNull.new.evaluate.should == 'null'
+    end
+  end
+
+  describe Jsonify::JsonNumber do
+    it 'should accept an integer' do
+      Jsonify::JsonNumber.new(1).evaluate.should == 1
+    end
+    it 'should accept a float' do
+      Jsonify::JsonNumber.new(1.23).evaluate.should == 1.23
+    end
+  end
+
+  describe Jsonify::JsonString do
+    it 'should quote the value' do
+      Jsonify::JsonString.new('foo').evaluate.should == "\"foo\""
+    end
+    it 'should encode unicode' do
+      unicode = 'goober'.concat(16)
+      Jsonify::JsonString.new(unicode).evaluate.should == "\"goober\\u0010\""
+    end
+  end
+
+
 end

metadata

@@ -2,7 +2,7 @@
 name: jsonify
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Bill Siggelkow
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-23 00:00:00 -04:00
+date: 2011-07-25 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -79,6 +79,28 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: yard
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  name: rdiscount
+  requirement: &id008 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id008
 description: Turn Ruby objects into JSON -- correctly!
 email: 
 - bsiggelkow@me.com
@@ -90,6 +112,7 @@ extra_rdoc_files: []
 
 files: 
 - .gitignore
+- .travis.yml
 - Gemfile
 - LICENSE
 - README.md
@@ -121,7 +144,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3514387947205950198
+      hash: -2236513269003945627
       segments: 
       - 0
       version: "0"
@@ -130,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3514387947205950198
+      hash: -2236513269003945627
       segments: 
       - 0
       version: "0"