rubyoshka 0.2 → 0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff842a3a48141bcef19e1298cb26ff59cd9dbb0a58075efe50b3f73892a75c2f
-  data.tar.gz: 4556f2fc468d48d9a98b4582ab25f0068d814d933e0e0c198d45fce9f692960b
+  metadata.gz: 3be682087384cd706b089c77e53334d5e60923106e3fa514bdb298c73aae64fc
+  data.tar.gz: 6efb14adab373708f4a171ed8b07b22b535a71fe05874d26e75f7147f3eefbc0
 SHA512:
-  metadata.gz: 79e2fd4e9f970201191e576f1b4bd971bef99cd1a7fbcbaee2102d6be8b8e0ec59e6ad0d26f6770ba756bd2e7b92ab84128a6bded62219417af94e1f9dbce159
-  data.tar.gz: 9d78ee6402ddc3e873d7b47073c655cb6501c46f91e8f4f6bb2041581367ee7cc5c661cc63e6f356e17a8d9cab59f9cf719e4497166f3fa890b4b320c62473c0
+  metadata.gz: '002368e44d062f4eeb02f8ef33a5eb09ead01b48895bc4fd1b899e88ab99da80ccc3c7a193c814d0b97ac0766245c39dbf1b2ccda96702c58090dc7106442ea5'
+  data.tar.gz: ea84ebb4e043e76ce51d6916d5b814116d6d5dc2ba2c781150e43c052d55c2ef611c8c2444316765a4f20e6798fb474452ab5623fbc221568949e0ca44317788

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+0.3 2019-01-13
+--------------
+
+* Implement caching
+* Improve performance
+* Handle attributes with `false` value correctly
+
 0.2 2019-01-07
 --------------
 

data/README.md

