RubyGems - papercraft - Versions diffs - 0.8.1 → 0.10 - Mend

papercraft 0.8.1 → 0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +10 -0
data/README.md +132 -123
data/lib/papercraft/component.rb +93 -6
data/lib/papercraft/extension_proxy.rb +30 -0
data/lib/papercraft/html.rb +36 -4
data/lib/papercraft/renderer.rb +102 -41
data/lib/papercraft/version.rb +1 -1
data/lib/papercraft.rb +31 -11
metadata +45 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 944fb4023202a5fb15158b4dcd455eb12f37c5abff353f5ea63e3b605204f52b
-  data.tar.gz: 618aea8b154aff252af187bca43cdc569fae80a6c7a3ec6489b168d61a5ab7e4
+  metadata.gz: a7d34aa76efd449fc6a63182195e8353886887e13963b79439a19dc3b0f9a9d2
+  data.tar.gz: e199245d969426b75627401b7c57fe1a01e7121a656ece8cd97b004a22b3ab2e
 SHA512:
-  metadata.gz: d622166425334b096158ee425e75f4e4ad9c16c466db5aa7f45b51774137def33b4e4f891425bc917ee56b81fb91e39adc15c6f2476e009f3a4be4a73b295c74
-  data.tar.gz: 8546f39f7f6b08cc49049fae52db77891f7664b6ac6d8bce9c0a1a41f19bc0f8a92c59909ab4778cf15d6ef958f756bc6b6f392aa0c028a8d9ddd54bbee67afa
+  metadata.gz: 75d5dd94c26d1ee15b11f8a439ff1c26cd7336c60ce609e334f3c0e823e8813f67923b79e8f023e9d1bcc3f2af20b5fffc93196ba5731d1cea42b2e0f75f3102
+  data.tar.gz: 7bdcbfa67dabec451c00f006256b16b9875d60fc726d295135db5de94a5b8854e3bdf648410d6ef6e7a7b76766c6c07d21ebb4da9788cab45fcb67a8c9d6b221

data/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,13 @@
+## 0.10 2021-12-25
+- Add support for extensions
+## 0.9 2021-12-23
+- Add support for emitting Markdown
+- Add support for passing proc as argument to `#H` and `#X`
+- Deprecate `Encoding` module
 ## 0.8.1 2021-12-22
 - Fix gemspec

data/README.md CHANGED Viewed

