rack-component 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5f073b2ec6adad102c5fb898e7071c7531663960f6188c678a1b46c7f564e2f
-  data.tar.gz: f0bbc1b2c7cee8fca01ec2f7e0d75b0ca260428e24a50ec6f28a9a70e714b6f7
+  metadata.gz: f4f080e40de93c62a1a6b1aa9aabf3ee3f2a92fa10823f52c9dade5b075d440f
+  data.tar.gz: '08d3866748d7e14320a274f67e3682b67a51448154ecdae5034c2c01ec5a3e3f'
 SHA512:
-  metadata.gz: bdfd59e87eccbc6cc0be4a92579813d76195d14e0cfb3620f6ec3a3204730cb8ba35f528d59e260db268bb2a697acb1bb6ccf3c8615fbb52979aa67e15e91858
-  data.tar.gz: 76ab042215b76839bab82c36ac19682da07050ed0da54d714ffc6e609160ef360962e445b4ef9f71ade86e35ff2dc65668ace167880c92203c4da565f4d09036
+  metadata.gz: 6e5c02e8c994ed4fa58e2a62004d248033d796c4f7163217c8a164c127a7ccf26c01a99c3a1fd0415aecff7af2ceae07eec800b2d04ab755da77bb3cd1dd4ab5
+  data.tar.gz: 96405e2d4e8b8f9add4d47f1129f035f00a5a9fbf00d6c363c8f056db88d43c962c1c43d367f88cf7557efccfb11386ae760a73b69cab20a795387efd0bab1f2

data/.rubocop.yml

@@ -24,5 +24,3 @@ Style/TrailingCommaInHashLiteral:
   Enabled: false
   StyleGuide: http://relaxed.ruby.style/#styletrailingcommainliteral
   EnforcedStyleForMultiline: consistent_comma
-Style/Documentation:
-  Enabled: false

data/.travis.yml

@@ -2,5 +2,7 @@
 language: ruby
 cache: bundler
 rvm:
-  - 2.5.1
+  - 2.5.3
+  - 2.4
+  - 2.3
 before_install: gem install bundler -v 1.16.5

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.5.0
+### Fixed
+- The `env` argument of the `render` block is now optional, as per standard Ruby
+  block behavior.
+  ```ruby
+  class WorksInThisVersion < Rack::Component
+    render do
+      'This component raised an ArgumentError in old versions but works now.'
+    end
+  end
+
+  class StillWorks < Rack::Component
+    render do |env|
+      'This style still works. Using |keyword:, arguments:| in env is nice.'
+    end
+  end
+  ```
+
+### Added
+- A changelog
+- Templating via [tilt](https://github.com/rtomayko/tilt), with support for
+  escaping HTML by default
+
+### Removed
+- Calling `Component.memoized(env)` is no longer supported. Use Sam Saffron's
+  [lru_redux](https://github.com/SamSaffron/lru_redux) as an almost drop-in
+  replacement, like this:
+
+    ```ruby
+    require 'rack/component'
+    require 'lru_redux'
+    class MyComponent < Rack::Component
+      Cache = LruRedux::ThreadSafeCache.new(100)
+
+      render do |env|
+        Cache.getset(env) { 'this block will render after checking the cache' }
+      end
+    end
+    ```
+
+## 0.4.2 - 2019-01-04
+### Added
+- `#h` method for escaping HTML inside interpolated strings
+
+## 0.4.1 - 2019-01-02
+- First public, documented release

data/Gemfile.lock

@@ -21,26 +21,33 @@ GEM
       thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.3)
     equalizer (0.0.11)
+    erubi (1.8.0)
+    haml (5.0.4)
+      temple (>= 0.8.0)
+      tilt
     ice_nine (0.11.2)
-    jaro_winkler (1.5.1)
+    jaro_winkler (1.5.2)
     kwalify (0.7.2)
-    method_source (0.9.0)
+    liquid (4.0.1)
+    method_source (0.9.2)
     parallel (1.12.1)
-    parser (2.5.1.2)
+    parser (2.5.3.0)
       ast (~> 2.4.0)
     powerpack (0.1.2)
-    pry (0.11.3)
+    pry (0.12.2)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
+    psych (3.1.0)
     rack (2.0.6)
     rack-test (0.8.3)
       rack (>= 1.0, < 3)
     rainbow (3.0.0)
     rake (10.5.0)
-    reek (5.2.0)
+    reek (5.3.0)
       codeclimate-engine-rb (~> 0.4.0)
       kwalify (~> 0.7.0)
       parser (>= 2.5.0.0, < 2.6, != 2.5.1.1)
+      psych (~> 3.1.0)
       rainbow (>= 2.0, < 4.0)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
@@ -55,18 +62,19 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
     rspec-support (3.8.0)
-    rubocop (0.59.2)
+    rubocop (0.62.0)
       jaro_winkler (~> 1.5.1)
       parallel (~> 1.10)
       parser (>= 2.5, != 2.5.1.1)
       powerpack (~> 0.1)
       rainbow (>= 2.2.2, < 4.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (~> 1.0, >= 1.0.1)
+      unicode-display_width (~> 1.4.0)
     ruby-progressbar (1.10.0)
+    temple (0.8.0)
     thread_safe (0.3.6)
-    tilt (2.0.8)
-    unicode-display_width (1.4.0)
+    tilt (2.0.9)
+    unicode-display_width (1.4.1)
     virtus (1.0.5)
       axiom-types (~> 0.1)
       coercible (~> 1.0)
@@ -79,7 +87,10 @@ PLATFORMS
 
 DEPENDENCIES
   benchmark-ips (~> 2.7)
-  bundler (~> 1.16)
+  bundler (~> 2)
+  erubi (~> 1.8)
+  haml (~> 5)
+  liquid (~> 4)
   pry (~> 0.11)
   rack (~> 2.0.6)
   rack-component!
@@ -92,4 +103,4 @@ DEPENDENCIES
   yard (~> 0.9)
 
 BUNDLED WITH
-   1.17.1
+   2.0.1

data/README.md

@@ -13,6 +13,7 @@ gem 'rack-component'
 ```
 
 ## Quickstart with Sinatra
+
 ```ruby
 # config.ru
 require 'sinatra'
@@ -20,7 +21,7 @@ require 'rack/component'
 
 class Hello < Rack::Component
   render do |env|
-    "<h1>Hello, #{h(env[:name])}</h1>"
+    "<h1>Hello, #{h env[:name]}</h1>"
   end
 end
 
@@ -31,27 +32,25 @@ end
 run Sinatra::Application
 ```
 
-**Note that Rack::Component currently does not escape strings by default**. To
-escape strings, you must use the `#h` helper, as in the example above.
-
-There is an [issue open](https://github.com/chrisfrank/rack-component/issues/4)
-to discuss how to enable escaping by default. If you have ideas or opinions, I'd
-love to hear about them there.
+**Note that Rack::Component does not escape strings by default**. To escape
+strings, you can either use the `#h` helper like in the example above, or you
+can configure your components to render a template that escapes automatically.
+See the [Recipes](#recipes) section for details.
 
 ## Table of Contents
 
 * [Getting Started](#getting-started)
   * [Components as plain functions](#components-as-plain-functions)
   * [Components as Rack::Components](#components-as-rackcomponents)
-  * [Components that re-render instantly](#components-that-re-render-instantly)
+    * [Components if you hate inheritance](#components-if-you-hate-inheritance)
 * [Recipes](#recipes)
   * [Render one component inside another](#render-one-component-inside-another)
-  * [Memoize an expensive component for one minute](#memoize-an-expensive-component-for-one-minute)
-  * [Memoize an expensive component until its content changes](#memoize-an-expensive-component-until-its-content-changes)
+  * [Render a template that escapes output by default via Tilt](#render-a-template-that-escapes-output-by-default-via-tilt)
   * [Render an HTML list from an array](#render-an-html-list-from-an-array)
   * [Render a Rack::Component from a Rails controller](#render-a-rackcomponent-from-a-rails-controller)
   * [Mount a Rack::Component as a Rack app](#mount-a-rackcomponent-as-a-rack-app)
   * [Build an entire App out of Rack::Components](#build-an-entire-app-out-of-rackcomponents)
+  * [Define `#render` at the instance level instead of via `render do`](#define-render-at-the-instance-level-instead-of-via-render-do)
 * [API Reference](#api-reference)
 * [Performance](#performance)
 * [Compatibility](#compatibility)
@@ -77,57 +76,38 @@ Greeter.call(name: 'Mina') #=> '<h1>Hi, Mina.</h1>'
 
 ### Components as Rack::Components
 
-Convert your lambda to a `Rack::Component` when it needs instance methods or
-state:
+Upgrade your lambda to a `Rack::Component` when it needs HTML escaping, instance
+methods, or state:
 
 ```ruby
 require 'rack/component'
 class FormalGreeter < Rack::Component
   render do |env|
-    "<h1>Hi, #{title} #{env[:name]}.</h1>"
+    "<h1>Hi, #{h title} #{h env[:name]}.</h1>"
   end
 
+  # +env+ is available in instance methods too
   def title
-    # the hash you pass to `call` is available as `env` in instance methods
-    env[:title] || "President"
+    env[:title] || "Queen"
   end
 end
 
-FormalGreeter.call(name: 'Macron') #=> "<h1>Hi, President Macron.</h1>"
-FormalGreeter.call(name: 'Merkel', title: 'Chancellor') #=> "<h1>Hi, Chancellor Merkel.</h1>"
+FormalGreeter.call(name: 'Franklin') #=> "<h1>Hi, Queen Franklin.</h1>"
+FormalGreeter.call(
+  title: 'Captain',
+  name: 'Kirk <kirk@starfleet.gov>'
+) #=> <h1>Hi, Captain Kirk &lt;kirk@starfleet.gov&gt;.</h1>
 ```
 
-### Components that re-render instantly
+#### Components if you hate inheritance
 
-Replace `#call` with `#memoized` to make re-renders with the same `env` instant:
+Instead of inheriting from `Rack::Component`, you can `extend` its methods:
 
 ```ruby
-require 'rack/component'
-require 'net/http'
-class NetworkGreeter < Rack::Component
-  render do |env|
-    "Hi, #{get_job_title_from_api} #{env[:name]}."
-  end
-
-  def get_job_title_from_api
-    endpoint = URI("http://api.heads-of-state.gov/")
-    Net::HTTP.get("#{endpoint}?q=#{env[:name]}")
-  end
+class SoloComponent
+  extend Rack::Component::Methods
+  render { "Family is complicated" }
 end
-
-NetworkGreeter.memoized(name: 'Macron')
-# ...after a slow network call to our fictional Heads Of State API
-#=> "Hi, President Macron."
-
-NetworkGreeter.memoized(name: 'Macron') # subsequent calls with the same env are instant.
-#=> "Hi, President Macron."
-
-NetworkGreeter.memoized(name: 'Merkel')
-# ...this env is new, so NetworkGreeter makes another network call
-#=> "Hi, Chancellor Merkel."
-
-NetworkGreeter.memoized(name: 'Merkel') #=> instant! "Hi, Chancellor Merkel."
-NetworkGreeter.memoized(name: 'Macron') #=> instant! "Hi, President Macron."
 ```
 
 ## Recipes
@@ -138,7 +118,9 @@ You can nest Rack::Components as if they were [React Children][jsx children] by
 calling them with a block.
 
 ```ruby
-Layout.call(title: 'Home') { Content.call }
+Layout.call(title: 'Home') do
+  Content.call
+end
 ```
 
 Here's a more fully fleshed example:
@@ -151,11 +133,12 @@ get '/posts/:id' do
   PostPage.call(id: params[:id])
 end
 
-# fetch a post from the database and render it inside a layout
+# Fetch a post from the database and render it inside a Layout
 class PostPage < Rack::Component
   render do |env|
-    post = Post.find(id: env[:id])
-    # Nest a PostContent instance inside a Layout instance, with some arbitrary HTML too
+    post = Post.find env[:id]
+    # Nest a PostContent instance inside a Layout instance,
+    # with some arbitrary HTML too
     Layout.call(title: post.title) do
       <<~HTML
         <main>
@@ -169,80 +152,122 @@ class PostPage < Rack::Component
   end
 end
 
-class PostContent < Rack::Component
-  render do |env|
-    <<~HTML
-      <article>
-        <h1>#{env[:title]}</h1>
-        #{env[:body]}
-      </article>
-    HTML
-  end
-end
-
 class Layout < Rack::Component
-  render do |env, &children|
-    # the `&children` param is just a standard ruby block
+  # The +render+ macro supports Ruby's keyword arguments, and, like any other
+  # Ruby function, can accept a block via the & operator.
+  # Here, :title is a required key in +env+, and &child is just a regular Ruby
+  # block that could be named anything.
+  render do |title:, **, &child|
     <<~HTML
       <!DOCTYPE html>
       <html>
         <head>
-          <title>#{env[:title]}</title>
+          <title>#{h title}</title>
         </head>
         <body>
-          #{children.call}
+        #{child.call}
         </body>
       </html>
     HTML
   end
 end
+
+class PostContent < Rack::Component
+  render do |title:, body:, **|
+    <<~HTML
+      <article>
+        <h1>#{h title}</h1>
+        #{h body}
+      </article>
+    HTML
+  end
+end
 ```
 
-### Memoize an expensive component for one minute
+### Render a template that escapes output by default via Tilt
 
-You can use `memoized` as a time-based cache by passing a timestamp to `env`:
+If you add [Tilt][tilt] and `erubi` to your Gemfile, you can use the `render`
+macro with an automatically-escaped template instead of a block.
 
 ```ruby
-require 'rack/component'
+# Gemfile
+gem 'tilt'
+gem 'erubi'
+gem 'rack-component'
+
+# my_component.rb
+class TemplateComponent < Rack::Component
+  render erb: <<~ERB
+    <h1>Hello, <%= name %></h1>
+  ERB
 
-# Render one million posts as JSON
-class MillionPosts < Rack::Component
-  render { |env| Post.limit(1_000_000).to_json }
+  def name
+    env[:name] || 'Someone'
+  end
 end
 
-MillionPosts.memoized(Time.now.to_i / 60) #=> first call is slow
-MillionPosts.memoized(Time.now.to_i / 60) #=> next calls in same minute are quick
+TemplateComponent.call #=> <h1>Hello, Someone</h1>
+TemplateComponent.call(name: 'Spock<>') #=> <h1>Hello, Spock&lt;&gt;</h1>
+```
+
+Rack::Component passes `{ escape_html: true }` to Tilt by default, which enables
+automatic escaping in ERB (via erubi) Haml, and Markdown. To disable automatic
+escaping, or to pass other tilt options, use an `opts: {}` key in `render`:
+
+```ruby
+class OptionsComponent < Rack::Component
+  render opts: { escape_html: false, trim: false }, erb: <<~ERB
+    <article>
+      Hi there, <%= {env[:name] %>
+      <%== yield %>
+    </article>
+  ERB
+end
 ```
 
-### Memoize an expensive component until its content changes
+Template components support using the `yield` keyword to render child
+components, but note the double-equals `<%==` in the example above. If your
+component escapes HTML, and you're yielding to a component that renders HTML,
+you probably want to disable escaping via `==`, just for the `<%== yield %>`
+call. This is safe, as long as the component you're yielding to uses escaping.
 
-This recipe will speed things up when your database calls are fast but your
-render method is slow:
+Using `erb` as a key for the inline template is a shorthand, which also works
+with `haml` and `markdown`. But you can also specify `engine` and `template`
+explicitly.
 
 ```ruby
-require 'rack/component'
-class PostAnalysis < Rack::Component
-  render do |env|
-    <<~HTML
-      <h1>#{env[:post].title}</h1>
-      <article>#{env[:post].content}</article>
-      <aside>#{expensive_natural_language_analysis}</aside>
-    HTML
-  end
+require 'haml'
+class HamlComponent < Rack::Component
+  # Note the special HEREDOC syntax for inline Haml templates! Without the
+  # single-quotes, Ruby will interpret #{strings} before Haml does.
+  render engine: 'haml', template: <<~'HAML'
+    %h1 Hi #{env[:name]}.
+  HAML
+end
+```
 
-  def expensive_natural_language_analysis
-    FancyNaturalLanguageLibrary.analyze(env[:post].content)
+Using a template instead of raw string interpolation is a safer default, but it
+can make it less convenient to do logic while rendering. Feel free to override
+your Component's `#initialize` method and do logic there:
+
+```ruby
+class EscapedPostView < Rack::Component
+  def initialize(env)
+    @post = Post.find(env[:id])
+    # calling `super` will populate the instance-level `env` hash, making
+    # `env` available outside this method. But it's fine to skip it.
+    super
   end
-end
 
-PostAnalysis.memoized(post: Post.find(1)) #=> slow, because it runs an expensive natural language analysis
-PostAnalysis.memoized(post: Post.find(1)) #=> instant, because the content of :post has not changed
+  render erb: <<~ERB
+    <article>
+      <h1><%= @post.title %></h1>
+      <%= @post.body %>
+    </article>
+  ERB
+end
 ```
 
-This recipe works with any Ruby object that implements a `#hash` method based
-on the object's content, including instances of `ActiveRecord::Base` and
-`Sequel::Model`.
-
 ### Render an HTML list from an array
 
 [JSX Lists][jsx lists] use JavaScript's `map` function. Rack::Component does
@@ -251,7 +276,7 @@ likewise, only you need to call `join` on the array:
 ```ruby
 require 'rack/component'
 class PostsList < Rack::Component
-  render do |env|
+  render do
     <<~HTML
       <h1>This is a list of posts</h1>
       <ul>
@@ -264,12 +289,12 @@ class PostsList < Rack::Component
     env[:posts].map { |post|
       <<~HTML
         <li class="item">
-          <a href="#{post[:url]}">
+          <a href="/posts/#{post[:id]}">
             #{post[:name]}
           </a>
         </li>
       HTML
-    }.join #unlike JSX, you need to call `join` on your array
+    }.join # unlike JSX, you need to call `join` on your array
   end
 end
 
@@ -289,26 +314,24 @@ end
 
 # app/components/posts_list.rb
 class PostsList < Rack::Component
-  render { |env| posts.to_json }
-
-  def posts
-    Post.magically_filter_via_params(env)
+  def render
+    Post.magically_filter_via_params(env).to_json
   end
 end
 ```
 
 ### Mount a Rack::Component as a Rack app
 
-Because Rack::Components follow the same API as a Rack app, you can mount them
-anywhere you can mount a Rack app. It's up to you to return a valid rack
-tuple, though.
+Because Rack::Components have the same signature as Rack app, you can mount them
+anywhere you can mount a Rack app. It's up to you to return a valid rack tuple,
+though.
 
 ```ruby
 # config.ru
 require 'rack/component'
 
 class Posts < Rack::Component
-  render do |env|
+  def render
     [status, headers, [body]]
   end
 
@@ -335,66 +358,102 @@ Rack::Component instead of Controllers, Views, and templates. But to see an
 entire app built only out of Rack::Components, see
 [the example spec](https://github.com/chrisfrank/rack-component/blob/master/spec/raw_rack_example_spec.rb).
 
+### Define `#render` at the instance level instead of via `render do`
+
+The class-level `render` macro exists to make using templates easy, and to lean
+on Ruby's keyword arguments as a limited imitation of React's `defaultProps` and
+`PropTypes`. But you can define render at the instance level instead.
+
+```ruby
+# these two components render identical output
+
+class MacroComponent < Rack::Component
+  render do |name:, dept: 'Engineering'|
+    "#{name} - #{dept}"
+  end
+end
+
+class ExplicitComponent < Rack::Component
+  def initialize(name:, dept: 'Engineering')
+    @name = name
+    @dept = dept
+    # calling `super` will populate the instance-level `env` hash, making
+    # `env` available outside this method. But it's fine to skip it.
+    super
+  end
+
+  def render
+    "#{@name} - #{@dept}"
+  end
+end
+```
+
 ## API Reference
 
 The full API reference is available here:
 
 https://www.rubydoc.info/gems/rack-component
 
-For info on how to clear or change the size of the memoziation cache, please see
-[the spec][spec].
-
 ## Performance
 
-On my machine, Rendering a Rack::Component is almost 10x faster than rendering a
-comparable Tilt template, and almost 100x faster than ERB from the Ruby standard
-library. Run `ruby spec/benchmarks.rb` to see what to expect in your env.
+Run `ruby spec/benchmarks.rb` to see what to expect in your environment. These
+results are from a 2015 iMac:
 
 ```
 $ ruby spec/benchmarks.rb
 Warming up --------------------------------------
-     Ruby stdlib ERB     2.807k i/100ms
-       Tilt (cached)    28.611k i/100ms
-              Lambda   249.958k i/100ms
-           Component   161.176k i/100ms
-Component [memoized]    94.586k i/100ms
+          stdlib ERB     2.682k i/100ms
+            Tilt ERB    15.958k i/100ms
+         Bare lambda    77.124k i/100ms
+     RC [def render]    64.905k i/100ms
+      RC [render do]    57.725k i/100ms
+    RC [render erb:]    15.595k i/100ms
 Calculating -------------------------------------
-     Ruby stdlib ERB     29.296k (± 2.0%) i/s -    148.771k in   5.080274s
-       Tilt (cached)    319.935k (± 2.8%) i/s -      1.602M in   5.012009s
-              Lambda      6.261M (± 1.2%) i/s -     31.495M in   5.031302s
-           Component      2.773M (± 1.8%) i/s -     14.022M in   5.057528s
-Component [memoized]      1.276M (± 0.9%) i/s -      6.432M in   5.041348s
+          stdlib ERB     27.423k (± 1.8%) i/s -    139.464k in   5.087391s
+            Tilt ERB    169.351k (± 2.2%) i/s -    861.732k in   5.090920s
+         Bare lambda    929.473k (± 3.0%) i/s -      4.705M in   5.065991s
+     RC [def render]    775.176k (± 1.1%) i/s -      3.894M in   5.024347s
+      RC [render do]    686.653k (± 2.3%) i/s -      3.464M in   5.046728s
+    RC [render erb:]    165.113k (± 1.7%) i/s -    826.535k in   5.007444s
 ```
 
-Notice that using `Component#memoized` is _slower_ than using `Component#call`
-in this benchmark. Because these components do almost nothing, it's more work to
-check the memoziation cache than to just render. For components that don't
-access a database, don't do network I/O, and aren't very CPU-intensive, it's
-probably fastest not to memoize. For components that do I/O, using `#memoize`
-can speed things up by several orders of magnitude.
+Every component in the benchmark is configured to escape HTML when rendering.
+When rendering via a block, Rack::Component is about 25x faster than ERB and 4x
+faster than Tilt. When rendering a template via Tilt, it (unsurprisingly)
+performs roughly at tilt-speed.
 
 ## Compatibility
 
-Rack::Component has zero dependencies, and will work in any Rack app. It should
-even work _outside_ a Rack app, because it's not actually dependent on Rack. I
-packaged it under the Rack namespace because it follows the Rack `call`
-specification, and because that's where I use and test it.
+When not rendering Tilt templates, Rack::Component has zero dependencies,
+and will work in any Rack app. It should even work _outside_ a Rack app, because
+it's not actually dependent on Rack. I packaged it under the Rack namespace
+because it follows the Rack `call` specification, and because that's where I
+use and test it.
+
+When using Tilt templates, you will need `tilt` and a templating gem in your
+`Gemfile`:
+
+```ruby
+gem 'tilt'
+gem 'erubi' # or gem 'haml', etc
+gem 'rack-component'
+```
 
 ## Anybody using this in production?
 
 Aye:
 
-- [future.com](https://www.future.com/)
-- [Seattle & King County Homelessness Response System](https://hrs.kc.future.com/)
+* [future.com](https://www.future.com/)
+* [Seattle & King County Homelessness Response System](https://hrs.kc.future.com/)
 
 ## Ruby reference
 
 Where React uses [JSX] to make components more ergonomic, Rack::Component leans
 heavily on some features built into the Ruby language, specifically:
 
-- [Heredocs]
-- [String Interpolation]
-- [Calling methods with a block][ruby blocks]
+* [Heredocs]
+* [String Interpolation]
+* [Calling methods with a block][ruby blocks]
 
 ## Development
 
@@ -426,3 +485,4 @@ MIT
 [ruby blocks]: https://mixandgo.com/learn/mastering-ruby-blocks-in-less-than-5-minutes
 [roda]: http://roda.jeremyevans.net
 [sinatra]: http://sinatrarb.com
+[tilt]: https://github.com/rtomayko/tilt

data/lib/rack/component.rb

@@ -1,131 +1,86 @@
 require_relative 'component/version'
-require_relative 'component/memory_cache'
+require_relative 'component/renderer'
 require 'cgi'
 
 module Rack
   # Subclass Rack::Component to compose functional, declarative responses to
   # HTTP requests.
+  # @example Subclass Rack::Component to compose functional, declarative
+  # responses to HTTP requests.
+  #   class Greeter < Rack::Component
+  #     render { "Hi, #{env[:name]" }
+  #   end
   class Component
-    class << self
-      # Instantiate a new component with given +env+ return its rendered output.
-      # @example Render a child block inside an HTML document
-      #   class Layout < Rack::Component
-      #     render do |env, &child|
-      #       <<~HTML
-      #         <!DOCTYPE html>
-      #         <html>
-      #           <head>
-      #             <title>#{env[:title]}</title>
-      #           </head>
-      #           <body>#{child.call}</body>
-      #         </html>
-      #       HTML
-      #     end
-      #   end
-      #
-      #   Layout.call(title: 'Hello') { "<h1>Hello from Rack::Component" } #=>
-      #   # <!DOCTYPE html>
-      #   # <html>
-      #   #   <head>
-      #   #     <title>Hello</title>
-      #   #   </head>
-      #   #   <body><h1>Hello from Rack::Component</h1></body>
-      #   # </html>
-      def call(env = {}, &child)
-        new(env).call env, &child
+    # @example If you don't want to subclass, you can extend
+    # Rack::Component::Methods instead.
+    #   class POROGreeter
+    #     extend Rack::Component::Methods
+    #     render { "Hi, #{env[:name]" }
+    #   end
+    module Methods
+      def self.extended(base)
+        base.include(InstanceMethods)
       end
 
-      # Use +memoized+ instead of +call+ to memoize the result of +call(env)+
-      # and return it. Subsequent uses of +memoized(env)+ with the same +env+
-      # will be read from a threadsafe in-memory cache, not computed.
-      # @example Cache a slow network call
-      #   class Fetcher < Rack::Component
-      #     render do |env|
-      #       Net::HTTP.get(env[:uri]).to_json
-      #     end
-      #   end
-      #
-      #   Fetcher.memoized(uri: '/slow/api.json')
-      #   # ...
-      #   # many seconds later...
-      #   # => { some: "data" }
-      #
-      #   Fetcher.memoized(uri: '/slow/api.json') #=> instant! { some: "data" }
-      #   Fetcher.memoized(uri: '/other/source.json') #=> slow again!
-      def memoized(env = {}, &child)
-        cache.fetch(env.hash) { call(env, &child) }
+      def render(opts = {})
+        block_given? ? configure_block(Proc.new) : configure_template(opts)
       end
 
-      # Forget all memoized calls to this component.
-      def flush
-        cache.flush
+      def call(env = {}, &children)
+        new(env).render(&children)
       end
 
-      # Use a +render+ block define what a component will do when you +call+ it.
-      # @example Say hello
-      #   class Greeter < Rack::Component
-      #     render do |env|
-      #       "Hi, #{env[:name]}"
-      #     end
-      #   end
-      #
-      #   Greeter.call(name: 'Jim') #=> 'Hi, Jim'
-      #   Greeter.call(name: 'Bones') #=> 'Hi, Bones'
-      def render(&block)
-        define_method :call, &block
-      end
+      # Instances of Rack::Component come with these methods.
+      # :reek:ModuleInitialize
+      module InstanceMethods
+        # +env+ is Rack::Component's version of React's +props+ hash.
+        def initialize(env)
+          @env = env
+        end
+
+        # +env+ can be an empty hash, but cannot be nil
+        # @return [Hash]
+        def env
+          @env || {}
+        end
 
-      # Find or initialize a cache store for a Component class.
-      # With no configuration, the store is a threadsafe in-memory cache, capped
-      # at 100 keys in length to avoid leaking RAM.
-      # @example Use a larger cache instead
-      #   class BigComponent < Rack::Component
-      #     cache { MemoryCache.new(length: 2000) }
-      #   end
-      def cache
-        @cache ||= (block_given? ? yield : MemoryCache.new(length: 100))
+        # +h+ removes HTML characters from strings via +CGI.escapeHTML+.
+        # @return [String]
+        def h(obj)
+          CGI.escapeHTML(obj.to_s)
+        end
       end
-    end
 
-    def initialize(env = {})
-      @env = env
-    end
+      private
 
-    # Out of the box, a +Rack::Component+ just returns whatever +env+ you call
-    # it with, or yields with +env+ if you call it with a block.
-    # Use a class-level +render+ block when wiriting your Components to override
-    # this method with more useful behavior.
-    # @see Rack::Component#render
-    #
-    # @example a useless component
-    #   Useless = Class.new(Rack::Component)
-    #   Useless.call(number: 1) #=> { number: 1 }
-    #   Useless.call(number: 2) #=> { number: 2 }
-    #   Useless.call(number: 2) { |env| "the number was #{env[:number]" }
-    #   #=> 'the number was 2'
-    #
-    # @example a useful component
-    #   class Greeter < Rack::Component
-    #     render do |env|
-    #       "Hi, #{env[:name]}"
-    #     end
-    #   end
-    #
-    #   Greeter.call(name: 'Jim') #=> 'Hi, Jim'
-    #   Greeter.call(name: 'Bones') #=> 'Hi, Bones'
-    def call(*)
-      block_given? ? yield(env) : env
-    end
+      # :reek:TooManyStatements
+      # :reek:DuplicateMethodCall
+      def configure_block(block)
+        # Convert the block to an instance method, because instance_exec
+        # doesn't allow passing an &child param, and because it's faster.
+        define_method :_rc_render, &block
+        private :_rc_render
 
-    attr_reader :env
+        # Now that the block is a method, it must be called with the correct
+        # number of arguments. Ruby's +arity+ method is unreliable when keyword
+        # args are involved, so we count arity by hand.
+        arity = block.parameters.reject { |type, _| type == :block }.length
 
-    # @example Strip HTML entities from a string
-    #   class SafeComponent < Rack::Component
-    #     render { |env| h(env[:name]) }
-    #   end
-    #   SafeComponent.call(name: '<h1>hi</h1>') #=> &lt;h1&gt;hi&lt;/h1&gt;
-    def h(obj)
-      CGI.escapeHTML(obj.to_s)
+        # Reek hates this DuplicateMethodCall, but fixing it would mean checking
+        # arity at runtime, rather than when the render macro is called.
+        if arity.zero?
+          define_method(:render) { |&child| _rc_render(&child) }
+        else
+          define_method(:render) { |&child| _rc_render(env, &child) }
+        end
+      end
+
+      def configure_template(options)
+        renderer = Renderer.new(options)
+        define_method(:render) { |&child| renderer.call(self, &child) }
+      end
     end
+
+    extend Methods
   end
 end

data/lib/rack/component/renderer.rb

@@ -0,0 +1,31 @@
+module Rack
+  class Component
+    # Compile a Tilt template, which a component will render
+    class Renderer
+      DEFAULT_TILT_OPTIONS = { escape_html: true }.freeze
+      FORMATS = %i[erb rhtml erubis haml liquid markdown md mkd].freeze
+
+      def initialize(options = {})
+        require 'tilt'
+        engine, template, @config = OptionParser.call(options)
+        require 'erubi' if engine == 'erb' && @config[:escape_html]
+        @template = Tilt[engine].new(@config) { template }
+      end
+
+      def call(scope, &child)
+        @template.render(scope, &child)
+      end
+
+      OptionParser = lambda do |opts|
+        tilt_options = DEFAULT_TILT_OPTIONS.merge(opts.delete(:opts) || {})
+        engine, template =
+          opts.find { |key, _| FORMATS.include?(key) } ||
+          [opts[:engine], opts[:template]]
+
+        [engine.to_s, template, tilt_options]
+      end
+
+      private_constant :OptionParser
+    end
+  end
+end

data/lib/rack/component/version.rb

@@ -1,5 +1,5 @@
 module Rack
   class Component
-    VERSION = '0.4.2'.freeze
+    VERSION = '0.5.0'.freeze
   end
 end

data/rack-component.gemspec

@@ -30,10 +30,13 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = '>= 2.2'
+  spec.required_ruby_version = '>= 2.3'
 
   spec.add_development_dependency 'benchmark-ips', '~> 2.7'
-  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'bundler', '~> 2'
+  spec.add_development_dependency 'erubi', '~> 1.8'
+  spec.add_development_dependency 'haml', '~> 5'
+  spec.add_development_dependency 'liquid', '~> 4'
   spec.add_development_dependency 'pry', '~> 0.11'
   spec.add_development_dependency 'rack', '~> 2.0.6'
   spec.add_development_dependency 'rack-test', '~> 0'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rack-component
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Chris Frank
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-04 00:00:00.000000000 Z
+date: 2019-01-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
@@ -30,14 +30,56 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: erubi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: haml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: liquid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -176,6 +218,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - README.md
@@ -184,6 +227,7 @@ files:
 - bin/setup
 - lib/rack/component.rb
 - lib/rack/component/memory_cache.rb
+- lib/rack/component/renderer.rb
 - lib/rack/component/version.rb
 - rack-component.gemspec
 homepage: https://www.github.com/chrisfrank/rack-component
@@ -199,7 +243,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.2'
+      version: '2.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="