papercraft 0.29 → 1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ca707074311c909d6e2b4aa86748f1ffbd5b614d73fb78e85985d174b69e263
-  data.tar.gz: f53dc4fa5088472ccc805f50938f25539950446fe14e97facb2cc346722d13fe
+  metadata.gz: 41c765213957fc2681e2f4cd7d94e7580e45394128d61a800349aa6e848c6b00
+  data.tar.gz: 5c2b0a91c3d4c744db20536d08ae741a07dab3a9cfc2c5fa790ea987224b5c7e
 SHA512:
-  metadata.gz: 0d216f2c8db4beed8c7fe184d3b8e0a13ba8af4684d4e46f5506f0b1eb6c3bfaa0ad76b7a5b1b6e28a8ba37a730545ca00139fd0bf35b74628d117c504fc1e9c
-  data.tar.gz: 27ac04cf8b75b5d6abda511513618fb6ef20417365ac7b45855d909323db3c536204f85d719a44e2374b095d955f4eb0c25901290990dab861c908fa4d73142e
+  metadata.gz: cf87f3ae1bcf718ad7b03e5b1b895cd8065e2aee72f7044cf0fb822db029477aa98297b8caf66d9e3db1ee664d9e42a954afb203f856fa6f190765defe5139e1
+  data.tar.gz: bfd2847daa9f2d9be7a0aa7e0adee170771e3fcdd6ca0ad407478f7b5bff2848b63639d21c26d1b9d040ac44b741d9032ac24742e839e19f1327d81ffd88e901

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 1.1 2023-07-03
+
+- Add direct iteration using the `_for` attribute
+
+## 1.0 2023-03-30
+
+- Add support for Array attribute values
+
 ## 0.29 2023-03-11
 
 - Add Tilt integration (#15)

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)
@@ -84,6 +86,7 @@ hello.render('world')
 - [Emitting Markdown](#emitting-markdown)
 - [Working with MIME Types](#working-with-mime-types)
 - [Deferred Evaluation](#deferred-evaluation)
+- [HTML Templates](#html-templates)
 - [XML Templates](#xml-templates)
 - [JSON Templates](#json-templates)
 - [Papercraft Extensions](#papercraft-extensions)
@@ -129,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'
@@ -198,14 +201,28 @@ Papercraft.html { hr() }.render #=> "<hr/>"
 Tag methods also accept tag attributes, given as a hash:
 
 ```ruby
-Papercraft.html { img src: '/my.gif' }.render #=> "<img src="/my.gif"/>
+Papercraft.html { img src: '/my.gif' }.render #=> "<img src=\"/my.gif\"/>"
 
 Papercraft.html { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</p>"
 ```
 
+A `true` attribute value will emit a valueless attribute. A `nil` or `false`
+attribute value will emit nothing:
+
+```ruby
+Papercraft.html { button disabled: nil }.render #=> "<button></button>"
+Papercraft.html { button disabled: true }.render #=> "<button disabled></button>"
+```
+
+An attribute value given as an array will be joined by space characters:
+
+```ruby
+Papercraft.html { div class: [:foo, :bar] }.render #=> "<div class=\"foo bar\"></div>"
+```
+
 ## Tag and Attribute Formatting
 
-Papercraft does not make any presumption about what tags and attributes you can
+Papercraft does not make any assumption about what tags and attributes you can
 use. You can mix upper and lower case letters, and you can include arbitrary
 characters in tag and attribute names. However, in order to best adhere to the
 HTML and XML specs and common practices, tag names and attributes will be
@@ -256,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
@@ -276,7 +353,7 @@ greeting.render(name: 'world') #=> "<h1>Hello, world!</h1>"
 
 ## Template Logic
 
-Since Papercraft templates are just a bunch of Ruby, you can easily write your
+Since Papercraft templates are just a bunch of Ruby, you can easily embed your
 view logic right in the template:
 
 ```ruby
@@ -585,6 +662,24 @@ page = default_layout.apply {
 }
 ```
 
+## HTML Templates
+
+HTML templates include a few HTML-specific methods to facilitate writing modern
+HTML:
+
+- `html5 { ... }` - emits an HTML 5 DOCTYPE (`<!DOCTYPE html>`)
+- `import_map(root_path, root_url)` - emits an import map including all files
+  matching `<root_path>/*.js`, based on the given `root_url`
+- `js_module(js)` - emits a `<script type="module">` element
+- `link_stylesheet(href, **attributes)` - emits a `<link rel="stylesheet" ...>`
+  element
+- `script(js, **attributes)` - emits an inline `<script>` element
+- `style(css, **attributes)` - emits an inline `<style>` element
+- `versioned_file_href(href, root_path, root_url)` - calculates a versioned href
+  for the given file
+
+[HTML docs](https://www.rubydoc.info/gems/papercraft/Papercraft/HTML)
+
 ## XML Templates
 
 XML templates behave largely the same as HTML templates, with a few minor
@@ -620,6 +715,8 @@ rss = Papercraft.xml(mime_type: 'text/xml; charset=utf-8') { |resource:, **props
 }
 ```
 
+[XML docs](https://www.rubydoc.info/gems/papercraft/Papercraft/XML)
+
 ## JSON Templates
 
 JSON templates behave largely the same as HTML and XML templates. The only major
@@ -651,6 +748,8 @@ Papercraft.json {
 Papercraft uses the [JSON gem](https://rubyapi.org/3.1/o/json) under the hood in
 order to generate actual JSON.
 
+[JSON docs](https://www.rubydoc.info/gems/papercraft/Papercraft/JSON)
+
 ## Papercraft Extensions
 
 Papercraft extensions are modules that contain one or more methods that can be
@@ -857,6 +956,8 @@ xml = Papercraft.xml {
 }
 ```
 
+[SOAP docs](https://www.rubydoc.info/gems/papercraft/Papercraft/Extensions/Soap)
+
 ## API Reference
 
 The API reference for this library can be found

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
 
@@ -387,6 +393,10 @@ module Papercraft
             @buffer << S_SPACE << att_repr(k)
           when false, nil
             # emit nothing
+          when Array
+            v = v.join(' ')
+            @buffer << S_SPACE << att_repr(k) <<
+              S_EQUAL_QUOTE << escape_text(v) << S_QUOTE
           else
             @buffer << S_SPACE << att_repr(k) <<
               S_EQUAL_QUOTE << escape_text(v) << S_QUOTE

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 = '0.29'
+  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: '0.29'
+  version: '1.1'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-03-11 00:00:00.000000000 Z
+date: 2023-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils