json_builder 2.0.6 → 3.0.0

data/.gitignore

@@ -0,0 +1,4 @@
+json_builder.gemspec
+pkg/*
+.DS_Store
+*.log

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+
+gemspec
+
+gem "rails", "3.0.10"
+gem "capybara", ">= 0.4.0"
+gem "sqlite3"
+
+gem "rspec-rails", ">= 2.0.0.beta"
+
+# To use debugger (ruby-debug for Ruby 1.8.7+, ruby-debug19 for Ruby 1.9.2+)
+# gem 'ruby-debug'
+# gem 'ruby-debug19'

data/Gemfile.lock

@@ -0,0 +1,122 @@
+PATH
+  remote: .
+  specs:
+    json_builder (3.0.0)
+      activesupport (>= 2.0.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    abstract (1.0.0)
+    actionmailer (3.0.10)
+      actionpack (= 3.0.10)
+      mail (~> 2.2.19)
+    actionpack (3.0.10)
+      activemodel (= 3.0.10)
+      activesupport (= 3.0.10)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.5.0)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.14)
+      rack-test (~> 0.5.7)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.10)
+      activesupport (= 3.0.10)
+      builder (~> 2.1.2)
+      i18n (~> 0.5.0)
+    activerecord (3.0.10)
+      activemodel (= 3.0.10)
+      activesupport (= 3.0.10)
+      arel (~> 2.0.10)
+      tzinfo (~> 0.3.23)
+    activeresource (3.0.10)
+      activemodel (= 3.0.10)
+      activesupport (= 3.0.10)
+    activesupport (3.0.10)
+    arel (2.0.10)
+    builder (2.1.2)
+    capybara (1.1.1)
+      mime-types (>= 1.16)
+      nokogiri (>= 1.3.3)
+      rack (>= 1.0.0)
+      rack-test (>= 0.5.4)
+      selenium-webdriver (~> 2.0)
+      xpath (~> 0.1.4)
+    childprocess (0.2.2)
+      ffi (~> 1.0.6)
+    diff-lcs (1.1.3)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    ffi (1.0.9)
+    i18n (0.5.0)
+    json (1.6.1)
+    json_pure (1.6.1)
+    mail (2.2.19)
+      activesupport (>= 2.3.6)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.17.2)
+    nokogiri (1.5.0)
+    polyglot (0.3.3)
+    rack (1.2.4)
+    rack-mount (0.6.14)
+      rack (>= 1.0.0)
+    rack-test (0.5.7)
+      rack (>= 1.0)
+    rails (3.0.10)
+      actionmailer (= 3.0.10)
+      actionpack (= 3.0.10)
+      activerecord (= 3.0.10)
+      activeresource (= 3.0.10)
+      activesupport (= 3.0.10)
+      bundler (~> 1.0)
+      railties (= 3.0.10)
+    railties (3.0.10)
+      actionpack (= 3.0.10)
+      activesupport (= 3.0.10)
+      rake (>= 0.8.7)
+      rdoc (~> 3.4)
+      thor (~> 0.14.4)
+    rake (0.9.2.2)
+    rdoc (3.11)
+      json (~> 1.4)
+    rspec (2.8.0.rc1)
+      rspec-core (= 2.8.0.rc1)
+      rspec-expectations (= 2.8.0.rc1)
+      rspec-mocks (= 2.8.0.rc1)
+    rspec-core (2.8.0.rc1)
+    rspec-expectations (2.8.0.rc1)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.8.0.rc1)
+    rspec-rails (2.8.0.rc1)
+      actionpack (~> 3.0)
+      activesupport (~> 3.0)
+      railties (~> 3.0)
+      rspec (= 2.8.0.rc1)
+    rubyzip (0.9.4)
+    selenium-webdriver (2.10.0)
+      childprocess (>= 0.2.1)
+      ffi (= 1.0.9)
+      json_pure
+      rubyzip
+    sqlite3 (1.3.4)
+    thor (0.14.6)
+    treetop (1.4.10)
+      polyglot
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.31)
+    xpath (0.1.4)
+      nokogiri (~> 1.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  capybara (>= 0.4.0)
+  json_builder!
+  rails (= 3.0.10)
+  rspec
+  rspec-rails (>= 2.0.0.beta)
+  sqlite3

data/README.md

@@ -1,90 +1,252 @@
 # JSON Builder
-Rails provides an excellent XML Builder by default to build RSS and ATOM feeds, but nothing to help you build complex and custom JSON data structures. The standard `to_json` works well, but can get very verbose when you need full control of what is generated. JSON Builder hopes to solve that problem.
+Rails provides an excellent XML Builder by default to build RSS and ATOM feeds, but nothing to help you build complex and custom JSON data structures. The standard `to_json` works just fine, but can get very verbose when you need full control of what is generated and performance is a factor. JSON Builder hopes to solve that problem.
 
-## Using JSON Builder with Rails
-First, make sure to add the gem to your `Gemfile`.
+## Sample Usage
 
-    gem 'json_builder'
+```ruby
+require 'json_builder'
+
+json = JSONBuilder::Compiler.generate do
+  name "Garrett Bjerkhoel"
+  email "spam@garrettbjerkhoel.com"
+  address do
+    street "1234 1st Ave"
+    street2 "Apt 1"
+    city "New York"
+    state "NY"
+    zip 10065
+  end
+  key :nil, "testing a custom key name"
+  skills do
+    ruby true
+    asp false
+  end
+  longstring do
+    # Could be a highly intensive process that only returns a string
+    "12345" * 25
+  end
+end
+```
+
+Which will generate:
+
+```json
+{
+  "name": "Garrett Bjerkhoel",
+  "email": "spam@garrettbjerkhoel.com",
+  "address": {
+    "street": "1234 1st Ave",
+    "street2": "Apt 1",
+    "city": "New York",
+    "state": "NY",
+    "zip": 10065
+  },
+  "nil": "testing a custom key name",
+  "skills": {
+    "ruby": true,
+    "asp": false
+  },
+  "longstring": "1234512345123451234512345..."
+}
+```
+
+If you'd like to just generate an array:
+
+```ruby
+array ["Garrett Bjerkhoel", "John Doe"] do |name|
+  first, last = name.split(' ')
+  first first
+  last last
+end
+```
+
+Which will output the following:
+
+```json
+[
+  {
+    "first": "Garrett",
+    "last": "Bjerkhoel"
+  },
+  {
+    "first": "John",
+    "last": "Doe"
+  }
+]
+```
+
+Just a note, if you use an array block, all other builder methods will be ignored.
 
-Not required, but if you'd like to run the generated JSON through a prettifier for debugging reasons, just set `config.action_view.pretty_print_json` to `true` in your environment config. It defaults to false for speed.
+## Using JSON Builder with Rails
+First, make sure to add the gem to your `Gemfile`.
 
-    Your::Application.configure do
-      config.action_view.pretty_print_json = true
-    end
+```ruby
+gem 'json_builder'
+```
 
 Second, make sure your controller responds to `json`:
 
-    class PostsController < ApplicationController
-      respond_to :json
-      
-      def index
-        @posts = Post.all
-        respond_with @posts
-      end
-    end
-
-Lastly, create `app/views/posts/index.json_builder` which could look something like:
+```ruby
+class UsersController < ApplicationController
+  respond_to :json
+  
+  def index
+    @users = User.order('id DESC').page(params[:page]).per(2)
+    respond_with @users
+  end
+end
+```
+
+Lastly, create `app/views/users/index.json_builder` which could look something like:
     
-    json.posts do
-      json.array! @posts do
-        @posts.each do |user|
-          json.array_item! do
-            render :partial => 'post', :locals => { :json => json, :post => post }
-          end
-        end
-      end
-    end
+```ruby
+count @users.count
+current_page @users.current_page
+per_page @users.per_page
+num_pages @users.num_pages
+results @users do |user|
+  id user.id
+  name user.name
+  body user.body
+  links user.links do |link|
+    url link.url
+    visits link.visits
+    last_visited link.last_visited
+  end
+end
+```
 
 You will get something like:
 
+```json
+{
+  "total": 10,
+  "page": 1,
+  "per_page": 2,
+  "total_pages": 5,
+  "results": [
     {
-      "posts": [
+      "id": 1,
+      "name": "Garrett Bjerkhoel",
+      "body": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod.",
+      "links": [
+        {
+          "url": "http://github.com/",
+          "visits": 500,
+          "last_visited": "2011-11-271T00:00:01Z"
+        },
+        {
+          "url": "http://garrettbjerkhoel.com/",
+          "visits": 1500,
+          "last_visited": "2011-11-261T00:00:01Z"
+        }
+      ]
+    }, {
+      "id": 2,
+      "name": "John Doe",
+      "body": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod.",
+      "links": [
         {
-          "id": 1,
-          "name": "Garrett Bjerkhoel",
-          "body": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod."
-        }, {
-          "id": 2,
-          "name": "John Doe",
-          "body": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod."
+          "url": "http://google.com/",
+          "visits": 11000,
+          "last_visited": "2010-05-221T00:00:01Z"
+        },
+        {
+          "url": "http://twitter.com/",
+          "visits": 155012857,
+          "last_visited": "2011-11-261T00:00:01Z"
         }
       ]
     }
+  ]
+}
+```
 
-## Sample Usage
+### Including JSONP callbacks
 
-    require 'json_builder'
-    json = JSONBuilder::Generator.new
-
-    json.name "Garrett Bjerkhoel"
-    json.address do
-      json.street "1143 1st Ave"
-      json.street2 "Apt 1"
-      json.city "New York"
-      json.state "NY"
-      json.zip 10065
-    end
-    json.skills do
-      json.ruby true
-      json.asp false
-    end
-    
-    puts json.compile!
+Out of the box JSON Builder supports JSONP callbacks when used within a Rails project just by using the callback parameter. For instance, if you requested `/users.json?callback=myjscallback`, you'll get a callback wrapping the response:
+
+```json
+myjscallback([
+  {
+    "name": "Garrett Bjerkhoel"
+  },
+  {
+    "name": "John Doe"
+  }
+])
+```
+
+To be able to turn off this functionality, you can do it per-environment, or globally:
+
+#### Per Environment
+
+```ruby
+Spyder::Application.configure do
+  config.action_view.json_callback = false
+end
+```
+
+#### Globally
+
+```ruby
+ActionView::Base.json_callback = false
+```
+
+### Pretty Print Output
+
+Out of the box JSON Builder supports pretty printing the JSON for the development environment, the rest have it turned off for performance reasons. If you'd like to enable or disable pretty printing you can do it within your environment file or you can do it globally.
+
+With pretty print on:
+
+```json
+{
+  "name": "Garrett Bjerkhoel",
+  "email": "spam@garrettbjerkhoel.com"
+}
+```
+
+Without:
+
+```json
+{"name": "Garrett Bjerkhoel", "email": "spam@garrettbjerkhoel.com"}
+```
+
+#### Per Environment
+
+```ruby
+Spyder::Application.configure do
+  config.action_view.pretty_print_json = false
+end
+```
+
+#### Globally
+
+```ruby
+ActionView::Base.pretty_print_json = false
+```
 
 ## Conversions
 
 Time - [ISO-8601](http://en.wikipedia.org/wiki/ISO_8601)
 
 ## Speed
-JSON Builder is very fast, it's roughly 6 times faster than the core XML Builder based on the [speed benchmark](http://github.com/dewski/json_builder/blob/master/test/benchmarks/speed.rb).
+JSON Builder is very fast, it's roughly 3.6 times faster than the core XML Builder based on the [speed benchmark](http://github.com/dewski/json_builder/blob/master/spec/benchmarks/builder.rb).
 
-                            user       system     total     real
-    JSON Builder            0.700000   0.030000   0.730000  (0.724748)
-    JSON Builder Pretty     1.080000   0.060000   1.140000  (1.149416)
-    XML Builder             4.700000   0.110000   4.810000  (4.822932)
+                 user       system      total       real
+    JSONBuilder  2.950000   0.010000    2.960000    (2.968790)
+        Builder  10.820000  0.040000    10.860000   (10.930497)
 
 ## Examples
 See the [examples](http://github.com/dewski/json_builder/tree/master/examples) directory.
 
+## Note on Patches/Pull Requests
+
+- Fork the project.
+- Make your feature addition or bug fix.
+- Add tests for it. This is important so I don't break it in a future version unintentionally.
+- Commit, do not mess with Rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself in another branch so I can ignore when I pull)
+- Send me a pull request. Bonus points for topic branches.
+
 ## Copyright
-Copyright © 2010 Garrett Bjerkhoel. See [MIT-LICENSE](http://github.com/dewski/json_builder/blob/master/MIT-LICENSE) for details.
+Copyright © 2011 Garrett Bjerkhoel. See [MIT-LICENSE](http://github.com/dewski/json_builder/blob/master/MIT-LICENSE) for details.