rabl-rails 0.5.5 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee0aee27278d987f9cca5d2c0a1660ae9cb4e0d6ae51734fa120f09d7c66449c
-  data.tar.gz: 64d9d559ba02a59de347391031bc16bb21ace05d54d293c3b302125668b76f7e
+  metadata.gz: 4fc57874aa491be7a0c8cc778a9d4e0a307740cf4648c3733d5e49f855eb1cc4
+  data.tar.gz: d4024078d1b780d66a297fb0a2aef0a7e37e6c4db392fa577afa1f16686c595c
 SHA512:
-  metadata.gz: c5b87c14f4c3f356f00c47ea35d3506475bdfd109b4144b60194b151e8b04f180844d1e9ebf5acb6755b834d886bc4a80141a3cba240740c8aeabe2893875d59
-  data.tar.gz: 9eca1d27951909e3f309240a46d0408de07379c91f21c8366d4620ef0bc4d090b3365e61f942f5a8c076f258472edb86ed74594f0336b0ef847497a81cb4a5c2
+  metadata.gz: 6b80cd63b8e17d97833f5696d04e82535c154d69b830ea291c7db344c485dead0ffb355cb75a83b1d155b992801f67815a142aa6da2657a4f7ce65820dd7d929
+  data.tar.gz: 05f604364890ce38ab76e311d76c51ce328b2f5bcf1c389b2837f95f17b89c31b7529dcadd42e52d745d11ce1be2e74f8a5a83d2a13e3e9478185a69c5e47d23

data/.travis.yml

@@ -4,13 +4,13 @@ dist: trusty
 env:
   - "RAILS_VERSION=4.2.6"
   - "RAILS_VERSION=5.2.0"
+  - "RAILS_VERSION=6.1.0"
 rvm:
   - 2.5.3
   - 2.6.0
+  - 2.7.2
   - jruby
 before_install:
   - gem update bundler
 matrix:
   fast_finish: true
-  allow_failures:
-    - env: RAILS_VERSION=master

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## 0.6.1
+  * Fix bug when template contains double quotes
+
+## 0.6.0 (yanked)
+  * Remove Rails 6+ warnings
+  * Uniformize node options
+  * Refresh README.md
+
 ## 0.5.5
   * Add `lookup` node
 

data/README.md

@@ -1,10 +1,10 @@
-# RABL for Rails [![Build Status](https://travis-ci.org/ccocchi/rabl-rails.png?branch=master)](https://travis-ci.org/ccocchi/rabl-rails)
+# RABL for Rails [![Build Status](https://travis-ci.org/ccocchi/rabl-rails.svg?branch=master)](https://travis-ci.org/ccocchi/rabl-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` is a ruby templating system for rendering your objects in different format (JSON, XML, PLIST).
 
-rabl-rails is **faster** and uses **less memory** than the standard rabl gem while letting you access the same features. 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.
+This gem aims for speed and little memory footprint while letting you build complex response with a very intuitive DSL.
 
-rabl-rails only targets **Rails 4.2+ application** and is compatible with mri 2.2+, jRuby and rubinius.
+`rabl-rails` targets **Rails 4.2/5/6 application** and have been testing with MRI and jRuby.
 
 ## Installation
 
@@ -17,23 +17,18 @@ gem install rabl-rails
 or add directly to your `Gemfile`
 
 ```
-gem 'rabl-rails'
+gem 'rabl-rails', '~> 0.6.0'
 ```
 
-And that's it !
-
 ## Overview
 
-Once you have installed rabl-rails, you can directly used RABL-rails 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 :
+The gem enables you to build responses using views like you would using HTML/erb/haml.
+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
 ```
@@ -43,6 +38,7 @@ You can create the following RABL-rails template to express the API output of `@
 ```ruby
 # app/views/post/index.rabl
 collection :@posts
+
 attributes :id, :title, :subject
 child(:user) { attributes :full_name }
 node(:read) { |post| post.read_by?(@user) }
@@ -58,15 +54,13 @@ This would output the following JSON when visiting `http://localhost:3000/posts.
 }]
 ```
 
-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.
+This gem separates compiling, ie. transforming a RABL-rails template into a Ruby hash, and the actual rendering of the object or collection. This allows to only compile the template once (when template caching is enabled) which is the slow part, and only use hashes during rendering.
 
-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 drawback of compiling the template outside of any rendering context is that we can't access instance variables like usual. Instead, you'll mostly use symbols representing your variables and the gem will retrieve them when needed.
 
-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).
+There are places where the gem allows for "dynamic code" -- code that is evaluated at each rendering, such as within `node` or `condition` blocks.
 
 ```ruby
 # We reference the @posts varibles that will be used at rendering time