@@ -1,30 +1,56 @@
-# Papercraft - Composable HTML templating for Ruby
+<h1 align="center">
+  Papercraft
+</h1>
+<h4 align="center">Composable HTML templating for Ruby</h4>
+<p align="center">
+  <a href="http://rubygems.org/gems/papercraft">
+    <img src="https://badge.fury.io/rb/papercraft.svg" alt="Ruby gem">
+  </a>
+  <a href="https://github.com/digital-fabric/papercraft/actions?query=workflow%3ATests">
+    <img src="https://github.com/digital-fabric/papercraft/workflows/Tests/badge.svg" alt="Tests">
+  </a>
+  <a href="https://github.com/digital-fabric/papercraft/blob/master/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
+  </a>
+</p>
+<p align="center">
+  <a href="https://www.rubydoc.info/gems/papercraft">API reference</a>
+</p>
-[INSTALL](#installing-papercraft) |
-[TUTORIAL](#getting-started) |
-[EXAMPLES](examples) |
-[REFERENCE](#api-reference)
+# Papercraft - Composable HTML templating for Ruby
 ## What is Papercraft?
+```ruby
+require 'papercraft'
+page = H { |*args|
+  html {
+    head { }
+    body { emit_yield *args }
+  }
+}
+hello = H.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:
-- HTML templating using plain Ruby syntax
+- HTML and XML templating using plain Ruby syntax
 - Minimal boilerplate
 - Mix logic and tags freely
-- Use global and local contexts to pass values to reusable components
-- Automatic HTML escaping
+- Automatic HTML and XML escaping
 - Composable components
+- Explicit parameter passing to nested components
 - Higher order components
-- Built-in support for rendering Markdown
-> **Note** Papercraft is a new library and as such may be missing features and
-> contain bugs. Also, its API may change unexpectedly. Your issue reports and
-> code contributions are most welcome!
-With Papercraft you can structure your templates as nested HTML components, in a
-somewhat similar fashion to React.
+- Built-in support for rendering [Markdown](#emitting-markdown)
+- Support for namespaced extensions
 ## Installing Papercraft
@@ -42,42 +68,25 @@ $ gem install papercraft
 ## Getting started
-To use Papercraft in your code just require it:
+To create a template use the global method `Kernel#H`:
 ```ruby
 require 'papercraft'
-```
-To create a template use `Papercraft.new` or the global method `Kernel#H`:
-```ruby
-# can also use Papercraft.new
 html = H {
-  div { p 'hello' }
+  div(id: 'greeter') { p 'Hello!' }
 }
 ```
-## Rendering a template
-To render a Papercraft template use the `#render` method:
+Rendering a template is done using `#render`:
 ```ruby
-H { span 'best span' }.render  #=> "<span>best span</span>"
-```
-The render method accepts an arbitrary context variable:
-```ruby
-html = H {
-  h1 context[:title]
-}
-html.render(title: 'My title') #=> "<h1>My title</h1>"
+html.render #=> "<div id="greeter"><p>Hello!</p></div>"
 ```
 ## All about tags
-Tags are added using unqualified method calls, and are nested using blocks:
+Tags are added using unqualified method calls, and can be nested using blocks:
 ```ruby
 H {
@@ -114,8 +123,9 @@ H { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</
 ## Template parameters
-Template parameters are specified as block parameters, and are passed to the
-template on rendering:
+In Papercraft, parameters are always passed explicitly. This means that template
+parameters are specified as block parameters, and are passed to the template on
+rendering:
 ```ruby
 greeting = H { |name| h1 "Hello, #{name}!" }
@@ -328,110 +338,109 @@ H { str 'hi&lo' }.render #=> "hi&amp;lo"
 ## Emitting Markdown
-To emit Markdown, use `#emit_markdown`:
+Markdown is rendered using the
+[Kramdown](https://kramdown.gettalong.org/index.html) gem. To emit Markdown, use
+`#emit_markdown`:
 ```ruby
 template = H { |md| div { emit_markdown md } }
-template.render("Here's some *Markdown*") #=> "<div>Here's some <em>Markdown</em></div>"
+template.render("Here's some *Markdown*") #=> "<div><p>Here's some <em>Markdown</em><p>\n</div>"
 ```
-## Some interesting use cases
-Papercraft opens up all kinds of new possibilities when it comes to putting
-together pieces of HTML. Feel free to explore the API!
+[Kramdown
+options](https://kramdown.gettalong.org/options.html#available-options) can be
+specified by adding them to the `#emit_markdown` call:
-### A higher-order list component
+```ruby
+template = H { |md| div { emit_markdown md, auto_ids: false } }
+template.render("# title") #=> "<div><h1>title</h1></div>"
+```
-Here's another demonstration of a higher-order component, a list component that
-takes an item component as an argument. The `List` component can be reused for
-rendering any kind of unordered list, and with any kind of item component:
+The default Kramdown options are:
 ```ruby
-List = ->(items, item_component) {
-  H {
-    ul {
-      items.each { |item|
-        with(item: item) {
-          li { emit item_component }
-        }
-      }
-    }
-  }
-}
-TodoItem = H {
-  span item.text, class: item.completed ? 'completed' : 'pending'
+{
+  entity_output: :numeric,
+  syntax_highlighter: :rouge,
+  input: 'GFM',
+  hard_wrap: false
 }
-def todo_list(items)
-  H {
-    div { List(items, TodoItem) }
-  }
-end
 ```
-## API Reference
-#### `Papercraft#initialize(**context, &block)` a.k.a. `Kernel#H`
-- `context`: local context hash
-- `block`: template block
-Initializes a new Papercraft instance. This method takes a block of template
-code, and an optional [local context](#local-context) in the form of a hash.
-The `Kernel#H` method serves as a shortcut for creating Papercraft instances.
-#### `Papercraft#render(**context)`
-- `context`: global context hash
-Renders the template with an optional [global context](#global-context)
-hash.
-#### Methods accessible inside template blocks
-#### `#<tag/component>(*args, **props, &block)`
-- `args`: tag arguments. For an HTML tag Papercraft expects a single `String`
-  argument containing the inner text of the tag.
-- `props`: hash of tag attributes
-- `block`: inner HTML block
-Adds a tag or component to the current template. If the method name starts with
-an upper-case letter, it is considered a [component](#templates-as-components).
-If a text argument is given for a tag, it will be escaped.
-#### `#cache(*vary, &block)`
-- `vary`: variables used in cached block. The given values will be used to
-  create a separate cache entry.
-- `block`: inner HTML block
+The deafult options can be configured by accessing
+`Papercraft::HTML.kramdown_options`:
-Caches the markup in the given block, storing it in the Papercraft cache store.
-If a cache entry for the given block is found, it will be used instead of
-invoking the block. If one or more variables given, those will be used to create
-a separate cache entry.
+```ruby
+Papercraft::HTML.kramdown_options[:auto_ids] = false
+```
-#### `#context`
+## Papercraft extensions
+Papercraft extensions are modules that contain one or more methods that can be
+used to render complex HTML components. Extension modules can be used by
+installing them as a namespaced extension using `Papercraft.extension`.
+Extensions are particularly useful when you work with CSS frameworks such as
+[Bootstrap](https://getbootstrap.com/), [Tailwind](https://tailwindui.com/) or
+[Primer](https://primer.style/).
+For example, to create a Bootstrap card component, the following HTML markup is
+needed (example taken from the [Bootstrap
+docs](https://getbootstrap.com/docs/5.1/components/card/#titles-text-and-links)):
+```html
+<div class="card" style="width: 18rem;">
+  <div class="card-body">
+    <h5 class="card-title">Card title</h5>
+    <h6 class="card-subtitle mb-2 text-muted">Card subtitle</h6>
+    <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p>
+    <a href="#" class="card-link">Card link</a>
+    <a href="#" class="card-link">Another link</a>
+  </div>
+</div>
+```
-Accesses the [global context](#global-context).
+With Papercraft, we could create a `Bootstrap` extension with a `#card` method
+and other associated methods:
-#### `#emit(object)` a.k.a. `#e(object)`
+```ruby
+module BootstrapComponents
+  ...
-- `object`: `Proc`, `Papercraft` instance or `String`
+  def card(**props)
+    div(class: 'card', **props) {
+      div(class: 'card-body') {
+        emit_yield
+      }
+    }
+  end
-Adds the given object to the current template. If a `String` is given, it is
-rendered verbatim, i.e. without escaping.
+  def card_title(title)
+    h5 title, class: 'card-title'
+  end
-#### `html5(&block)`
+  ...
+end
-- `block`: inner HTML block
+Papercraft.extension(bootstrap: BootstrapComponents)
+```
-Adds an HTML5 `doctype` tag, followed by an `html` tag with the given block.
+The call to `Papercraft.extension` lets us access the different methods of
+`BootstrapComponents` by calling `#bootstrap` inside a template. With this,
+we'll be able to express the above markup as follows:
-#### `#text(data)`
+```ruby
+H {
+  bootstrap.card(style: 'width: 18rem') {
+    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'
+  }
+}
+```
-- `data` - text to add
+## API Reference
-Adds text without wrapping it in a tag. The text will be escaped.
+The API reference for this library can be found
+[here](https://www.rubydoc.info/gems/papercraft).

data/lib/papercraft/component.rb CHANGED Viewed

@@ -3,18 +3,19 @@
 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.
   #
   # Since in Papercraft HTML is expressed using blocks (or procs,) the Component
   # 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:
   #
-  #   greeter = H { |name| h1 "Hello, #{name}!" } greeter.render('world') #=>
-  #   "<h1>Hello, world!</h1>"
+  #   greeter = H { |name| h1 "Hello, #{name}!" }
+  #   greeter.render('world') #=> "<h1>Hello, world!</h1>"
   #
   # Components can also be created using the normal constructor:
   #
@@ -23,9 +24,71 @@ module Papercraft
   #
   # In the component block, HTML elements are created by simply calling
   # unqualified methods:
+  #
+  #   page_layout = H {
+  #     html5 {
+  #       head {
+  #         title 'foo'
+  #       }
+  #       body {
+  #         h1 "Hello, world!"
+  #       }
+  #     }
+  #   }
+  #
+  # Papercraft components 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 = H { |uri: , text: | a(text, href: uri) }
+  #
+  # The above component could later be rendered by passing the needed arguments:
+  #
+  #   anchor.render(uri: 'https://example.com', text: 'Example')
+  #
+  # ## Component Composition
+  #
+  # A component can be included in another component using the `emit` method:
+  #
+  #   links = H {
+  #     emit anchor, uri: '/posts',   text: 'Posts'
+  #     emit anchor, uri: '/archive', text: 'Archive'
+  #     emit anchor, uri: '/about',   text: 'About'
+  #   }
+  #
+  # Another way of composing components is to pass the components themselves as
+  # parameters:
+  #
+  #   links = H { |anchors|
+  #     anchors.each { |a| emit a }
+  #   }
+  #   links.render([
+  #     anchor.apply(uri: '/posts', text: 'Posts'),
+  #     anchor.apply(uri: '/archive', text: 'Archive'),
+  #     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:
+  #
+  #   links_with_anchors = links.apply([
+  #     anchor.apply(uri: '/posts', text: 'Posts'),
+  #     anchor.apply(uri: '/archive', text: 'Archive'),
+  #     anchor.apply(uri: '/about', text: 'About')
+  #   ])
+  #   links_with_anchors.render
+  #
   class Component < Proc
-    # Initializes a component with the given block
-    # @param mode [Symbol] local context
+    # Determines the rendering mode: `:html` or `:xml`.
+    attr_accessor :mode
+    # 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 block [Proc] nested HTML block
     def initialize(mode: :html, &block)
       @mode = mode
@@ -34,7 +97,9 @@ module Papercraft
     H_EMPTY = {}.freeze
-    # Renders the associated block and returns the string result
+    # Renders the template with the given parameters and or block, and returns
+    # the string result.
+    #
     # @param context [Hash] context
     # @return [String]
     def render(*a, **b, &block)
@@ -51,6 +116,24 @@ module Papercraft
       raise Papercraft::Error, e.message
     end
+    # Creates a new component, 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:
+    #
+    #   article_wrapper = H {
+    #     article {
+    #       emit_yield
+    #     }
+    #   }
+    #   wrapped_article = article_wrapper.apply {
+    #     h1 'Article title'
+    #   }
+    #   wrapped_article.render #=> "<article><h1>Article title</h1></article>"
+    #
+    # @param *a [<any>] normal parameters
+    # @param **b [Hash] named parameters
+    # @param &block [Proc] inner block
+    # @return [Papercraft::Component] applied component
     def apply(*a, **b, &block)
       template = self
       if block
@@ -64,6 +147,10 @@ module Papercraft
       end
     end
+    # Returns the Renderer class used for rendering the templates, according to
+    # the component's mode.
+    #
+    # @return [Papercraft::Renderer] Renderer used for rendering the component
     def renderer_class
       case @mode
       when :html

data/lib/papercraft/extension_proxy.rb ADDED Viewed

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+module Papercraft
+  # An ExtensionProxy proxies method calls to a renderer. Extension proxies are
+  # used to provide an namespaced interface to Papercraft extensions. When an
+  # extension is installed using `Papercraft.extension`, a corresponding method
+  # is defined on the `Papercraft::Renderer` class that creates an extension
+  # proxy that gives access to the different extension methods.
+  class ExtensionProxy
+    # Initializes a new ExtensionProxy.
+    # @param renderer [Papercraft::Renderer] renderer to proxy to
+    # @param mod [Module] extension module
+    # @return [void]
+    def initialize(renderer, mod)
+      @renderer = renderer
+      extend(mod)
+    end
+    # Proxies missing methods to the renderer
+    # @param sym [Symbol] method name
+    # @param *args [Array] arguments
+    # @param &block [Proc] block
+    # @return void
+    def method_missing(sym, *args, &block)
+      @renderer.send(sym, *args, &block)
+    end
+  end
+end

data/lib/papercraft/html.rb CHANGED Viewed

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
-require_relative './html'
+require 'kramdown'
+require 'rouge'
+require 'kramdown-parser-gfm'
-module Papercraft
-  # Markup extensions
+module Papercraft
+  # HTML Markup extensions
   module HTML
     # Emits the p tag (overrides Object#p)
+    #
     # @param text [String] text content of tag
     # @param props [Hash] tag attributes
     # @para block [Proc] nested HTML block
@@ -16,7 +19,8 @@ module Papercraft
     S_HTML5_DOCTYPE = '<!DOCTYPE html>'
-    # Emits an HTML5 doctype tag and an html tag with the given block
+    # Emits an HTML5 doctype tag and an html tag with the given block.
+    #
     # @param block [Proc] nested HTML block
     # @return [void]
     def html5(&block)
@@ -24,6 +28,11 @@ module Papercraft
       self.html(&block)
     end
+    # Emits a link element with a stylesheet.
+    #
+    # @param href [String] stylesheet URL
+    # @param custom_attributes [Hash] optional custom attributes for the link element
+    # @return [void]
     def link_stylesheet(href, custom_attributes = nil)
       attributes = {
         rel: 'stylesheet',
@@ -34,5 +43,28 @@ module Papercraft
       end
       link(**attributes)
     end
+    def emit_markdown(markdown, **opts)
+      emit Kramdown::Document.new(markdown, **kramdown_options(opts)).to_html
+    end
+    def kramdown_options(opts)
+      HTML.kramdown_options.merge(**opts)
+    end
+    class << self
+      def kramdown_options
+        @kramdown_options ||= {
+          entity_output: :numeric,
+          syntax_highlighter: :rouge,
+          input: 'GFM',
+          hard_wrap: false
+        }
+      end
+      def kramdown_options=(opts)
+        @kramdown_options = opts
+      end
+    end
   end
 end

data/lib/papercraft/renderer.rb CHANGED Viewed

@@ -1,11 +1,22 @@
 # frozen_string_literal: true
 require_relative './html'
+require_relative './extension_proxy'
 module Papercraft
   # A Renderer renders a Papercraft component into a string
   class Renderer
     class << self
+      # Verifies that the given template proc can be called with the given
+      # arguments and named arguments. If the proc demands named argument keys
+      # that do not exist in `named_args`, `Papercraft::Error` is raised.
+      #
+      # @param template [Proc] proc to verify
+      # @param args [Array<any>] arguments passed to proc
+      # @param named_args [Hash] named arguments passed to proc
       def verify_proc_parameters(template, args, named_args)
         param_count = 0
         template.parameters.each do |(type, name)|
@@ -21,34 +32,47 @@ module Papercraft
         if param_count > args.size
           raise Papercraft::Error, "Missing template parameters"
         end
-      end
-    end
+      end
+      # Installs the given extensions, mapping a method name to the extension
+      # module.
+      # @param map [Hash] hash mapping methods to extension modules
+      # @return [void]
+      def extension(map)
+        map.each do |sym, mod|
+          define_extension_method(sym, mod)
+        end
+      end
-    attr_reader :context
+      private
-    # Initializes attributes and renders the given block
-    # @param context [Hash] rendering context
-    # @param block [Proc] template block
-    # @return [void]
+      # Defines a method returning an extension proxy for the given module
+      # @param sym [Symbol] method name
+      # @param mod [Module] extension module
+      # @return [void]
+      def define_extension_method(sym, mod)
+        define_method(sym) do
+          (@extension_proxies ||= {})[mod] ||= ExtensionProxy.new(self, mod)
+        end
+      end
+    end
+    # Initializes the renderer and evaulates the given template in the
+    # renderer's scope.
+    #
+    # @param &template [Proc] template block
     def initialize(&template)
       @buffer = +''
       instance_eval(&template)
     end
-    # Returns the result of the rendering
+    # Returns the rendered template.
+    #
     # @return [String]
     def to_s
       @buffer
     end
-    def escape_text(text)
-      raise NotImplementedError
-    end
-    def escape_uri(uri)
-      EscapeUtils.escape_uri(v)
-    end
     S_TAG_METHOD_LINE = __LINE__ + 1
     S_TAG_METHOD = <<~EOF
       S_TAG_%<TAG>s_PRE = '<%<tag>s'.tr('_', '-')
@@ -74,33 +98,42 @@ module Papercraft
       end
     EOF
-    # Catches undefined tag method call and handles them by defining the method
+    # Catches undefined tag method call and handles it by defining the method.
+    #
     # @param sym [Symbol] HTML tag or component identifier
-    # @param args [Array] method call arguments
-    # @param block [Proc] block passed to method call
+    # @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)
-      value = @local && @local[sym]
-      return value if value
       tag = sym.to_s
       code = S_TAG_METHOD % { tag: tag, TAG: tag.upcase }
       self.class.class_eval(code, __FILE__, S_TAG_METHOD_LINE)
       send(sym, *args, **opts, &block)
     end
-    # Emits the given object into the rendering buffer
+    # 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,
+    # nothing is emitted. Otherwise, the object is converted into a string using
+    # `#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>"
+    #
+    #   H { emit 'hi&<bye>' }.render #=> "hi&<bye>"
+    #
+    #   H { emit nil }.render #=> ""
+    #
     # @param o [Proc, Papercraft::Component, 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)
       case o
       when ::Proc
         Renderer.verify_proc_parameters(o, a, b)
         instance_exec(*a, **b, &o)
-      # when Papercraft::Component
-      #   o = o.template
-      #   Renderer.verify_proc_parameters(o, a, b)
-      #   instance_exec(*a, **b, &o)
       when nil
       else
         @buffer << o.to_s
@@ -108,14 +141,15 @@ module Papercraft
     end
     alias_method :e, :emit
-    def with_block(block, &run_block)
-      old_block = @inner_block
-      @inner_block = block
-      instance_eval(&run_block)
-    ensure
-      @inner_block = old_block
-    end
+    # Emits a block supplied using `Component#apply` or `Component#render`.
+    #
+    #   div_wrap = H { |*args| div { emit_yield(*args) } }
+    #   greeter = div_wrap.apply { |name| h1 "Hello, #{name}!" }
+    #   greeter.render('world') #=> "<div><h1>Hello, world!</h1></div>"
+    #
+    # @param *a [Array<any>] arguments to pass to a proc
+    # @param **b [Hash] named arguments to pass to a proc
+    # @return [void]
     def emit_yield(*a, **b)
       raise Papercraft::Error, "No block given" unless @inner_block
@@ -131,6 +165,31 @@ module Papercraft
     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.
+    def escape_text(text)
+      raise NotImplementedError
+    end
+    # Sets up a block to be called with `#emit_yield`
+    def with_block(block, &run_block)
+      old_block = @inner_block
+      @inner_block = block
+      instance_eval(&run_block)
+    ensure
+      @inner_block = old_block
+    end
     # Emits tag attributes into the rendering buffer
     # @param props [Hash] tag attributes
     # @return [void]
@@ -153,23 +212,25 @@ module Papercraft
         end
       }
     end
-    # Emits text into the rendering buffer
-    # @param data [String] text
-    def text(data)
-      @buffer << escape_text(data)
-    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

data/lib/papercraft/version.rb CHANGED Viewed

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

data/lib/papercraft.rb CHANGED Viewed

@@ -11,24 +11,44 @@ require_relative 'papercraft/encoding'
 module Papercraft
   # Exception class used to signal templating-related errors
   class Error < RuntimeError; 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.
+  def self.extension(map)
+    Renderer.extension(map)
+  end
 end
 # Kernel extensions
 module ::Kernel
-  # Convenience method for creating a new Papercraft
-  # @param ctx [Hash] local context
+  # 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`.
+  #
+  # H(proc { h1 'hi' }).render #=> "<h1>hi</h1>"
+  # H { h1 'hi' }.render #=> "<h1>hi</h1>"
+  #
   # @param template [Proc] template block
-  # @return [Papercraft] Papercraft template
-  def H(&template)
-    Papercraft::Component.new(&template)
+  # @return [Papercraft::Component] Papercraft component
+  def H(o = nil, &template)
+    return o if o.is_a?(Papercraft::Component)
+    template ||= o
+    Papercraft::Component.new(mode: :html, &template)
   end
-  def X(&template)
+  # 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`.
+  #
+  # X(proc { item 'foo' }).render #=> "<item>foo</item>"
+  # X { item 'foo' }.render #=> "<item>foo</item>"
+  #
+  # @param template [Proc] template block
+  # @return [Papercraft::Component] Papercraft component
+  def X(o = nil, &template)
+    return o if o.is_a?(Papercraft::Component)
+    template ||= o
     Papercraft::Component.new(mode: :xml, &template)
   end
 end
-# Object extensions
-class Object
-  include Papercraft::Encoding
-end

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: '0.10'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-22 00:00:00.000000000 Z
+date: 2021-12-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils
@@ -24,6 +24,48 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 1.2.1
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+- !ruby/object:Gem::Dependency
+  name: rouge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.26.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.26.0
+- !ruby/object:Gem::Dependency
+  name: kramdown-parser-gfm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +135,7 @@ files:
 - lib/papercraft/compiler.rb
 - lib/papercraft/component.rb
 - lib/papercraft/encoding.rb
+- lib/papercraft/extension_proxy.rb
 - lib/papercraft/html.rb
 - lib/papercraft/renderer.rb
 - lib/papercraft/version.rb