@@ -3,7 +3,7 @@
 [INSTALL](#installing-rubyoshka) |
 [TUTORIAL](#getting-started) |
 [EXAMPLES](examples) |
-[REFERENCE](reference)
+[REFERENCE](#api-reference)
 
 ## What is Rubyoshka
 
@@ -16,19 +16,27 @@ features:
 - Use global and local contexts to pass values to reusable components
 - Automatic HTML escaping
 - Composable nested components
-- Access to a global context from anywhere in the component hierarchy
-- About 4 times faster than ERubis (see [benchmark](examples/perf.rb)).
 
 > **Note** Rubyoshka is a new library and as such may be missing features and
-> contain bugs. Your issue reports and code conributions are most welcome!
+> contain bugs. Also, its API may change unexpectedly. Your issue reports and
+> code contributions are most welcome!
 
 With Rubyoshka you can structure your templates like a Russian doll, each
 component containing any number of nested components, in a somewhat similar
-fashion to React. The name *Rubyoshka* is a nod to Matryoshka, the Russian
+fashion to React. The name *Rubyoshka* is a nod to 
+[Matryoshka](https://en.wikipedia.org/wiki/Matryoshka_doll), the Russian
 nesting doll.
 
 ## Installing Rubyoshka
 
+Using bundler:
+
+```ruby
+gem 'polyphony'
+```
+
+Or manually:
+
 ```bash
 $ gem install polyphony
 ```
@@ -265,6 +273,54 @@ H {
 }
 ```
 
+## Fragment caching
+
+Any part of a Rubyoshka template can be cached - a fragment, a component, or a
+whole template. It is up to you, the user, to determine which parts of the 
+template to cache. By default, a call to `#cache` creates a cache entry based on
+the source location of the cached block:
+
+```ruby
+Head = H {
+  cache {
+    head {
+      title 'My app'
+      style "@import '/app.css';"
+    }
+  }
+}
+```
+
+However, if your template references local or global variables, you'll want to
+take those into account when caching. This is done by passing any variables used
+in the template to `#cache` in order to create separate cache entries for each
+discrete value or combination of values:
+
+```ruby
+Greeting = H {
+  cache(name) {
+    div {
+      span "Hello, #{name}"
+    }
+  }
+}
+
+names = %w{tommy dolly world}
+App = H {
+  names.each { |n| Greeting(name: n) }
+}
+```
+
+In the above example a separate cache entry will be created for each name. The 
+use of caching in components is especially beneficial since components may be 
+reused in multiple different templates in your app.
+
+### Changing the cache store
+
+Rubyoshka ships with a naïve in-memory cache store built-in. You can use
+another cache store by overriding the `Rubyoshka.cache_get` and
+`Rubyoshka.cache_set` methods (see API [reference](#api-reference)).
+
 ## Wrapping arbitrary HTML with a component
 
 Components can also be used to wrap arbitrary HTML with addional markup. This is
@@ -347,7 +403,37 @@ Blog = H {
 }
 ```
 
-## Reference
+### A higher-order list component
+
+Here's another demonstration of a higher-order component, a list component that
+takes an item component as an argument. The `List` component can be reused for
+rendering any kind of unordered list, and with any kind of item component:
+
+```ruby
+List = ->(items, item_component) {
+  H {
+    ul {
+      items.each { |item|
+        with(item: item) { 
+          li { emit item_component }
+        }
+      }
+    }
+  }
+}
+
+TodoItem = H {
+  span item.text, class: item.completed ? 'completed' : 'pending'
+}
+
+def todo_list(items)
+  H {
+    div { List(items, TodoItem) }
+  }
+end
+```
+
+## API Reference
 
 #### `Rubyoshka#initialize(**context, &block)` a.k.a. `Kernel#H`
 
@@ -379,6 +465,17 @@ an upper-case letter, it is considered a [component](#templates-as-components).
 
 If a text argument is given for a tag, it will be escaped.
 
+#### `#cache(*vary, &block)`
+
+- `vary`: variables used in cached block. The given values will be used to
+  create a separate cache entry.
+- `block`: inner HTML block
+
+Caches the markup in the given block, storing it in the Rubyoshka cache store.
+If a cache entry for the given block is found, it will be used instead of
+invoking the block. If one or more variables given, those will be used to create
+a separate cache entry.
+
 #### `#context`
 
 Accesses the [global context](#global-context).
@@ -409,3 +506,31 @@ Adds text without wrapping it in a tag. The text will be escaped.
 
 Sets a [local context](#local-context) for use inside the given block. The
 previous local context will be restored upon exiting the given block.
+
+#### `Rubyoshka.cache`
+
+Returns the cache store. A cache store should implement two methods - `#[]` and
+`#[]=`. Here's an example implementing a Redis-based cache store:
+
+```ruby
+class RedisTemplateCache
+  def initialize(conn, prefix)
+    @conn = conn
+    @prefix = prefix
+  end
+
+  def [](key)
+    @conn.get("#{prefix}:#{key}")
+  end
+
+  def []=(key, value)
+    @conn.set("#{prefix}:#{key}", value)
+  end
+end
+
+TEMPLATE_CACHE = RedisTemplaceCache.new(redis_conn, "templates:cache")
+
+def Rubyoshka.cache
+  TEMPLATE_CACHE
+end
+```

data/lib/rubyoshka.rb

@@ -26,10 +26,30 @@ class Rubyoshka
     def to_s
       @buffer
     end
+
+    E = EscapeUtils
   
     S_TAG_METHOD = <<~EOF
-      def %1$s(*args, &block)
-        tag(:%1$s, *args, &block)
+      S_TAG_%<TAG>s_PRE = '<%<tag>s'
+      S_TAG_%<TAG>s_CLOSE = '</%<tag>s>'
+      
+      def %<tag>s(text = nil, **props, &block)
+        @buffer << S_TAG_%<TAG>s_PRE
+        emit_props(props) unless props.empty?
+      
+        if block
+          @buffer << S_GT
+          instance_eval(&block)
+          @buffer << S_TAG_%<TAG>s_CLOSE
+        elsif Rubyoshka === text
+          @buffer << S_GT
+          emit(text)
+          @buffer << S_TAG_%<TAG>s_CLOSE
+        elsif text
+          @buffer << S_GT << E.escape_html(text.to_s) << S_TAG_%<TAG>s_CLOSE
+        else
+          @buffer << S_SLASH_GT
+        end
       end
     EOF
 
@@ -65,8 +85,9 @@ class Rubyoshka
           raise e
         end
       else
-        self.class.class_eval(S_TAG_METHOD % sym)
-        tag(sym, *args, &block)
+        tag = sym.to_s
+        self.class.class_eval(S_TAG_METHOD % { tag: tag, TAG: tag.upcase })
+        send(sym, *args, &block)
       end
     end
   
@@ -95,49 +116,21 @@ class Rubyoshka
     S_EQUAL_QUOTE     = '="'
     S_QUOTE           = '"'
 
-    E = EscapeUtils
-  
-    # Emits an HTML tag
-    # @param sym [Symbol] HTML tag
-    # @param text [String] text content of tag
-    # @param props [Hash] tag attributes
-    # @param block [Proc] nested HTML block
-    # @return [void]
-    def tag(sym, text = nil, **props, &block)
-      sym = sym.to_s
-  
-      @buffer << S_LT << sym
-      emit_props(props) unless props.empty?
-  
-      if block
-        @buffer << S_GT
-        instance_eval(&block)
-        @buffer << S_LT_SLASH << sym << S_GT
-      elsif Rubyoshka === text
-        @buffer << S_GT
-        emit(text)
-        @buffer << S_LT_SLASH << sym << S_GT
-      elsif text
-        @buffer << S_GT << E.escape_html(text.to_s) <<
-          S_LT_SLASH << sym << S_GT
-      else
-        @buffer << S_SLASH_GT
-      end
-    end
-
     # Emits tag attributes into the rendering buffer
     # @param props [Hash] tag attributes
     # @return [void]
     def emit_props(props)
       props.each { |k, v|
         case k
-        when :text
         when :src, :href
           @buffer << S_SPACE << k.to_s << S_EQUAL_QUOTE <<
             E.escape_uri(v) << S_QUOTE
         else
-          if v == true
+          case v
+          when true
             @buffer << S_SPACE << k.to_s
+          when false, nil
+            # emit nothing
           else
             @buffer << S_SPACE << k.to_s << S_EQUAL_QUOTE << v << S_QUOTE
           end
@@ -151,7 +144,7 @@ class Rubyoshka
     # @para block [Proc] nested HTML block
     # @return [void]
     def p(text = nil, **props, &block)
-      tag(:p, text, **props, &block)
+      method_missing(:p, text, **props, &block)
     end
   
     S_HTML5_DOCTYPE = '<!DOCTYPE html>'
@@ -180,6 +173,24 @@ class Rubyoshka
     ensure
       @local = old_local
     end
+
+    # Caches the given block with the given arguments as cache key
+    # @param vary [*Object] cache key
+    # @param block [Proc] nested HTML block
+    # @return [void]
+    def cache(*vary, &block)
+      key = [block.source_location, *vary]
+
+      if (cached = Rubyoshka.cache[key])
+        @buffer << cached
+        return
+      end
+
+      cache_pos = @buffer.length
+      instance_eval(&block)
+      diff = @buffer[cache_pos..-1]
+      Rubyoshka.cache[key] = diff
+    end
   end
 
   attr_reader :block
@@ -192,12 +203,20 @@ class Rubyoshka
     @block = ctx.empty? ? block : proc { with(ctx, &block) }
   end
 
+  H_EMPTY = {}.freeze
+
   # Renders the associated block and returns the string result
   # @param context [Hash] context
   # @return [String]
-  def render(**context)
+  def render(context = H_EMPTY)
     Rendering.new(context, &block).to_s
   end
+
+  @@cache = {}
+
+  def self.cache
+    @@cache
+  end
 end
 
 module ::Kernel

data/lib/rubyoshka/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Rubyoshka
-  VERSION = '0.2'
+  VERSION = '0.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubyoshka
 version: !ruby/object:Gem::Version
-  version: '0.2'
+  version: '0.3'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-07 00:00:00.000000000 Z
+date: 2019-01-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: modulation
@@ -80,6 +80,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 2.7.0
+- !ruby/object:Gem::Dependency
+  name: tilt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.0.9
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.0.9
 description: 
 email: ciconia@gmail.com
 executables: []