RubyGems - papercraft - Versions diffs - 0.15 → 0.16 - Mend

papercraft 0.15 → 0.16

Files changed (9) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +7 -1
data/README.md +66 -33
data/lib/papercraft/component.rb +30 -11
data/lib/papercraft/json.rb +73 -0
data/lib/papercraft/renderer.rb +11 -6
data/lib/papercraft/version.rb +1 -1
data/lib/papercraft.rb +29 -16
metadata +3 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2200153b1b339d33c7e9e81c45c23bd4c117c274a52b1d1bfc97f83995727697
-  data.tar.gz: 3dae3cf3b6ea2530df8c498cdafb876e06d45d527b6e2bbbcb6302e6ef0842e9
+  metadata.gz: 996d95088c85415ca883c27b6b1c98e65af5c046e3121ea08f092ac7bcdcc588
+  data.tar.gz: 8fe294225c04dcfc82289fd2b9047760260b814712e83e9bf5ea7d361dad6950
 SHA512:
-  metadata.gz: 5f9727de69aac6d48de53ca174280c68dce7825b9a4aa6f8c955b6122f30d9f4541a7d47e7ed7caa319feda5659b14b73a3ad343db2733b4bb9518e9ade94f8c
-  data.tar.gz: 765e786959a6fdda6c25cddda11f5f987837d6853245e5bc8533dbe7b904792b09fc39e726371c81981275ef0abdb8d1d95de63a76889af34b037f34d01c6c3a
+  metadata.gz: 54fdbe164a4a2541153e57b90cdb35ba71b6887fbe2d199505da3389730f1bd937fe0254f8c019b39d81957058c5f51ad71bc900f324e3178b979f368642ee57
+  data.tar.gz: fa05ea9ae79a57a3eace2e708b01fe5f44412591875776cf1a2fe95cc6d9d1586357756e702e8a17e5458b3fa4c3e3224290bc234b71fdcd426db0dedff31dc0

