papercraft 0.19 → 0.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0f4910bd26625ca0349b1c471338fb4d13e8055e88367b5cad16f91cdee7531
-  data.tar.gz: 38e43978278ba069e3767abd94d83c676f42692f5eb55f1be4b4067fae2f935e
+  metadata.gz: 341520b9db20c53da441299fb449c4eea3321924517f4b93e70af1119b4516c3
+  data.tar.gz: 861a5a2747c3a468abb780cf50710698e52fbac1fc236c8672c2bbb328db6f4d
 SHA512:
-  metadata.gz: b096452cebe7b6bb34a428f4920a5940e5b745c86b54188a984a77df6175145cf6645753e6ae58b3df89813919920a17a96610e010724bc50077c6f9accc7293
-  data.tar.gz: 8d1cd5b2d6b70ee9ef0a748a064bbd6d1630cfa926663aded95a01c26ce289a159e2548068bf8210c5e8d37ba26c9671eb4a00fe4790a47bec6dd822b4de5d5d
+  metadata.gz: 7668a984a2c7957ba3f65234eab6770b4e969e0d2b4e1345839db8c0711d07afbfef5735b67de9a94c22994b4b6c1d6b2f87e07a810a0cae04ccbecb1ff5b38f
+  data.tar.gz: 1605f9b1459ab20b9cec97805529764ece6058ce34609dc7d75fe38d8b35889c65e4afa5174f1c1d89dfb46205d282e65e1020995c999f66b84a5f9b5e505de1

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 0.23 2022-02-15
+
+- Remove unused `Encoding` module
+- Add SOAP extension (#11, thanks [@aemadrid](https://github.com/aemadrid))
+
+## 0.22 2022-02-14
+
+- Fix behaviour of call to `#p` in an extension (#10)
+
+## 0.21 2022-02-13
+
+- Refactor and improve documentation
+
+## 0.20 2022-02-13
+
+- Add support for XML namespaced tags and attributes (#9)
+- Move and refactor HTML/XML common code to Tags module
+
 ## 0.19 2022-02-05
 
 - Rename `Papercraft::Component` to `Papercraft::Template`

data/README.md

@@ -64,6 +64,7 @@ hello.render('world')
 - [Installing papercraft](#installing-papercraft)
 - [Basic usage](#basic-usage)
 - [Adding tags](#adding-tags)
+- [Tag and attribute formatting](#tag-and-attribute-formatting)
 - [Template parameters](#template-parameters)
 - [Template logic](#template-logic)
 - [Template blocks](#template-blocks)
@@ -77,9 +78,10 @@ hello.render('world')
 - [Emitting Markdown](#emitting-markdown)
 - [Working with MIME types](#working-with-mime-types)
 - [Deferred evaluation](#deferred-evaluation)
-- [Papercraft extensions](#papercraft-extensions)
 - [XML templates](#xml-templates)
 - [JSON templates](#json-templates)
+- [Papercraft extensions](#papercraft-extensions)
+  - [Bundled extensions](#bundled-extensions)
 - [API Reference](#api-reference)
 
 ## Installing Papercraft
@@ -154,6 +156,43 @@ Papercraft.html { img src: '/my.gif' }.render #=> "<img src="/my.gif"/>
 Papercraft.html { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</p>"
 ```
 
+## Tag and attribute formatting
+
+Papercraft does not make any presumption 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
+formatted according to the following rules, depending on the template type:
+
+- HTML: underscores are converted to dashes:
+
+  ```ruby
+  Papercraft.html {
+    foo_bar { p 'Hello', data_name: 'world' }
+  }.render #=> '<foo-bar><p data-name="world">Hello</p></foo-bar>'
+  ```
+
+- XML: underscores are converted to dashes, double underscores are converted to
+  colons:
+
+  ```ruby
+  Papercraft.xml {
+    soap__Envelope(
+      xmlns__soap:  'http://schemas.xmlsoap.org/soap/envelope/',
+    ) { }
+  }.render #=> '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Envelope>'
+  ```
+
+If you need more precise control over tag names, you can use the `#tag` method,
+which takes the tag name as its first parameter, then the rest of the parameters
+normally used for tags:
+
+```ruby
+Papercraft.html {
+  tag 'cra_zy__:!tag', 'foo'
+}.render #=> '<cra_zy__:!tag>foo</cra_zy__:!tag>'
+```
+
 ## Template parameters
 
 In Papercraft, parameters are always passed explicitly. This means that template
@@ -483,6 +522,72 @@ page = default_layout.apply {
 }
 ```
 
+## XML templates
+
+XML templates behave largely the same as HTML templates, with a few minor
+differences. XML templates employ a different encoding algorithm, and lack some
+specific HTML functionality, such as emitting Markdown.
+
+Here's an example showing how to create an RSS feed:
+
+```ruby
+rss = Papercraft.xml(mime_type: 'text/xml; charset=utf-8') { |resource:, **props|
+  rss(version: '2.0', 'xmlns:atom' => 'http://www.w3.org/2005/Atom') {
+    channel {
+      title 'Noteflakes'
+      link 'https://noteflakes.com/'
+      description 'A website by Sharon Rosner'
+      language 'en-us'
+      pubDate Time.now.httpdate
+      emit '<atom:link href="https://noteflakes.com/feeds/rss" rel="self" type="application/rss+xml" />'
+      
+      article_entries = resource.page_list('/articles').reverse
+
+      article_entries.each { |e|
+        item {
+          title e[:title]
+          link "https://noteflakes.com#{e[:url]}"
+          guid "https://noteflakes.com#{e[:url]}"
+          pubDate e[:date].to_time.httpdate
+          description e[:html_content]
+        }  
+      }
+    }
+  }
+}
+```
+
+## JSON templates
+
+JSON templates behave largely the same as HTML and XML templates. The only major
+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 in
+order to generate actual JSON.
+
 ## Papercraft extensions
 
 Papercraft extensions are modules that contain one or more methods that can be
@@ -513,21 +618,27 @@ and other associated methods:
 
 ```ruby
 module BootstrapComponents
-  ...
-
-  def card(**props)
+  def card(**props, &block)
     div(class: 'card', **props) {
-      div(class: 'card-body') {
-        emit_yield
-      }
+      div(class: 'card-body', &block)
     }
   end
-
+  
   def card_title(title)
-    h5 title, class: 'card-title'
+    h4(title, class: 'card-title')
+  end
+
+  def card_subtitle(subtitle)
+    h5(subtitle, class: 'card-subtitle')
+  end
+
+  def card_text(text)
+    p(text, class: 'card-text')
   end
 
-  ...
+  def card_link(text, **opts)
+    a(text, class: 'card-link', **opts)
+  end
 end
 
 Papercraft.extension(bootstrap: BootstrapComponents)
@@ -543,80 +654,62 @@ Papercraft.html {
     bootstrap.card_title 'Card title'
     bootstrap.card_subtitle 'Card subtitle'
     bootstrap.card_text 'Some quick example text to build on the card title and make up the bulk of the card''s content.'
-    bootstrap.card_link '#', 'Card link'
-    bootstrap.card_link '#', 'Another link'
+    bootstrap.card_link 'Card link', href: '#foo'
+    bootstrap.card_link 'Another link', href: '#bar'
   }
 }
 ```
 
+## Bundled Extensions
 
+Papercraft comes bundled with a few extensions that address common use cases.
+All bundled extensions are namespaced under `Papercraft::Extensions`, and must
+be specifically required in order to be available to templates.
 
-## XML templates
+For all bundled Papercraft extensions, there's no need to call
+`Papercraft.extension`, requiring the extension is sufficient.
 
-XML templates behave largely the same as HTML templates, with a few minor
-differences. XML templates employ a different encoding algorithm, and lack some
-specific HTML functionality, such as emitting Markdown.
+### SOAP extension
 
-Here's an example showing how to create an RSS feed:
+> The SOAP extension was contributed by [@aemadrid](https://github.com/aemadrid).
 
-```ruby
-rss = Papercraft.xml(mime_type: 'text/xml; charset=utf-8') { |resource:, **props|
-  rss(version: '2.0', 'xmlns:atom' => 'http://www.w3.org/2005/Atom') {
-    channel {
-      title 'Noteflakes'
-      link 'https://noteflakes.com/'
-      description 'A website by Sharon Rosner'
-      language 'en-us'
-      pubDate Time.now.httpdate
-      emit '<atom:link href="https://noteflakes.com/feeds/rss" rel="self" type="application/rss+xml" />'
-      
-      article_entries = resource.page_list('/articles').reverse
+The SOAP extension provides common tags for building SOAP payloads. To load the
+SOAP extensions, require `polyphony/extensions/soap`. The extension provides the
+following methods:
 
-      article_entries.each { |e|
-        item {
-          title e[:title]
-          link "https://noteflakes.com#{e[:url]}"
-          guid "https://noteflakes.com#{e[:url]}"
-          pubDate e[:date].to_time.httpdate
-          description e[:html_content]
-        }  
-      }
-    }
-  }
-}
-```
+- `soap.Body(...)` - emits a `soap:Body` tag.
+- `soap.Envelope(...)` - emits a `soap:Envelope` tag.
+- `soap.Fault(...)` - emits a `soap:Fault` tag.
+- `soap.Header(...)` - emits a `soap:Header` tag.
 
-## JSON templates
-
-JSON templates behave largely the same as HTML and XML templates. The only major
-difference is that for adding array items you'll need to use the `#item` method:
+As mentioned above, namespaced tags and attributes may be specified by using
+double underscores for colons. Other tags that contain special characters may be
+emitted using the `#tag` method:
 
 ```ruby
-Papercraft.json {
-  item 1
-  item 2
-  item 3
-}.render #=> "[1,2,3]"
-```
+require 'polyphony/extensions/soap'
 
-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
+xml = Papercraft.xml {
+  soap.Envelope(
+    xmlns__xsd: 'http://www.w3.org/2001/XMLSchema',
+    xmlns__xsi: 'http://www.w3.org/2001/XMLSchema-instance'
+  ) {
+    soap.Body {
+      PosRequest(xmlns: 'http://Some.Site') {
+        tag('Ver1.0') {
+          Header {
+            SecretAPIKey 'some_secret_key'
+          }
+          Transaction {
+            SomeData {}
+          }
+        }
+      }
     }
   }
-}.render #=> "{\"foo\":{\"bar\":[null,true,123.456]}}"
+}
 ```
 
-Papercraft uses the [JSON gem](https://rubyapi.org/3.1/o/json) under the hood in
-order to generate actual JSON.
-
 ## API Reference
 
 The API reference for this library can be found

data/lib/papercraft/extension_proxy.rb

@@ -10,6 +10,7 @@ module Papercraft
   class ExtensionProxy
 
     # Initializes a new ExtensionProxy.
+    #
     # @param renderer [Papercraft::Renderer] renderer to proxy to
     # @param mod [Module] extension module
     # @return [void]
@@ -18,13 +19,25 @@ module Papercraft
       extend(mod)
     end
   
-    # Proxies missing methods to the renderer
+    # Proxies missing methods to the renderer.
+    #
     # @param sym [Symbol] method name
     # @param *args [Array] arguments
+    # @param *props [Array] named arguments
     # @param &block [Proc] block
     # @return void
-    def method_missing(sym, *args, &block)
-      @renderer.send(sym, *args, &block)
+    def method_missing(sym, *args, **props, &block)
+      @renderer.send(sym, *args, **props, &block)
+    end
+
+    # Overrides the `Kernel#p` method to emit a p tag.
+    #
+    # @param *args [Array] arguments
+    # @param *props [Array] named arguments
+    # @param &block [Proc] block
+    # @return void
+    def p(text = nil, **props, &block)
+      @renderer.p(text, **props, &block)
     end
   end
 end

data/lib/papercraft/extensions/soap.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Papercraft
+  module Extensions
+    module Soap
+      # Emits a SOAP XML tag that identifies the XML document as a SOAP message.
+      #
+      # @param **props [Hash] tag attributes
+      # @param &block [Proc] optional inner XML
+      # @return [void]
+      def Envelope(**props, &block)
+        props[:xmlns__soap] ||= 'http://schemas.xmlsoap.org/soap/envelope/'
+        tag('soap:Envelope', **props, &block)
+      end
+
+      # Emits a SOAP XML tag that contains header information.
+      #
+      # @param **props [Hash] tag attributes
+      # @param &block [Proc] optional inner XML
+      # @return [void]
+      def Header(**props, &blk)
+        tag('soap:Header', **props, &blk)
+      end
+
+      # Emits a SOAP XML tag that contains header information.
+      #
+      # @param **props [Hash] tag attributes
+      # @param &block [Proc] optional inner XML
+      # @return [void]
+      def Body(**props, &blk)
+        tag('soap:Body', **props, &blk)
+      end
+
+      # Emits a SOAP XML tag that contains errors and status information.
+      #
+      # @param **props [Hash] tag attributes
+      # @param &block [Proc] optional inner XML
+      # @return [void]
+      def Fault(**props, &blk)
+        tag('soap:Fault', **props, &blk)
+      end
+    end
+  end
+end
+
+Papercraft.extension(soap: Papercraft::Extensions::Soap)

data/lib/papercraft/html.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require_relative './tags'
+
 module Papercraft  
   # HTML Markup extensions
   module HTML
+    include Tags
+
     # Emits the p tag (overrides Object#p)
     #
     # @param text [String] text content of tag
@@ -81,5 +85,33 @@ module Papercraft
     def emit_markdown(markdown, **opts)
       emit Papercraft.markdown(markdown, **opts)
     end
+
+    private
+
+    # Escapes the given text using HTML entities.
+    #
+    # @param text [String] text
+    # @return [String] escaped text
+    def escape_text(text)
+      EscapeUtils.escape_html(text.to_s)
+    end
+
+    # Converts a tag to its string representation. Underscores will be converted
+    # to dashes.
+    #
+    # @param tag [Symbol, String] tag
+    # @return [String] tag string
+    def tag_repr(tag)
+      tag.to_s.tr('_', '-')
+    end
+
+    # Converts an attribute to its string representation. Underscores will be
+    # converted to dashes.
+    #
+    # @param att [Symbol, String] attribute
+    # @return [String] attribute string
+    def att_repr(att)
+      att.to_s.tr('_', '-')
+    end
   end
 end

data/lib/papercraft/json.rb

@@ -5,69 +5,122 @@ require 'json'
 module Papercraft  
   # JSON renderer extensions
   module JSON
-    def object_stack
-      @object_stack ||= [nil]
+    # Initializes a JSON renderer, setting up an object stack.
+    def initialize(&template)
+      @object_stack = [nil]
+      super
     end
 
+    # Adds an array item to the current object target. If a block is given, the
+    # block is evaulated against a new object target, then added to the current
+    # array.
+    #
+    # @param value [Object] item
+    # @param &block [Proc] template block
+    # @return [void]
+    def item(value = nil, &block)
+      verify_array_target
+      if block
+        value = enter_object(&block)
+      end
+      push_array_item(value)
+    end
+
+    # Adds a key-value item to the current object target. If a block is given,
+    # the block is evaulated against a new object target, then used as the
+    # value.
+    #
+    # @param key [Object] key
+    # @param value [Object] value
+    # @param &block [Proc] template block
+    # @return [void]
+    def kv(key, value = nil, &block)
+      verify_hash_target
+      if block
+        value = enter_object(&block)
+      end
+      push_kv_item(key, value)
+    end
+
+    # Intercepts method calls by adding key-value pairs to the current object
+    # target.
+    #
+    # @param key [Object] key
+    # @param value [Object] value
+    # @param &block [Proc] template block
+    # @return [void]
+    def method_missing(sym, value = nil, &block)
+      kv(sym, value, &block)
+    end
+
+    # Converts the root object target to JSON.
+    #
+    # @return [String] JSON template result
+    def to_s
+      @object_stack[0].to_json
+    end
+
+    private
+
+    # Adds a new entry to the object stack and evaluates the given block.
+    #
+    # @param &block [Proc] template block
+    # @return [void]
     def with_object(&block)
-      object_stack << nil
+      @object_stack << nil
       instance_eval(&block)
     end
 
+    # Verifies that the current object target is not a hash.
+    #
+    # @return [bool]
     def verify_array_target
-      case object_stack[-1]
+      case @object_stack[-1]
       when nil
-        object_stack[-1] = []
+        @object_stack[-1] = []
       when Hash
         raise "Mixing array and hash values"
       end
     end
 
+    # Verifies that the current object target is not an array.
+    #
+    # @return [bool]
     def verify_hash_target
-      case object_stack[-1]
+      case @object_stack[-1]
       when nil
-        object_stack[-1] = {}
+        @object_stack[-1] = {}
       when Array
         raise "Mixing array and hash values"
       end
     end
 
+    # Pushes an array item to the current object target.
+    #
+    # @param value [Object] item
+    # @return [void]
     def push_array_item(value)
-      object_stack[-1] << value
+      @object_stack[-1] << value
     end
 
+    # Pushes a key value into the current object target.
+    #
+    # @param key [Object] key
+    # @param value [Object] value
+    # @return [void]
     def push_kv_item(key, value)
-      object_stack[-1][key] = value
+      @object_stack[-1][key] = value
     end
 
+    # Adds a new object to the object stack, evaluates the given template block,
+    # then pops the object off the stack.
+    #
+    # @param &block [Proc] template block
+    # @return [void]
     def enter_object(&block)
-      object_stack << nil
+      @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
+      @object_stack.pop
+    end    
   end
 end

data/lib/papercraft/renderer.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-require 'escape_utils'
-
 require_relative './html'
+require_relative './xml'
 require_relative './json'
 require_relative './extension_proxy'
 
@@ -10,7 +9,7 @@ module Papercraft
   
   # A Renderer renders a Papercraft template into a string
   class Renderer
-  
+
     class << self
 
       # Verifies that the given template proc can be called with the given
@@ -45,7 +44,7 @@ module Papercraft
       # methods to extension modules. The methods will be available to all
       # Papercraft templates. Extension methods are executed in the context of
       # the the renderer instance, so they can look just like normal proc
-      # components. In cases where method names in the module clash with HTML
+      # 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
@@ -81,131 +80,14 @@ module Papercraft
       end
     end
 
-    INITIAL_BUFFER_CAPACITY = 8192
-
     # Initializes the renderer and evaulates the given template in the
     # renderer's scope.
     #
     # @param &template [Proc] template block
     def initialize(&template)
-      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
       instance_eval(&template)
     end
 
-    # Returns the rendered template.
-    #
-    # @return [String]
-    def to_s
-      if @parts
-        last = @buffer
-        @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
-        parts = @parts
-        @parts = nil
-        parts.each do |p|
-          if Proc === p
-            render_deferred_proc(&p)
-          else
-            @buffer << p
-          end
-        end
-        @buffer << last unless last.empty?
-      end
-      @buffer
-    end
-
-    # The tag method template below is optimized for performance. Do not touch!
-
-    S_TAG_METHOD_LINE = __LINE__ + 2
-    S_TAG_METHOD = <<~EOF
-      S_TAG_%<TAG>s_PRE = %<tag_pre>s
-      S_TAG_%<TAG>s_CLOSE = %<tag_close>s
-
-      def %<tag>s(text = nil, **props, &block)
-        if text.is_a?(Hash) && props.empty?
-          props = text
-          text = nil
-        end
-
-        @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 Proc === text
-          @buffer << S_GT
-          emit(text)
-          @buffer << S_TAG_%<TAG>s_CLOSE
-        elsif text
-          @buffer << S_GT << escape_text(text.to_s) << S_TAG_%<TAG>s_CLOSE
-        else
-          @buffer << S_SLASH_GT
-        end
-      end
-    EOF
-
-    # Emits an HTML tag with the given content, properties and optional block.
-    # This method is an alternative to emitting HTML tags using dynamically
-    # created methods. This is particularly useful when using extensions that
-    # have method names that clash with HTML tags, such as `button` or `a`, or
-    # when you need to override the behaviour of a particular HTML tag.
-    #
-    # The following two method calls have the same effect:
-    #
-    # button 'text', id: 'button1'
-    # tag :button, 'text', id: 'button1'
-    #
-    # @param sym [Symbol, String] HTML tag
-    # @param text [String, nil] tag content
-    # @param **props [Hash] tag attributes
-    # @param &block [Proc] optional inner HTML
-    # @return [void]
-    def tag(sym, text = nil, **props, &block)
-      if text.is_a?(Hash) && props.empty?
-        props = text
-        text = nil
-      end
-
-      tag = sym.to_s.tr('_', '-')
-
-      @buffer << S_LT << tag
-      emit_props(props) unless props.empty?
-
-      if block
-        @buffer << S_GT
-        instance_eval(&block)
-        @buffer << S_LT_SLASH << tag << S_GT
-      elsif Proc === text
-        @buffer << S_GT
-        emit(text)
-        @buffer << S_LT_SLASH << tag << S_GT
-      elsif text
-        @buffer << S_GT << escape_text(text.to_s) << S_LT_SLASH << tag << S_GT
-      else
-        @buffer << S_SLASH_GT
-      end
-    end
-
-    # Catches undefined tag method call and handles it by defining the method.
-    #
-    # @param sym [Symbol] HTML tag or component identifier
-    # @param args [Array] method arguments
-    # @param opts [Hash] named method arguments
-    # @param &block [Proc] block passed to method
-    # @return [void]
-    def method_missing(sym, *args, **opts, &block)
-      tag = sym.to_s
-      code = S_TAG_METHOD % {
-        tag: tag,
-        TAG: tag.upcase,
-        tag_pre: "<#{tag.tr('_', '-')}".inspect,
-        tag_close: "</#{tag.tr('_', '-')}>".inspect
-      }
-      self.class.class_eval(code, __FILE__, S_TAG_METHOD_LINE)
-      send(sym, *args, **opts, &block)
-    end
-
     # Emits the given object into the rendering buffer. If the given object is a
     # proc or a component, `emit` will passes any additional arguments and named
     # arguments to the object when rendering it. If the given object is nil,
@@ -230,8 +112,9 @@ module Papercraft
         push_emit_yield_block(block) if block
         instance_exec(*a, **b, &o)
       when nil
+        # do nothing
       else
-        @buffer << o.to_s
+        emit_object(o)
       end
     end
     alias_method :e, :emit
@@ -251,140 +134,28 @@ module Papercraft
       
       instance_exec(*a, **b, &block)
     end
-
-    # Defers the given block to be evaluated later. Deferred evaluation allows
-    # Papercraft templates to inject state into sibling components, regardless
-    # of the component's order in the container component. For example, a nested
-    # component may set an instance variable used by another component. This is
-    # an elegant solution to the problem of setting the HTML page's title, or
-    # adding elements to the `<head>` section. Here's how a title can be
-    # controlled from a nested component:
-    #
-    #   layout = Papercraft.html {
-    #     html {
-    #       head {
-    #         defer { title @title }
-    #       }
-    #       body {
-    #         emit_yield
-    #       }
-    #     }
-    #   }
-    #
-    #   html.render {
-    #     @title = 'My super page'
-    #     h1 'content'
-    #   }
-    #
-    # @param &block [Proc] Deferred block to be emitted
-    # @return [void]
-    def defer(&block)
-      if !@parts
-        @parts = [@buffer, block]
-      else
-        @parts << @buffer unless @buffer.empty?
-        @parts << block
-      end
-      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
-    end
     
-    S_LT              = '<'
-    S_GT              = '>'
-    S_LT_SLASH        = '</'
-    S_SPACE_LT_SLASH  = ' </'
-    S_SLASH_GT        = '/>'
-    S_SPACE           = ' '
-    S_EQUAL_QUOTE     = '="'
-    S_QUOTE           = '"'
-
-    # Emits text into the rendering buffer, escaping any special characters to
-    # the respective HTML entities.
-    #
-    # @param data [String] text
-    # @return [void]
-    def text(data)
-      @buffer << escape_text(data)
-    end
-
     private
 
-    # Escapes text. This method must be overriden in descendant classes.
-    #
-    # @param text [String] text to be escaped
-    def escape_text(text)
-      raise NotImplementedError
-    end
-
     # Pushes the given block onto the emit_yield stack.
     #
     # @param block [Proc] block
     def push_emit_yield_block(block)
       (@emit_yield_stack ||= []) << block
     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 :src, :href
-          @buffer << S_SPACE << k.to_s << S_EQUAL_QUOTE <<
-            EscapeUtils.escape_uri(v) << S_QUOTE
-        else
-          case v
-          when true
-            @buffer << S_SPACE << k.to_s.tr('_', '-')
-          when false, nil
-            # emit nothing
-          else
-            @buffer << S_SPACE << k.to_s.tr('_', '-') <<
-              S_EQUAL_QUOTE << v << S_QUOTE
-          end
-        end
-      }
-    end
-
-    # Renders a deferred proc by evaluating it, then adding the rendered result
-    # to the buffer.
-    #
-    # @param &block [Proc] deferred proc
-    # @return [void]
-    def render_deferred_proc(&block)
-      old_buffer = @buffer
-      
-      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
-      @parts = nil
-
-      instance_eval(&block)
-
-      old_buffer << to_s
-      @buffer = old_buffer
-    end
   end
 
   # Implements an HTML renderer
   class HTMLRenderer < Renderer
     include HTML
-
-    private
-
-    # Escapes the given text using HTML entities.
-    def escape_text(text)
-      EscapeUtils.escape_html(text.to_s)
-    end
   end
 
   # Implements an XML renderer
   class XMLRenderer < Renderer
-    private
-
-    # Escapes the given text using XML entities.
-    def escape_text(text)
-      EscapeUtils.escape_xml(text.to_s)
-    end
+    include XML
   end
 
+  # Implements a JSON renderer
   class JSONRenderer < Renderer
     include JSON
   end

data/lib/papercraft/tags.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+module Papercraft  
+  # Markup (HTML/XML) extensions
+  module Tags
+    S_LT              = '<'
+    S_GT              = '>'
+    S_LT_SLASH        = '</'
+    S_SPACE_LT_SLASH  = ' </'
+    S_SLASH_GT        = '/>'
+    S_SPACE           = ' '
+    S_EQUAL_QUOTE     = '="'
+    S_QUOTE           = '"'
+
+    # The tag method template below is optimized for performance. Do not touch!
+
+    S_TAG_METHOD_LINE = __LINE__ + 2
+    S_TAG_METHOD = <<~EOF
+      S_TAG_%<TAG>s_PRE = %<tag_pre>s
+      S_TAG_%<TAG>s_CLOSE = %<tag_close>s
+
+      def %<tag>s(text = nil, **props, &block)
+        if text.is_a?(Hash) && props.empty?
+          props = text
+          text = nil
+        end
+
+        @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 Proc === text
+          @buffer << S_GT
+          emit(text)
+          @buffer << S_TAG_%<TAG>s_CLOSE
+        elsif text
+          @buffer << S_GT << escape_text(text.to_s) << S_TAG_%<TAG>s_CLOSE
+        else
+          @buffer << S_SLASH_GT
+        end
+      end
+    EOF
+
+    INITIAL_BUFFER_CAPACITY = 8192
+
+    # Initializes a tag renderer.
+    def initialize(&template)
+      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
+      super
+    end
+
+    # Returns the rendered template.
+    #
+    # @return [String]
+    def to_s
+      if @parts
+        last = @buffer
+        @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
+        parts = @parts
+        @parts = nil
+        parts.each do |p|
+          if Proc === p
+            render_deferred_proc(&p)
+          else
+            @buffer << p
+          end
+        end
+        @buffer << last unless last.empty?
+      end
+      @buffer
+    end
+
+    # Defers the given block to be evaluated later. Deferred evaluation allows
+    # Papercraft templates to inject state into sibling components, regardless
+    # of the component's order in the container component. For example, a nested
+    # component may set an instance variable used by another component. This is
+    # an elegant solution to the problem of setting the XML page's title, or
+    # adding elements to the `<head>` section. Here's how a title can be
+    # controlled from a nested component:
+    #
+    #   layout = Papercraft.html {
+    #     html {
+    #       head {
+    #         defer { title @title }
+    #       }
+    #       body {
+    #         emit_yield
+    #       }
+    #     }
+    #   }
+    #
+    #   html.render {
+    #     @title = 'My super page'
+    #     h1 'content'
+    #   }
+    #
+    # @param &block [Proc] Deferred block to be emitted
+    # @return [void]
+    def defer(&block)
+      if !@parts
+        @parts = [@buffer, block]
+      else
+        @parts << @buffer unless @buffer.empty?
+        @parts << block
+      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
+    # have method names that clash with XML tags, such as `button` or `a`, or
+    # when you need to override the behaviour of a particular XML tag.
+    #
+    # The following two method calls have the same effect:
+    #
+    # button 'text', id: 'button1'
+    # tag :button, 'text', id: 'button1'
+    #
+    # @param sym [Symbol, String] XML tag
+    # @param text [String, nil] tag content
+    # @param **props [Hash] tag attributes
+    # @param &block [Proc] optional inner XML
+    # @return [void]
+    def tag(sym, text = nil, **props, &block)
+      if text.is_a?(Hash) && props.empty?
+        props = text
+        text = nil
+      end
+
+      tag = tag_repr(sym)
+
+      @buffer << S_LT << tag
+      emit_props(props) unless props.empty?
+
+      if block
+        @buffer << S_GT
+        instance_eval(&block)
+        @buffer << S_LT_SLASH << tag << S_GT
+      elsif Proc === text
+        @buffer << S_GT
+        emit(text)
+        @buffer << S_LT_SLASH << tag << S_GT
+      elsif text
+        @buffer << S_GT << escape_text(text.to_s) << S_LT_SLASH << tag << S_GT
+      else
+        @buffer << S_SLASH_GT
+      end
+    end
+
+    # Catches undefined tag method call and handles it by defining the method.
+    #
+    # @param sym [Symbol] XML tag or component identifier
+    # @param args [Array] method arguments
+    # @param opts [Hash] named method arguments
+    # @param &block [Proc] block passed to method
+    # @return [void]
+    def method_missing(sym, *args, **opts, &block)
+      tag = sym.to_s
+      repr = tag_repr(tag)
+      code = S_TAG_METHOD % {
+        tag: tag,
+        TAG: tag.upcase,
+        tag_pre: "<#{repr}".inspect,
+        tag_close: "</#{repr}>".inspect
+      }
+      self.class.class_eval(code, __FILE__, S_TAG_METHOD_LINE)
+      send(sym, *args, **opts, &block)
+    end
+
+    # Emits text into the rendering buffer, escaping any special characters to
+    # the respective XML entities.
+    #
+    # @param data [String] text
+    # @return [void]
+    def text(data)
+      @buffer << escape_text(data)
+    end
+
+    private
+
+    # Emits an arbitrary object by converting it to string, then adding it to
+    # the internal buffer. This method is called internally by `Renderer#emit`.
+    #
+    # @param obj [Object] emitted object
+    # @return [void]
+    def emit_object(obj)
+      @buffer << obj.to_s
+    end
+
+    # Renders a deferred proc by evaluating it, then adding the rendered result
+    # to the buffer.
+    #
+    # @param &block [Proc] deferred proc
+    # @return [void]
+    def render_deferred_proc(&block)
+      old_buffer = @buffer
+      
+      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
+      @parts = nil
+
+      instance_eval(&block)
+
+      old_buffer << to_s
+      @buffer = old_buffer
+    end
+
+    # Escapes text. This method must be overriden in Renderers which include
+    # this module.
+    #
+    # @param text [String] text to be escaped
+    def escape_text(text)
+      raise NotImplementedError
+    end
+
+    # Converts a tag to its string representation. This method must be overriden
+    # in Renderers which include this module.
+    #
+    # @param tag [Symbol, String] tag
+    def tag_repr(tag)
+      raise NotImplementedError
+    end
+
+    # Converts an attribute to its string representation. This method must be
+    # overriden in Renderers which include this module.
+    #
+    # @param att [Symbol, String] attribute
+    def att_repr(att)
+      raise NotImplementedError
+    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 :src, :href
+          @buffer << S_SPACE << k.to_s << S_EQUAL_QUOTE <<
+            EscapeUtils.escape_uri(v) << S_QUOTE
+        else
+          case v
+          when true
+            @buffer << S_SPACE << att_repr(k)
+          when false, nil
+            # emit nothing
+          else
+            @buffer << S_SPACE << att_repr(k) <<
+              S_EQUAL_QUOTE << v << S_QUOTE
+          end
+        end
+      }
+    end
+  end
+end

data/lib/papercraft/template.rb

@@ -167,6 +167,9 @@ module Papercraft
       end
     end
 
+    # Returns the template's associated MIME type.
+    #
+    # @return [String] MIME type
     def mime_type
       @mime_type
     end

data/lib/papercraft/version.rb

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

data/lib/papercraft/xml.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'escape_utils'
+require_relative './tags'
+
+module Papercraft  
+  # XML renderer extensions
+  module XML
+    include Tags
+
+    private
+
+    # Converts a tag to its string representation. Underscores will be converted
+    # to dashes, double underscores will be converted to colon.
+    #
+    # @param tag [Symbol, String] tag
+    # @return [String] tag string
+    def tag_repr(tag)
+      tag.to_s.gsub('__', ':').tr('_', '-')
+    end
+
+    # Converts an attribute to its string representation. Underscores will be
+    # converted to dashes, double underscores will be converted to colon.
+    #
+    # @param att [Symbol, String] attribute
+    # @return [String] attribute string
+    def att_repr(att)
+      att.to_s.gsub('__', ':').tr('_', '-')
+    end
+
+    # Escapes the given text using XML entities.
+    #
+    # @param text [String] text
+    # @return [String] escaped text
+    def escape_text(text)
+      EscapeUtils.escape_xml(text.to_s)
+    end
+  end
+end

data/lib/papercraft.rb

@@ -6,7 +6,6 @@ require 'kramdown-parser-gfm'
 
 require_relative 'papercraft/template'
 require_relative 'papercraft/renderer'
-require_relative 'papercraft/encoding'
 # require_relative 'papercraft/compiler'
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '0.19'
+  version: '0.23'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-02-05 00:00:00.000000000 Z
+date: 2022-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils
@@ -134,13 +134,15 @@ files:
 - README.md
 - lib/papercraft.rb
 - lib/papercraft/compiler.rb
-- lib/papercraft/encoding.rb
 - lib/papercraft/extension_proxy.rb
+- lib/papercraft/extensions/soap.rb
 - lib/papercraft/html.rb
 - lib/papercraft/json.rb
 - lib/papercraft/renderer.rb
+- lib/papercraft/tags.rb
 - lib/papercraft/template.rb
 - lib/papercraft/version.rb
+- lib/papercraft/xml.rb
 - papercraft.png
 homepage: http://github.com/digital-fabric/papercraft
 licenses:

data/lib/papercraft/encoding.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-module Papercraft
-  # Papercraft::Encoding includes common encoding methods
-  module Encoding
-    # Encodes the given string to safe HTML text, converting special characters
-    # into the respective HTML entities. If a non-string value is given, it is
-    # converted to `String` using `#to_s`.
-    #
-    # @param text [String] string to be encoded
-    # @return [String] HTML-encoded string
-    def __html_encode__(text)
-      EscapeUtils.escape_html(text.to_s)
-    end
-
-    # Encodes the given string to safe URI component, converting special
-    # characters to URI entities. If a non-string value is given, it is
-    # converted to `String` using `#to_s`.
-    #
-    # @param text [String] string to be encoded
-    # @return [String] URI-encoded string
-    def __uri_encode__(text)
-      EscapeUtils.escape_uri(text.to_s)
-    end
-  end
-end