papercraft 0.8

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4404d5b6a84318eab12f0c7d13b4c3be4355c8ebb36b6a3fbd65c6f62af8f361
+  data.tar.gz: 175a60878f6770ae52d956b6e7c72326af5a0db9faefecae2bd2c3e2fb406f97
+SHA512:
+  metadata.gz: 307d3e37cb946b0adb54fa2d6b2939ec0016cc81205f3b4d4dfb6c01d57b65b1f609024b0499f6b5717c858b6dc5aea472f0b82585df44f761f4ac9fdb8c2eae
+  data.tar.gz: 96162c1707785e3d54ce6cb55bd9a5801658b92d294e28b4168b78ee68e49027ec945eab13d47142382e458fdd33c6d26182a7a08bfc403038c170a8f119984f

data/CHANGELOG.md

@@ -0,0 +1,48 @@
+## 0.8 2021-12-22
+
+- Cleanup and refactor code
+- Add X global method for XML templates
+- Make `Component` a descendant of `Proc`
+- Introduce new component API
+- Rename Rubyoshka to Papercraft
+- Convert underscores to dashes for tag  and attribute names (@jaredcwhite)
+
+## 0.7 2021-09-29
+
+- Add `#emit_yield` for rendering layouts
+- Add experimental template compilation (WIP)
+
+## 0.6.1 2021-03-03
+
+- Remove support for Ruby 2.6
+
+## 0.6 2021-03-03
+
+- Fix Rubyoshka on Ruby 3.0
+- Refactor and add more tests
+
+## 0.5 2021-02-27
+
+- Add support for rendering XML
+- Add Rubyoshka.component method
+- Remove Modulation dependency
+
+## 0.4 2019-02-05
+
+- Add support for emitting component modules
+
+## 0.3 2019-01-13
+
+- Implement caching
+- Improve performance
+- Handle attributes with `false` value correctly
+
+## 0.2 2019-01-07
+
+- Better documentation
+- Fix #text
+- Add local context
+
+## 0.1 2019-01-06
+
+- First working version

data/README.md

@@ -0,0 +1,437 @@
+# Papercraft - Composable HTML templating for Ruby
+
+[INSTALL](#installing-papercraft) |
+[TUTORIAL](#getting-started) |
+[EXAMPLES](examples) |
+[REFERENCE](#api-reference)
+
+## What is Papercraft?
+
+Papercraft is an HTML templating engine for Ruby that offers the following
+features:
+
+- HTML 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
+- Composable 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.
+
+## Installing Papercraft
+
+Using bundler:
+
+```ruby
+gem 'papercraft'
+```
+
+Or manually:
+
+```bash
+$ gem install papercraft
+```
+
+## Getting started
+
+To use Papercraft in your code just require it:
+
+```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' }
+}
+```
+
+## Rendering a template
+
+To render a Papercraft template use the `#render` method:
+
+```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>"
+```
+
+## All about tags
+
+Tags are added using unqualified method calls, and are nested using blocks:
+
+```ruby
+H {
+  html {
+    head {
+      title 'page title'
+    }
+    body {
+      article {
+        h1 'article title'
+      }
+    }
+  }
+}
+```
+
+Tag methods accept a string argument, a block, or no argument at all:
+
+```ruby
+H { p 'hello' }.render #=> "<p>hello</p>"
+
+H { p { span '1'; span '2' } }.render #=> "<p><span>1</span><span>2</span></p>"
+
+H { hr() }.render #=> "<hr/>"
+```
+
+Tag methods also accept tag attributes, given as a hash:
+
+```ruby
+H { img src: '/my.gif' }.render #=> "<img src="/my.gif"/>
+
+H { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</p>"
+```
+
+## Template parameters
+
+Template parameters are specified as block parameters, and are passed to the
+template on rendering:
+
+```ruby
+greeting = H { |name| h1 "Hello, #{name}!" }
+greeting.render('world') #=> "<h1>Hello, world!</h1>"
+```
+
+Templates can also accept named parameters:
+
+```ruby
+greeting = H { |name:| h1 "Hello, #{name}!" }
+greeting.render(name: 'world') #=> "<h1>Hello, world!</h1>"
+```
+
+## Logic in templates
+
+Since Papercraft templates are just a bunch of Ruby, you can easily write your
+view logic right in the template:
+
+```ruby
+H { |user = nil|
+  if user
+    span "Hello, #{user.name}!"
+  else
+    span "Hello, guest!"
+  end
+}
+```
+
+## Template blocks
+
+Templates can also accept and render blocks by using `emit_yield`:
+
+```ruby
+page = H {
+  html {
+    body { emit_yield }
+  }
+}
+
+# we pass the inner HTML
+page.render { h1 'hi' }
+```
+
+## Plain procs as components
+
+With Papercraft you can write a template as a plain Ruby proc, and later render
+it by passing it as a block to `H`:
+
+```ruby
+greeting = proc { |name| h1 "Hello, #{name}!" }
+H(&greeting).render('world')
+```
+
+Components can also be expressed using lambda notation:
+
+```ruby
+greeting = ->(name) { h1 "Hello, #{name}!" }
+H(&greeting).render('world')
+```
+
+## Component composition
+
+Papercraft makes it easy to compose multiple components into a whole HTML
+document. A Papercraft component can contain other components, as the following
+example shows.
+
+```ruby
+Title = ->(title) { h1 title }
+
+Item = ->(id:, text:, checked:) {
+  li {
+    input name: id, type: 'checkbox', checked: checked
+    label text, for: id
+  }
+}
+
+ItemList = ->(items) {
+  ul {
+    items.each { |i|
+      Item(**i)
+    }
+  }
+}
+
+page = H { |title, items|
+  html5 {
+    head { Title(title) }
+    body { ItemList(items) }
+  }
+}
+
+page.render('Hello from components', [
+  { 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:
+
+```ruby
+greeting = -> { span "Hello, world" }
+
+H {
+  div {
+    emit greeting
+  }
+}
+```
+
+## 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.
+
+The `#apply` method returns a new component which applies the given parameters and
+or block to the original component:
+
+```ruby
+# parameter application
+hello = H { |name| h1 "Hello, #{name}!" }
+hello_world = hello.apply('world')
+hello_world.render #=> "<h1>Hello, world!</h1>"
+
+# block application
+div_wrap = H { div { emit_yield } }
+wrapped_h1 = div_wrap.apply { h1 'hi' }
+wrapped_h1.render #=> "<div><h1>hi</h1></div>"
+
+# wrap a component
+wrapped_hello_world = div_wrap.apply(&hello_world)
+wrapped_hello_world.render #=> "<div><h1>Hello, world!</h1></div>"
+```
+
+## Higher-order components
+
+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.
+
+Here is a HOC that takes a component as parameter:
+
+```ruby
+div_wrap = H { |inner| div { emit inner } }
+greeter = H { h1 'hi' }
+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:
+
+```ruby
+div_wrap = H { div { emit_yield } }
+wrapped_greeter = div_wrap.apply { h1 'hi' }
+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
+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`
+to create the other templates:
+
+```ruby
+default_layout = H { |**params|
+  html5 {
+    head {
+      title: params[:title]
+    }
+    body {
+      emit_yield(**params)
+    }
+  }
+}
+
+article_layout = default_layout.apply { |title:, body:|
+  article {
+    h1 title
+    emit_markdown body
+  }
+}
+
+article_layout.render(
+  title: 'This is a title',
+  body: 'Hello from *markdown body*'
+)
+```
+
+## Emitting raw HTML
+
+Raw HTML can be emitted using `#emit`:
+
+```ruby
+wrapped = H { |html| div { emit html } }
+wrapped.render("<h1>hi</h1>") #=> "<div><h1>hi</h1></div>"
+```
+
+## Emitting a string with HTML Encoding
+
+To emit a string with proper HTML encoding, without wrapping it in an HTML
+element, use `#text`:
+
+```ruby
+H { str 'hi&lo' }.render #=> "hi&amp;lo"
+```
+
+## Emitting Markdown
+
+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>"
+```
+
+## 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!
+
+### A higher-order list component
+
+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:
+
+```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'
+}
+
+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
+
+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.
+
+#### `#context`
+
+Accesses the [global context](#global-context).
+
+#### `#emit(object)` a.k.a. `#e(object)`
+
+- `object`: `Proc`, `Papercraft` instance or `String`
+
+Adds the given object to the current template. If a `String` is given, it is
+rendered verbatim, i.e. without escaping.
+
+#### `html5(&block)`
+
+- `block`: inner HTML block
+
+Adds an HTML5 `doctype` tag, followed by an `html` tag with the given block.
+
+#### `#text(data)`
+
+- `data` - text to add
+
+Adds text without wrapping it in a tag. The text will be escaped.

data/lib/papercraft/compiler.rb

@@ -0,0 +1,428 @@
+# frozen_string_literal: true
+
+module Papercraft
+  # The Compiler class compiles Papercraft templates
+  class Compiler
+    DEFAULT_CODE_BUFFER_CAPACITY = 8192
+    DEFAULT_EMIT_BUFFER_CAPACITY = 4096
+
+    def initialize
+      @level = 1
+      @code_buffer = String.new(capacity: DEFAULT_CODE_BUFFER_CAPACITY)
+    end
+
+    def emit_output
+      @output_mode = true
+      yield
+      @output_mode = false
+    end
+
+    def emit_code_line_break
+      return if @code_buffer.empty?
+
+      @code_buffer << "\n" if @code_buffer[-1] != "\n"
+      @line_break = nil
+    end
+
+    def emit_literal(lit)
+      if @output_mode
+        emit_code_line_break if @line_break
+        @emit_buffer ||= String.new(capacity: DEFAULT_EMIT_BUFFER_CAPACITY)
+        @emit_buffer << lit
+      else
+        emit_code(lit)
+      end
+    end
+
+    def emit_text(str, encoding: :html)
+      emit_code_line_break if @line_break
+      @emit_buffer ||= String.new(capacity: DEFAULT_EMIT_BUFFER_CAPACITY)
+      @emit_buffer << encode(str, encoding).inspect[1..-2]
+    end
+
+    def encode(str, encoding)
+      case encoding
+      when :html
+        __html_encode__(str)
+      when :uri
+        __uri_encode__(str)
+      else
+        raise "Invalid encoding #{encoding.inspect}"
+      end
+    end
+
+    def emit_expression
+      if @output_mode
+        emit_literal('#{__html_encode__(')
+        yield
+        emit_literal(')}')
+      else
+        yield
+      end
+    end
+
+    def flush_emit_buffer
+      return if !@emit_buffer
+
+      @code_buffer << "#{'  ' * @level}__buffer__ << \"#{@emit_buffer}\"\n"
+      @emit_buffer = nil
+      true
+    end
+
+    def emit_code(code)
+      if flush_emit_buffer || @line_break
+        emit_code_line_break if @line_break
+        @code_buffer << "#{'  ' * @level}#{code}"
+      else
+        if @code_buffer.empty? || (@code_buffer[-1] == "\n")
+          @code_buffer << "#{'  ' * @level}#{code}"
+        else
+          @code_buffer << "#{code}"
+        end
+      end
+    end
+
+    def compile(template)
+      @block = template.to_proc
+      ast = RubyVM::AbstractSyntaxTree.of(@block)
+      # Compiler.pp_ast(ast)
+      parse(ast)
+      flush_emit_buffer
+      self
+    end
+
+    attr_reader :code_buffer
+
+    def to_code
+      "->(__buffer__, __context__) do\n#{@code_buffer}end"
+    end
+
+    def to_proc
+      @block.binding.eval(to_code)
+    end
+
+    def parse(node)
+      @line_break = @last_node && node.first_lineno != @last_node.first_lineno
+      @last_node = node
+      # puts "- parse(#{node.type}) (break: #{@line_break.inspect})"
+      send(:"parse_#{node.type.downcase}", node)
+    end
+
+    def parse_scope(node)
+      parse(node.children[2])
+    end
+
+    def parse_iter(node)
+      call, scope = node.children
+      if call.type == :FCALL
+        parse_fcall(call, scope)
+      else
+        parse(call)
+        emit_code(" do")
+        args = scope.children[0]
+        emit_code(" |#{args.join(', ')}|") if args
+        emit_code("\n")
+        @level += 1
+        parse(scope)
+        flush_emit_buffer
+        @level -= 1
+        emit_code("end\n")
+      end
+    end
+
+    def parse_ivar(node)
+      ivar = node.children.first.match(/^@(.+)*/)[1]
+      emit_literal("__context__[:#{ivar}]")
+    end
+
+    def parse_fcall(node, block = nil)
+      tag, args = node.children
+      args = args.children.compact if args
+      text = fcall_inner_text_from_args(args)
+      atts = fcall_attributes_from_args(args)
+      if block
+        emit_tag(tag, atts) { parse(block) }
+      elsif text
+        emit_tag(tag, atts) do
+          emit_output do
+            if text.is_a?(String)
+              emit_text(text)
+            else
+              emit_expression { parse(text) }
+            end
+          end
+        end
+      else
+        emit_tag(tag, atts)
+      end
+    end
+
+    def fcall_inner_text_from_args(args)
+      return nil if !args
+
+      first = args.first
+      case first.type
+      when :STR
+        first.children.first
+      when :LIT
+        first.children.first.to_s
+      when :HASH
+        nil
+      else
+        first
+      end
+    end
+
+    def fcall_attributes_from_args(args)
+      return nil if !args
+
+      last = args.last
+      (last.type == :HASH) ? last : nil
+    end
+
+    def emit_tag(tag, atts, &block)
+      emit_output do
+        if atts
+          emit_literal("<#{tag}")
+          emit_tag_attributes(atts)
+          emit_literal(block ? '>' : '/>')
+        else
+          emit_literal(block ? "<#{tag}>" : "<#{tag}/>")
+        end
+      end
+      if block
+        block.call
+        emit_output { emit_literal("</#{tag}>") }
+      end
+    end
+
+    def emit_tag_attributes(atts)
+      list = atts.children.first.children
+      while true
+        key = list.shift
+        break unless key
+
+        value = list.shift
+        value_type = value.type
+        case value_type
+        when :FALSE, :NIL
+          next
+        end
+
+        emit_literal(' ')
+        emit_tag_attribute_key(key)
+        next if value_type == :TRUE
+
+        emit_literal('=\"')
+        emit_tag_attribute_value(value, key)
+        emit_literal('\"')
+      end
+    end
+
+    def emit_tag_attribute_key(key)
+      case key.type
+      when :STR
+        emit_literal(key.children.first)
+      when :LIT
+        emit_literal(key.children.first.to_s)
+      when :NIL
+        emit_literal('nil')
+      else
+        emit_expression { parse(key) }
+      end
+    end
+
+    def emit_tag_attribute_value(value, key)
+      case value.type
+      when :STR
+        encoding = (key.type == :LIT) && (key.children.first == :href) ? :uri : :html
+        emit_text(value.children.first, encoding: encoding)
+      when :LIT
+        emit_text(value.children.first.to_s)
+      else
+        parse(value)
+      end
+    end
+
+    def parse_call(node)
+      receiver, method, args = node.children
+      if receiver.type == :VCALL && receiver.children == [:context]
+        emit_literal('__context__')
+      else
+        parse(receiver)
+      end
+      if method == :[]
+        emit_literal('[')
+        args = args.children.compact
+        while true
+          arg = args.shift
+          break unless arg
+
+          parse(arg)
+          emit_literal(', ') if !args.empty?
+        end
+        emit_literal(']')
+      else
+        emit_literal('.')
+        emit_literal(method.to_s)
+        if args
+          emit_literal('(')
+          args = args.children.compact
+          while true
+            arg = args.shift
+            break unless arg
+
+            parse(arg)
+            emit_literal(', ') if !args.empty?
+          end
+          emit_literal(')')
+        end
+      end
+    end
+
+    def parse_str(node)
+      str = node.children.first
+      emit_literal(str.inspect)
+    end
+
+    def parse_lit(node)
+      value = node.children.first
+      emit_literal(value.inspect)
+    end
+
+    def parse_true(node)
+      emit_expression { emit_literal('true') }
+    end
+
+    def parse_false(node)
+      emit_expression { emit_literal('true') }
+    end
+
+    def parse_list(node)
+      emit_literal('[')
+      items = node.children.compact
+      while true
+        item = items.shift
+        break unless item
+
+        parse(item)
+        emit_literal(', ') if !items.empty?
+      end
+      emit_literal(']')
+    end
+
+    def parse_vcall(node)
+      tag = node.children.first
+      emit_tag(tag, nil)
+    end
+
+    def parse_opcall(node)
+      left, op, right = node.children
+      parse(left)
+      emit_literal(" #{op} ")
+      right.children.compact.each { |c| parse(c) }
+    end
+
+    def parse_block(node)
+      node.children.each { |c| parse(c) }
+    end
+
+    def parse_if(node)
+      cond, then_branch, else_branch = node.children
+      if @output_mode
+        emit_if_output(cond, then_branch, else_branch)
+      else
+        emit_if_code(cond, then_branch, else_branch)
+      end
+    end
+
+    def parse_unless(node)
+      cond, then_branch, else_branch = node.children
+      if @output_mode
+        emit_unless_output(cond, then_branch, else_branch)
+      else
+        emit_unless_code(cond, then_branch, else_branch)
+      end
+    end
+
+    def emit_if_output(cond, then_branch, else_branch)
+      parse(cond)
+      emit_literal(" ? ")
+      parse(then_branch)
+      emit_literal(" : ")
+      if else_branch
+        parse(else_branch)
+      else
+        emit_literal(nil)
+      end
+    end
+
+    def emit_unless_output(cond, then_branch, else_branch)
+      parse(cond)
+      emit_literal(" ? ")
+      if else_branch
+        parse(else_branch)
+      else
+        emit_literal(nil)
+      end
+      emit_literal(" : ")
+      parse(then_branch)
+    end
+
+    def emit_if_code(cond, then_branch, else_branch)
+      emit_code('if ')
+      parse(cond)
+      emit_code("\n")
+      @level += 1
+      parse(then_branch)
+      flush_emit_buffer
+      @level -= 1
+      if else_branch
+        emit_code("else\n")
+        @level += 1
+        parse(else_branch)
+        flush_emit_buffer
+        @level -= 1
+      end
+      emit_code("end\n")
+    end
+
+    def emit_unless_code(cond, then_branch, else_branch)
+      emit_code('unless ')
+      parse(cond)
+      emit_code("\n")
+      @level += 1
+      parse(then_branch)
+      flush_emit_buffer
+      @level -= 1
+      if else_branch
+        emit_code("else\n")
+        @level += 1
+        parse(else_branch)
+        flush_emit_buffer
+        @level -= 1
+      end
+      emit_code("end\n")
+    end
+
+    def parse_dvar(node)
+
+      emit_literal(node.children.first.to_s)
+    end
+
+    def self.pp_ast(node, level = 0)
+      case node
+      when RubyVM::AbstractSyntaxTree::Node
+        puts "#{'  ' * level}#{node.type.inspect}"
+        node.children.each { |c| pp_ast(c, level + 1) }
+      when Array
+        puts "#{'  ' * level}["
+        node.each { |c| pp_ast(c, level + 1) }
+        puts "#{'  ' * level}]"
+      else
+        puts "#{'  ' * level}#{node.inspect}"
+        return
+      end
+    end
+  end
+end

data/lib/papercraft/component.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+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>"
+  #
+  # Components can also be created using the normal constructor:
+  #
+  #   greeter = Papercraft::Component.new { |name| h1 "Hello, #{name}!" }
+  #   greeter.render('world') #=> "<h1>Hello, world!</h1>"
+  #
+  # In the component block, HTML elements are created by simply calling
+  # unqualified methods:
+  class Component < Proc
+    # Initializes a component with the given block
+    # @param mode [Symbol] local context
+    # @param block [Proc] nested HTML block
+    def initialize(mode: :html, &block)
+      @mode = mode
+      super(&block)
+    end
+  
+    H_EMPTY = {}.freeze
+  
+    # Renders the associated block and returns the string result
+    # @param context [Hash] context
+    # @return [String]
+    def render(*a, **b, &block)
+      template = self
+      Renderer.verify_proc_parameters(template, a, b)
+      renderer_class.new do
+        if block
+          with_block(block) { instance_exec(*a, **b, &template) }
+        else
+          instance_exec(*a, **b, &template)
+        end
+      end.to_s
+    rescue ArgumentError => e
+      raise Papercraft::Error, e.message
+    end
+  
+    def apply(*a, **b, &block)
+      template = self
+      if block
+        Component.new(&proc do |*x, **y|
+          with_block(block) { instance_exec(*x, **y, &template) }
+        end)
+      else
+        Component.new(&proc do |*x, **y|
+          instance_exec(*a, **b, &template)
+        end)
+      end
+    end
+  
+    def renderer_class
+      case @mode
+      when :html
+        HTMLRenderer
+      when :xml
+        XMLRenderer
+      else
+        raise "Invalid mode #{@mode.inspect}"
+      end
+    end
+  
+    # def compile
+    #   Papercraft::Compiler.new.compile(self)
+    # end
+  end
+end

data/lib/papercraft/encoding.rb

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

data/lib/papercraft/html.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative './html'
+
+module Papercraft
+  # 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
+    # @return [void]
+    def p(text = nil, **props, &block)
+      method_missing(:p, text, **props, &block)
+    end
+
+    S_HTML5_DOCTYPE = '<!DOCTYPE html>'
+
+    # Emits an HTML5 doctype tag and an html tag with the given block
+    # @param block [Proc] nested HTML block
+    # @return [void]
+    def html5(&block)
+      @buffer << S_HTML5_DOCTYPE
+      self.html(&block)
+    end
+
+    def link_stylesheet(href, custom_attributes = nil)
+      attributes = {
+        rel: 'stylesheet',
+        href: href
+      }
+      if custom_attributes
+        attributes = custom_attributes.merge(attributes)
+      end
+      link(**attributes)
+    end
+  end
+end

data/lib/papercraft/renderer.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require_relative './html'
+
+module Papercraft
+  # A Renderer renders a Papercraft component into a string
+  class Renderer
+    class << self
+      def verify_proc_parameters(template, args, named_args)
+        param_count = 0
+        template.parameters.each do |(type, name)|
+          case type
+          when :req
+            param_count += 1
+          when :keyreq
+            if !named_args.has_key?(name)
+              raise Papercraft::Error, "Missing template parameter #{name.inspect}"
+            end
+          end
+        end
+        if param_count > args.size
+          raise Papercraft::Error, "Missing template parameters"
+        end
+      end  
+    end
+
+    attr_reader :context
+
+    # Initializes attributes and renders the given block
+    # @param context [Hash] rendering context
+    # @param block [Proc] template block
+    # @return [void]
+    def initialize(&template)
+      @buffer = +''
+      instance_eval(&template)
+    end
+
+    # Returns the result of the rendering
+    # @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('_', '-')
+      S_TAG_%<TAG>s_CLOSE = '</%<tag>s>'.tr('_', '-')
+
+      def %<tag>s(text = nil, **props, &block)
+        @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
+
+    # Catches undefined tag method call and handles them 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
+    # @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
+    # @param o [Proc, Papercraft::Component, String] emitted object
+    # @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
+      end
+    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
+  
+    def emit_yield(*a, **b)
+      raise Papercraft::Error, "No block given" unless @inner_block
+      
+      instance_exec(*a, **b, &@inner_block)
+    end
+    
+    S_LT              = '<'
+    S_GT              = '>'
+    S_LT_SLASH        = '</'
+    S_SPACE_LT_SLASH  = ' </'
+    S_SLASH_GT        = '/>'
+    S_SPACE           = ' '
+    S_EQUAL_QUOTE     = '="'
+    S_QUOTE           = '"'
+
+    # 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
+
+    # Emits text into the rendering buffer
+    # @param data [String] text
+    def text(data)
+      @buffer << escape_text(data)
+    end
+  end
+
+  class HTMLRenderer < Renderer
+    include HTML
+
+    def escape_text(text)
+      EscapeUtils.escape_html(text.to_s)
+    end
+  end
+
+  class XMLRenderer < Renderer
+    def escape_text(text)
+      EscapeUtils.escape_xml(text.to_s)
+    end
+  end
+end

data/lib/papercraft/version.rb

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

data/lib/papercraft.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'escape_utils'
+
+require_relative 'papercraft/component'
+require_relative 'papercraft/renderer'
+require_relative 'papercraft/encoding'
+# require_relative 'papercraft/compiler'
+
+# Papercraft is a component-based HTML templating library
+module Papercraft
+  # Exception class used to signal templating-related errors
+  class Error < RuntimeError; end
+end
+
+# Kernel extensions
+module ::Kernel
+  # Convenience method for creating a new Papercraft
+  # @param ctx [Hash] local context
+  # @param template [Proc] template block
+  # @return [Papercraft] Papercraft template
+  def H(&template)
+    Papercraft::Component.new(&template)
+  end
+
+  def X(&template)
+    Papercraft::Component.new(mode: :xml, &template)
+  end
+end
+
+# Object extensions
+class Object
+  include Papercraft::Encoding
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: papercraft
+version: !ruby/object:Gem::Version
+  version: '0.8'
+platform: ruby
+authors:
+- Sharon Rosner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-12-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: escape_utils
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 5.11.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 5.11.3
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.7.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.7.2
+- !ruby/object:Gem::Dependency
+  name: erubis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.7.0
+- !ruby/object:Gem::Dependency
+  name: tilt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.0.9
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.0.9
+description: 
+email: sharon@noteflakes.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- CHANGELOG.md
+- README.md
+- lib/papercraft.rb
+- lib/papercraft/compiler.rb
+- lib/papercraft/component.rb
+- lib/papercraft/encoding.rb
+- lib/papercraft/html.rb
+- lib/papercraft/renderer.rb
+- lib/papercraft/version.rb
+homepage: http://github.com/digital-fabric/papercraft
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/digital-fabric/papercraft
+post_install_message: 
+rdoc_options:
+- "--title"
+- Papercraft
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: 'Papercraft: component-based HTML templating for Ruby'
+test_files: []