tokamak 1.0.0.beta2 → 1.0.0.beta4

data/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2010 Abril Midia
+All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License"); 
+you may not use this file except in compliance with the License. 
+You may obtain a copy of the License at 
+
+	http://www.apache.org/licenses/LICENSE-2.0 
+
+Unless required by applicable law or agreed to in writing, software 
+distributed under the License is distributed on an "AS IS" BASIS, 
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
+See the License for the specific language governing permissions and 
+limitations under the License.

data/README.md

@@ -0,0 +1,159 @@
+# Tokamak
+
+Is a template engine for hypermedia resources that provides a single DSL to generate several media types representations.
+
+This version supports json and xml generation (you can add other media types
+easily)
+
+The lib provide hooks for:
+
+* Rails
+* Sinatra
+* Tilt ([https://github.com/rtomayko/tilt](https://github.com/rtomayko/tilt))
+
+Just put `require "tokamak/hook/[sinatra|rails|tilt]"` on your app. See unit
+tests for hook samples.
+
+You are also able to implement hooks for other frameworks.
+
+## Sample
+
+### Tokamak code
+
+    collection(@some_articles) do |collection|
+        collection.values do |values|
+            values.id      "http://example.com/json"
+            values.title   "Feed"
+            values.updated Time.now
+
+            values.author {
+                values.name  "John Doe"
+                values.email "joedoe@example.com"
+            }
+
+            values.author {
+                values.name  "Foo Bar"
+                values.email "foobar@example.com"
+            }
+        end
+
+        collection.link("next"    , "http://a.link.com/next")
+        collection.link("previous", "http://a.link.com/previous")
+
+        collection.members(:root => "articles") do |member, article|
+            member.values do |values|
+                values.id      "uri:#{article[:id]}"
+                values.title   article[:title]
+                values.updated article[:updated]
+            end
+
+            member.link("image", "http://example.com/image/1")
+            member.link("image", "http://example.com/image/2", :type => "application/json")
+        end
+    end
+
+Generates the following representations:
+
+### JSON
+
+    {
+        "author": [{
+            "name": "John Doe",
+            "email": "joedoe@example.com"
+        },
+        {
+            "name": "Foo Bar",
+            "email": "foobar@example.com"
+        }],
+        "title": "Feed",
+        "id": "http://example.com/json",
+        "link": [{
+            "href": "http://a.link.com/next",
+            "rel": "next",
+            "type": "application/json"
+        },
+        {
+            "href": "http://a.link.com/previous",
+            "rel": "previous",
+            "type": "application/json"
+        }],
+        "articles": [{
+            "title": "a great article",
+            "id": "uri:1",
+            "link": [{
+                "href": "http://example.com/image/1",
+                "rel": "image",
+                "type": "application/json"
+            },
+            {
+                "type": "application/json",
+                "href": "http://example.com/image/2",
+                "rel": "image",
+                "type": "application/json"
+            }],
+            "updated": "2011-01-05T10:40:58-02:00"
+        },
+        {
+            "title": "another great article",
+            "id": "uri:2",
+            "link": [{
+                "href": "http://example.com/image/1",
+                "rel": "image",
+                "type": "application/json"
+            },
+            {
+                "type": "application/json",
+                "href": "http://example.com/image/2",
+                "rel": "image",
+                "type": "application/json"
+            }],
+            "updated": "2011-01-05T10:40:58-02:00"
+        }],
+        "updated": "2011-01-05T10:40:58-02:00"
+    }
+
+### XML
+
+    <?xml version="1.0"?>
+    <root>
+      <id>http://example.com/json</id>
+      <title>Feed</title>
+      <updated>2011-01-05T10:40:58-02:00</updated>
+      <author>
+        <name>John Doe</name>
+        <email>joedoe@example.com</email>
+      </author>
+      <author>
+        <name>Foo Bar</name>
+        <email>foobar@example.com</email>
+      </author>
+      <link href="http://a.link.com/next" rel="next" type="application/xml"/>
+      <link href="http://a.link.com/previous" rel="previous" type="application/xml"/>
+      <articles>
+        <id>uri:1</id>
+        <title>a great article</title>
+        <updated>2011-01-05T10:40:58-02:00</updated>
+        <link href="http://example.com/image/1" rel="image" type="application/xml"/>
+        <link href="http://example.com/image/2" type="application/json" rel="image"/>
+      </articles>
+      <articles>
+        <id>uri:2</id>
+        <title>another great article</title>
+        <updated>2011-01-05T10:40:58-02:00</updated>
+        <link href="http://example.com/image/1" rel="image" type="application/xml"/>
+        <link href="http://example.com/image/2" type="application/json" rel="image"/>
+      </articles>
+    </root>
+
+## Other features
+
+* You can declare recipes once and reuse it later (see `Tokamak::Recipes`)
+* You can extend `Tokamak::Builder::Base` to support a custom media type.
+* You can customize the DSL entrypoint helpers, used by the hooks (see `Tokamak::Builder::HelperTest`)
+
+## Want to know more?
+
+Please check the unit tests, you can see a lot of richer samples, including tests for the hooks.
+
+*This library was extracted from [Restfulie](https://github.com/caelum/restfulie) and then heavy refactored. The same terms apply, see LICENSE.txt*
+

data/lib/tokamak/builder/base.rb

@@ -0,0 +1,74 @@
+module Tokamak
+  module Builder
+    class Base
+
+      @@global_media_types = {}
+
+      class << self
+        def builder_for(*args)
+          # class instance variable to store media types handled by a builder
+          @media_types = args
+          args.each do |media_type|
+            @@global_media_types[media_type] = self
+          end
+        end
+
+        def media_types
+          @media_types
+        end
+
+        def global_media_types
+          @@global_media_types
+        end
+
+        def build(obj, options = {}, &block)
+          if block_given?
+            recipe = block
+          else
+            recipe = options.delete(:recipe)
+          end
+
+          unless recipe.respond_to?(:call)
+            recipe = Tokamak::Recipes[recipe]
+            raise Tokamak::BuilderError.new("Recipe required to build representation.") unless recipe.respond_to?(:call)
+          end
+
+          builder = self.new(obj, options)
+
+          recipe.call(*[builder, obj, options][0, recipe.arity])
+
+          builder.representation
+        end
+
+        def helper
+          unless instance_variable_get(:@helper_module)
+            @helper_module = Tokamak::Builder.helper_module_for(self)
+          end
+          @helper_module
+        end
+
+        def collection_helper_default_options(options = {}, &block)
+          generic_helper(:collection, options, &block)
+        end
+
+        def member_helper_default_options(type, options = {}, &block)
+          generic_helper(:member, options, &block)
+        end
+
+        def generic_helper(section, options = {}, &block)
+          helper.send(:remove_method, section)
+          var_name = "@@more_options_#{section.to_s}".to_sym
+          helper.send(:class_variable_set, var_name, options)
+          helper.module_eval <<-EOS
+            def #{section.to_s}(obj, *args, &block)
+              #{var_name}.merge!(args.shift)
+              args.unshift(#{var_name})
+              #{self.name}.build(obj, *args, &block)
+            end
+          EOS
+        end
+      end
+
+    end
+  end
+end

data/lib/tokamak/{json/builder.rb → builder/json.rb}

@@ -1,67 +1,75 @@
+require "json/pure"
+
 module Tokamak
-  module Json
-    class Builder
-      def initialize(obj, initial_obj = {})
-        @doc     = initial_obj
+  module Builder
+    class Json < Tokamak::Builder::Base
+
+      builder_for "application/json"
+
+      attr_reader :raw
+
+      def initialize(obj, options = {})
+        @raw     = options[:root] ? { options[:root] => {} } : {}
+        @current = options[:root] ? @raw[options[:root]]     : @raw
         @obj     = obj
-        @current = @doc
       end
-  
-      def values(options = nil, &block)
-        yield Values.new(self)
-      end
-      
+
       def members(options = {}, &block)
-        collection = options[:collection] || @obj 
-        raise Error::BuilderError.new("Members method require a collection to execute") unless collection.respond_to?(:each)
-        root = options[:root] || Tokamak.root_element_for(collection)
-        
+        collection = options[:collection] || @obj
+        raise Tokamak::BuilderError.new("Members method require a collection to execute") unless collection.respond_to?(:each)
+        root = options[:root] || "members"
+
+        add_to_current(root, [])
         collection.each do |member|
           node = {}
-          
+
           parent = @current
           @current = node
           block.call(self, member)
           @current = parent
-          
+
           add_to_current(root, node)
         end
       end
-      
+
+      def values(options = {}, &block)
+        yield Values.new(self)
+      end
+
       def link(relationship, uri, options = {})
         options["rel"] = relationship.to_s
         options["href"] = uri
-        options["type"] ||= "application/json"
+        options["type"] ||= options[:type] || "application/json"
         insert_value("link", nil, options)
       end
-  
+
       def insert_value(name, prefix, *args, &block)
         node = create_element(block_given?, *args)
-        
+
         if block_given?
           parent = @current
           @current = node
           block.call
           @current = parent
         end
-        
+
         add_to_current(name, node)
       end
-  
+
       def representation
-        Tokamak::Representation::Json.create(@doc).to_json
+        @raw.to_json
       end
-      
+
     private
-    
+
       def create_element(has_block, *args)
         vals = []
         hashes = []
-        
+
         args.each do |arg|
           arg.kind_of?(Hash) ? hashes << arg : vals << arg
         end
-        
+
         if hashes.empty?
           # only simple values
           unless vals.empty?
@@ -72,7 +80,7 @@ module Tokamak
           end
         else
           # yes we have hashes
-          node = {} 
+          node = {}
           hashes.each { |hash| node.merge!(hash) }
           unless vals.empty?
             vals = vals.first if vals.size == 1
@@ -81,7 +89,7 @@ module Tokamak
           node
         end
       end
-      
+
       def add_to_current(name, value)
         if @current[name]
           if @current[name].kind_of?(Array)
@@ -93,6 +101,7 @@ module Tokamak
           @current[name] = value
         end
       end
+
     end
   end
 end

data/lib/tokamak/builder/values.rb

@@ -0,0 +1,33 @@
+module Tokamak
+  module Builder
+  
+    # This is a Blank Slate class to support the renderization of the values block of Builder DSLs
+    # Every Media type should implement a Builder with a insert_value method that renders the values block to a specific format
+    class Values
+      attr_accessor :builder
+
+      # BlankSlate
+      instance_methods.each do |m|
+        undef_method m unless m.to_s =~ /\[\]|method_missing|respond_to\?|^__/
+      end
+
+      def initialize(builder)
+        @builder = builder
+        @current_prefix = nil
+      end
+
+      def [](prefix)
+        @current_prefix = prefix
+        self
+      end
+
+      def method_missing(symbol, *args, &block)
+        name = symbol.to_s
+        prefix = @current_prefix
+        @current_prefix = nil
+        @builder.insert_value(name, prefix, *args, &block)
+      end
+    end
+    
+  end
+end

data/lib/tokamak/{atom/builder.rb → builder/xml.rb}

@@ -1,15 +1,32 @@
+require "nokogiri"
+
 module Tokamak
-  module Atom
-    class Builder
-      attr_accessor :atom_type
-      def initialize(atom_type, obj)
-        @doc    = Nokogiri::XML::Document.new
-        @obj    = obj
-        @parent = @doc.create_element(atom_type.to_s)
-        @parent.add_namespace_definition(nil, "http://www.w3.org/2005/Atom")
-        @parent.parent = @doc
+  module Builder
+    class Xml < Tokamak::Builder::Base
+
+      builder_for "application/xml", "text/xml"
+
+      attr_reader :raw
+
+      def initialize(obj, options = {})
+        @raw = Nokogiri::XML::Document.new
+        @obj = obj
+        @parent = @raw.create_element(options[:root] || "root")
+        @parent.parent = @raw
       end
-  
+
+      def members(options = {}, &block)
+        collection = options[:collection] || @obj
+        raise Tokamak::BuilderError.new("Members method require a collection to execute") unless collection.respond_to?(:each)
+        collection.each do |member|
+          member_root = @raw.create_element(options[:root] || "member")
+          member_root.parent = @parent
+          @parent = member_root
+          block.call(self, member)
+          @parent = member_root.parent
+        end
+      end
+
       def values(options = {}, &block)
         options.each do |key,value|
           attr = key.to_s
@@ -17,47 +34,35 @@ module Tokamak
             ns = attr.split(":", 2)[1]
             @parent.add_namespace_definition(ns, value)
           end
-        end            
-        yield Values.new(self)
-      end
-      
-      def members(options = {}, &block)
-        collection = options[:collection] || @obj 
-        raise Error::BuilderError.new("Members method require a collection to execute") unless collection.respond_to?(:each)
-        collection.each do |member|
-          entry = @doc.create_element("entry")
-          entry.parent = @parent
-          @parent = entry
-          block.call(self, member)
-          @parent = entry.parent
         end
+        yield Values.new(self)
       end
-      
+
       def link(relationship, uri, options = {})
         options["rel"] = relationship.to_s
         options["href"] = uri
-        options["type"] ||= "application/atom+xml"
+        options["type"] ||= options[:type] || "application/xml"
         insert_value("link", nil, options)
       end
-  
+
       def insert_value(name, prefix, *args, &block)
         node = create_element(name.to_s, prefix, *args)
-        node.parent = @parent            
+        node.parent = @parent
         if block_given?
           @parent = node
           block.call
           @parent = node.parent
         end
       end
-  
+
       def representation
-        Tokamak::Representation::Atom::Factory.create(@doc)
+        @raw.to_xml
       end
-      
+
     private
-    
+
       def create_element(node, prefix, *args)
-        node = @doc.create_element(node) do |n|
+        node = @raw.create_element(node) do |n|
           if prefix
             if namespace = prefix_valid?(prefix)
               # Adding namespace prefix
@@ -65,7 +70,7 @@ module Tokamak
               namespace = nil
             end
           end
-  
+
           args.each do |arg|
             case arg
             # Adding XML attributes
@@ -80,28 +85,28 @@ module Tokamak
                 n[k.to_s] = v.to_s
               }
             # Adding XML node content
-            else            
-              arg.kind_of?(Time) || arg.kind_of?(DateTime) ? content = arg.xmlschema : content = arg
+            else
+              content = arg.kind_of?(Time) || arg.kind_of?(DateTime) ? arg.xmlschema : arg
               n.content = content
             end
           end
         end
       end
-      
+
       def prefix_valid?(prefix)
         ns = @parent.namespace_definitions.find { |x| x.prefix == prefix.to_s }
-        
+
         unless ns
           @parent.ancestors.each do |a|
-            next if a == @doc
+            next if a == @raw
             ns = a.namespace_definitions.find { |x| x.prefix == prefix.to_s }
             break if ns
-          end      
+          end
         end
-        
+
         return ns
-        #TODO: raise ArgumentError, "Namespace #{prefix} has not been defined" if wanted
       end
+
     end
   end
 end

data/lib/tokamak/builder.rb

@@ -0,0 +1,22 @@
+module Tokamak
+  module Builder
+    autoload :Base  , "tokamak/builder/base"
+    autoload :Values, "tokamak/builder/values"
+    autoload :Json  , "tokamak/builder/json"
+    autoload :Xml   , "tokamak/builder/xml"
+
+    def self.helper_module_for(const)
+      mod = Module.new
+      mod.module_eval <<-EOS
+        def collection(obj, *args, &block)
+          #{const.name}.build(obj, *args, &block)
+        end
+
+        def member(obj, *args, &block)
+          #{const.name}.build(obj, *args, &block)
+        end
+      EOS
+      mod
+    end
+  end
+end

data/lib/tokamak/errors.rb

@@ -0,0 +1,3 @@
+module Tokamak
+  class BuilderError < StandardError; end
+end

data/lib/tokamak/hook/rails.rb

@@ -0,0 +1,78 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../tokamak.rb') unless defined? ::Tokamak
+
+module Tokamak
+  module Hook
+    module Rails
+
+      class Tokamak < ::ActionView::TemplateHandler
+        include ::ActionView::TemplateHandlers::Compilable
+
+        def compile(template)
+          "@content_type_helpers = ::Tokamak.builder_lookup(self.response.content_type).helper; " +
+          "extend @content_type_helpers; " +
+          "extend Tokamak::Hook::Rails::Helpers; " +
+          "code_block = lambda { #{template.source} };" +
+          "builder = code_block.call; " +
+          "builder"
+        end
+      end
+
+      module Helpers
+        # Load a partial template to execute in describe
+        #
+        # For example:
+        #
+        # Passing the current context to partial in template:
+        #
+        #  member(@album) do |member, album|
+        #    partial('member', binding)
+        #  end
+        #
+        # in partial:
+        #
+        #  member.links << link(:rel => :artists, :href => album_artists_url(album))
+        #
+        # Or passing local variables assing
+        #
+        # collection(@albums) do |collection|
+        #   collection.members do |member, album|
+        #     partial("member", :locals => {:member => member, :album => album})
+        #   end
+        # end
+        #
+        def partial(partial_path, caller_binding = nil)
+          template = _pick_partial_template(partial_path)
+
+          # Create a context to assing variables
+          if caller_binding.kind_of?(Hash)
+            Proc.new do
+              extend @content_type_helpers
+              context = eval("(class << self; self; end)", binding)
+
+              unless caller_binding[:locals].nil?
+                caller_binding[:locals].each do |k, v|
+                  context.send(:define_method, k.to_sym) { v }
+                end
+              end
+
+              partial(partial_path, binding)
+            end.call
+          else
+            eval(template.source, caller_binding, template.path)
+          end
+        end
+      end
+
+      if defined? ::ActionView::Template and ::ActionView::Template.respond_to?(:register_template_handler)
+        ::ActionView::Template
+      else
+        ::ActionView::Base
+      end.register_template_handler(:tokamak, Tokamak)
+
+      if defined? ::ActionController::Base
+        ::ActionController::Base.exempt_from_layout :tokamak
+      end
+
+    end
+  end
+end

data/lib/tokamak/hook/sinatra.rb

@@ -0,0 +1,18 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../tokamak.rb') unless defined? ::Tokamak
+require "tokamak/hook/tilt"
+
+module Tokamak
+  module Hook
+    module Sinatra
+
+      module ::Sinatra::Templates
+
+        def tokamak(template, options={}, locals={})
+          options.merge! :layout => false, :media_type => response["Content-Type"]
+          render :tokamak, template, options, locals
+        end
+
+      end
+    end
+  end
+end