data/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,9 @@
+## 0.16 2022-01-23
+- Implement JSON templating (#7)
+- Add support for MIME types (#6)
+- Change entrypoint from `Kernel#H`, `Kernel#X` to `Papercraft.html`, `.xml` (#5)
 ## 0.15 2022-01-20
 - Fix tag method line reference
@@ -42,7 +48,7 @@
 ## 0.8 2021-12-22
 - Cleanup and refactor code
-- Add X global method for XML templates
+- Add Papercraft.xml global method for XML templates
 - Make `Component` a descendant of `Proc`
 - Introduce new component API
 - Rename Rubyoshka to Papercraft

data/README.md CHANGED Viewed

@@ -4,7 +4,7 @@
   Papercraft
 </h1>
-<h4 align="center">Composable HTML templating for Ruby</h4>
+<h4 align="center">Composable templating for Ruby</h4>
 <p align="center">
   <a href="http://rubygems.org/gems/papercraft">
@@ -27,26 +27,28 @@
 ```ruby
 require 'papercraft'
-page = H { |*args|
+page = Papercraft.html { |*args|
   html {
     head { }
     body { emit_yield *args }
   }
 }
+page.render { p 'foo' }
+#=> "<html><head/><body><p>foo</p></body></html>"
-hello = H.apply { |name| h1 "Hello, #{name}!" }
+hello = page.apply { |name| h1 "Hello, #{name}!" }
 hello.render('world')
 #=> "<html><head/><body><h1>Hello, world!</h1></body></html>"
 ```
-Papercraft is an HTML templating engine for Ruby that offers the following
-features:
+Papercraft is a templating engine for Ruby that offers the following features:
-- HTML and XML templating using plain Ruby syntax
+- HTML, XML and JSON templating using plain Ruby syntax
 - Minimal boilerplate
 - Mix logic and tags freely
 - Automatic HTML and XML escaping
 - Composable components
+- Standard or custom MIME types
 - Explicit parameter passing to nested components
 - Higher order components
 - Built-in support for rendering [Markdown](#emitting-markdown)
@@ -73,7 +75,7 @@ To create a template use the global method `Kernel#H`:
 ```ruby
 require 'papercraft'
-html = H {
+html = Papercraft.html {
   div(id: 'greeter') { p 'Hello!' }
 }
 ```
@@ -89,7 +91,7 @@ html.render #=> "<div id="greeter"><p>Hello!</p></div>"
 Tags are added using unqualified method calls, and can be nested using blocks:
 ```ruby
-H {
+Papercraft.html {
   html {
     head {
       title 'page title'
@@ -106,19 +108,19 @@ H {
 Tag methods accept a string argument, a block, or no argument at all:
 ```ruby
-H { p 'hello' }.render #=> "<p>hello</p>"
+Papercraft.html { p 'hello' }.render #=> "<p>hello</p>"
-H { p { span '1'; span '2' } }.render #=> "<p><span>1</span><span>2</span></p>"
+Papercraft.html { p { span '1'; span '2' } }.render #=> "<p><span>1</span><span>2</span></p>"
-H { hr() }.render #=> "<hr/>"
+Papercraft.html { hr() }.render #=> "<hr/>"
 ```
 Tag methods also accept tag attributes, given as a hash:
 ```ruby
-H { img src: '/my.gif' }.render #=> "<img src="/my.gif"/>
+Papercraft.html { img src: '/my.gif' }.render #=> "<img src="/my.gif"/>
-H { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</p>"
+Papercraft.html { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</p>"
 ```
 ## Template parameters
@@ -128,14 +130,14 @@ parameters are specified as block parameters, and are passed to the template on
 rendering:
 ```ruby
-greeting = H { |name| h1 "Hello, #{name}!" }
+greeting = Papercraft.html { |name| h1 "Hello, #{name}!" }
 greeting.render('world') #=> "<h1>Hello, world!</h1>"
 ```
 Templates can also accept named parameters:
 ```ruby
-greeting = H { |name:| h1 "Hello, #{name}!" }
+greeting = Papercraft.html { |name:| h1 "Hello, #{name}!" }
 greeting.render(name: 'world') #=> "<h1>Hello, world!</h1>"
 ```
@@ -145,7 +147,7 @@ Since Papercraft templates are just a bunch of Ruby, you can easily write your
 view logic right in the template:
 ```ruby
-H { |user = nil|
+Papercraft.html { |user = nil|
   if user
     span "Hello, #{user.name}!"
   else
@@ -159,7 +161,7 @@ H { |user = nil|
 Templates can also accept and render blocks by using `emit_yield`:
 ```ruby
-page = H {
+page = Papercraft.html {
   html {
     body { emit_yield }
   }
@@ -176,14 +178,14 @@ it by passing it as a block to `H`:
 ```ruby
 greeting = proc { |name| h1 "Hello, #{name}!" }
-H(&greeting).render('world')
+Papercraft.html(&greeting).render('world')
 ```
 Components can also be expressed using lambda notation:
 ```ruby
 greeting = ->(name) { h1 "Hello, #{name}!" }
-H(&greeting).render('world')
+Papercraft.html(&greeting).render('world')
 ```
 ## Component composition
@@ -210,7 +212,7 @@ ItemList = ->(items) {
   }
 }
-page = H { |title, items|
+page = Papercraft.html { |title, items|
   html5 {
     head { Title(title) }
     body { ItemList(items) }
@@ -229,7 +231,7 @@ non-constant components by invoking the `#emit` method:
 ```ruby
 greeting = -> { span "Hello, world" }
-H {
+Papercraft.html {
   div {
     emit greeting
   }
@@ -247,12 +249,12 @@ or block to the original component:
 ```ruby
 # parameter application
-hello = H { |name| h1 "Hello, #{name}!" }
+hello = Papercraft.html { |name| h1 "Hello, #{name}!" }
 hello_world = hello.apply('world')
 hello_world.render #=> "<h1>Hello, world!</h1>"
 # block application
-div_wrap = H { div { emit_yield } }
+div_wrap = Papercraft.html { div { emit_yield } }
 wrapped_h1 = div_wrap.apply { h1 'hi' }
 wrapped_h1.render #=> "<div><h1>hi</h1></div>"
@@ -271,8 +273,8 @@ markup, enhancing components or injecting component parameters.
 Here is a HOC that takes a component as parameter:
 ```ruby
-div_wrap = H { |inner| div { emit inner } }
-greeter = H { h1 'hi' }
+div_wrap = Papercraft.html { |inner| div { emit inner } }
+greeter = Papercraft.html { h1 'hi' }
 wrapped_greeter = div_wrap.apply(greeter)
 wrapped_greeter.render #=> "<div><h1>hi</h1></div>"
 ```
@@ -280,7 +282,7 @@ wrapped_greeter.render #=> "<div><h1>hi</h1></div>"
 The inner component can also be passed as a block, as shown above:
 ```ruby
-div_wrap = H { div { emit_yield } }
+div_wrap = Papercraft.html { div { emit_yield } }
 wrapped_greeter = div_wrap.apply { h1 'hi' }
 wrapped_greeter.render #=> "<div><h1>hi</h1></div>"
 ```
@@ -294,7 +296,7 @@ this by creating a `default` page template that takes a block, then use `#apply`
 to create the other templates:
 ```ruby
-default_layout = H { |**params|
+default_layout = Papercraft.html { |**params|
   html5 {
     head {
       title: params[:title]
@@ -323,7 +325,7 @@ article_layout.render(
 Raw HTML can be emitted using `#emit`:
 ```ruby
-wrapped = H { |html| div { emit html } }
+wrapped = Papercraft.html { |html| div { emit html } }
 wrapped.render("<h1>hi</h1>") #=> "<div><h1>hi</h1></div>"
 ```
@@ -333,7 +335,7 @@ To emit a string with proper HTML encoding, without wrapping it in an HTML
 element, use `#text`:
 ```ruby
-H { str 'hi&lo' }.render #=> "hi&amp;lo"
+Papercraft.html { str 'hi&lo' }.render #=> "hi&amp;lo"
 ```
 ## Emitting Markdown
@@ -343,7 +345,7 @@ Markdown is rendered using the
 `#emit_markdown`:
 ```ruby
-template = H { |md| div { emit_markdown md } }
+template = Papercraft.html { |md| div { emit_markdown md } }
 template.render("Here's some *Markdown*") #=> "<div><p>Here's some <em>Markdown</em><p>\n</div>"
 ```
@@ -352,7 +354,7 @@ options](https://kramdown.gettalong.org/options.html#available-options) can be
 specified by adding them to the `#emit_markdown` call:
 ```ruby
-template = H { |md| div { emit_markdown md, auto_ids: false } }
+template = Papercraft.html { |md| div { emit_markdown md, auto_ids: false } }
 template.render("# title") #=> "<div><h1>title</h1></div>"
 ```
@@ -395,7 +397,7 @@ class that can collect JS and CSS dependencies from the different components
 integrated into the page, and adds them to the page's `<head>` element:
 ```ruby
-default_layout = H { |**args|
+default_layout = Papercraft.html { |**args|
   @dependencies = DependencyMananger.new
   head {
     defer { emit @dependencies.head_markup }
@@ -481,7 +483,7 @@ The call to `Papercraft::extension` lets us access the different methods of
 we'll be able to express the above markup as follows:
 ```ruby
-H {
+Papercraft.html {
   bootstrap.card(style: 'width: 18rem') {
     bootstrap.card_title 'Card title'
     bootstrap.card_subtitle 'Card subtitle'
@@ -492,6 +494,37 @@ H {
 }
 ```
+## JSON templating
+You can create a JSON template using the same API used for HTML and XML
+templating. The only difference is that for adding array items you'll need to
+use the `#item` method:
+```ruby
+Papercraft.json {
+  item 1
+  item 2
+  item 3
+}.render #=> "[1,2,3]"
+```
+Otherwise, you can create arbitrarily complex JSON structures by mixing hashes
+and arrays:
+```Ruby
+Papercraft.json {
+  foo {
+    bar {
+      item nil
+      item true
+      item 123.456
+    }
+  }
+}.render #=> "{\"foo\":{\"bar\":[null,true,123.456]}}"
+```
+Papercraft uses the [JSON gem](https://rubyapi.org/3.1/o/json) under the hood.
 ## API Reference
 The API reference for this library can be found

data/lib/papercraft/component.rb CHANGED Viewed

@@ -11,21 +11,26 @@ module Papercraft
   # class is simply a special kind of Proc, which has some enhanced
   # capabilities, allowing it to be easily composed in a variety of ways.
   #
-  # Components are usually created using the global methods `H` or `X`, for HTML
-  # or XML templates, respectively:
+  # Components are usually created using the class methods `html`, `xml` or
+  # `json`, for HTML, XML or JSON templates, respectively:
   #
-  #   greeter = H { |name| h1 "Hello, #{name}!" }
+  #   greeter = Papercraft.html { |name| h1 "Hello, #{name}!" }
   #   greeter.render('world') #=> "<h1>Hello, world!</h1>"
   #
   # Components can also be created using the normal constructor:
   #
-  #   greeter = Papercraft::Component.new { |name| h1 "Hello, #{name}!" }
+  #   greeter = Papercraft::Component.new(mode: :html) { |name| h1 "Hello, #{name}!" }
   #   greeter.render('world') #=> "<h1>Hello, world!</h1>"
   #
+  # The different methods for creating components can also take a custom MIME
+  # type, by passing a `mime_type` named argument:
+  #
+  #   json = Papercraft.json(mime_type: 'application/feed+json') { ... }
+  #
   # In the component block, HTML elements are created by simply calling
   # unqualified methods:
   #
-  #   page_layout = H {
+  #   page_layout = Papercraft.html {
   #     html5 {
   #       head {
   #         title 'foo'
@@ -41,7 +46,7 @@ module Papercraft
   # `greeter` template shown above takes a single `name` parameter. Here's how a
   # anchor component could be implemented with named parameters:
   #
-  #   anchor = H { |uri: , text: | a(text, href: uri) }
+  #   anchor = Papercraft.html { |uri: , text: | a(text, href: uri) }
   #
   # The above component could later be rendered by passing the needed arguments:
   #
@@ -51,7 +56,7 @@ module Papercraft
   #
   # A component can be included in another component using the `emit` method:
   #
-  #   links = H {
+  #   links = Papercraft.html {
   #     emit anchor, uri: '/posts',   text: 'Posts'
   #     emit anchor, uri: '/archive', text: 'Archive'
   #     emit anchor, uri: '/about',   text: 'About'
@@ -60,7 +65,7 @@ module Papercraft
   # Another way of composing components is to pass the components themselves as
   # parameters:
   #
-  #   links = H { |anchors|
+  #   links = Papercraft.html { |anchors|
   #     anchors.each { |a| emit a }
   #   }
   #   links.render([
@@ -84,14 +89,22 @@ module Papercraft
     # Determines the rendering mode: `:html` or `:xml`.
     attr_accessor :mode
+    STOCK_MIME_TYPE = {
+      html: 'text/html',
+      xml:  'application/xml',
+      json: 'application/json'
+    }.freeze
     # Initializes a component with the given block. The rendering mode (HTML or
     # XML) can be passed in the `mode:` parameter. If `mode:` is not specified,
     # the component defaults to HTML.
     #
     # @param mode [:html, :xml] rendering mode
+    # @param mime_type [String, nil] the component's mime type (nil for default)
     # @param block [Proc] nested HTML block
-    def initialize(mode: :html, &block)
+    def initialize(mode: :html, mime_type: nil, &block)
       @mode = mode
+      @mime_type = mime_type || STOCK_MIME_TYPE[mode]
       super(&block)
     end
@@ -115,7 +128,7 @@ module Papercraft
     # current one. Application is one of the principal methods of composing
     # components, particularly when passing inner components as blocks:
     #
-    #   article_wrapper = H {
+    #   article_wrapper = Papercraft.html {
     #     article {
     #       emit_yield
     #     }
@@ -131,7 +144,7 @@ module Papercraft
     # @return [Papercraft::Component] applied component
     def apply(*a, **b, &block)
       template = self
-      Component.new(&proc do |*x, **y|
+      Component.new(mode: @mode, mime_type: @mime_type, &proc do |*x, **y|
         push_emit_yield_block(block) if block
         instance_exec(*a, *x, **b, **y, &template)
       end)
@@ -147,10 +160,16 @@ module Papercraft
         HTMLRenderer
       when :xml
         XMLRenderer
+      when :json
+        JSONRenderer
       else
         raise "Invalid mode #{@mode.inspect}"
       end
     end
+    def mime_type
+      @mime_type
+    end
     # def compile
     #   Papercraft::Compiler.new.compile(self)

data/lib/papercraft/json.rb ADDED Viewed

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+require 'json'
+module Papercraft
+  # JSON renderer extensions
+  module JSON
+    def object_stack
+      @object_stack ||= [nil]
+    end
+    def with_object(&block)
+      object_stack << nil
+      instance_eval(&block)
+    end
+    def verify_array_target
+      case object_stack[-1]
+      when nil
+        object_stack[-1] = []
+      when Hash
+        raise "Mixing array and hash values"
+      end
+    end
+    def verify_hash_target
+      case object_stack[-1]
+      when nil
+        object_stack[-1] = {}
+      when Array
+        raise "Mixing array and hash values"
+      end
+    end
+    def push_array_item(value)
+      object_stack[-1] << value
+    end
+    def push_kv_item(key, value)
+      object_stack[-1][key] = value
+    end
+    def enter_object(&block)
+      object_stack << nil
+      instance_eval(&block)
+      object_stack.pop
+    end
+    def item(value = nil, &block)
+      verify_array_target
+      if block
+        value = enter_object(&block)
+      end
+      push_array_item(value)
+    end
+    def kv(key, value, &block)
+      verify_hash_target
+      if block
+        value = enter_object(&block)
+      end
+      push_kv_item(key, value)
+    end
+    def method_missing(sym, value = nil, &block)
+      kv(sym, value, &block)
+    end
+    def to_s
+      object_stack[0].to_json
+    end
+  end
+end

data/lib/papercraft/renderer.rb CHANGED Viewed

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 require_relative './html'
+require_relative './json'
 require_relative './extension_proxy'
 module Papercraft
@@ -55,7 +56,7 @@ module Papercraft
       # end
       #
       # Papercraft.extension(components: ComponentLibrary)
-      # H { components.card('Foo', '**Bar**') }
+      # Papercraft.html { components.card('Foo', '**Bar**') }
       #
       # @param map [Hash] hash mapping methods to extension modules
       # @return [void]
@@ -210,11 +211,11 @@ module Papercraft
     # `#to_s` which is then added to the rendering buffer, without any escaping.
     #
     #   greeter = proc { |name| h1 "Hello, #{name}!" }
-    #   H { emit(greeter, 'world') }.render #=> "<h1>Hello, world!</h1>"
+    #   Papercraft.html { emit(greeter, 'world') }.render #=> "<h1>Hello, world!</h1>"
     #
-    #   H { emit 'hi&<bye>' }.render #=> "hi&<bye>"
+    #   Papercraft.html { emit 'hi&<bye>' }.render #=> "hi&<bye>"
     #
-    #   H { emit nil }.render #=> ""
+    #   Papercraft.html { emit nil }.render #=> ""
     #
     # @param o [Proc, Papercraft::Component, String] emitted object
     # @param *a [Array<any>] arguments to pass to a proc
@@ -234,7 +235,7 @@ module Papercraft
     # Emits a block supplied using `Component#apply` or `Component#render`.
     #
-    #   div_wrap = H { |*args| div { emit_yield(*args) } }
+    #   div_wrap = Papercraft.html { |*args| div { emit_yield(*args) } }
     #   greeter = div_wrap.apply { |name| h1 "Hello, #{name}!" }
     #   greeter.render('world') #=> "<div><h1>Hello, world!</h1></div>"
     #
@@ -256,7 +257,7 @@ module Papercraft
     # adding elements to the `<head>` section. Here's how a title can be
     # controlled from a nested component:
     #
-    #   layout = H {
+    #   layout = Papercraft.html {
     #     html {
     #       head {
     #         defer { title @title }
@@ -380,4 +381,8 @@ module Papercraft
       EscapeUtils.escape_xml(text.to_s)
     end
   end
+  class JSONRenderer < Renderer
+    include JSON
+  end
 end

data/lib/papercraft/version.rb CHANGED Viewed

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

data/lib/papercraft.rb CHANGED Viewed

@@ -25,36 +25,49 @@ module Papercraft
   def self.extension(map)
     Renderer.extension(map)
   end
-end
-# Kernel extensions
-module ::Kernel
-  # Creates a new papercraft component. `#H` can take either a proc argument or
-  # a block. In both cases, the proc is converted to a `Papercraft::Component`.
+  # Creates a new papercraft component. `Papercraft.html` can take either a proc
+  # argument or a block. In both cases, the proc is converted to a
+  # `Papercraft::Component`.
+  #
+  # Papercraft.html(proc { h1 'hi' }).render #=> "<h1>hi</h1>"
+  # Papercraft.html { h1 'hi' }.render #=> "<h1>hi</h1>"
+  #
+  # @param template [Proc] template block
+  # @return [Papercraft::Component] Papercraft component
+  def self.html(o = nil, mime_type: nil, &template)
+    return o if o.is_a?(Papercraft::Component)
+    template ||= o
+    Papercraft::Component.new(mode: :html, mime_type: mime_type, &template)
+  end
+  # Creates a new papercraft component in XML mode. `Papercraft.xml` can take
+  # either a proc argument or a block. In both cases, the proc is converted to a
+  # `Papercraft::Component`.
   #
-  # H(proc { h1 'hi' }).render #=> "<h1>hi</h1>"
-  # H { h1 'hi' }.render #=> "<h1>hi</h1>"
+  # Papercraft.xml(proc { item 'foo' }).render #=> "<item>foo</item>"
+  # Papercraft.xml { item 'foo' }.render #=> "<item>foo</item>"
   #
   # @param template [Proc] template block
   # @return [Papercraft::Component] Papercraft component
-  def H(o = nil, &template)
+  def self.xml(o = nil, mime_type: nil, &template)
     return o if o.is_a?(Papercraft::Component)
     template ||= o
-    Papercraft::Component.new(mode: :html, &template)
+    Papercraft::Component.new(mode: :xml, mime_type: mime_type, &template)
   end
-  # Creates a new papercraft component in XML mode. `#X` can take either a proc argument or
-  # a block. In both cases, the proc is converted to a `Papercraft::Component`.
+  # Creates a new papercraft component in JSON mode. `Papercraft.json` can take
+  # either a proc argument or a block. In both cases, the proc is converted to a
+  # `Papercraft::Component`.
   #
-  # X(proc { item 'foo' }).render #=> "<item>foo</item>"
-  # X { item 'foo' }.render #=> "<item>foo</item>"
+  # Papercraft.json(proc { item 42 }).render #=> "[42]"
+  # Papercraft.json { foo 'bar' }.render #=> "{\"foo\": \"bar\"}"
   #
   # @param template [Proc] template block
   # @return [Papercraft::Component] Papercraft component
-  def X(o = nil, &template)
+  def self.json(o = nil, mime_type: nil, &template)
     return o if o.is_a?(Papercraft::Component)
     template ||= o
-    Papercraft::Component.new(mode: :xml, &template)
+    Papercraft::Component.new(mode: :json, mime_type: mime_type, &template)
   end
 end

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '0.15'
+  version: '0.16'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-20 00:00:00.000000000 Z
+date: 2022-01-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils
@@ -137,6 +137,7 @@ files:
 - lib/papercraft/encoding.rb
 - lib/papercraft/extension_proxy.rb
 - lib/papercraft/html.rb
+- lib/papercraft/json.rb
 - lib/papercraft/renderer.rb
 - lib/papercraft/version.rb
 homepage: http://github.com/digital-fabric/papercraft