@@ -79,7 +73,7 @@ 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.
+After the template is compiled into a hash, `rabl-rails` will use a renderer to create the actual output. Currently, JSON, XML and PList formats are supported.
 
 ## Configuration
 
@@ -87,6 +81,7 @@ RablRails works out of the box, with default options and fastest engine availabl
 
 ```ruby
 # config/initializers/rabl_rails.rb
+
 RablRails.configure do |config|
   # These are the default
   # config.cache_templates = true
@@ -125,7 +120,7 @@ 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.
+There are rares cases when the template doesn't map directly to any object. In these cases, you can set data to false.
 
 ```ruby
 object false
@@ -133,27 +128,15 @@ node(:some_count) { |_| @user.posts.count }
 child(:@user) { attribute :name }
 ```
 
-If you use gem like *decent_exposure* or *focused_controller*, you can use your variable directly without the leading `@`
+If you use gems like *decent_exposure* or *focused_controller*, you can use your variable directly without the leading `@`
 
 ```ruby
 object :object_exposed
 ```
 
-You can even skip data declaration at all. If you used `respond_with`, rabl-rails will render the data you passed to it.
-As there is no name, you can set a root via the `root` macro. This allow you to use your template without caring about variables passed to it.
-
-```ruby
-# in controller
-respond_with(@post)
-
-# in rabl-rails template
-root :article
-attribute :title
-```
-
 ### Attributes / Methods
 
-Basic usage is to declared attributes to include in the response. These can be database attributes or any instance method.
+Adds a new field to the response object, calling the method on the object being rendered. Methods called this way should return natives types from the format you're using (such as `String`, `integer`, etc for JSON). For more complex objects, see `child` nodes.
 
 ```ruby
 attributes :id, :title, :to_s
@@ -162,64 +145,91 @@ 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> }
+attributes :my_custom_method, as: :title
+# => { "title" : <result of my_custom_method> }
 ```
 
-or show attributes only if a condition is true
+or show attributes based on a condition. The currently rendered object is given to the `proc` condition.
+
 ```ruby
 attributes :published_at, :anchor, if: ->(post) { post.published? }
 ```
 
 ### Child nodes
 
-You can include informations from data associated with the parent model or arbitrary data. These informations can be grouped under a node or directly merged into current node.
+Changes the object being rendered for the duration of the block. Depending on if you use `node` or `glue`, the result will be added as a new field or merged respectively.
+
+Data passed can be a method or a reference to an instance variable.
 
-For example if you have a `Post` model that belongs to a `User`
+For example if you have a `Post` model that belongs to a `User` and want to add the user's name to your response.
 
 ```ruby
 object :@post
-child(user: :author) do
+
+child(:user, as: :author) do
 	attributes :name
 end
-# => { "post" : { "author" : { "name" : "John D." } } }
+# => { "post": { "author" : { "name" : "John D." } } }
 ```
 
-You can also use arbitrary data source with child nodes
+If instead of having an `author` node in your response you wanted the name at the root level, you can use `glue`:
+
 ```ruby
-child(:@users) do
-	attributes :id, :name
+object :@post
+
+glue(:user) do
+  attributes :name, as: :author_name
 end
+# => { "post": { "author_name" : "John D." } }
 ```
 
-If you want to merge directly into current node, you can use the `glue` keywork
+Arbitrary data source can also be passed:
 
 ```ruby
-attribute :title
-glue(:user) do
-  attributes :name => :author_name
+# in your controller
+# @custom_data = [...]
+
+# in the view
+child(:@custom_data) do
+	attributes :id, :name
 end
-# => { "post" : { "title" : "Foo", "author_name" : "John D." } }
+# => { "custom_data": [...] }
 ```
 
-### Custom nodes
+### Constants
 
-You can create custom node in your response, based on the result of a given block
+Adds a new field to the response using an immutable value.
 
 ```ruby
-object :@user
-node(:full_name) { |u| u.first_name + " " + u.last_name }
-# => { "user" : { "full_name" : "John Doe" } }
+const(:api_version, API::VERSION)
+const(:locale, 'fr_FR')
 ```
 
-or with an assigned constant
+### Lookups
+
+Adds a new field to the response, using rendered resource's id by default or any method to fetch a value from the given hash variable.
 
 ```ruby
-const(:api_version, API::VERSION)
-const(:locale, 'fr_FR')
+collection :@posts
+
+lookup(:comments_count, :@comments_count, field: :uuid, cast: false)
+# => [{ "comments_count": 3 }, { "comments_count": 6 }]
+```
+
+In the example above, for each post it will fetch the value from `@comments_count` using the post's `uuid` as key. When the `cast` value is set to `true` (it is `false` by default), the value will be casted to a boolean using `!!`.
+
+
+### Custom nodes
+
+Adds a new field to the response with block's result as value.
+
+```ruby
+object :@user
+node(:full_name) { |u| u.first_name + " " + u.last_name }
+# => { "user" : { "full_name" : "John Doe" } }
 ```
 
-You can add condition on your custom nodes (if the condition is evaluated to false, the node will not be included).
+You can add condition on your custom nodes. If the condition evaluates to a falsey value, the node will not added to the response at all.
 
 ```ruby
 node(:email, if: ->(u) { u.valid_email? }) do |u|
@@ -227,13 +237,13 @@ node(:email, if: ->(u) { u.valid_email? }) do |u|
 end
 ```
 
-Nodes are evaluated at the rendering time, so you can use any instance variables or view helpers inside them
+Nodes are evaluated at rendering time, so you can use any instance variables or view helpers within them
 
 ```ruby
 node(:url) { |post| post_url(post) }
 ```
 
-If you want to include directly the result into the current node, use the `merge` keyword (result returned from the block should be a hash)
+If the result of the block is a Hash, it can be directly merge into the response using `merge` instead of `node`
 
 ```ruby
 object :@user
@@ -241,33 +251,42 @@ merge { |u| { name: u.first_name + " " + u.last_name } }
 # => { "user" : { "name" : "John Doe" } }
 ```
 
-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
+# app/views/shared/_user.rabl
 attributes :id, :name
 
-# app/views/users/private.json.rabl
+# app/views/users/show.rabl
+object :@user
+
+extends('shared/_user')
 attributes :super_secret_attribute
 
-extends 'users/base'
-# or using partial instead of extends
-# merge { |u| partial('users/base', object: u) }
+#=> { "id": 1, "name": "John", "super_secret_attribute": "Doe" }
+```
+
+When used with child node, if they are the only thing added you can instead use the `partial` option directly.
+
+```ruby
+child(:user, partial: 'shared/_user')
+
+# is equivalent to
+
+child(:user) do
+  extends('shared/_user')
+end
 ```
 
-You can also extends template in child nodes using `partial` option (this is the same as using `extends` in the child block)
+Extends can be used dynamically using rendered object and lambdas.
 
 ```ruby
-collection @posts
-attribute :title
-child(:user, partial: 'users/base')
+extends ->(user) { "shared/_#{user.client_type}_infos" }
 ```
 
-Partials can also be used inside custom nodes. When using partial this way, you MUST declare the object associated to the partial
+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|
@@ -275,28 +294,33 @@ node(:location) do |user|
 end
 ```
 
-When used within `node`, partials can take locals variables that can be accessed in the included template.
+When used this way, partials can take locals variables that can be accessed in the included template.
+
 ```ruby
-# base.json.rabl
+# _credit_card.rabl
 node(:credit_card, if: ->(u) { locals[:display_credit_card] }) do |user|
   user.credit_card_info
 end
 
 # user.json.rabl
-merge { |u| partial('users/base', object: u, locals: { display_credit_card: true }) }
+merge { |u| partial('_credit_card', object: u, locals: { display_credit_card: true }) }
 ```
 
-### Nesting
+### Putting it all together
 
-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
+`rabl-rails` allows you to format your responses easily, from simple objects to hierarchy of 2 or 3 levels.
 
 ```ruby
 object :@thread
