hypertemplate 1.2.0

data/LICENSE

@@ -0,0 +1,29 @@
+Copyright (c) 2010 Caelum
+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.
+Copyright applicable to Tokamak's original code:
+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,134 @@
+# Hypertemplate
+
+*Hypertemplate* is a template engine for hypermedia resources.
+It provides a single DSL to generate different representations.
+This version supports json and xml generation (you can add other media types
+easily).
+
+## Configuring
+
+If you are using Restfulie, there is no need to configure it, simply check the DSL.
+
+The lib provide hooks for:
+
+* Rails
+* Sinatra
+* Tilt ([https://github.com/rtomayko/tilt](https://github.com/rtomayko/tilt))
+
+Just put `require "hypertemplate/hook/[sinatra|rails|tilt]"` on your app. See
+the integration tests for hook samples.
+
+## Hypertemplate DSL
+
+products {
+  link "order", orders_url, "type" => "application/xml"
+  @products.each do |prod|
+    product {
+      link   :self,  product_url(prod)
+      id prod.id
+      name prod.name
+      price prod.price
+    }
+  end
+}
+
+
+Generates the following representations:
+
+### JSON
+
+{"products":
+	{"link":[
+		{"type":"application/xml",
+		 "rel":"order",
+		 "href":"http://localhost:3000/orders"}],
+	"product":[
+		{"link":
+			[{"rel":"self",
+			  "href":"http://localhost:3000/products/2",
+			  "type":"application/json"}],
+			 "id":2,
+			 "name":"Rest Training (20h)",
+			 "price":"800.0"},
+		{"link":
+			[{"rel":"self",
+			  "href":"http://localhost:3000/products/3",
+			  "type":"application/json"}],
+		 	 "id":3,
+		 	 "name":"Modern Software architecture and Design (20h)",
+			 "price":"800.0"}
+		]
+	}
+}
+
+### XML
+
+<?xml version="1.0"?>
+<products>
+  <link type="application/xml" rel="order" href="http://localhost:3000/orders"/>
+  <product>
+    <link rel="self" href="http://localhost:3000/products/2" type="application/xml"/>
+    <id>2</id>
+    <name>Rest Training (20h)</name>
+    <price>800.0</price>
+  </product>
+  <product>
+    <link rel="self" href="http://localhost:3000/products/3" type="application/xml"/>
+    <id>3</id>
+    <name>Modern Software architecture and Design (20h)</name>
+    <price>800.0</price>
+  </product>
+</products>
+
+
+
+## Other features
+
+* You can declare recipes once and reuse it later (see `Hypertemplate::Recipes`)
+* You can extend `Hypertemplate::Builder::Base` to support a custom media type.
+* You can customize the DSL entrypoint helpers, used by the hooks (see `Hypertemplate::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),
+then forked from [Tokamak](http://github.com/abril/tokamak). See LICENSE.txt*
+
+## A more complex example
+
+order {
+  link "self", order_url(@order)
+  link "payment", order_payments_url(@order), "type" => "application/xml"
+  link "calendar", order_calendar_url(@order), "type" => "text/calendar"
+  address @order.address
+  price @order.price
+  state @order.state
+  payments {
+    @order.payments.each do |p|
+      payment do 
+        value  p.value
+        state  p.state
+      end
+    end
+  }
+  items {
+    @order.items.each do |i|
+      item do
+        id     i.product.id
+        name   i.product.name
+        price  i.product.price
+        quantity  i.quantity
+      end
+    end
+  }
+}
+
+## Questions? Help?
+
+* Join the mailing list restfulie@googlegroups.com
+* Join #restfulie at freenode IRC
+
+## Compatibility
+
+Hypertemplate can be used within Restfulie and its DSL is backward compatible with Tokamak 1.1.0 ~ 1.1.5.

data/lib/hypertemplate.rb

@@ -0,0 +1,14 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__))
+
+# Dependencies
+require "rubygems"
+require "bundler/setup"
+
+module Hypertemplate
+end
+
+require "hypertemplate/errors"
+require "hypertemplate/recipes"
+require "hypertemplate/builder"
+require "hypertemplate/registry"
+require "hypertemplate/hook"

data/lib/hypertemplate/builder.rb

@@ -0,0 +1,33 @@
+module Hypertemplate
+  module Builder
+    require "hypertemplate/builder/base"
+    require "hypertemplate/builder/values"
+    require "hypertemplate/builder/json"
+    require "hypertemplate/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
+
+        alias_method :member, :collection
+        
+        def method_missing(sym, *args, &block)
+          
+          # you thought meta-(meta-programming) was nasty?
+          # this is nasty... help me! i am an ActionView
+          # so coupled to the entire Rails stack that I need
+          # this hack.
+          super if @first_invocation
+          @first_invocation = true
+          
+          #{const.name}.build_dsl(self, :root => sym.to_s, &block)
+        end
+        
+      EOS
+      mod
+    end
+  end
+end

data/lib/hypertemplate/builder/base.rb

@@ -0,0 +1,111 @@
+module Hypertemplate
+  module Builder
+    class Base
+
+      # field id is quite common
+      undef_method :id if respond_to?(:id)
+
+      class << self
+        
+        def build_dsl(obj, options = {}, &block)
+          recipe = block_given? ? block : options.delete(:recipe)
+          raise Hypertemplate::BuilderError.new("Recipe required to build representation.") unless recipe.respond_to?(:call)
+
+          builder = self.new(nil, options)
+          copy_internal_variables(builder, obj)
+          builder.instance_variable_set :@view, obj
+          def builder.method_missing(name, *args, &block)
+            begin
+              @view.send name, *args, &block
+            rescue
+              super
+            end
+          end
+          builder.instance_exec(obj, &recipe)
+
+          builder.representation
+        end
+        
+        def copy_internal_variables(builder, obj)
+          # TODO this is nasty. i am sorry.
+          obj.instance_variables.each do |name|
+            builder.instance_variable_set name, obj.instance_variable_get(name)
+          end
+        end
+
+        def build(obj, options = {}, &block)
+          recipe = block_given? ? block : options.delete(:recipe)
+          raise Hypertemplate::BuilderError.new("Recipe required to build representation.") unless recipe.respond_to?(:call)
+
+          builder = self.new(obj, options)
+
+          if recipe.arity==-1
+            builder.instance_exec(&recipe)
+          else
+            recipe.call(*[builder, obj, options][0, recipe.arity])
+          end
+
+          builder.representation
+        end
+
+        def helper
+          @helper_module ||= Hypertemplate::Builder.helper_module_for(self)
+        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
+
+      # adds a key and value pair to the representation
+      # example:
+      #
+      # name 'guilherme'
+      def method_missing(sym, *args, &block)
+        values do |v|
+          v.send sym, *args, &block
+        end
+      end
+      
+      def ns(*args, &block)
+        values do |v|
+          v.send(:[], *args, &block)
+        end
+      end
+
+      # writes a key and value pair to the representation
+      # example:
+      #
+      # write :name, "guilherme"
+      def write(sym, val)
+        values do |v|
+          v.send sym, val
+        end
+      end
+
+      
+      def each(collection, options = {}, &block)
+        options[:collection] = collection
+        members(options, &block)
+      end
+
+    end
+  end
+end

data/lib/hypertemplate/builder/json.rb

@@ -0,0 +1,132 @@
+module Hypertemplate
+  module Builder
+    class Json < Hypertemplate::Builder::Base
+      
+      def self.media_types
+        ["application/json"]
+      end
+
+      attr_reader :raw
+
+      def initialize(obj, options = {})
+        initialize_library
+        if options[:root]
+          @raw     = { options[:root] => {} }
+          @current = @raw[options[:root]]
+        else
+          @current = @raw = {}
+        end
+        @obj     = obj
+      end
+
+      def initialize_library
+        return if defined?(::JSON)
+        require "json/pure"
+      end
+
+      def members(options = {}, &block)
+        collection = options[:collection] || @obj
+        raise Hypertemplate::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|
+
+          parent = @current
+          @current = {}
+          if block.arity==1
+            # new dsl
+            block.call(member)
+          else
+            # old dsl (deprecate at 1.3?)
+            block.call(self, member)
+          end
+          add_to(parent, root, @current)
+          @current = parent
+
+        end
+      end
+
+      def values(options = {}, &block)
+        yield Values.new(self)
+      end
+
+      def link(relationship, uri, options = {})
+        # Start link array
+        @current["link"] ||= []
+        stringify_keys(options) 
+
+        options["rel"]  = relationship.to_s
+        options["href"] = uri
+        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
+
+        # TODO change to name.to_sym in 1.3?
+        add_to(@current, name, node)
+      end
+
+      def representation
+        @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?
+          if has_block
+            {}
+          elsif vals.size<=1
+            vals.first
+          else
+            vals
+          end
+        else
+          # yes we have hashes
+          node = {}
+          hashes.each { |hash| node.merge!(hash) }
+          unless vals.empty?
+            vals = vals.first if vals.size == 1
+            node = has_block ? {} : [node, vals]
+          end
+          node
+        end
+      end
+
+      def add_to(node, name, value)
+        if node[name]
+          if node[name].kind_of?(Array)
+            node[name] << value
+          else
+            node[name] = [node[name], value]
+          end
+        else
+          node[name] = value
+        end
+      end
+
+      def stringify_keys(hash)
+        hash.keys.each do |key|
+          hash[key.to_s] = hash.delete(key)
+        end
+      end
+    end
+  end
+end