curly-templates 1.0.1 → 2.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d72b1af07f110af3c9bfb294cc3187b6d3c50e90
-  data.tar.gz: e9dac2337a59c5784231de4aafb3055f96722b6c
+  metadata.gz: f70027aee738dbd7ac5cc496cce7017943304833
+  data.tar.gz: 68947fc8e15e97945fcba195b0c278e14930d9dd
 SHA512:
-  metadata.gz: 7a599cadb2fbede5c03f5f650a5c2385540e9280c5414c3f1fef7b3b6978139551f9865320a563cd83e21c5727d90d230a0c852103f0b72b4b0b09eb0ff2b872
-  data.tar.gz: 9fc5cddddd5cad763b949c308ed35a53cc1ce72f04188e195f16c9a92c9a78054091cf9f0307e00779cf57fe2d6a5c89d3156c0a61efb2f9c38897b14f93219c
+  metadata.gz: d3d6816a0d6fb0e6125cc89845bea00ef363e03012f9bc96e083d0d0951febb032b31472a8bcb23271c16333a470a881e2bf0c4129b8712f06e4f5c24aa86c4b
+  data.tar.gz: 141f19f518dc381ecde8ac6d451bde20551bdcc711c4a9d1a7aa0f981cb100e1e840feb603a01eed956d5e865c3e6c7ef95d736f6302921fb29d3ad858c3150b

data/CHANGELOG.md

@@ -1,9 +1,18 @@
-### Curly 1.0.1 (June 24, 2014)
+### Unreleased
 
-* Use SortedSet to store view dependencies. We always want these to be in
-  order.
+### Curly 2.0.0.beta1 (June 27, 2014)
 
-  *Liborio Cannici*
+* Add support for collection blocks.
+
+  *Daniel Schierbeck*
+
+* Add support for keyword parameters to references.
+
+  *Alisson Cavalcante Agiani, Jeremy Rodi, and Daniel Schierbeck*
+
+* Remove memory leak that could cause unbounded memory growth.
+
+  *Daniel Schierbeck*
 
 ### Curly 1.0.0rc1 (February 18, 2014)
 

data/README.md

@@ -1,3 +1,7 @@
+Note: this documentation is for the upcoming Curly v2 – you may be looking for the
+[documentation for the latest final release](https://github.com/zendesk/curly/tree/1-0-stable).
+
+
 Curly
 =======
 
@@ -24,8 +28,13 @@ or [Handlebars](http://handlebarsjs.com/), Curly is different in some key ways:
 
 1. [Installing](#installing)
 2. [How to use Curly](#how-to-use-curly)
+    1. [Identifiers](#identifiers)
+    1. [Attributes](#attributes)
     1. [Conditional blocks](#conditional-blocks)
+    1. [Collection blocks](#collection-blocks)
+    1. [Setting up state](#setting-up-state)
     2. [Escaping Curly syntax](#escaping-curly-syntax)
+    2. [Comments](#comments)
 3. [Presenters](#presenters)
     1. [Layouts and Content Blocks](#layouts-and-content-blocks)
     2. [Examples](#examples)
@@ -53,7 +62,7 @@ these are placed in `app/presenters/`, so in this case the presenter would
 reside in `app/presenters/posts/comment_presenter.rb`. Note that presenters
 for partials are not prepended with an underscore.
 
-Add some HTML to the partial template along with some Curly variables:
+Add some HTML to the partial template along with some Curly components:
 
 ```html
 <!-- app/views/posts/_comment.html.curly -->
@@ -70,8 +79,8 @@ Add some HTML to the partial template along with some Curly variables:
 </div>
 ```
 
-The presenter will be responsible for filling in the variables. Add the necessary
-Ruby code to the presenter:
+The presenter will be responsible for providing the data for the components. Add
+the necessary Ruby code to the presenter:
 
 ```ruby
 # app/presenters/posts/comment_presenter.rb
@@ -108,6 +117,54 @@ render comment
 render collection: post.comments
 ```
 
+### Identifiers
+
+Curly components can specify an _identifier_ using the so-called dot notation: `{{x.y.z}}`.
+This can be very useful if the data you're accessing is hierarchical in nature. One common
+example is I18n:
+
+```html
+<h1>{{i18n.homepage.header}}</h1>
+```
+
+```ruby
+# In the presenter, the identifier is passed as an argument to the method. The
+# argument will always be a String.
+def i18n(key)
+  translate(key)
+end
+```
+
+The identifier is separated from the component name with a dot. If the presenter method
+has a default value for the argument, the identifier is optional – otherwise it's mandatory.
+
+
+### Attributes
+
+In addition to [an identifier](#identifiers), Curly components can be annotated
+with *attributes*. These are key-value pairs that affect how a component is rendered.
+
+The syntax is reminiscent of HTML:
+
+```html
+<div>{{sidebar rows=3 width=200px title="I'm the sidebar!"}}</div>
+```
+
+The presenter method that implements the component must have a matching keyword argument:
+
+```ruby
+def sidebar(rows: "1", width: "100px", title:); end
+```
+
+All argument values will be strings. A compilation error will be raised if
+
+- an attribute is used in a component without a matching keyword argument being present
+  in the method definition; or
+- a required keyword argument in the method definition is not set as an attribute in the
+  component.
+
+You can define default values using Ruby's own syntax.
+
 
 ### Conditional blocks
 
@@ -116,8 +173,8 @@ use _conditional blocks_. The `{{#admin?}}...{{/admin?}}` syntax will only rende
 content of the block if the `admin?` method on the presenter returns true, while the
 `{{^admin?}}...{{/admin?}}` syntax will only render the content if it returns false.
 
-Both forms can be parameterized by a single argument: `{{#locale.en?}}...{{/locale.en?}}`
-will only render the block if the `locale?` method on the presenter returns true given the
+Both forms can have an identifier: `{{#locale.en?}}...{{/locale.en?}}` will only
+render the block if the `locale?` method on the presenter returns true given the
 argument `"en"`. Here's how to implement that method in the presenter:
 
 ```ruby
@@ -129,6 +186,108 @@ class SomePresenter < Curly::Presenter
 end
 ```
 
+Furthermore, attributes can be set on the block. These only need to be specified when
+opening the block, not when closing it:
+
+```html
+{{#square? width=3 height=3}}
+  <p>It's square!</p>
+{{/square?}}
+```
+
+Attributes work the same way as they do for normal components.
+
+
+### Collection blocks
+
+Sometimes you want to render one or more items within the current template, and splitting
+out a separate template and rendering that in the presenter is too much overhead. You can
+instead define the template that should be used to render the items inline in the current
+template using the _collection block syntax_.
+
+Collection blocks are opened using an asterisk:
+
+```html
+{{*comments}}
+  <li>{{body}} ({{author_name}})</li>
+{{/comments}}
+```
+
+The presenter will need to expose the method `#comments`, which should return a collection
+of objects:
+
+```ruby
+class Posts::ShowPresenter < Curly::Presenter
+  presents :post
+
+  def comments
+    @post.comments
+  end
+end
+```
+
+The template within the collection block will be used to render each item, and it will
+be backed by a presenter named after the component – in this case, `comments`. The name
+will be singularized and Curly will try to find the presenter class in the following
+order:
+
+* `Posts::ShowPresenter::CommentPresenter`
+* `Posts::CommentPresenter`
+* `CommentPresenter`
+
+This allows you some flexibility with regards to how you want to organize these nested
+templates and presenters.
+
+Note that the nested template will *only* have access to the methods on the nested
+presenter, but all variables passed to the "parent" presenter will be forwarded to
+the nested presenter. In addition, the current item in the collection will be
+passed, as well as that item's index in the collection:
+
+```ruby
+class Posts::CommentPresenter < Curly::Presenter
+  presents :post, :comment, :comment_counter
+
+  def number
+    # `comment_counter` is automatically set to the item's index in the collection,
+    # starting with 1.
+    @comment_counter
+  end
+
+  def body
+    @comment.body
+  end
+
+  def author_name
+    @comment.author.name
+  end
+end
+```
+
+Collection blocks are an alternative to splitting out a separate template and rendering
+that from the presenter – which solution is best depends on your use case.
+
+
+### Setting up state
+
+Although most code in Curly presenters should be free of side effects, sometimes side
+effects are required. One common example is defining content for a `content_for` block.
+
+If a Curly presenter class defines a `setup!` method, it will be called before the view
+is rendered:
+
+```ruby
+class PostPresenter < Curly::Presenter
+  presents :post
+
+  def setup!
+    content_for :title, post.title
+
+    content_for :sidebar do
+      render 'post_sidebar', post: post
+    end
+  end
+end
+```
 
 ### Escaping Curly syntax
 
@@ -141,6 +300,16 @@ This is {{{escaped}}.
 You don't need to escape the closing `}}`.
 
 
+### Comments
+
+If you want to add comments to your Curly templates that are not visible in the rendered HTML,
+use the following syntax:
+
+```html
+{{! This is some interesting stuff }}
+```
+
+
 Presenters
 ----------
 
@@ -151,7 +320,7 @@ rendering `posts/show`, the `Posts::ShowPresenter` class will be used. Note that
 is only used to render a view if a template can be found – in this case, at
 `app/views/posts/show.html.curly`.
 
-Presenters can declare a list of accepted parameters using the `presents` method:
+Presenters can declare a list of accepted variables using the `presents` method:
 
 ```ruby
 class Posts::ShowPresenter < Curly::Presenter
@@ -159,7 +328,7 @@ class Posts::ShowPresenter < Curly::Presenter
 end
 ```
 
-A parameter can have a default value:
+A variable can have a default value:
 
 ```ruby
 class Posts::ShowPresenter < Curly::Presenter
@@ -168,7 +337,8 @@ class Posts::ShowPresenter < Curly::Presenter
 end
 ```
 
-Any public method defined on the presenter is made available to the template:
+Any public method defined on the presenter is made available to the template as
+a component:
 
 ```ruby
 class Posts::ShowPresenter < Curly::Presenter
@@ -420,6 +590,7 @@ Thanks to [Zendesk](http://zendesk.com/) for sponsoring the work on Curly.
 - Daniel Schierbeck ([@dasch](https://github.com/dasch))
 - Benjamin Quorning ([@bquorning](https://github.com/bquorning))
 - Jeremy Rodi ([@redjazz96](https://github.com/redjazz96))
+- Alisson Cavalcante Agiani ([@thelinuxlich](https://github.com/thelinuxlich))
 
 
 Build Status

data/Rakefile

@@ -65,7 +65,7 @@ end
 
 desc "Create tag v#{version} and build and push #{gem_file} to Rubygems"
 task :release => :build do
-  unless `git branch` =~ /^\* master$/ || `git branch` =~ /^\* \d+-\d+-stable$/
+  unless `git branch` =~ /^\* master$/
     puts "You must be on the master branch to release!"
     exit!
   end

data/curly-templates.gemspec

@@ -4,8 +4,8 @@ Gem::Specification.new do |s|
   s.rubygems_version = '1.3.5'
 
   s.name              = 'curly-templates'
-  s.version           = '1.0.1'
-  s.date              = '2014-06-24'
+  s.version           = '2.0.0.beta1'
+  s.date              = '2014-06-27'
 
   s.summary     = "Free your views!"
   s.description = "A view layer for your Rails apps that separates structure and logic."
@@ -36,13 +36,16 @@ Gem::Specification.new do |s|
     curly-templates.gemspec
     lib/curly-templates.rb
     lib/curly.rb
+    lib/curly/attribute_parser.rb
     lib/curly/compilation_error.rb
     lib/curly/compiler.rb
+    lib/curly/component_compiler.rb
+    lib/curly/component_parser.rb
     lib/curly/dependency_tracker.rb
     lib/curly/error.rb
     lib/curly/incomplete_block_error.rb
     lib/curly/incorrect_ending_error.rb
-    lib/curly/invalid_reference.rb
+    lib/curly/invalid_component.rb
     lib/curly/presenter.rb
     lib/curly/railtie.rb
     lib/curly/scanner.rb
@@ -52,8 +55,12 @@ Gem::Specification.new do |s|
     lib/generators/curly/controller/templates/presenter.rb.erb
     lib/generators/curly/controller/templates/view.html.curly.erb
     lib/rails/projections.json
+    spec/attribute_parser_spec.rb
+    spec/compiler/collections_spec.rb
     spec/compiler_spec.rb
+    spec/component_compiler_spec.rb
     spec/generators/controller_generator_spec.rb
+    spec/incorrect_ending_error_spec.rb
     spec/presenter_spec.rb
     spec/scanner_spec.rb
     spec/spec_helper.rb

data/lib/curly.rb

@@ -1,11 +1,11 @@
 # Curly is a simple view system. Each view consists of two parts, a
 # template and a presenter. The template is a simple string that can contain
-# references in the format `{{refname}}`, e.g.
+# components in the format `{{refname}}`, e.g.
 #
 #   Hello {{recipient}},
 #   you owe us ${{amount}}.
 #
-# The references will be converted into messages that are sent to the
+# The components will be converted into messages that are sent to the
 # presenter, which is any Ruby object. Only public methods can be referenced.
 # To continue the earlier example, here's the matching presenter:
 #
@@ -26,7 +26,7 @@
 # See Curly::Presenter for more information on presenters.
 #
 module Curly
-  VERSION = "1.0.1"
+  VERSION = "2.0.0.beta1"
 
   # Compiles a Curly template to Ruby code.
   #
@@ -38,7 +38,7 @@ module Curly
   end
 
   # Whether the Curly template is valid. This includes whether all
-  # references are available on the presenter class.
+  # components are available on the presenter class.
   #
   # template        - The template String that should be validated.
   # presenter_class - The presenter Class.

data/lib/curly/attribute_parser.rb

@@ -0,0 +1,69 @@
+module Curly
+  AttributeError = Class.new(Curly::Error)
+
+  class AttributeParser
+    def self.parse(string)
+      return {} if string.nil?
+      new(string).parse
+    end
+
+    def initialize(string)
+      @scanner = StringScanner.new(string)
+    end
+
+    def parse
+      attributes = scan_attributes
+      Hash[attributes]
+    end
+
+    private
+
+    def scan_attributes
+      attributes = []
+
+      while attribute = scan_attribute
+        attributes << attribute
+      end
+
+      attributes
+    end
+
+    def scan_attribute
+      skip_whitespace
+
+      return if @scanner.eos?
+
+      name = scan_name or raise AttributeError
+      value = scan_value or raise AttributeError
+
+      [name, value]
+    end
+
+    def scan_name
+      name = @scanner.scan(/\w+=/)
+      name && name[0..-2]
+    end
+
+    def scan_value
+      scan_unquoted_value || scan_single_quoted_value || scan_double_quoted_value
+    end
+
+    def scan_unquoted_value
+      @scanner.scan(/\w+/)
+    end
+
+    def scan_single_quoted_value
+      value = @scanner.scan(/'[^']*'/)
+      value && value[1..-2]
+    end
+
+    def scan_double_quoted_value
+      value = @scanner.scan(/"[^"]*"/)
+      value && value[1..-2]
+    end
+
+    def skip_whitespace
+      @scanner.skip(/\s*/)
+    end
+  end
+end