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

papercraft 0.16 → 0.20

Files changed (12) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +19 -0
data/README.md +145 -53
data/lib/papercraft/html.rb +7 -34
data/lib/papercraft/renderer.rb +11 -155
data/lib/papercraft/tags.rb +152 -0
data/lib/papercraft/{component.rb → template.rb} +26 -26
data/lib/papercraft/version.rb +1 -1
data/lib/papercraft/xml.rb +26 -0
data/lib/papercraft.rb +96 -59
data/papercraft.png +0 -0
metadata +7 -3

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 996d95088c85415ca883c27b6b1c98e65af5c046e3121ea08f092ac7bcdcc588
-  data.tar.gz: 8fe294225c04dcfc82289fd2b9047760260b814712e83e9bf5ea7d361dad6950
+  metadata.gz: 2eaf6ba31b9300176af0bf55b76f7bbdc16508d0e495ed1d76f9f273ea88f250
+  data.tar.gz: 90e132928ebfe78e577e71c8dc498f0ce1b1f2c58f453fbedaad96121c448a48
 SHA512:
-  metadata.gz: 54fdbe164a4a2541153e57b90cdb35ba71b6887fbe2d199505da3389730f1bd937fe0254f8c019b39d81957058c5f51ad71bc900f324e3178b979f368642ee57
-  data.tar.gz: fa05ea9ae79a57a3eace2e708b01fe5f44412591875776cf1a2fe95cc6d9d1586357756e702e8a17e5458b3fa4c3e3224290bc234b71fdcd426db0dedff31dc0
+  metadata.gz: fcada325a3f8cd1c4cbe38674efaf6a86d0eb947ad5815d07778e2a09a54bee2c7d6b731e87d110390e9c87abc0a61f81cbc4cb30fdce11a4fc8a8cd322466a0
+  data.tar.gz: 031c86f7dade95af3dca979b4543fcb26e1fab2eb98c5642746d6efcf8b4bd56fe30b70f2f5aa8309352f421cae9f116a901f464216f54a0be50630dcc52815f

