rabl-rails 0.1.0

data/.gitignore

@@ -0,0 +1,7 @@
+.bundle/
+log/*.log
+pkg/
+test/dummy/db/*.sqlite3
+test/dummy/log/*.log
+test/dummy/tmp/
+test/dummy/.sass-cache

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+gemspec
+
+gem 'yajl-ruby'
+
+group :test do
+  gem 'rspec-mocks'
+end

data/Gemfile.lock

@@ -0,0 +1,69 @@
+PATH
+  remote: .
+  specs:
+    rabl-rails (0.1.0)
+      activesupport (~> 3.0)
+      railties (~> 3.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    actionpack (3.2.6)
+      activemodel (= 3.2.6)
+      activesupport (= 3.2.6)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      journey (~> 1.0.1)
+      rack (~> 1.4.0)
+      rack-cache (~> 1.2)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.1.3)
+    activemodel (3.2.6)
+      activesupport (= 3.2.6)
+      builder (~> 3.0.0)
+    activesupport (3.2.6)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    builder (3.0.0)
+    erubis (2.7.0)
+    hike (1.2.1)
+    i18n (0.6.0)
+    journey (1.0.4)
+    json (1.7.3)
+    multi_json (1.3.6)
+    rack (1.4.1)
+    rack-cache (1.2)
+      rack (>= 0.4)
+    rack-ssl (1.3.2)
+      rack
+    rack-test (0.6.1)
+      rack (>= 1.0)
+    railties (3.2.6)
+      actionpack (= 3.2.6)
+      activesupport (= 3.2.6)
+      rack-ssl (~> 1.3.2)
+      rake (>= 0.8.7)
+      rdoc (~> 3.4)
+      thor (>= 0.14.6, < 2.0)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec-mocks (2.11.1)
+    sprockets (2.1.3)
+      hike (~> 1.2)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sqlite3 (1.3.6)
+    thor (0.15.4)
+    tilt (1.3.3)
+    yajl-ruby (1.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  actionpack (~> 3.0)
+  rabl-rails!
+  rspec-mocks
+  sqlite3
+  yajl-ruby

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 Christopher Cocchi-Perrier
+
+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,248 @@
+# RABL for Rails #
+
+RABL (Ruby API Builder Language) is a ruby templating system for rendering resources in different format (JSON, XML, BSON, ...). You can find documentation [here](http://github.com/nesquena/rabl).
+
+RABL-rails only target Rails 3+ application because Rails 2 applications are becoming less and less present and will be obsolete with Rails 4. So let's look to the future !
+
+So now you ask why used `rabl-rails` if `rabl` already exists and supports Rails. Rabl-rails is **faster** and uses **less memory** than standard rabl gem while letting you access same features. Of course, there are some slight changes to do on your templates to get this gem to work but it should't take you more than 5 minutes.
+
+## Installation
+
+Install as a gem :
+
+```
+gem install rabl-rails
+```
+
+or add directly to your `Gemfile`
+
+```
+gem 'rabl-rails'
+```
+
+And that's it !
+
+## Overview
+
+Once you have installed RABL, you can directly used RABL templates to render your resources without changing anything to you controller. As example,
+assuming you have a `Post` model filled with blog posts, and a `PostController` that look like this :
+
+```ruby
+class PostController < ApplicationController
+  respond_to :html, :json, :xml
+
+  def index
+	  @posts = Post.order('created_at DESC')
+	  respond_with(@posts)
+  end
+end
+```
+
+You can create the following RABL-rails template to express the API output of `@posts`
+
+```ruby
+# app/views/post/index.rabl
+collection :@posts
+attributes :id, :title, :subject
+child(:user) { attributes :full_name }
+node(:read) { |post| post.read_by?(@user) }
+```
+
+This would output the following JSON when visiting `http://localhost:3000/posts.json`
+
+```js
+[{
+  "id" : 5, title: "...", subject: "...",
+  "user" : { full_name : "..." },
+  "read" : true
+}]
+```
+
+That's a basic overview but there is a lot more to see such as partials, inheritance or fragment caching.
+
+## How it works
+
+As opposed to standard RABL gem, this gem separate compiling (a.k.a transforming a RABL-rails template into a Ruby hash) and the actual rendering of the object or collection. This allow to only compile the template once and only Ruby hashes.
+
+The fact of compiling the template outside of any rendering context prevent us to use any instances variables (with the exception of node) in the template because they are rendering objects. So instead, you'll have to use symbols of these variables.For example, to render the collection `@posts` inside your `PostController`, you need to use `:@posts` inside of the template.
+
+The only places where you can actually used instance variables  are into Proc (or lambda) or into custom node (because they are treated as Proc).
+
+```ruby
+# We reference the @posts varibles that will be used at rendering time
+collection :@posts
+	
+# Here you can use directly the instance variable because it
+# will be evaluated when rendering the object 
+node(:read) { |post| post.read_by?(@user) }
+```
+
+The same rule applies for view helpers such as `current_user`
+
+After the template is compiled into a hash, Rabl-rails will use a renderer to do the actual output. Actually, only JSON and XML formats are supported.
+
+## Usage
+
+### Data declaration
+
+To declare data to use in the template, you can use either `object` or `collection` with the symbol name or your data.
+
+```ruby
+# app/views/users/show.json.rabl
+object :@user
+
+# app/views/users/index.json.rabl
+collection :@users
+```
+
+You can specify root label for the collection using hash or `:root` option
+
+```ruby
+collection :@posts, root: :articles
+#is equivalent to
+collection :@posts => :articles
+
+# => { "articles" : [{...}, {...}] }
+```
+
+There are rares cases when the template doesn't map directly to any object. In these cases, you can set data to false or skip data declaration altogether.
+
+```ruby
+object false
+node(:some_count) { |_| @user.posts.count }
+child(:@user) { attribute :name }
+```
+
+### Attributes / Methods
+
+Basic usage is to declared attributes to include in the response. These can be database attributes or any instance method.
+
+```ruby
+attributes :id, :title, :to_s
+```
+
+You can aliases these attributes in your response
+
+```ruby
+attributes title: :foo, to_s: :bar
+# => { "foo" : <title value>, "bar" : <to_s value> } 
+```
+
+### Child nodes
+
+You can include nested information from data associated with the parent model. You can also alias these associations.
+For example if you have a `Post` model that belongs to a `User`
+
+```ruby
+object :@post
+child(user: :author) do
+	attributes :name
+end
+# => { "post" : { "author" : { "name" : "John D." } } }
+```
+
+You can also use arbitrary data source with child nodes
+```ruby
+child(:@users) do
+	attributes :id, :name
+end
+```
+
+### Custom nodes
+
+You can create custom node in your response, based on the result of the given block
+
+```ruby
+object :@user
+node(:full_name) { |u| u.first_name + " " + u.last_name }
+# => { "user" : { "full_name" : "John Doe" } }
+```
+
+You can add the node only if a condition is true
+
+```ruby
+node(:email, if: -> { |u| u.valid_email? }) do |u| 
+	u.email
+end
+```
+
+Nodes are evaluated at the rendering time, so you can use any instance variables or view helpers inside them
+
+```ruby
+node(:url) { |post| post_url(post) }
+```
+
+Custom nodes are really usefull to create flexible representations of your resources.
+
+### Extends & Partials
+
+Often objects have a basic representation that is shared accross different views and enriched according to it. To avoid code redundancy you can extend your template from any other RABL template.
+
+```ruby
+# app/views/users/base.json.rabl
+attributes :id, :name
+
+# app/views/users/private.json.rabl
+extends 'users/base'
+attributes :super_secret_attribute
+```
+
+You can also extends template in child nodes using `partial` option (this is the same as using `extends` in the child block)
+
+```ruby
+collection @posts
+attribute :title
+child(:user, partial: 'users/base')
+```
+
+Partials can also be used inside custom nodes. When using partial this way, you MUST declare the object associated to the partial
+
+```ruby
+node(:location) do |user|
+	{ city: user.city, address: partial('users/address', object: m.address) }
+end
+```
+
+### Nesting
+
+Rabl allow you to define easily your templates, even with hierarchy of 2 or 3 levels. Let's suppose your have a `thread` model that has many `posts` and that each post has many `comments`. We can display a full thread in a few lines
+
+```ruby
+object :@thread
+attribute :caption
+child :posts do
+  attribute :title
+	child :comments do
+		extends 'comments/base'
+	end
+end
+```
+
+## Performance
+
+Benchmarks have been made using this [application](http://github.com/ccocchi/rabl-benchmark), with rabl 0.6.14 and rabl-rails 0.1.0
+
+Overall, Rabl-rails is **20% faster and use 10% less memory**.
+
+You can see full tests on test application repository.
+
+## Caching
+
+Caching is not a part of Rabl-rails. It is already in Rails itself, because caching all view output is the same as action caching (Rails caching is even better because it will also not run your queries).
+
+And caching each object in a collection can be really not effective with big collections or simple objects. This is also a nightmare with cache expiration.
+
+## Authors and contributors
+
+* [Christopher Cocchi-Perrier](http://github.com/ccocchi) - Creator of the project
+
+Want to add another format to Rabl-rails ? Checkout [JSON renderer](http://github.com/ccocchi/rabl-rails/blob/master/lib/rabl-rails/renderers/json.rb) for reference
+Want to make another change ? Just fork and contribute, any help is very much appreciated
+
+## Original idea
+
+* [RABL](http://github.com/nesquena/rabl) Standart RABL gem. I used it a lot before deciding I wanted faster views
+
+## Copyright
+
+Copyright © 2011-2012 Christopher Cocchi-Perrier. See [MIT-LICENSE](http://github.com/ccocchi/rabl-rails/blob/master/MIT-LICENSE) for details.

data/Rakefile

@@ -0,0 +1,35 @@
+#!/usr/bin/env rake
+# begin
+#   require 'bundler/setup'
+# rescue LoadError
+#   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+# end
+# begin
+#   require 'rdoc/task'
+# rescue LoadError
+#   require 'rdoc/rdoc'
+#   require 'rake/rdoctask'
+#   RDoc::Task = Rake::RDocTask
+# end
+#
+# RDoc::Task.new(:rdoc) do |rdoc|
+#   rdoc.rdoc_dir = 'rdoc'
+#   rdoc.title    = 'RablRails'
+#   rdoc.options << '--line-numbers'
+#   rdoc.rdoc_files.include('README.rdoc')
+#   rdoc.rdoc_files.include('lib/**/*.rb')
+# end
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+
+task :default => :test

