jbuilder 0.3

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 David Heinemeier Hansson, 37signals
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,73 @@
+Jbuilder
+========
+
+Jbuilder gives you a simple DSL for declaring JSON structures that beats massaging giant hash structures. This is particularly helpful when the generation process is fraught with conditionals and loops. Here's a simple example:
+
+    Jbuilder.encode do |json|
+      json.content format_content(@message.content)
+      json.(@message, :created_at, :updated_at)
+  
+      json.author do |json|
+        json.name @message.creator.name.familiar
+        json.email_address @message.creator.email_address_with_name
+        json.url url_for(@message.creator, format: :json)
+      end
+  
+      if current_user.admin?
+        json.visitors calculate_visitors(@message)
+      end
+  
+      json.comments @message.comments, :content, :created_at
+      
+      json.attachments @message.attachments do |json, attachment|
+        json.filename attachment.filename
+        json.url url_for(attachment)
+      end
+    end
+
+This will build the following structure:
+
+    { 
+      "content": "<p>This is <i>serious</i> monkey business",
+      "created_at": "2011-10-29T20:45:28-05:00",
+      "updated_at": "2011-10-29T20:45:28-05:00",
+    
+      "author": {
+        "name": "David H.",
+        "email_address": "'David Heinemeier Hansson' <david@heinemeierhansson.com>",
+        "url": "http://example.com/users/1-david.json"
+      },
+    
+      "visitors": 15,
+    
+      "comments": [
+        { "content": "Hello everyone!", "created_at": "2011-10-29T20:45:28-05:00" },
+        { "content": "To you my good sir!", "created_at": "2011-10-29T20:47:28-05:00" }
+      ],
+      
+      "attachment": [
+        { "filename": "forecast.xls", "url": "http://example.com/downloads/forecast.xls" },
+        { "filename": "presentation.pdf", "url": "http://example.com/downloads/presentation.pdf" }
+      ]
+    }
+
+You can either use Jbuilder stand-alone or directly as an ActionView template language. When required in Rails, you can create views ala show.json.jbuilder (the json is already yielded):
+
+    # Any helpers available to views are available to the builder
+    json.content format_content(@message.content)
+    json.(@message, :created_at, :updated_at)
+
+    json.author do |json|
+      json.name @message.creator.name.familiar
+      json.email_address @message.creator.email_address_with_name
+      json.url url_for(@message.creator, format: :json)
+    end
+
+    if current_user.admin?
+      json.visitors calculate_visitors(@message)
+    end
+
+    # You can use partials as well, just remember to pass in the json instance
+    json.partial! "api/comments/comments" @message.comments
+
+Note: Jbuilder is similar to Garrett Bjerkhoel's json_builder, which I discovered after making this, but the DSL has taken a different turn and will retain the explicit yield style (vs json_builder's 3.0's move to instance_eval).

data/jbuilder.gemspec

@@ -0,0 +1,12 @@
+Gem::Specification.new do |s|
+  s.name    = 'jbuilder'
+  s.version = '0.3'
+  s.author  = 'David Heinemeier Hansson'
+  s.email   = 'david@37signals.com'
+  s.summary = 'Create JSON structures via a Builder-style DSL'
+
+  s.add_dependency 'activesupport', '>= 3.0.0'
+  s.add_dependency 'blankslate', '>= 2.1.2.4'
+
+  s.files = Dir["#{File.dirname(__FILE__)}/**/*"]
+end

data/lib/jbuilder.rb