data/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,22 @@
+## 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`
+## 0.18 2022-02-04
+- Cleanup and update examples
+- Fix behaviour of #emit with block
+- Improve README
+## 0.17 2022-01-23
+- Refactor markdown code, add `Papercraft.markdown` method (#8)
 ## 0.16 2022-01-23
 - Implement JSON templating (#7)

data/README.md CHANGED Viewed

@@ -24,35 +24,63 @@
 ## What is Papercraft?
+Papercraft is a templating engine for dynamically producing HTML, XML or JSON.
+Papercraft templates are expressed in plain Ruby, leading to easier debugging,
+better protection against HTML/XML injection attacks, and better code reuse.
+Papercraft templates can be composed in a variety of ways, facilitating the
+usage of layout templates, and enabling a component-oriented approach to
+building complex web interfaces.
+In Papercraft, dynamic data is passed explicitly to the template as block
+arguments, making the data flow easy to follow and understand. Papercraft also
+lets developers create derivative templates using full or partial parameter
+application.
+Papercraft includes built-in support for rendering Markdown (using
+[Kramdown](https://github.com/gettalong/kramdown/)), as well as support for
+creating template extensions in order to allow the creation of component
+libraries.
 ```ruby
 require 'papercraft'
 page = Papercraft.html { |*args|
   html {
-    head { }
+    head { title 'Title' }
     body { emit_yield *args }
   }
 }
 page.render { p 'foo' }
-#=> "<html><head/><body><p>foo</p></body></html>"
+#=> "<html><head><title>Title</title></head><body><p>foo</p></body></html>"
 hello = page.apply { |name| h1 "Hello, #{name}!" }
 hello.render('world')
-#=> "<html><head/><body><h1>Hello, world!</h1></body></html>"
-```
-Papercraft is a templating engine for Ruby that offers the following features:
-- 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)
-- Support for namespaced extensions
+#=> "<html><head><title>Title</title></head><body><h1>Hello, world!</h1></body></html>"
+```
+## Table of content
+- [Installing papercraft](#installing-papercraft)
+- [Basic usage](#basic-usage)
+- [Adding tags](#adding-tags)
+- [Template parameters](#template-parameters)
+- [Template logic](#template-logic)
+- [Template blocks](#template-blocks)
+- [Plain procs as templates](#plain-procs-as-templates)
+- [Template composition](#template-composition)
+- [Parameter and block application](#parameter-and-block-application)
+- [Higher-order templates](#higher-order-templates)
+- [Layout template composition](#layout-template-composition)
+- [Emitting raw HTML](#emitting-raw-html)
+- [Emitting a string with HTML Encoding](#emitting-a-string-with-html-encoding)
+- [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)
+- [API Reference](#api-reference)
 ## Installing Papercraft
@@ -68,9 +96,9 @@ Or manually:
 $ gem install papercraft
 ```
-## Getting started
+## Basic usage
-To create a template use the global method `Kernel#H`:
+To create an HTML template use `Papercraft.html`:
 ```ruby
 require 'papercraft'
@@ -80,13 +108,16 @@ html = Papercraft.html {
 }
 ```
+(You can also use `Papercraft.xml` and `Papercraft.json` to create XML and JSON
+templates, respectively.)
 Rendering a template is done using `#render`:
 ```ruby
 html.render #=> "<div id="greeter"><p>Hello!</p></div>"
 ```
-## All about tags
+## Adding tags
 Tags are added using unqualified method calls, and can be nested using blocks:
@@ -141,7 +172,7 @@ greeting = Papercraft.html { |name:| h1 "Hello, #{name}!" }
 greeting.render(name: 'world') #=> "<h1>Hello, world!</h1>"
 ```
-## Logic in templates
+## Template logic
 Since Papercraft templates are just a bunch of Ruby, you can easily write your
 view logic right in the template:
@@ -171,10 +202,10 @@ page = Papercraft.html {
 page.render { h1 'hi' }
 ```
-## Plain procs as components
+## Plain procs as templates
 With Papercraft you can write a template as a plain Ruby proc, and later render
-it by passing it as a block to `H`:
+it by passing it as a block to `Papercraft.html`:
 ```ruby
 greeting = proc { |name| h1 "Hello, #{name}!" }
@@ -188,10 +219,10 @@ greeting = ->(name) { h1 "Hello, #{name}!" }
 Papercraft.html(&greeting).render('world')
 ```
-## Component composition
+## Template composition
-Papercraft makes it easy to compose multiple components into a whole HTML
-document. A Papercraft component can contain other components, as the following
+Papercraft makes it easy to compose multiple templates into a whole HTML
+document. A Papercraft template can contain other templates, as the following
 example shows.
 ```ruby
@@ -219,14 +250,14 @@ page = Papercraft.html { |title, items|
   }
 }
-page.render('Hello from components', [
+page.render('Hello from composed templates', [
   { id: 1, text: 'foo', checked: false },
   { id: 2, text: 'bar', checked: true }
 ])
 ```
-In addition to using components defined as constants, you can also use
-non-constant components by invoking the `#emit` method:
+In addition to using templates defined as constants, you can also use
+non-constant templates by invoking the `#emit` method:
 ```ruby
 greeting = -> { span "Hello, world" }
@@ -241,11 +272,11 @@ Papercraft.html {
 ## Parameter and block application
 Parameters and blocks can be applied to a template without it being rendered, by
-using `#apply`. This mechanism is what allows component composition and the
-creation of higher-order components.
+using `#apply`. This mechanism is what allows template composition and the
+creation of higher-order templates.
-The `#apply` method returns a new component which applies the given parameters and
-or block to the original component:
+The `#apply` method returns a new template which applies the given parameters and
+or block to the original template:
 ```ruby
 # parameter application
@@ -258,19 +289,19 @@ div_wrap = Papercraft.html { div { emit_yield } }
 wrapped_h1 = div_wrap.apply { h1 'hi' }
 wrapped_h1.render #=> "<div><h1>hi</h1></div>"
-# wrap a component
+# wrap a template
 wrapped_hello_world = div_wrap.apply(&hello_world)
 wrapped_hello_world.render #=> "<div><h1>Hello, world!</h1></div>"
 ```
-## Higher-order components
+## Higher-order templates
-Papercraft also lets you create higher-order components (HOCs), that is,
-components that take other components as parameters, or as blocks. Higher-order
-components are handy for creating layouts, wrapping components in arbitrary
-markup, enhancing components or injecting component parameters.
+Papercraft also lets you create higher-order templates, that is,
+templates that take other templates as parameters, or as blocks. Higher-order
+templates are handy for creating layouts, wrapping templates in arbitrary
+markup, enhancing templates or injecting template parameters.
-Here is a HOC that takes a component as parameter:
+Here is a higher-order template that takes a template as parameter:
 ```ruby
 div_wrap = Papercraft.html { |inner| div { emit inner } }
@@ -279,7 +310,7 @@ wrapped_greeter = div_wrap.apply(greeter)
 wrapped_greeter.render #=> "<div><h1>hi</h1></div>"
 ```
-The inner component can also be passed as a block, as shown above:
+The inner template can also be passed as a block, as shown above:
 ```ruby
 div_wrap = Papercraft.html { div { emit_yield } }
@@ -289,7 +320,7 @@ wrapped_greeter.render #=> "<div><h1>hi</h1></div>"
 ## Layout template composition
-One of the principal uses of higher-order components is the creation of nested
+One of the principal uses of higher-order templates is the creation of nested
 layouts. Suppose we have a website with a number of different layouts, and we'd
 like to avoid having to repeat the same code in the different layouts. We can do
 this by creating a `default` page template that takes a block, then use `#apply`
@@ -358,6 +389,14 @@ template = Papercraft.html { |md| div { emit_markdown md, auto_ids: false } }
 template.render("# title") #=> "<div><h1>title</h1></div>"
 ```
+The `#emit_markdown` method is available only to HTML templates. If you need to
+render markdown in XML or JSON templates (usually for implementing RSS or JSON
+feeds), you can use `Papercraft.markdown` directly:
+```ruby
+Papercraft.markdown('# title') #=> "<h1>title</h1>"
+```
 The default Kramdown options are:
 ```ruby
@@ -370,17 +409,33 @@ The default Kramdown options are:
 ```
 The deafult options can be configured by accessing
-`Papercraft::HTML.kramdown_options`, e.g.:
+`Papercraft.default_kramdown_options`, e.g.:
+```ruby
+Papercraft.default_kramdown_options[:auto_ids] = false
+```
+## Working with MIME types
+Papercraft lets you set and interrogate a template's MIME type, in order to be
+able to dynamically set the `Content-Type` HTTP response header. A template's
+MIME type can be set when creating the template, e.g. `Papercraft.xml(mime_type:
+'application/rss+xml')`. You can interrogate the template's MIME type using
+`#mime_type`:
 ```ruby
-Papercraft::HTML.kramdown_options[:auto_ids] = false
+# using Qeweney (https://github.com/digital-fabric/qeweney)
+def serve_template(req, template)
+  body = template.render
+  respond(body, 'Content-Type' => template.mime_type)
+end
 ```
 ## Deferred evaluation
 Deferred evaluation allows deferring the rendering of parts of a template until
-the last moment, thus allowing an inner component to manipulate the state of the
-outer component. To in order to defer a part of a template, use `#defer`, and
+the last moment, thus allowing an inner template to manipulate the state of the
+outer template. To in order to defer a part of a template, use `#defer`, and
 include any markup in the provided block. This technique, in in conjunction with
 holding state in instance variables, is an alternative to passing parameters,
 which can be limiting in some situations.
@@ -389,11 +444,11 @@ A few use cases for deferred evaulation come to mind:
 - Setting the page title.
 - Adding a flash message to a page.
-- Using components that dynamically add static dependencies (JS and CSS) to the
+- Using templates that dynamically add static dependencies (JS and CSS) to the
   page.
 The last use case is particularly interesting. Imagine a `DependencyMananger`
-class that can collect JS and CSS dependencies from the different components
+class that can collect JS and CSS dependencies from the different templates
 integrated into the page, and adds them to the page's `<head>` element:
 ```ruby
@@ -494,11 +549,47 @@ Papercraft.html {
 }
 ```
-## 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:
+## 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 {
@@ -523,7 +614,8 @@ Papercraft.json {
 }.render #=> "{\"foo\":{\"bar\":[null,true,123.456]}}"
 ```
-Papercraft uses the [JSON gem](https://rubyapi.org/3.1/o/json) under the hood.
+Papercraft uses the [JSON gem](https://rubyapi.org/3.1/o/json) under the hood in
+order to generate actual JSON.
 ## API Reference

data/lib/papercraft/html.rb CHANGED Viewed

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
-require 'kramdown'
-require 'rouge'
-require 'kramdown-parser-gfm'
+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
@@ -83,41 +83,14 @@ module Papercraft
     # @param **opts [Hash] Kramdown options
     # @return [void]
     def emit_markdown(markdown, **opts)
-      emit Kramdown::Document.new(markdown, **kramdown_options(opts)).to_html
-    end
-    class << self
-      # Returns the default Kramdown options used for converting Markdown to
-      # HTML.
-      #
-      # @return [Hash] Default Kramdown options
-      def kramdown_options
-        @kramdown_options ||= {
-          entity_output: :numeric,
-          syntax_highlighter: :rouge,
-          input: 'GFM',
-          hard_wrap: false
-        }
-      end
-      # Sets the default Kramdown options used for converting Markdown to
-      # HTML.
-      #
-      # @param opts [Hash] New deafult Kramdown options
-      # @return [Hash] New default Kramdown options
-      def kramdown_options=(opts)
-        @kramdown_options = opts
-      end
+      emit Papercraft.markdown(markdown, **opts)
     end
     private
-    # Returns the default Kramdown options, merged with the given overrides.
-    #
-    # @param opts [Hash] Kramdown option overrides
-    # @return [Hash] Merged Kramdown options
-    def kramdown_options(opts)
-      HTML.kramdown_options.merge(**opts)
+    # Escapes the given text using XML entities.
+    def escape_text(text)
+      EscapeUtils.escape_html(text.to_s)
     end
   end
 end

data/lib/papercraft/renderer.rb CHANGED Viewed

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 require_relative './html'
+require_relative './xml'
 require_relative './json'
 require_relative './extension_proxy'
 module Papercraft
-  # A Renderer renders a Papercraft component into a string
+  # 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
@@ -41,9 +42,9 @@ module Papercraft
       #
       # Installs the given extensions, passed in the form of a Ruby hash mapping
       # methods to extension modules. The methods will be available to all
-      # Papercraft components. Extension methods are executed in the context of
+      # 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
@@ -111,99 +112,6 @@ module Papercraft
       @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,
@@ -217,14 +125,15 @@ module Papercraft
     #
     #   Papercraft.html { emit nil }.render #=> ""
     #
-    # @param o [Proc, Papercraft::Component, String] emitted object
+    # @param o [Proc, Papercraft::Template, String] emitted object
     # @param *a [Array<any>] arguments to pass to a proc
     # @param **b [Hash] named arguments to pass to a proc
     # @return [void]
-    def emit(o, *a, **b)
+    def emit(o, *a, **b, &block)
       case o
       when ::Proc
         Renderer.verify_proc_parameters(o, a, b)
+        push_emit_yield_block(block) if block
         instance_exec(*a, **b, &o)
       when nil
       else
@@ -250,10 +159,10 @@ module Papercraft
     end
     # Defers the given block to be evaluated later. Deferred evaluation allows
-    # Papercraft components to inject state into sibling components, regardless
+    # 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
+    # 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:
     #
@@ -285,24 +194,6 @@ module Papercraft
       @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.
@@ -319,29 +210,6 @@ module Papercraft
       (@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.
     #
@@ -363,23 +231,11 @@ module Papercraft
   # 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
   class JSONRenderer < Renderer

data/lib/papercraft/tags.rb ADDED Viewed

@@ -0,0 +1,152 @@
+# 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
+    # 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)
+      # p method_missing: sym, self: self
+      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
+    def tag_repr(tag)
+      tag.to_s.tr('_', '-')
+    end
+    def att_repr(att)
+      att.to_s.tr('_', '-')
+    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/{component.rb → template.rb} RENAMED Viewed

@@ -4,30 +4,30 @@ require_relative './html'
 module Papercraft
-  # Component represents a distinct, reusable HTML template. A component can
-  # include other components, and also be nested inside other components.
+  # Template represents a distinct, reusable HTML template. A template can
+  # include other templates, and also be nested inside other templates.
   #
-  # Since in Papercraft HTML is expressed using blocks (or procs,) the Component
+  # Since in Papercraft HTML is expressed using blocks (or procs,) the Template
   # 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 class methods `html`, `xml` or
+  # Templates are usually created using the class methods `html`, `xml` or
   # `json`, for HTML, XML or JSON templates, respectively:
   #
   #   greeter = Papercraft.html { |name| h1 "Hello, #{name}!" }
   #   greeter.render('world') #=> "<h1>Hello, world!</h1>"
   #
-  # Components can also be created using the normal constructor:
+  # Templates can also be created using the normal constructor:
   #
-  #   greeter = Papercraft::Component.new(mode: :html) { |name| h1 "Hello, #{name}!" }
+  #   greeter = Papercraft::Template.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
+  # The different methods for creating templates 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
+  # In the template block, HTML elements are created by simply calling
   # unqualified methods:
   #
   #   page_layout = Papercraft.html {
@@ -41,20 +41,20 @@ module Papercraft
   #     }
   #   }
   #
-  # Papercraft components can take explicit parameters in order to render
+  # Papercraft templates can take explicit parameters in order to render
   # dynamic content. This can be in the form of regular or named parameters. The
   # `greeter` template shown above takes a single `name` parameter. Here's how a
-  # anchor component could be implemented with named parameters:
+  # anchor template could be implemented with named parameters:
   #
   #   anchor = Papercraft.html { |uri: , text: | a(text, href: uri) }
   #
-  # The above component could later be rendered by passing the needed arguments:
+  # The above template could later be rendered by passing the needed arguments:
   #
   #   anchor.render(uri: 'https://example.com', text: 'Example')
   #
-  # ## Component Composition
+  # ## Template Composition
   #
-  # A component can be included in another component using the `emit` method:
+  # A template can be included in another template using the `emit` method:
   #
   #   links = Papercraft.html {
   #     emit anchor, uri: '/posts',   text: 'Posts'
@@ -62,7 +62,7 @@ module Papercraft
   #     emit anchor, uri: '/about',   text: 'About'
   #   }
   #
-  # Another way of composing components is to pass the components themselves as
+  # Another way of composing templates is to pass the templates themselves as
   # parameters:
   #
   #   links = Papercraft.html { |anchors|
@@ -74,8 +74,8 @@ module Papercraft
   #     anchor.apply(uri: '/about', text: 'About')
   #   ])
   #
-  # The `#apply` method creates a new component, applying the given parameters
-  # such that the component can be rendered without parameters:
+  # The `#apply` method creates a new template, applying the given parameters
+  # such that the template can be rendered without parameters:
   #
   #   links_with_anchors = links.apply([
   #     anchor.apply(uri: '/posts', text: 'Posts'),
@@ -84,7 +84,7 @@ module Papercraft
   #   ])
   #   links_with_anchors.render
   #
-  class Component < Proc
+  class Template < Proc
     # Determines the rendering mode: `:html` or `:xml`.
     attr_accessor :mode
@@ -95,12 +95,12 @@ module Papercraft
       json: 'application/json'
     }.freeze
-    # Initializes a component with the given block. The rendering mode (HTML or
+    # Initializes a template 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.
+    # the template defaults to HTML.
     #
     # @param mode [:html, :xml] rendering mode
-    # @param mime_type [String, nil] the component's mime type (nil for default)
+    # @param mime_type [String, nil] the template's mime type (nil for default)
     # @param block [Proc] nested HTML block
     def initialize(mode: :html, mime_type: nil, &block)
       @mode = mode
@@ -124,9 +124,9 @@ module Papercraft
       end.to_s
     end
-    # Creates a new component, applying the given parameters and or block to the
+    # Creates a new template, applying the given parameters and or block to the
     # current one. Application is one of the principal methods of composing
-    # components, particularly when passing inner components as blocks:
+    # templates, particularly when passing inner templates as blocks:
     #
     #   article_wrapper = Papercraft.html {
     #     article {
@@ -141,19 +141,19 @@ module Papercraft
     # @param *a [<any>] normal parameters
     # @param **b [Hash] named parameters
     # @param &block [Proc] inner block
-    # @return [Papercraft::Component] applied component
+    # @return [Papercraft::Template] applied template
     def apply(*a, **b, &block)
       template = self
-      Component.new(mode: @mode, mime_type: @mime_type, &proc do |*x, **y|
+      Template.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)
     end
     # Returns the Renderer class used for rendering the templates, according to
-    # the component's mode.
+    # the template's mode.
     #
-    # @return [Papercraft::Renderer] Renderer used for rendering the component
+    # @return [Papercraft::Renderer] Renderer used for rendering the template
     def renderer_class
       case @mode
       when :html

data/lib/papercraft/version.rb CHANGED Viewed

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

data/lib/papercraft/xml.rb ADDED Viewed

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+require 'escape_utils'
+require_relative './tags'
+module Papercraft
+  # XML renderer extensions
+  module XML
+    include Tags
+    private
+    def tag_repr(tag)
+      tag.to_s.gsub('__', ':').tr('_', '-')
+    end
+    def att_repr(att)
+      att.to_s.gsub('__', ':').tr('_', '-')
+    end
+    # Escapes the given text using XML entities.
+    def escape_text(text)
+      EscapeUtils.escape_xml(text.to_s)
+    end
+  end
+end

data/lib/papercraft.rb CHANGED Viewed

@@ -1,73 +1,110 @@
 # frozen_string_literal: true
-require 'escape_utils'
+require 'kramdown'
+require 'rouge'
+require 'kramdown-parser-gfm'
-require_relative 'papercraft/component'
+require_relative 'papercraft/template'
 require_relative 'papercraft/renderer'
 require_relative 'papercraft/encoding'
 # require_relative 'papercraft/compiler'
-# Papercraft is a component-based HTML templating library
+# Papercraft is a composable templating library
 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
+    # module can be used to render a specific HTML element or a set of elements.
+    #
+    # This is a convenience method. For more information on using Papercraft
+    # extensions, see `Papercraft::Renderer::extension`
+    #
+    # @param map [Hash] hash mapping methods to extension modules
+    # @return [void]
+    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`.
+    #
+    # Papercraft.html(proc { h1 'hi' }).render #=> "<h1>hi</h1>"
+    # Papercraft.html { h1 'hi' }.render #=> "<h1>hi</h1>"
+    #
+    # @param template [Proc] template block
+    # @return [Papercraft::Template] Papercraft template
+    def html(o = nil, mime_type: nil, &template)
+      return o if o.is_a?(Papercraft::Template)
+      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`.
+    #
+    # Papercraft.xml(proc { item 'foo' }).render #=> "<item>foo</item>"
+    # Papercraft.xml { item 'foo' }.render #=> "<item>foo</item>"
+    #
+    # @param template [Proc] template block
+    # @return [Papercraft::Template] Papercraft template
+    def xml(o = nil, mime_type: nil, &template)
+      return o if o.is_a?(Papercraft::Template)
+      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`.
+    #
+    # Papercraft.json(proc { item 42 }).render #=> "[42]"
+    # Papercraft.json { foo 'bar' }.render #=> "{\"foo\": \"bar\"}"
+    #
+    # @param template [Proc] template block
+    # @return [Papercraft::Template] Papercraft template
+    def json(o = nil, mime_type: nil, &template)
+      return o if o.is_a?(Papercraft::Template)
+      template ||= o
+      Papercraft::Template.new(mode: :json, mime_type: mime_type, &template)
+    end
-  # 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
-  # module can be used to render a specific HTML element or a set of elements.
-  #
-  # This is a convenience method. For more information on using Papercraft
-  # extensions, see `Papercraft::Renderer::extension`
-  #
-  # @param map [Hash] hash mapping methods to extension modules
-  # @return [void]
-  def self.extension(map)
-    Renderer.extension(map)
-  end
-  # 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`.
-  #
-  # 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 self.xml(o = nil, mime_type: nil, &template)
-    return o if o.is_a?(Papercraft::Component)
-    template ||= o
-    Papercraft::Component.new(mode: :xml, mime_type: mime_type, &template)
-  end
+    # Renders Markdown into HTML. The `opts` argument will be merged with the
+    # default Kramdown options in order to change the rendering behaviour.
+    #
+    # @param markdown [String] Markdown
+    # @param **opts [Hash] Kramdown option overrides
+    # @return [String] HTML
+    def markdown(markdown, **opts)
+      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
+    def default_kramdown_options
+      @default_kramdown_options ||= {
+        entity_output: :numeric,
+        syntax_highlighter: :rouge,
+        input: 'GFM',
+        hard_wrap: false
+      }
+    end
-  # 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`.
-  #
-  # 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 self.json(o = nil, mime_type: nil, &template)
-    return o if o.is_a?(Papercraft::Component)
-    template ||= o
-    Papercraft::Component.new(mode: :json, mime_type: mime_type, &template)
+    # Sets the default Kramdown options used for rendering Markdown.
+    #
+    # @param opts [Hash] Kramdown options
+    # @return [void]
+    def default_kramdown_options=(opts)
+      @default_kramdown_options = opts
+    end
   end
 end

data/papercraft.png ADDED Viewed

Binary file

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '0.16'
+  version: '0.20'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-23 00:00:00.000000000 Z
+date: 2022-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils
@@ -128,18 +128,22 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - README.md
+- papercraft.png
 files:
 - CHANGELOG.md
 - README.md
 - lib/papercraft.rb
 - lib/papercraft/compiler.rb
-- lib/papercraft/component.rb
 - lib/papercraft/encoding.rb
 - lib/papercraft/extension_proxy.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:
 - MIT