-attribute :caption
-child :posts do
-  attribute :title
-	child :comments do
-		extends 'comments/base'
+
+attribute :caption, as: :title
+
+child(:@sorted_posts, as: :posts) do
+  attributes :title, :slug
+
+  child :comments do
+		extends 'shared/_comment'
+    lookup(:upvotes, :@upvotes_per_comment)
 	end
 end
 ```
@@ -328,4 +352,4 @@ Want to make another change ? Just fork and contribute, any help is very much ap
 
 ## Copyright
 
-Copyright © 2012-2017 Christopher Cocchi-Perrier. See [MIT-LICENSE](http://github.com/ccocchi/rabl-rails/blob/master/MIT-LICENSE) for details.
+Copyright © 2012-2020 Christopher Cocchi-Perrier. See [MIT-LICENSE](http://github.com/ccocchi/rabl-rails/blob/master/MIT-LICENSE) for details.

data/lib/rabl-rails/compiler.rb

@@ -69,7 +69,8 @@ module RablRails
     #
     def child(name_or_data, options = {})
       data, name  = extract_data_and_name(name_or_data)
-      name        = options[:root] if options.has_key? :root
+      name        = options[:root]  if options.has_key? :root
+      name        = options[:as]    if options.has_key? :as
       template    = partial_or_block(data, options) { yield }
       @template.add_node Nodes::Child.new(name, template)
     end

data/lib/rabl-rails/configuration.rb

@@ -33,9 +33,9 @@ module RablRails
     def result_flags
       @result_flags ||= begin
         result = 0
-        result |= 0b01  if @replace_nil_values_with_empty_strings
-        result |= 0b10  if @replace_empty_string_values_with_nil
-        result |= 0b100 if @exclude_nil_values
+        result |= 0b001   if @replace_nil_values_with_empty_strings
+        result |= 0b010   if @replace_empty_string_values_with_nil
+        result |= 0b100   if @exclude_nil_values
         result
       end
     end

data/lib/rabl-rails/handler.rb

@@ -3,12 +3,12 @@ require 'active_support/core_ext/class/attribute'
 module RablRails
   module Handlers
     class Rabl
-      def self.call(template)
+      def self.call(template, source = nil)
         %{
           RablRails::Library.instance.
-            get_rendered_template(#{template.source.inspect}, self, local_assigns)
+            get_rendered_template(#{(source || template.source).inspect}, self, local_assigns)
         }
       end
     end
   end
-end
+end

data/lib/rabl-rails/library.rb

@@ -25,7 +25,7 @@ module RablRails
 
     def get_rendered_template(source, view, locals = nil)
       compiled_template = compile_template_from_source(source, view)
-      format = view.lookup_context.rendered_format || :json
+      format = view.lookup_context.formats.first || :json
       raise UnknownFormat, "#{format} is not supported in rabl-rails" unless RENDERER_MAP.key?(format)
       RENDERER_MAP[format].render(compiled_template, view, locals)
     end

data/lib/rabl-rails/version.rb

@@ -1,3 +1,3 @@
 module RablRails
-  VERSION = '0.5.5'
+  VERSION = '0.6.1'
 end

data/lib/rabl-rails/visitors/to_hash.rb

@@ -57,7 +57,7 @@ module Visitors
     end
 
     def visit_Lookup n
-      object  = object_from_data(nil, n)
+      object  = object_from_data(_resource, n)
       key     = _resource.public_send(n.field)
       value   = object[key]
       value   = !!value if n.cast_to_boolean?

data/rabl-rails.gemspec

@@ -14,9 +14,7 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version     = '>= 2.2.0'
 
-  s.files = `git ls-files -z`.split("\x0").reject do |file|
-    file.start_with?('test/')
-  end
+  s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- test/*`.split("\n")
   s.require_paths = ["lib"]
 

data/test/helper.rb

@@ -49,8 +49,8 @@ class Context
       @format = format
     end
 
-    def rendered_format
-      @format.to_sym
+    def formats
+      [@format]
     end
   end
 

data/test/test_compiler.rb

@@ -11,13 +11,20 @@ class TestCompiler < Minitest::Test
     }
   end
 
+  @@view_class = if ActionView::Base.respond_to?(:with_empty_template_cache)
+    # From Rails 6.1
+    ActionView::Base.with_empty_template_cache
+  else
+    ActionView::Base
+  end
+
   describe 'compiler' do
     def extract_attributes(nodes)
       nodes.map(&:hash)
     end
 
     before do
-      @view     = ActionView::Base.new(@@tmp_path, {})
+      @view     = @@view_class.new(ActionView::LookupContext.new(@@tmp_path), {}, nil)
       @compiler = RablRails::Compiler.new(@view)
     end
 
@@ -156,6 +163,14 @@ class TestCompiler < Minitest::Test
       assert_equal(:user, child_node.data)
     end
 
+    it "compiles child with root name defined with `as` option" do
+      t = @compiler.compile_source(%{ child(:user, as: :author) do attributes :foo end })
+      child_node = t.nodes.first
+
+      assert_equal(:author, child_node.name)
+      assert_equal(:user, child_node.data)
+    end
+
     it "compiles child with arbitrary source" do
       t = @compiler.compile_source(%{ child :@user => :author do attribute :name end })
       child_node = t.nodes.first

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rabl-rails
 version: !ruby/object:Gem::Version
-  version: 0.5.5
+  version: 0.6.1
 platform: ruby
 authors:
 - Christopher Cocchi-Perrier
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-02-19 00:00:00.000000000 Z
+date: 2021-03-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -158,8 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: Fast Rails 4+ templating system with JSON, XML and PList support