@@ -0,0 +1,165 @@
+require 'blankslate'
+require 'active_support/ordered_hash'
+require 'active_support/core_ext/array/access'
+require 'active_support/core_ext/enumerable'
+require 'active_support/json'
+
+class Jbuilder < BlankSlate
+  # Yields a builder and automatically turns the result into a JSON string
+  def self.encode
+    new._tap { |jbuilder| yield jbuilder }.target!
+  end
+
+  define_method(:__class__, find_hidden_method(:class))
+  define_method(:_tap, find_hidden_method(:tap))
+
+  def initialize
+    @attributes = ActiveSupport::OrderedHash.new
+  end
+
+  # Turns the current element into an array and yields a builder to add a hash.
+  #
+  # Example:
+  #
+  #   json.comments do |json|
+  #     json.child! { |json| json.content "hello" }
+  #     json.child! { |json| json.content "world" }
+  #   end
+  #
+  #   { "comments": [ { "content": "hello" }, { "content": "world" } ]}
+  #
+  # More commonly, you'd use the combined iterator, though:
+  #
+  #   json.comments(@post.comments) do |json, comment|
+  #     json.content comment.formatted_content
+  #   end  
+  def child!
+    @attributes = [] unless @attributes.is_a? Array
+    @attributes << _new_instance._tap { |jbuilder| yield jbuilder }.attributes!
+  end
+
+  # Iterates over the passed collection and adds each iteration as an element of the resulting array.
+  #
+  # Example:
+  #
+  #   json.array!(@people) do |json, person|
+  #     json.name person.name
+  #     json.age calculate_age(person.birthday)
+  #   end
+  #
+  #   [ { "David", 32 }, { "Jamie", 31 } ]
+  #
+  # If you are using Ruby 1.9+, you can use the call syntax instead of an explicit extract! call:
+  #
+  #   json.(@people) { |json, person| ... }
+  #
+  # It's generally only needed to use this method for top-level arrays. If you have named arrays, you can do:
+  #
+  #   json.people(@people) do |json, person|
+  #     json.name person.name
+  #     json.age calculate_age(person.birthday)
+  #   end  
+  #
+  #   { "people": [ { "David", 32 }, { "Jamie", 31 } ] }
+  def array!(collection)
+    collection.each do |element|
+      child! do |child|
+        yield child, element
+      end
+    end
+  end
+
+  # Extracts the mentioned attributes from the passed object and turns them into attributes of the JSON.
+  #
+  # Example:
+  #
+  #   json.extract! @person, :name, :age
+  #
+  #   { "David", 32 }, { "Jamie", 31 }
+  #
+  # If you are using Ruby 1.9+, you can use the call syntax instead of an explicit extract! call:
+  #
+  #   json.(@person, :name, :age)
+  def extract!(object, *attributes)
+    attributes.each do |attribute|
+      __send__ attribute, object.send(attribute)
+    end
+  end
+
+  if RUBY_VERSION > '1.9'
+    def call(*args)
+      case
+      when args.one?
+        array!(args.first) { |json, element| yield json, element }
+      when args.many?
+        extract!(*args)
+      end
+    end
+  end
+
+  # Returns the attributes of the current builder.
+  def attributes!
+    @attributes
+  end
+  
+  # Encodes the current builder as JSON.
+  def target!
+    ActiveSupport::JSON.encode @attributes
+  end
+
+
+  private
+    def method_missing(method, *args)
+      case
+      when args.one? && block_given?
+        _yield_iteration(method, args.first) { |child, element| yield child, element }
+      when args.one?
+        _assign method, args.first
+      when args.empty? && block_given?
+        _yield_nesting(method) { |jbuilder| yield jbuilder }
+      when args.many? && args.first.is_a?(Enumerable)
+        _inline_nesting method, args.first, args.from(1)
+      when args.many?
+        _inline_extract method, args.first, args.from(1)
+      end
+    end
+
+    def _assign(key, value)
+      @attributes[key] = value
+    end
+
+    # Overwrite in subclasses if you need to add initialization values
+    def _new_instance
+      __class__.new
+    end
+
+    def _yield_nesting(container)
+      @attributes[container] = _new_instance._tap { |jbuilder| yield jbuilder }.attributes!
+    end
+
+    def _inline_nesting(container, collection, attributes)
+      __send__(container) do |parent|
+        collection.each do |element|
+          parent.child! do |child|
+            attributes.each do |attribute|
+              child.__send__ attribute, element.send(attribute)
+            end
+          end
+        end
+      end
+    end
+    
+    def _yield_iteration(container, collection)
+      __send__(container) do |parent|
+        parent.array!(collection) do |child, element|
+          yield child, element
+        end
+      end
+    end
+    
+    def _inline_extract(container, record, attributes)
+      __send__(container) { |parent| parent.extract! record, *attributes }
+    end
+end
+
+require "jbuilder_template" if defined?(ActionView::Template)

data/lib/jbuilder_template.rb

@@ -0,0 +1,23 @@
+class JbuilderTemplate < Jbuilder
+  def self.encode(context)
+    new(context)._tap { |jbuilder| yield jbuilder }.target!
+  end
+
+  def initialize(context)
+    @context = context
+    super()
+  end
+  
+  def partial!(partial_name, options = {})
+    @context.render(partial_name, options.merge(json: self))
+  end
+  
+  private
+    def _new_instance
+      __class__.new(@context)
+    end
+end
+
+ActionView::Template.register_template_handler :jbuilder, Proc.new { |template|
+  "if defined?(json); #{template.source}; else; JbuilderTemplate.encode(self) do |json|;#{template.source};end; end;"
+}

data/test/jbuilder_test.rb

@@ -0,0 +1,195 @@
+require 'test/unit'
+require 'active_support/test_case'
+
+require 'jbuilder'
+
+class JbuilderTest < ActiveSupport::TestCase
+  test "single key" do
+    json = Jbuilder.encode do |json|
+      json.content "hello"
+    end
+    
+    assert_equal "hello", JSON.parse(json)["content"]
+  end
+
+  test "multiple keys" do
+    json = Jbuilder.encode do |json|
+      json.title "hello"
+      json.content "world"
+    end
+    
+    JSON.parse(json).tap do |parsed|
+      assert_equal "hello", parsed["title"]
+      assert_equal "world", parsed["content"]
+    end
+  end
+  
+  test "extracting from object" do
+    person = Struct.new(:name, :age).new("David", 32)
+    
+    json = Jbuilder.encode do |json|
+      json.extract! person, :name, :age
+    end
+    
+    JSON.parse(json).tap do |parsed|
+      assert_equal "David", parsed["name"]
+      assert_equal 32, parsed["age"]
+    end
+  end
+  
+  test "extracting from object using call style for 1.9" do
+    person = Struct.new(:name, :age).new("David", 32)
+    
+    json = Jbuilder.encode do |json|
+      json.(person, :name, :age)
+    end
+    
+    JSON.parse(json).tap do |parsed|
+      assert_equal "David", parsed["name"]
+      assert_equal 32, parsed["age"]
+    end
+  end
+  
+  test "nesting single child with block" do
+    json = Jbuilder.encode do |json|
+      json.author do |json|
+        json.name "David"
+        json.age  32
+      end
+    end
+    
+    JSON.parse(json).tap do |parsed|
+      assert_equal "David", parsed["author"]["name"]
+      assert_equal 32, parsed["author"]["age"]
+    end
+  end
+  
+  test "nesting multiple children with block" do
+    json = Jbuilder.encode do |json|
+      json.comments do |json|
+        json.child! { |json| json.content "hello" }
+        json.child! { |json| json.content "world" }
+      end
+    end
+
+    JSON.parse(json).tap do |parsed|
+      assert_equal "hello", parsed["comments"].first["content"]
+      assert_equal "world", parsed["comments"].second["content"]
+    end
+  end
+  
+  test "nesting single child with inline extract" do
+    person = Class.new do
+      attr_reader :name, :age
+      
+      def initialize(name, age)
+        @name, @age = name, age
+      end
+    end.new("David", 32)
+    
+    json = Jbuilder.encode do |json|
+      json.author person, :name, :age
+    end
+    
+    JSON.parse(json).tap do |parsed|
+      assert_equal "David", parsed["author"]["name"]
+      assert_equal 32,      parsed["author"]["age"]
+    end
+  end
+  
+  test "nesting multiple children from array" do
+    comments = [ Struct.new(:content, :id).new("hello", 1), Struct.new(:content, :id).new("world", 2) ]
+    
+    json = Jbuilder.encode do |json|
+      json.comments comments, :content
+    end
+    
+    JSON.parse(json).tap do |parsed|
+      assert_equal ["content"], parsed["comments"].first.keys
+      assert_equal "hello", parsed["comments"].first["content"]
+      assert_equal "world", parsed["comments"].second["content"]
+    end
+  end
+  
+  
+  test "nesting multiple children from array with inline loop" do
+    comments = [ Struct.new(:content, :id).new("hello", 1), Struct.new(:content, :id).new("world", 2) ]
+    
+    json = Jbuilder.encode do |json|
+      json.comments comments do |json, comment|
+        json.content comment.content
+      end
+    end
+    
+    JSON.parse(json).tap do |parsed|
+      assert_equal ["content"], parsed["comments"].first.keys
+      assert_equal "hello", parsed["comments"].first["content"]
+      assert_equal "world", parsed["comments"].second["content"]
+    end
+  end
+
+  test "nesting multiple children from array with inline loop on root" do
+    comments = [ Struct.new(:content, :id).new("hello", 1), Struct.new(:content, :id).new("world", 2) ]
+    
+    json = Jbuilder.encode do |json|
+      json.(comments) do |json, comment|
+        json.content comment.content
+      end
+    end
+    
+    JSON.parse(json).tap do |parsed|
+      assert_equal "hello", parsed.first["content"]
+      assert_equal "world", parsed.second["content"]
+    end
+  end
+  
+  test "array nested inside nested hash" do
+    json = Jbuilder.encode do |json|
+      json.author do |json|
+        json.name "David"
+        json.age  32
+        
+        json.comments do |json|
+          json.child! { |json| json.content "hello" }
+          json.child! { |json| json.content "world" }
+        end
+      end
+    end
+    
+    JSON.parse(json).tap do |parsed|
+      assert_equal "hello", parsed["author"]["comments"].first["content"]
+      assert_equal "world", parsed["author"]["comments"].second["content"]
+    end
+  end
+  
+  test "array nested inside array" do
+    json = Jbuilder.encode do |json|
+      json.comments do |json|
+        json.child! do |json| 
+          json.authors do |json|
+            json.child! do |json|
+              json.name "david"
+            end
+          end
+        end
+      end
+    end
+    
+    assert_equal "david", JSON.parse(json)["comments"].first["authors"].first["name"]
+  end
+  
+  test "top-level array" do
+    comments = [ Struct.new(:content, :id).new("hello", 1), Struct.new(:content, :id).new("world", 2) ]
+
+    json = Jbuilder.encode do |json|
+      json.array!(comments) do |json, comment|
+        json.content comment.content
+      end
+    end
+    
+    JSON.parse(json).tap do |parsed|
+      assert_equal "hello", parsed.first["content"]
+      assert_equal "world", parsed.second["content"]
+    end
+  end 
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: jbuilder
+version: !ruby/object:Gem::Version
+  version: '0.3'
+  prerelease: 
+platform: ruby
+authors:
+- David Heinemeier Hansson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-11-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: &70104549490040 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *70104549490040
+- !ruby/object:Gem::Dependency
+  name: blankslate
+  requirement: &70104549489160 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.1.2.4
+  type: :runtime
+  prerelease: false
+  version_requirements: *70104549489160
+description: 
+email: david@37signals.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ./jbuilder.gemspec
+- ./lib/jbuilder.rb
+- ./lib/jbuilder_template.rb
+- ./MIT-LICENSE
+- ./README.md
+- ./test/jbuilder_test.rb
+homepage: 
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: Create JSON structures via a Builder-style DSL
+test_files: []