data/lib/rabl-rails.rb

@@ -0,0 +1,41 @@
+require 'rails/railtie'
+
+require 'active_support'
+require 'active_support/core_ext/class/attribute_accessors'
+
+require 'rabl-rails/version'
+require 'rabl-rails/template'
+require 'rabl-rails/compiler'
+
+require 'rabl-rails/renderer'
+
+require 'rabl-rails/library'
+require 'rabl-rails/handler'
+require 'rabl-rails/railtie'
+
+require 'multi_json'
+
+module RablRails
+  mattr_accessor :cache_templates
+  @@cache_templates = true
+  
+  mattr_accessor :include_json_root
+  @@include_json_root = true
+
+  mattr_accessor :json_engine
+  @@json_engine = :yajl
+
+  def self.configure
+    yield self
+    post_configure
+  end
+
+  def self.cache_templates?
+    ActionController::Base.perform_caching && @@cache_templates
+  end
+
+  private
+  def self.post_configure
+    MultiJson.engine = self.json_engine 
+  end
+end

data/lib/rabl-rails/compiler.rb

@@ -0,0 +1,146 @@
+module RablRails
+  #
+  # Class that will compile RABL source code into a hash
+  # representing data structure
+  #
+  class Compiler
+    def initialize
+      @glue_count = 0
+    end
+
+    #
+    # Compile from source code and return the CompiledTemplate
+    # created.
+    #
+    def compile_source(source)
+      @template = CompiledTemplate.new
+      instance_eval(source)
+      @template
+    end
+
+    #
+    # Sets the object to be used as the data for the template
+    # Example:
+    #   object :@user
+    #   object :@user, :root => :author
+    #
+    def object(data, options = {})
+      @template.data, @template.root_name = extract_data_and_name(data)
+      @template.root_name = options[:root] if options.has_key? :root
+    end
+    alias_method :collection, :object
+
+    #
+    # Includes the attribute or method in the output
+    # Example:
+    #   attributes :id, :name
+    #   attribute :email => :super_secret
+    #
+    def attribute(*args)
+      if args.first.is_a?(Hash)
+        args.first.each_pair { |k, v| @template[v] = k }
+      else
+        options = args.extract_options!
+        args.each { |name|
+          key = options[:as] || name
+          @template[key] = name
+        }
+      end
+    end
+    alias_method :attributes, :attribute
+
+    #
+    # Creates a child node to be included in the output.
+    # name_or data can be an object or collection or a method to call on the data. It
+    # accepts :root and :partial options.
+    # Notes that partial and blocks are not compatible
+    # Example:
+    #   child(:@posts, :root => :posts) { attribute :id }
+    #   child(:posts, :partial => 'posts/base')
+    #
+    def child(name_or_data, options = {})
+      data, name = extract_data_and_name(name_or_data)
+      name = options[:root] if options.has_key? :root
+      if options[:partial]
+        template = Library.instance.compile_template_from_path(options[:partial])
+        @template[name] = template.merge!(:_data => data)
+      elsif block_given?
+        @template[name] = sub_compile(data) { yield }
+      end
+    end
+
+    #
+    # Glues data from a child node to the output
+    # Example:
+    #   glue(:@user) { attribute :name }
+    #
+    def glue(data)
+      return unless block_given?
+      name = :"_glue#{@glue_count}"
+      @glue_count += 1
+      @template[name] = sub_compile(data) { yield }
+    end
+
+    #
+    # Creates an arbitrary node in the json output.
+    # It accepts :if option to create conditionnal nodes. The current data will
+    # be passed to the block so it is advised to use it instead of ivars.
+    # Example:
+    #   node(:name) { |user| user.first_name + user.last_name }
+    #   node(:role, if: ->(u) { !u.admin? }) { |u| u.role }
+    #
+    def node(name, options = {}, &block)
+      condition = options[:if]
+
+      if condition
+        if condition.is_a?(Proc)
+          @template[name] = [condition, block]
+        else
+          @template[name] = block if condition
+        end
+      else
+        @template[name] = block
+      end
+    end
+    alias_method :code, :node
+
+    #
+    # Extends an existing rabl template
+    # Example:
+    #   extends 'users/base'
+    #
+    def extends(path)
+      t = Library.instance.compile_template_from_path(path)
+      @template.merge!(t.source)
+    end
+
+    protected
+
+    #
+    # Extract data root_name and root name
+    # Example:
+    #   :@users -> [:@users, nil]
+    #   :@users => :authors -> [:@users, :authors]
+    #
+    def extract_data_and_name(name_or_data)
+      case name_or_data
+      when Symbol
+        str = name_or_data.to_s
+        str.start_with?('@') ? [name_or_data, str[1..-1]] : [name_or_data, name_or_data]
+      when Hash
+        name_or_data.first
+      else
+        name_or_data
+      end
+    end
+    
+    def sub_compile(data)
+      return {} unless block_given?
+      old_template, @template = @template, {}
+      yield
+      @template.merge!(:_data => data)
+    ensure
+      @template = old_template
+    end
+  end
+end