representative 0.2.3 → 0.2.4

data/README.markdown

@@ -1,16 +1,16 @@
 Representative
 ==============
 
-"Representative" makes it easier to create XML representations of your Ruby objects.
-It works best when you want the XML to roughly follow the object structure, 
-but still have complete control of the result.
+"Representative" makes it easier to create XML or JSON representations of your Ruby objects.
 
-Example
--------
+It works best when you want the output to roughly follow the object structure, but still want complete control of the result.
+
+Generating XML
+--------------
 
 Given a Ruby data-structure:
 
-    books = [
+    @books = [
       OpenStruct.new(
         :title => "Sailing for old dogs", 
         :authors => ["Jim Watson"],
@@ -34,13 +34,13 @@ Given a Ruby data-structure:
       )
     ]
 
-Representative::Xml can be used to generate XML, in a declarative style:
+Representative::Xml can be used to generate XML:
 
     xml = Builder::XmlMarkup.new(:indent => 2)
 
     Representative::Xml.new(xml) do |r|
     
-      r.list_of :books, books do
+      r.list_of :books, @books do
         r.element :title
         r.list_of :authors
         r.element :published do
@@ -53,7 +53,7 @@ Representative::Xml can be used to generate XML, in a declarative style:
 
     puts xml.target!
 
-The resulting XML looks like this:
+which produces:
 
     <books type="array">
       <book>
@@ -88,12 +88,65 @@ The resulting XML looks like this:
 
 Notice that:
 
-- The structure of the XML mirrors the structure described by the nested Ruby blocks.
+- The structure of the output mirrors the structure described by the nested Ruby blocks.
 - Representative walks the object-graph for you.
 - Using `list_of` for a collection attribute generates an "array" element, which plays nicely
   with most Ruby XML-to-hash converters.
 - Where a named object-attribute is nil, you get an empty element.
 
+Generating JSON
+---------------
+
+Representative::Json can be used to generate JSON, using exactly the same DSL:
+
+    json = Representative::Json.new do |r|
+    
+      r.list_of :books, @books do
+        r.element :title
+        r.list_of :authors
+        r.element :published do
+          r.element :by
+          r.element :year
+        end
+      end
+
+    end
+
+    puts json.to_s
+
+producing:
+
+    [
+      {
+        "title": "Sailing for old dogs",
+        "authors": [
+          "Jim Watson"
+        ],
+        "published": {
+          "by": "Credulous Print",
+          "year": 1994
+        }
+      },
+      {
+        "title": "On the horizon",
+        "authors": [
+          "Zoe Primpton",
+          "Stan Ford"
+        ],
+        "published": {
+          "by": "McGraw-Hill",
+          "year": 2005
+        }
+      },
+      {
+        "title": "The Little Blue Book of VHS Programming",
+        "authors": [
+          "Henry Nelson"
+        ],
+        "published": null
+      }
+    ]
+
 Installation
 ------------
 

data/Rakefile

@@ -17,6 +17,8 @@ require "spec/rake/spectask"
 Spec::Rake::SpecTask.new(:spec) do |spec|
   spec.libs << 'lib' << 'spec'
   spec.spec_files = FileList['spec/**/*_spec.rb']
+  spec.spec_opts << "-Du"
+  spec.spec_opts << "--color"
 end
 
 task :default => :spec

data/examples/json_demo.rb

@@ -0,0 +1,44 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require "rubygems"
+require "representative/json"
+require "ostruct"
+
+@books = [
+  OpenStruct.new(
+    :title => "Sailing for old dogs", 
+    :authors => ["Jim Watson"],
+    :published => OpenStruct.new(
+      :by => "Credulous Print",
+      :year => 1994
+    )
+  ),
+  OpenStruct.new(
+    :title => "On the horizon", 
+    :authors => ["Zoe Primpton", "Stan Ford"],
+    :published => OpenStruct.new(
+      :by => "McGraw-Hill",
+      :year => 2005
+    )
+  ),
+  OpenStruct.new(
+    :title => "The Little Blue Book of VHS Programming",
+    :authors => ["Henry Nelson"],
+    :rating => "****"
+  )
+]
+
+json = Representative::Json.new do |r|
+
+  r.list_of :books, @books do
+    r.element :title
+    r.list_of :authors
+    r.element :published do
+      r.element :by
+      r.element :year
+    end
+  end
+
+end
+
+puts json.to_s

data/examples/xml_demo.rb

@@ -4,7 +4,7 @@ require "rubygems"
 require "representative/xml"
 require "ostruct"
 
-books = [
+@books = [
   OpenStruct.new(
     :title => "Sailing for old dogs", 
     :authors => ["Jim Watson"],
@@ -29,8 +29,10 @@ books = [
 ]
 
 xml = Builder::XmlMarkup.new(:indent => 2)
+
 Representative::Xml.new(xml) do |r|
-  r.list_of :books, books do
+
+  r.list_of :books, @books do
     r.element :title
     r.list_of :authors
     r.element :published do
@@ -38,6 +40,7 @@ Representative::Xml.new(xml) do |r|
       r.element :year
     end
   end
+
 end
 
 puts xml.target!

data/lib/representative/base.rb

@@ -0,0 +1,62 @@
+require "representative/object_inspector"
+
+module Representative
+  
+  class Base
+    
+    def initialize(subject = nil, options = {})
+      @subjects = [subject]
+      @inspector = options[:inspector] || ObjectInspector.new
+    end
+
+    # Return the current "subject" of representation.  
+    #
+    # This object will provide element values where they haven't been 
+    # explicitly provided.
+    #
+    def current_subject
+      @subjects.last
+    end
+
+    alias :subject :current_subject
+    
+    # Evaluate a block with a specified object as #subject.
+    #
+    def representing(new_subject, &block)
+      with_subject(resolve_value(new_subject), &block)
+    end
+
+    protected 
+
+    def with_subject(subject)
+      @subjects.push(subject)
+      begin
+        yield subject
+      ensure
+        @subjects.pop
+      end
+    end
+
+    def resolve_value(value_generator)
+      if value_generator == :self
+        current_subject
+      elsif value_generator.respond_to?(:to_proc)
+        value_generator.to_proc.call(current_subject) unless current_subject.nil?
+      else
+        value_generator
+      end
+    end
+
+    def resolve_attributes(attributes)
+      if attributes
+        attributes.inject({}) do |resolved, (name, value_generator)|
+          resolved_value = resolve_value(value_generator)
+          resolved[name.to_s.dasherize] = resolved_value unless resolved_value.nil?
+          resolved
+        end
+      end
+    end
+    
+  end
+  
+end

data/lib/representative/json.rb

@@ -0,0 +1,122 @@
+require "active_support/core_ext/array"
+require "representative/base"
+require "json"
+
+module Representative
+  
+  class Json < Base
+    
+    def initialize(subject = nil, options = {})
+      super(subject, options)
+      @buffer = ""
+      @indent_level = 0
+      now_at :beginning_of_buffer
+      yield self if block_given?
+    end
+    
+    def element(name, *args, &block)
+
+      metadata = @inspector.get_metadata(current_subject, name)
+      attributes = args.extract_options!.merge(metadata)
+
+      subject_of_element = if args.empty? 
+        lambda do |subject|
+          @inspector.get_value(current_subject, name)
+        end
+      else 
+        args.shift
+      end
+
+      raise ArgumentError, "too many arguments" unless args.empty?
+
+      label(name)
+      value(subject_of_element, &block)
+      
+    end
+
+    def list_of(name, *args, &block)
+      list_subject = args.empty? ? name : args.shift
+      items = resolve_value(list_subject)
+      label(name)
+      inside "[", "]" do
+        items.each do |item|
+          new_item
+          value(item, &block)
+        end
+      end
+    end
+
+    def value(subject)
+      representing(subject) do
+        if block_given? && !current_subject.nil?
+          inside "{", "}" do
+            yield current_subject
+          end
+        else
+          emit(current_subject.to_json)
+        end
+      end
+      now_at :end_of_item
+    end
+        
+    def comment(text)
+      new_item
+      emit("// #{text}")
+      now_at :end_of_comment
+    end
+
+    def to_json
+      @buffer + "\n"
+    end
+    
+    def to_s
+      to_json
+    end
+
+    private
+    
+    def emit(s)
+      @buffer << s
+    end
+
+    def indentation
+      ("  " * @indent_level)
+    end
+
+    def label(name)
+      return false if @indent_level == 0
+      new_item
+      emit("#{name.to_s.to_json}: ")
+    end
+
+    def new_item
+      emit(",") if at? :end_of_item
+      emit("\n") unless at? :beginning_of_buffer
+      emit(indentation)
+      @pending_comma = ","
+    end
+    
+    def inside(opening_char, closing_char)
+      emit(opening_char)
+      @indent_level += 1
+      now_at :beginning_of_block
+      yield
+      @indent_level -= 1
+      emit("\n#{indentation}") unless at? :beginning_of_block
+      emit(closing_char)
+      now_at :end_of_item
+    end
+
+    def now_at(state)
+      @state = state
+    end
+
+    def at?(state)
+      @state == state
+    end
+    
+  end
+  
+  JSON = Json
+  
+end

data/lib/representative/version.rb

@@ -1,3 +1,3 @@
 module Representative
-  VERSION = "0.2.3".freeze
+  VERSION = "0.2.4".freeze
 end

data/lib/representative/xml.rb

@@ -1,14 +1,14 @@
 require "active_support/core_ext/array"
 require "active_support/core_ext/string"
 require "builder"
+require "representative/base"
 require "representative/empty"
-require "representative/object_inspector"
 
 module Representative
 
   # Easily generate XML while traversing an object-graph.
   #
-  class Xml
+  class Xml < Base
 
     # Create an XML-generating Representative.  The first argument should be an instance of
     # Builder::XmlMarkup (or something that implements it's interface).  The second argument
@@ -16,28 +16,10 @@ module Representative
     #
     def initialize(xml_builder, subject = nil, options = {})
       @xml = xml_builder
-      @subjects = [subject]
-      @inspector = options[:inspector] || ObjectInspector.new
+      super(subject, options)
       yield self if block_given?
     end
 
-    # Return the current "subject" of representation.  
-    #
-    # This object will provide element values where they haven't been 
-    # explicitly provided.
-    #
-    def current_subject
-      @subjects.last
-    end
-
-    alias :subject :current_subject
-    
-    # Evaluate a block with a specified object as #subject.
-    #
-    def representing(new_subject, &block)
-      with_subject(resolve_value(new_subject), &block)
-    end
-
     # Generate an element.
     #
     # With two arguments, it generates an element with the specified text content.
@@ -156,37 +138,6 @@ module Representative
       @xml.comment!(text)
     end
     
-    private 
-
-    def with_subject(subject)
-      @subjects.push(subject)
-      begin
-        yield subject
-      ensure
-        @subjects.pop
-      end
-    end
-
-    def resolve_value(value_generator)
-      if value_generator == :self
-        current_subject
-      elsif value_generator.respond_to?(:to_proc)
-        value_generator.to_proc.call(current_subject) unless current_subject.nil?
-      else
-        value_generator
-      end
-    end
-
-    def resolve_attributes(attributes)
-      if attributes
-        attributes.inject({}) do |resolved, (name, value_generator)|
-          resolved_value = resolve_value(value_generator)
-          resolved[name.to_s.dasherize] = resolved_value unless resolved_value.nil?
-          resolved
-        end
-      end
-    end
-    
   end
 
 end

data/spec/representative/json_spec.rb

@@ -0,0 +1,224 @@
+require 'spec_helper'
+
+require "representative/json"
+
+describe Representative::Json do
+
+  def r
+    @representative ||= Representative::Json.new(@subject)
+  end
+
+  def resulting_json
+    r.to_json
+  end
+
+  describe "at the top level" do
+
+    describe "#element" do
+
+      describe "with an explicit String value" do
+
+        it "outputs the value as JSON" do
+          r.element :name, "Fred"
+          resulting_json.should == %{"Fred"\n}
+        end
+
+      end
+
+      describe "with an explicit integer value" do
+
+        it "outputs the value as JSON" do
+          r.element :age, 36
+          resulting_json.should == "36\n"
+        end
+
+      end
+      
+      describe "with a nil value" do
+        
+        it "generates null" do
+          r.element :flavour, nil
+          resulting_json.should == "null\n"
+        end
+
+        describe "and a block" do
+
+          it "generates null" do
+            r.element :book, nil do
+              r.element :author
+            end
+            resulting_json.should == "null\n"
+          end
+
+        end
+        
+      end
+
+      describe "without an explicit value" do
+
+        it "extracts the value from the current subject" do
+          @author = OpenStruct.new(:name => "Fred", :age => 36)
+          r.representing(@author) do
+            r.element :name
+          end
+          resulting_json.should == %{"Fred"\n}
+        end
+
+      end
+
+      describe "with a block" do
+
+        it "outputs an object" do
+          r.element :something, Object.new do
+          end
+          resulting_json.should == "{}\n"
+        end
+
+      end
+
+    end
+
+    describe "#list_of" do
+
+      describe "with an explicit array value" do
+
+        it "outputs the array as JSON" do
+          r.list_of :names, %w(Hewey Dewey Louie)
+          resulting_json.should == undent(<<-JSON)
+          [
+            "Hewey",
+            "Dewey",
+            "Louie"
+          ]
+          JSON
+        end
+
+      end
+
+      describe "without an explicit value" do
+
+        it "extracts the value from the current subject" do
+          @donald = OpenStruct.new(:nephews => %w(Hewey Dewey Louie))
+          r.element(:duck, @donald) do
+            r.list_of :nephews
+          end
+          resulting_json.should == undent(<<-JSON)
+          {
+            "nephews": [
+              "Hewey",
+              "Dewey",
+              "Louie"
+            ]
+          }
+          JSON
+        end
+        
+      end
+
+      describe "with a block" do
+
+        it "generates an object for each array element" do
+          @authors = [
+            OpenStruct.new(:name => "Hewey", :age => 3),
+            OpenStruct.new(:name => "Dewey", :age => 4),
+            OpenStruct.new(:name => "Louie", :age => 5)
+          ]
+          r.list_of :authors, @authors do
+            r.element :name
+            r.element :age
+          end
+          resulting_json.should == undent(<<-JSON)
+          [
+            {
+              "name": "Hewey",
+              "age": 3
+            },
+            {
+              "name": "Dewey",
+              "age": 4
+            },
+            {
+              "name": "Louie",
+              "age": 5
+            }
+          ]
+          JSON
+        end
+        
+      end
+
+    end
+
+    describe "#comment" do
+      
+      it "inserts a comment" do
+        r.comment "now pay attention"
+        resulting_json.should == undent(<<-JSON)
+        // now pay attention
+        JSON
+      end
+      
+    end
+    
+  end
+
+  describe "within an element block" do
+
+    describe "#element" do
+
+      it "generates labelled values" do
+        r.element :author, Object.new do
+          r.element :name, "Fred"
+          r.element :age, 36
+        end
+        resulting_json.should == undent(<<-JSON)
+        {
+          "name": "Fred",
+          "age": 36
+        }
+        JSON
+      end
+
+      describe "without an explicit value" do
+
+        it "extracts the value from the current subject" do
+          @author = OpenStruct.new(:name => "Fred", :age => 36)
+          r.element :author, @author do
+            r.element :name
+            r.element :age
+          end
+          resulting_json.should == undent(<<-JSON)
+          { 
+            "name": "Fred",
+            "age": 36
+          }
+          JSON
+        end
+
+      end
+
+    end
+
+    describe "#comment" do
+      
+      it "inserts a comment" do
+        @author = OpenStruct.new(:name => "Fred", :age => 36)
+        r.element :author, @author do
+          r.element :name
+          r.comment "age is irrelevant"
+          r.element :age
+        end
+        resulting_json.should == undent(<<-JSON)
+        { 
+          "name": "Fred",
+          // age is irrelevant
+          "age": 36
+        }
+        JSON
+      end
+      
+    end
+    
+  end
+
+end

data/spec/representative/xml_spec.rb

@@ -1,4 +1,4 @@
-require File.dirname(__FILE__) + '/../spec_helper'
+require 'spec_helper'
 
 require "representative/xml"
 

data/spec/spec_helper.rb

@@ -8,3 +8,12 @@ require "rubygems"
 Spec::Runner.configure do |config|
   
 end
+
+def undent(raw)
+  if raw =~ /\A( +)/
+    indent = $1
+    raw.gsub(/^#{indent}/, '').gsub(/ +$/, '')
+  else
+    raw
+  end
+end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 2
-  - 3
-  version: 0.2.3
+  - 4
+  version: 0.2.4
 platform: ruby
 authors: 
 - Mike Williams
@@ -40,11 +40,14 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- lib/representative/base.rb
 - lib/representative/empty.rb
+- lib/representative/json.rb
 - lib/representative/object_inspector.rb
 - lib/representative/version.rb
 - lib/representative/xml.rb
 - lib/representative.rb
+- examples/json_demo.rb
 - examples/xml_demo.rb
 - README.markdown
 - LICENSE
@@ -79,6 +82,7 @@ signing_key:
 specification_version: 3
 summary: Builds XML representations of your Ruby objects
 test_files: 
+- spec/representative/json_spec.rb
 - spec/representative/xml_spec.rb
 - spec/spec_helper.rb
 - Rakefile