papercraft 1.0 → 1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d769e6ec71d8c6d60ebb0aa727037b691562a31ec1fc1a05ccb0f25f29858b7a
-  data.tar.gz: 97b15299e8b4ca3d801aec881bd0ea4cee245650225f9c6e41972333ab9f8011
+  metadata.gz: 41c765213957fc2681e2f4cd7d94e7580e45394128d61a800349aa6e848c6b00
+  data.tar.gz: 5c2b0a91c3d4c744db20536d08ae741a07dab3a9cfc2c5fa790ea987224b5c7e
 SHA512:
-  metadata.gz: ff74adc23fc616b579f9729cecc595e2eebe92d2b96b6edcceff4eae043c7ca8048e3baea14f275533667809183cd7961e14c74a6afb71b04fe7902806c8678c
-  data.tar.gz: 8fcecbac3baa12296ae3386ecb31eb0db0d7e001f4f38dd1c055ab497a3113471338d26cca8812582091e10c17ab5413c1e37cdf172d07ca1eac011206935d90
+  metadata.gz: cf87f3ae1bcf718ad7b03e5b1b895cd8065e2aee72f7044cf0fb822db029477aa98297b8caf66d9e3db1ee664d9e42a954afb203f856fa6f190765defe5139e1
+  data.tar.gz: bfd2847daa9f2d9be7a0aa7e0adee170771e3fcdd6ca0ad407478f7b5bff2848b63639d21c26d1b9d040ac44b741d9032ac24742e839e19f1327d81ffd88e901

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.1 2023-07-03
+
+- Add direct iteration using the `_for` attribute
+
 ## 1.0 2023-03-30
 
 - Add support for Array attribute values

data/README.md

@@ -24,7 +24,8 @@
 
 ## What is Papercraft?
 
