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

papercraft 0.8.1 → 0.10

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