json_builder 3.0.6 → 3.0.7

data/Gemfile

@@ -1,3 +1,9 @@
 source "http://rubygems.org"
 
 gemspec
+
+gem 'rake'
+
+group :test do
+	gem 'i18n'
+end

data/Gemfile.lock

@@ -1,121 +1,22 @@
 PATH
   remote: .
   specs:
-    json_builder (3.0.6)
+    json_builder (3.0.7)
       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)
+    activesupport (3.1.3)
+      multi_json (~> 1.0)
     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)
+    multi_json (1.0.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)
+  i18n
   json_builder!
-  rails (>= 2.0.0)
-  rspec-rails (>= 2.0.0.beta)
-  sqlite3
+  rake

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Garrett Bjerkhoel
+Copyright (c) 2012 Garrett Bjerkhoel
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,4 +1,4 @@
-JSON Builder
+JSON Builder [![Build Status](https://secure.travis-ci.org/dewski/json_builder.png)](http://travis-ci.org/dewski/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 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.
 
@@ -259,4 +259,4 @@ There are quite a few other alternatives to JSON Builder, each good in their own
 - Send me a pull request. Bonus points for topic branches.
 
 ## Copyright
-Copyright © 2011 Garrett Bjerkhoel. See [MIT-LICENSE](http://github.com/dewski/json_builder/blob/master/MIT-LICENSE) for details.
+Copyright © 2012 Garrett Bjerkhoel. See [MIT-LICENSE](http://github.com/dewski/json_builder/blob/master/MIT-LICENSE) for details.

data/Rakefile

@@ -1,5 +1,6 @@
 # encoding: UTF-8
 require 'rubygems'
+require 'rake/testtask'
 begin
   require 'bundler/setup'
   Bundler::GemHelper.install_tasks
@@ -7,20 +8,13 @@ rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
 
-require 'rake'
-require 'rake/task'
+desc 'Default: run tests'
+task :default => :test
 
-require 'rspec/core'
-require 'rspec/core/rake_task'
-
-RSpec::Core::RakeTask.new(:spec)
-
-task :default => :spec
-
-# Rake::Task.new(:rdoc) do |rdoc|
-#   rdoc.rdoc_dir = 'rdoc'
-#   rdoc.title    = 'JsonBuilder'
-#   rdoc.options << '--line-numbers' << '--inline-source'
-#   rdoc.rdoc_files.include('README.rdoc')
-#   rdoc.rdoc_files.include('lib/**/*.rb')
-# end
+desc 'Run JSONBuilder tests.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.test_files = FileList['test/*_test.rb']
+  t.verbose = true
+end

data/json_builder.gemspec

@@ -1,23 +1,19 @@
-$:.push File.expand_path("../lib", __FILE__)  
-require "json_builder/version"
+$:.push File.expand_path('../lib', __FILE__)
+require 'json_builder/version'
 
 Gem::Specification.new do |s|
-  s.name = "json_builder"
+  s.name = 'json_builder'
   s.version = JSONBuilder::VERSION
-  s.summary = "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."
-  s.description = "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."
-  s.authors     = ["Garrett Bjerkhoel"]
-  s.email       = ["me@garrettbjerkhoel.com"]
+  s.summary = '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.'
+  s.description = '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.'
+  s.authors     = ['Garrett Bjerkhoel']
+  s.email       = ['me@garrettbjerkhoel.com']
   s.platform    = Gem::Platform::RUBY
-  
-  s.files         = `git ls-files`.split("\n")  
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")  
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }  
-  s.require_paths = ["lib"]
-  
-  s.add_dependency "activesupport", ">= 2.0.0"
-  s.add_development_dependency "rspec-rails", ">= 2.0.0.beta"
-  s.add_development_dependency "rails", ">= 2.0.0"
-  s.add_development_dependency "sqlite3"
-  s.add_development_dependency "capybara", ">= 0.4.0"
-end
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ['lib']
+
+  s.add_dependency 'activesupport', '>= 2.0.0'
+end

data/lib/json_builder.rb

@@ -1,3 +1,8 @@
 require 'json_builder/version'
 require 'json_builder/compiler'
 require 'json_builder/template' if defined? Rails
+
+module JSONBuilder
+  class InvalidArgument < StandardError; end
+  class MissingKeyError < StandardError; end
+end

data/lib/json_builder/compiler.rb

@@ -3,6 +3,13 @@ require 'json_builder/member'
 module JSONBuilder
   class Compiler
     class << self
+      # Public: The helper that builds the JSON structure by calling the
+      # specific methods needed to build the JSON.
+      #
+      # args  - Any number of arguments needed for the JSONBuilder::Compiler.
+      # block - Yielding a block to generate the JSON.
+      #
+      # Returns a String.
       def generate(*args, &block)
         options = args.extract_options!
         compiler = self.new(options)
@@ -10,34 +17,68 @@ module JSONBuilder
         compiler.finalize
       end
     end
-    
+
     attr_accessor :members
     attr_accessor :array
     attr_accessor :scope
     attr_accessor :callback
     attr_accessor :pretty_print
-    
+
+    # Needed to allow for the id key to be used
     undef_method :id if methods.include? 'id'
-    
+
+    # Public: Creates a new Compiler instance used to hold any and
+    # all JSONBuilder::Member objects.
+    #
+    # options - Hash of options used to modify JSON output.
+    #
+    # Examples
+    #
+    #   json = JSONBuilder::Compiler.new(:callback => false)
+    #   json.compile do
+    #     name 'Garrett'
+    #   end
+    #   json.finalize
+    #   # => {"name": "Garrett"}
+    #
+    # Returns instance of JSONBuilder::Compiler.
     def initialize(options={})
       @_members = []
       @_scope = options[:scope]
       @_callback = options[:callback] || true
       @_pretty_print = options[:pretty] || false
-      
+
       # Only copy instance variables if there is a scope and presence of Rails
       copy_instance_variables_from(@_scope) if @_scope
     end
-    
+
+    # Public: Takes a block to generate the JSON structure by calling method_missing
+    # on all members passed to it through the block.
+    #
+    # args     - An array of values passed to JSONBuilder::Value.
+    # block    - Yielding a block to generate the JSON.
+    #
+    # Returns nothing.
     def compile(*args, &block)
       instance_exec(*args, &block)
     end
-    
+
+    # Public: Takes a set number of items to generate a plain JSON array response.
+    #
+    # Returns instance of JSONBuilder::Elements.
     def array(items, &block)
       @_array = Elements.new(@_scope, items, &block)
     end
-    
-    # Need to return a Key instance to allow for arrays to be handled appropriately
+
+    # Public: Called anytime the compiler is passed JSON keys,
+    # first checks to see if the parent object contains the method like
+    # a Rails helper.
+    #
+    # key_name - The key for the JSON member.
+    # args     - An array of values passed to JSONBuilder::Value.
+    # block    - Yielding any block passed to the element.
+    #
+    # Returns nothing.
     def method_missing(key_name, *args, &block)
       if @_scope.respond_to?(key_name) && !ignore_scope_methods.include?(key_name)
         @_scope.send(key_name, *args, &block)
@@ -45,42 +86,90 @@ module JSONBuilder
         key(key_name, *args, &block)
       end
     end
-    
+
+    # Public: Generates the start of the JSON member. Useful if the key you are
+    # generating is dynamic.
+    #
+    # key   - Used to generate the JSON member's key. Can be a String or Symbol.
+    # args  - An array of values passed to JSONBuilder::Value.
+    # block - Yielding any block passed to the element.
+    #
+    # Examples
+    #
+    #   key :hello, 'Hi'
+    #   # => "hello": "Hi"
+    #
+    #   key "item-#{rand(0, 500)}", "I'm random!"
+    #   # => "item-250": "I'm random!"
+    #
+    # Returns instance of JSONBuilder::Member.
     def key(key_name, *args, &block)
       member = Member.new(key_name, @_scope, *args, &block)
       @_members << member
       member
     end
-    
+
+    # Public: Combines the output of the compiled members and the change
+    # there is a JSONP callback. This is what is returned in the response.
+    #
+    # Returns a String.
     def finalize
       include_callback to_s
     end
-    
-    # Once all nodes are compiled, build the string
+
+    # Public: Gathers the JSON structure and calls it's compiler within each
+    # instance.
+    #
+    # Returns a String.
     def to_s
       @_array ? @_array.to_s : "{#{@_members.collect(&:to_s).join(', ')}}"
     end
-    
+
     private
-    
+
+    # Private: Determines whether or not to include a JSONP callback in
+    # the response.
+    #
+    # json - The String representation of the JSON structure.
+    #
+    # Returns a String.
     def include_callback(json)
       @_callback && request_params[:callback] ? "#{request_params[:callback]}(#{pretty_print(json)})" : pretty_print(json)
     end
-    
+
+    # Private: Determines whether or not to pass the string through the a
+    # JSON prettifier to help with debugging.
+    #
+    # json - The String representation of the JSON structure.
+    #
+    # Returns a String.
     def pretty_print(json)
       @_pretty_print ? JSON.pretty_generate(JSON[json]) : json
     end
-    
+
+    # Private: Contains the params from the request.
+    #
+    # Returns a Hash.
     def request_params
       @_scope.respond_to?(:params) ? @_scope.params : {}
     end
-    
+
+    # Private: Takes all instance variables from the scope passed to it
+    # and makes them available to the block that gets compiled.
+    #
+    # object  - The scope which contains the instance variables.
+    # exclude - Any instance variables that should not be set.
+    #
+    # Returns nothing.
     def copy_instance_variables_from(object, exclude = []) #:nodoc:
       vars = object.instance_variables.map(&:to_s) - exclude.map(&:to_s)
       vars.each { |name| instance_variable_set(name.to_sym, object.instance_variable_get(name)) }
     end
-    
-    # There are some special methods that need to be ignored that may be matched within +@_scope+.
+
+    # Private: Array of instance variable names that should not be set for
+    # the scope.
+    #
+    # Returns an Array of Symbols.
     def ignore_scope_methods
       [:id]
     end

data/lib/json_builder/elements.rb

@@ -1,15 +1,29 @@
 module JSONBuilder
   class Elements
     attr_accessor :compilers
-    
+
+    # Public: Creates a new instance of the Elements that generates
+    # an array of JSONBuilder::Member objects.
+    #
+    # scope - The view scope context for any variables.
+    # items - The array of elements to create values from.
+    # block - Yielding any block passed to the element.
+    #
+    # Raises InvalidArgument if the items passed does not respond to each.
+    # Returns a new instance of Elements.
     def initialize(scope, items, &block)
+      raise InvalidArgument.new('items does not respond to each') unless items.respond_to?(:each)
+
       @compilers = []
-      
+
       items.each do |item|
         @compilers << Value.new(scope, item, &block)
       end
     end
-    
+
+    # Public: Generates the array JSON block local values
+    #
+    # Returns a formated JSON String
     def to_s
       "[#{@compilers.collect(&:to_s).join(', ')}]"
     end