-Papercraft is a templating engine for dynamically producing HTML, XML or JSON.
+Papercraft is a templating engine for dynamically producing
+[HTML](#html-templates), [XML](#xml-templates) or [JSON](#json-templates).
 Papercraft templates are expressed in plain Ruby, leading to easier debugging,
 better protection against HTML/XML injection attacks, and better code reuse.
 
@@ -71,6 +72,7 @@ hello.render('world')
 - [Adding Tags](#adding-tags)
 - [Tag and Attribute Formatting](#tag-and-attribute-formatting)
 - [Escaping Content](#escaping-content)
+- [Direct Iteration][#direct-iteration]
 - [Template Parameters](#template-parameters)
 - [Template Logic](#template-logic)
 - [Template Blocks](#template-blocks)
@@ -130,7 +132,7 @@ html.render #=> "<div id="greeter"><p>Hello!</p></div>"
 
 ## Using with Tilt
 
-Papercraft templates can also be rendered using Tilt:
+Papercraft templates can also be rendered using [Tilt](https://github.com/jeremyevans/tilt):
 
 ```ruby
 require 'tilt/papercraft'
@@ -271,6 +273,66 @@ below](#emitting-raw-html).
 JSON templates are rendered using the `json` gem bundled with Ruby, which takes
 care of escaping text values.
 
+## Direct Iteration
+
+Papercraft enables iterating directly  over any enumerable data source. Instead
+of rendering each item in a given data container by wrapping it inside of an
+`#each` block, we can simply pass the data source *directly* to the tag using
+the `_for` attribute. This is particularly useful when we need to create a set
+of nested tags for each item. Consider the following example:
+
+```ruby
+data = %w{foo bar}
+
+Papercraft.html {
+  data.each { |item|
+    tr {
+      td item
+    }
+  }
+}.render #=> '<tr><td>foo</td></tr><tr><td>bar</td></tr>'
+```
+
+Instead of using `data.each` to iterate over the list of data, we can directly
+pass the data source to the `tr` tag using the special `_for` attribute:
+
+```ruby
+Papercraft.html {
+  tr(_for: data) { |item|
+    td item
+  }
+}.render #=> '<tr><td>foo</td></tr><tr><td>bar</td></tr>'
+```
+
+Note that this will work with any data source that is an `Enumerable` or an
+`Enumerator`. For example, you can use `#each_with_index` or iterate over a
+hash. Papercraft will pass all yielded values to the given block:
+
+```ruby
+data = %{foo bar}
+Papercraft.html {
+  tr(_for: data.each_with_index) { |item, idx|
+    td idx + 1
+    td item
+  }
+}.render #=> '<tr><td>1</td><td>foo</td></tr><tr><td>2</td><td>bar</td></tr>'
+
+data = [
+  { name: 'foo', age: 16 },
+  { name: 'bar', age: 32 }
+]
+Papercraft.html {
+  div(_for: data, class: 'row') { |row|
+    div(_for: row) { |k, v|
+      span k
+      span v
+    }
+  }
+}.render
+#=> '<div class="row"><div><span>name</span><span>foo</span></div><div><span>age</span><span>16</span></div></div>'
+#=> '<div class="row"><div><span>name</span><span>bar</span></div><div><span>age</span><span>32</span></div></div>'
+```
+
 ## Template Parameters
 
 In Papercraft, parameters are always passed explicitly. This means that template

data/lib/papercraft/extension_proxy.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Papercraft
-  
+
   # An ExtensionProxy proxies method calls to a renderer. Extension proxies are
   # used to provide an namespaced interface to Papercraft extensions. When an
   # extension is installed using `Papercraft.extension`, a corresponding method
@@ -18,7 +18,7 @@ module Papercraft
       @renderer = renderer
       extend(mod)
     end
-  
+
     # Proxies missing methods to the renderer.
     #
     # @param sym [Symbol] method name

data/lib/papercraft/html.rb

@@ -2,7 +2,7 @@
 
 require_relative './tags'
 
-module Papercraft  
+module Papercraft
   # HTML Markup extensions
   module HTML
     include Tags
@@ -55,7 +55,7 @@ module Papercraft
 
       @buffer << '>' << css << '</style>'
     end
-  
+
     # Emits an inline JS script element.
     #
     # @param js [String, nil] Javascript code
@@ -82,8 +82,8 @@ module Papercraft
       fn = File.join(root_path, href)
       version = File.stat(fn).mtime.to_i rescue 0
       "#{root_url}/#{href}?v=#{version}"
-    end  
-  
+    end
+
     # Emits an import map scrit tag. If a hash is given, emits the hash as is.
     # If a string is given, searches for all *.js files under the given path,
     # and emits an import map including all found files, with versioned URLs.
@@ -135,7 +135,7 @@ module Papercraft
     # @return [Bool] is it a void element
     def is_void_element_tag?(tag)
       case tag
-      # 
+      #
       when 'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr'
         true
       else

data/lib/papercraft/json.rb

@@ -2,7 +2,7 @@
 
 require 'json'
 
-module Papercraft  
+module Papercraft
   # JSON renderer extensions
   module JSON
     # Initializes a JSON renderer, setting up an object stack.
@@ -18,7 +18,9 @@ module Papercraft
     # @param value [Object] item
     # @param &block [Proc] template block
     # @return [void]
-    def item(value = nil, &block)
+    def item(value = nil, _for: nil, &block)
+      return _for.each { |*a| item(value) { block.(*a)} } if _for
+
       verify_array_target
       if block
         value = enter_object(&block)
@@ -121,6 +123,6 @@ module Papercraft
       @object_stack << nil
       instance_eval(&block)
       @object_stack.pop
-    end    
+    end
   end
 end

data/lib/papercraft/renderer.rb

@@ -6,7 +6,7 @@ require_relative './json'
 require_relative './extension_proxy'
 
 module Papercraft
-  
+
   # A Renderer renders a Papercraft template into a string
   class Renderer
 
@@ -46,7 +46,7 @@ module Papercraft
       # the the renderer instance, so they can look just like normal proc
       # components. In cases where method names in the module clash with XML
       # tag names, you can use the `#tag` method to emit the relevant tag.
-      # 
+      #
       #   module ComponentLibrary
       #     def card(title, content)
       #       div(class: 'card') {
@@ -96,9 +96,9 @@ module Papercraft
     #
     #   greeter = proc { |name| h1 "Hello, #{name}!" }
     #   Papercraft.html { emit(greeter, 'world') }.render #=> "<h1>Hello, world!</h1>"
-    #   
+    #
     #   Papercraft.html { emit 'hi&<bye>' }.render #=> "hi&<bye>"
-    #   
+    #
     #   Papercraft.html { emit nil }.render #=> ""
     #
     # @param o [Proc, Papercraft::Template, String] emitted object
@@ -131,10 +131,10 @@ module Papercraft
     def emit_yield(*a, **b)
       block = @emit_yield_stack&.pop
       raise Papercraft::Error, "No block given" unless block
-      
+
       instance_exec(*a, **b, &block)
     end
-    
+
     private
 
     # Pushes the given block onto the emit_yield stack.

data/lib/papercraft/tags.rb

@@ -2,7 +2,7 @@
 
 require_relative './extension_proxy'
 
-module Papercraft  
+module Papercraft
   # Markup (HTML/XML) extensions
   module Tags
     S_LT              = '<'
@@ -22,7 +22,9 @@ module Papercraft
       S_TAG_%<TAG>s_PRE = %<tag_pre>s
       S_TAG_%<TAG>s_CLOSE = %<tag_close>s
 
-      def %<tag>s(text = nil, **props, &block)
+      def %<tag>s(text = nil, _for: nil, **props, &block)
+        return _for.each { |*a| %<tag>s(text, **props) { block.(*a)} } if _for
+
         if text.is_a?(Hash) && props.empty?
           props = text
           text = nil
@@ -52,7 +54,9 @@ module Papercraft
       S_TAG_%<TAG>s_PRE = %<tag_pre>s
       S_TAG_%<TAG>s_CLOSE = %<tag_close>s
 
-      def %<tag>s(text = nil, **props, &block)
+      def %<tag>s(text = nil, _for: nil, **props, &block)
+        return _for.each { |*a| %<tag>s(text, **props) { block.(*a)} } if _for
+
         if text.is_a?(Hash) && props.empty?
           props = text
           text = nil
@@ -141,8 +145,8 @@ module Papercraft
       end
       @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
     end
-    
-    
+
+
     # Emits an XML tag with the given content, properties and optional block.
     # This method is an alternative to emitting XML tags using dynamically
     # created methods. This is particularly useful when using extensions that
@@ -159,7 +163,9 @@ module Papercraft
     # @param **props [Hash] tag attributes
     # @param &block [Proc] optional inner XML
     # @return [void]
-    def tag(sym, text = nil, **props, &block)
+    def tag(sym, text = nil, _for: nil, **props, &block)
+      return _for.each { |*a| tag(sym, text, **props) { block.(*a)} } if _for
+
       if text.is_a?(Hash) && props.empty?
         props = text
         text = nil
@@ -337,7 +343,7 @@ module Papercraft
     # @return [void]
     def render_deferred_proc(&block)
       old_buffer = @buffer
-      
+
       @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
       @parts = nil
 

data/lib/papercraft/template.rb

@@ -85,7 +85,7 @@ module Papercraft
   #   links_with_anchors.render
   #
   class Template < Proc
-    
+
     # Determines the rendering mode: `:html` or `:xml`.
     attr_accessor :mode
 
@@ -107,9 +107,9 @@ module Papercraft
       @mime_type = mime_type || STOCK_MIME_TYPE[mode]
       super(&block)
     end
-  
+
     H_EMPTY = {}.freeze
-  
+
     # Renders the template with the given parameters and or block, and returns
     # the string result.
     #
@@ -123,7 +123,7 @@ module Papercraft
         instance_exec(*a, **b, &template)
       end.to_s
     end
-  
+
     # Creates a new template, applying the given parameters and or block to the
     # current one. Application is one of the principal methods of composing
     # templates, particularly when passing inner templates as blocks:
@@ -149,7 +149,7 @@ module Papercraft
         instance_exec(*a, *x, **b, **y, &template)
       end)
     end
-  
+
     # Returns the Renderer class used for rendering the templates, according to
     # the template's mode.
     #
@@ -173,7 +173,7 @@ module Papercraft
     def mime_type
       @mime_type
     end
-  
+
     # def compile
     #   Papercraft::Compiler.new.compile(self)
     # end

data/lib/papercraft/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Papercraft
-  VERSION = '1.0'
+  VERSION = '1.1'
 end

data/lib/papercraft/xml.rb

@@ -3,7 +3,7 @@
 require 'escape_utils'
 require_relative './tags'
 
-module Papercraft  
+module Papercraft
   # XML renderer extensions
   module XML
     include Tags

data/lib/papercraft.rb

@@ -13,9 +13,9 @@ require_relative 'papercraft/renderer'
 module Papercraft
   # Exception class used to signal templating-related errors
   class Error < RuntimeError; end
-  
+
   class << self
-    
+
     # Installs one or more extensions. Extensions enhance templating capabilities
     # by adding namespaced methods to emplates. An extension is implemented as a
     # Ruby module containing one or more methods. Each method in the extension
@@ -29,7 +29,7 @@ module Papercraft
     def extension(map)
       Renderer.extension(map)
     end
-    
+
     # Creates a new papercraft template. `Papercraft.html` can take either a proc
     # argument or a block. In both cases, the proc is converted to a
     # `Papercraft::Template`.
@@ -44,7 +44,7 @@ module Papercraft
       template ||= o
       Papercraft::Template.new(mode: :html, mime_type: mime_type, &template)
     end
-    
+
     # Creates a new Papercraft template in XML mode. `Papercraft.xml` can take
     # either a proc argument or a block. In both cases, the proc is converted to a
     # `Papercraft::Template`.
@@ -59,7 +59,7 @@ module Papercraft
       template ||= o
       Papercraft::Template.new(mode: :xml, mime_type: mime_type, &template)
     end
-    
+
     # Creates a new Papercraft template in JSON mode. `Papercraft.json` can take
     # either a proc argument or a block. In both cases, the proc is converted to a
     # `Papercraft::Template`.
@@ -85,7 +85,7 @@ module Papercraft
       opts = default_kramdown_options.merge(opts)
       Kramdown::Document.new(markdown, **opts).to_html
     end
-    
+
     # Returns the default Kramdown options used for rendering Markdown.
     #
     # @return [Hash] Kramdown options
@@ -94,7 +94,7 @@ module Papercraft
         entity_output: :numeric,
         syntax_highlighter: :rouge,
         input: 'GFM',
-        hard_wrap: false  
+        hard_wrap: false
       }
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '1.0'
+  version: '1.1'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-03-30 00:00:00.000000000 Z
+date: 2023-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils