p2 2.4 → 2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43fb47ab7470259fddb850f19724caf5b8fdc07a232df7d893405a1031211313
-  data.tar.gz: 80999e97751f662940ad37f23f9fe10a4ce7914bb80084dc1ffe120d1cafc872
+  metadata.gz: a84949b86e99acbe131d37cb624dbf60010fe720ce27081d5e5652b33f2de004
+  data.tar.gz: c03bef8c358bae1536c04739c2fa67bd3ce6e879fd036f2e7352c6291677b888
 SHA512:
-  metadata.gz: ac2f9c15a39756f9da5da13d5a5cfcc9e4819574da83851c9e526c0d687b16cd36d6634bcabee3f3e15d59e199a54c6915e9251d87749aa4ff187f1c73c44d8e
-  data.tar.gz: 537dc36e03464ddf332bd63b73bc8cbdbc2e00063480307df60dabba4afed5829ebfa851c69f28cfbd161d292e5e01af183e28fe114532b6aac997caae651b21
+  metadata.gz: 2993a42368846048e02ca7cb01d2ba6f7be013870a5f39597478442d16659b730356443b1b77ee8bb36c6b9a3942bde7d8ef19e66ad087d2a69d9b686d5cc706
+  data.tar.gz: 7739be72dd3bdf195188339509a21e24bccbae6ac8efb140a16780445f71b60fea12ab0a87831f117422b620102c277391f33db944b94b7945088f16cf099d73

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+# 2.8 2025-08-17
+
+- Add render_children builtin
+- Rename emit_yield to render_yield
+- Add `Proc#render_cached` for caching render result
+
+# 2.7 2025-08-17
+
+- Improve source maps and whitespace in compiled code
+- Minor improvements to emit_yield generated code
+- Add support for extensions
+
+# 2.6 2025-08-16
+
+- Add support for block invocation.
+
+# 2.5 2025-08-15
+
+- Translate backtrace for exceptions raised in `#render_to_buffer`.
+- Improve display of backtrace when source map is missing entries.
+- Improve handling of ArgumentError raised on calling the template.
+- Add `Template#apply`, `Template#compiled_proc` methods
+
 # 2.4 2025-08-10
 
 - Add P2::Template wrapper class

data/README.md

@@ -30,7 +30,7 @@ require 'p2'
 page = ->(**props) {
   html {
     head { title 'My Title' }
-    body { emit_yield **props }
+    body { render_yield **props }
   }
 }
 page.render {
@@ -45,8 +45,8 @@ templates are expressed as Ruby procs, leading to easier debugging, better
 protection against HTML injection attacks, and better code reuse.
 
 P2 templates can be composed in a variety of ways, facilitating the usage of
-layout templates, and enabling a component-oriented approach to building complex
-web interfaces.
+layout templates, and enabling a component-oriented approach to building web
+interfaces of arbitrary complexity.
 
 In P2, dynamic data is passed explicitly to the template as block/lambda
 arguments, making the data flow easy to follow and understand. P2 also lets
@@ -77,19 +77,21 @@ hello.render(name: 'world')
 P2 features:
 
 - Express HTML using plain Ruby procs.
-- Deferred rendering using `defer`.
-- Template composition (for uses such as layouts).
-- Markdown rendering using [Kramdown](https://github.com/gettalong/kramdown/).
 - Automatic compilation for super-fast execution (about as
   [fast](https://github.com/digital-fabric/p2/blob/master/examples/perf.rb) as
   compiled ERB/ERubi).
+- Deferred rendering using `defer`.
+- Simple and easy template composition (for uses such as layouts, or modular
+  templates).
+- Markdown rendering using [Kramdown](https://github.com/gettalong/kramdown/).
+- Support for extensions.
+- Simple caching API for caching the rendering result.
 
 ## Table of Content
 
-- [Basic Usage](#basic-usage)
-- [Adding Tags](#adding-tags)
-- [Tag and Attribute Formatting](#tag-and-attribute-formatting)
-- [Escaping Content](#escaping-content)
+- [Getting Started](#getting-started)
+- [Basic Markup](#markup)
+- [Builtin Methods](#builtin-methods)
 - [Template Parameters](#template-parameters)
 - [Template Logic](#template-logic)
 - [Template Blocks](#template-blocks)
@@ -103,7 +105,7 @@ P2 features:
 - [Deferred Evaluation](#deferred-evaluation)
 - [API Reference](#api-reference)
 
-## Basic Usage
+## Getting Started
 
 In P2, an HTML template is expressed as a proc:
 
@@ -113,7 +115,7 @@ html = -> {
 }
 ```
 
-Rendering a template is done using `#render`:
+Rendering a template is done using `Proc#render`:
 
 ```ruby
 require 'p2'
@@ -121,7 +123,7 @@ require 'p2'
 html.render #=> "<div id="greeter"><p>Hello!</p></div>"
 ```
 
-## Expressing HTML Using Ruby
+## Markup
 
 Tags are added using unqualified method calls, and can be nested using blocks:
 
@@ -172,7 +174,7 @@ An attribute value given as an array will be joined by space characters:
 -> { div class: [:foo, :bar] }.render #=> "<div class=\"foo bar\"></div>"
 ```
 
-## Tag and Attribute Formatting
+### Tag and Attribute Formatting
 
 P2 does not make any assumption about what tags and attributes you can use. You
 can mix upper and lower case letters, and you can include arbitrary characters
@@ -198,16 +200,137 @@ normally used for tags:
 }.render #=> '<cra_zy__:!tag>foo</cra_zy__:!tag>'
 ```
 
-## Escaping Content
+### Escaping Content
 
 P2 automatically escapes all text content emitted in a template. The specific
-escaping algorithm depends on the template type. For HTML templates, P2 uses
-[escape_utils](https://github.com/brianmario/escape_utils), specifically:
+escaping algorithm depends on the template type. To emit raw HTML, use the
+`#raw` method as [described below](#builtin-methods).
+
+## Builtin Methods
+
+In addition to normal tags, P2 provides the following method calls for templates:
+
+### `#text` - emit escaped text
+
+`#text` is used for emitting text that will be escaped. This method can be used
+to emit text not directly inside an enclosing tag:
+
+```ruby
+-> {
+  p {
+    text 'The time is: '
+    span(Time.now, id: 'clock')
+  }
+}.render #=> <p>The time is: <span id="clock">XX:XX:XX</span></p>
+```
+
+### `#raw` - emit raw HTML
+
+`#raw` is used for emitting raw HTML, i.e. without escaping. You can use this to
+emit an HTML snippet:
+
+```ruby
+TITLE_HTML = '<h1>hi</h1>'
+-> {
+  div {
+    raw TITLE_HTML
+  }
+}.render #=> <div><h1>hi</h1></div>
+```
+
+### `#render_yield` - emit given block
+
+`#render_yield` is used to emit a given block. If no block is given, a
+`LocalJumpError` exception is raised:
+
+```ruby
+Card = ->(**props) {
+  card { render_yield(**props) }
+}
+
+Card.render(foo: 'bar') { |foo|
+  h1 foo
+} #=> <card><h1>bar</h1></card>
+```
+
+`render_yield` can be called with or without arguments, which are passed to the
+given block.
+
+### `#render_children` - emit given block
+
+`#render_children` is used to emit a given block, but does not raise an
+exception if no block is given.
+
+### `#defer` - emit deferred HTML
+
+`#defer` is used to emit HTML in a deferred fashion - the deferred part will be
+evaluated only after processing the entire template:
+
+```ruby
+Layout = -> {
+  head {
+    defer {
+      title @title
+    }
+  }
+  body {
+    render_yield
+  }
+}
+
+Layout.render {
+  @title = 'Foobar'
+  h1 'hi'
+} #=> <head><title>Foobar</title></head><body><h1>hi</h1></body>
+```
+
+### `#render` - render the given template inline
+
+`#render` is used to emit the given template. This can be used to compose
+templates:
 
-- HTML: `escape_utils.escape_html`
+```ruby
+partial = -> { p 'foo' }
+-> {
+  div {
+    render partial
+  }
+}.render #=> <div><p>foo</p></div>
+```
+
+Any argument following the given template is passed to the template for
+rendering:
+
+```ruby
+large_button = ->(title) { button(title, class: 'large') }
 
-In order to emit raw HTML, you can use the `#emit` method as [described
-below](#emitting-raw-html).
+-> {
+  render large_button, 'foo'
+}.render #=> <button class="large">foo</button>
+```
+
+### `#html5` - emit an HTML5 document type declaration and html tag
+
+```ruby
+-> {
+  html5 {
+    p 'hi'
+  }
+} #=> <!DOCTYPE html><html><p>hi</p></html>
+```
+
+### `#markdown` emit markdown content
+
+`#markdown` is used for rendering markdown content. The call converts the given
+markdown to HTML and emits it into the rendered HTML:
+
+```ruby
+-> {
+  div {
+    markdown 'This is *markdown*'
+  }
+}.render #=> <p>This is <em>markdown</em></p>
+```
 
 ## Template Parameters
 
@@ -216,14 +339,14 @@ parameters are specified as block parameters, and are passed to the template on
 rendering:
 
 ```ruby
-greeting = -> { |name| h1 "Hello, #{name}!" }
+greeting = ->(name) { h1 "Hello, #{name}!" }
 greeting.render('world') #=> "<h1>Hello, world!</h1>"
 ```
 
 Templates can also accept named parameters:
 
 ```ruby
-greeting = -> { |name:| h1 "Hello, #{name}!" }
+greeting = ->(name:) { h1 "Hello, #{name}!" }
 greeting.render(name: 'world') #=> "<h1>Hello, world!</h1>"
 ```
 
@@ -233,7 +356,7 @@ Since P2 templates are just a bunch of Ruby, you can easily embed your view
 logic right in the template:
 
 ```ruby
--> { |user = nil|
+->(user = nil) {
   if user
     span "Hello, #{user.name}!"
   else
@@ -244,12 +367,12 @@ logic right in the template:
 
 ## Template Blocks
 
-Templates can also accept and render blocks by using `emit_yield`:
+Templates can also accept and render blocks by using `render_yield`:
 
 ```ruby
 page = -> {
   html {
-    body { emit_yield }
+    body { render_yield }
   }
 }
 
@@ -280,7 +403,7 @@ ItemList = ->(items) {
   }
 }
 
-page = -> { |title, items|
+page = ->(title, items) {
   html5 {
     head { Title(title) }
     body { ItemList(items) }
@@ -322,7 +445,7 @@ hello_world = hello.apply('world')
 hello_world.render #=> "<h1>Hello, world!</h1>"
 
 # block application
-div_wrap = -> { div { emit_yield } }
+div_wrap = -> { div { render_yield } }
 wrapped_h1 = div_wrap.apply { h1 'hi' }
 wrapped_h1.render #=> "<div><h1>hi</h1></div>"
 
@@ -350,7 +473,7 @@ wrapped_greeter.render #=> "<div><h1>hi</h1></div>"
 The inner template can also be passed as a block, as shown above:
 
 ```ruby
-div_wrap = -> { div { emit_yield } }
+div_wrap = -> { div { render_yield } }
 wrapped_greeter = div_wrap.apply { h1 'hi' }
 wrapped_greeter.render #=> "<div><h1>hi</h1></div>"
 ```
@@ -370,7 +493,7 @@ default_layout = -> { |**params|
       title: params[:title]
     }
     body {
-      emit_yield(**params)
+      render_yield(**params)
     }
   }
 }
@@ -477,7 +600,7 @@ default_layout = -> { |**args|
   head {
     defer { render deps.head_markup }
   }
-  body { emit_yield **args }
+  body { render_yield **args }
 }
 
 button = proc { |text, onclick|

data/lib/p2/compiler/nodes.rb

@@ -1,8 +1,21 @@
 # frozen_string_literal: true
 
+class Prism::InspectVisitor
+  def visit_tag_node(node)
+    commands << [inspect_node("TagNode", node), indent]
+    # flags = [("newline" if node.newline?), ("static_literal" if node.static_literal?), ].compact
+    # commands << ["├── flags: #{flags.empty? ? "∅" : flags.join(", ")}\n", indent]
+    # commands << ["├── left:\n", indent]
+    # commands << [node.left, "#{indent}│   "]
+    # commands << ["├── right:\n", indent]
+    # commands << [node.right, "#{indent}│   "]
+    # commands << ["└── operator_loc: #{inspect_location(node.operator_loc)}\n", indent]
+  end
+end
+
 module P2
   # Represents a tag call
-  class TagNode
+  class TagNode < Prism::Node
     attr_reader :call_node, :location, :tag, :tag_location, :inner_text, :attributes, :block
 
     def initialize(call_node, translator)
@@ -78,6 +91,19 @@ module P2
     end
   end
 
+  class ConstTagNode
+    attr_reader :call_node, :location
+
+    def initialize(call_node, translator)
+      @call_node = call_node
+      @location = call_node.location
+    end
+
+    def accept(visitor)
+      visitor.visit_const_tag_node(self)
+    end
+  end
+
   # Represents a text call
   class TextNode
     attr_reader :call_node, :location
@@ -136,4 +162,62 @@ module P2
       visitor.visit_builtin_node(self)
     end
   end
+
+  class ExtensionTagNode
+    attr_reader :tag, :call_node, :location, :block
+
+    def initialize(call_node, translator)
+      @call_node = call_node
+      @tag = call_node.name
+      @location = call_node.location
+      @block = call_node.block && translator.visit(call_node.block)
+    end
+
+    def accept(visitor)
+      visitor.visit_extension_tag_node(self)
+    end
+  end
+
+  class BlockInvocationNode
+    attr_reader :call_node, :location, :block
+
+    def initialize(call_node, translator)
+      @call_node = call_node
+      @tag = call_node.name
+      @location = call_node.location
+      @block = call_node.block && translator.visit(call_node.block)
+    end
+
+    def accept(visitor)
+      visitor.visit_block_invocation_node(self)
+    end
+  end
+end
+
+class RenderYieldNode
+  attr_reader :call_node, :location
+
+  def initialize(call_node, translator)
+    @call_node = call_node
+    @tag = call_node.name
+    @location = call_node.location
+  end
+
+  def accept(visitor)
+    visitor.visit_render_yield_node(self)
+  end
+end
+
+class RenderChildrenNode
+  attr_reader :call_node, :location
+
+  def initialize(call_node, translator)
+    @call_node = call_node
+    @tag = call_node.name
+    @location = call_node.location
+  end
+
+  def accept(visitor)
+    visitor.visit_render_children_node(self)
+  end
 end

data/lib/p2/compiler/tag_translator.rb

@@ -10,22 +10,36 @@ module P2
   class TagTranslator < Prism::MutationCompiler
     include Prism::DSL
 
-    def self.transform(ast)
-      ast.accept(new)
+    def initialize(root)
+      @root = root
+      super()
     end
 
-    def visit_call_node(node)
-      # We're only interested in compiling method calls without a receiver
-      return super(node) if node.receiver
+    def self.transform(ast, root)
+      ast.accept(new(root))
+    end
+
+    def visit_call_node(node, dont_translate: false)
+      return super(node) if dont_translate
+
+      match_builtin(node) ||
+      match_extension(node) ||
+      match_const_tag(node) ||
+      match_block_call(node) ||
+      match_tag(node) ||
+      super(node)
+    end
+
+    def match_builtin(node)
+      return if node.receiver
 
       case node.name
-      when :emit_yield
-        yield_node(
-          location: node.location,
-          arguments: node.arguments
-        )
+      when :render_yield
+        RenderYieldNode.new(node, self)
+      when :render_children
+        RenderChildrenNode.new(node, self)
       when :raise
-        super(node)
+        visit_call_node(node, dont_translate: true)
       when :render
         RenderNode.new(node, self)
       when :raw
@@ -37,8 +51,43 @@ module P2
       when :html5, :markdown
         BuiltinNode.new(node, self)
       else
-        TagNode.new(node, self)
+        nil
       end
     end
+
+    def match_extension(node)
+      return if node.receiver
+      return if !P2::Extensions[node.name]
+    
+      ExtensionTagNode.new(node, self)
+    end
+
+    def match_const_tag(node)
+      return if node.receiver
+      return if node.name !~ /^[A-Z]/
+
+      ConstTagNode.new(node, self)
+    end
+
+    def match_block_call(node)
+      return if !node.receiver
+      return if node.name != :call
+
+      receiver = node.receiver
+      return if !receiver.is_a?(Prism::LocalVariableReadNode)
+      return if @root.parameters&.parameters.block&.name != receiver.name
+
+      if node.block
+        raise P2::Error, 'No support for proc invocation with block'
+      end
+
+      BlockInvocationNode.new(node, self)
+    end
+
+    def match_tag(node)
+      return if node.receiver
+
+      TagNode.new(node, self)
+    end
   end
 end

data/lib/p2/compiler.rb

@@ -23,7 +23,7 @@ module P2
       ast = ast.block if ast.is_a?(Prism::CallNode)
 
       compiler = new.with_source_map(proc, ast)
-      transformed_ast = TagTranslator.transform(ast.body)
+      transformed_ast = TagTranslator.transform(ast.body, ast)
       compiler.format_compiled_template(transformed_ast, ast, wrap:, binding: proc.binding)
       [compiler.source_map, compiler.buffer]
     end
@@ -53,19 +53,22 @@ module P2
     end
 
     def self.store_source_map(source_map)
+      return if !source_map
+
       fn = source_map[:compiled_fn]
       source_map_store[fn] = source_map
     end
 
+    def self.source_location_to_fn(source_location)
+      "::(#{source_location.join(':')})"
+    end
+
     attr_reader :source_map
 
     # Initializes a compiler.
     def initialize(**)
       super(**)
       @pending_html_parts = []
-      @html_loc_start = nil
-      @html_loc_end = nil
-      @yield_used = nil
     end
 
     # Initializes a source map.
@@ -74,15 +77,26 @@ module P2
     # @param orig_ast [Prism::Node] template AST
     # @return [self]
     def with_source_map(orig_proc, orig_ast)
-      compiled_fn = "::(#{orig_proc.source_location.join(':')})"
+      fn = Compiler.source_location_to_fn(orig_proc.source_location)
+      @orig_proc = orig_proc
+      @orig_proc_fn = orig_proc.source_location.first
       @source_map = {
         source_fn: orig_proc.source_location.first,
-        compiled_fn: compiled_fn
+        compiled_fn: fn
       }
       @source_map_line_ofs = 2
       self
     end
 
+    def update_source_map(str = nil)
+      return if !@source_map
+
+      buffer_cur_line = @buffer.count("\n") + 1
+      orig_source_cur_line = @last_loc_start ? @last_loc_start.first : '?'
+      @source_map[buffer_cur_line + @source_map_line_ofs] ||=
+        "#{@orig_proc_fn}:#{orig_source_cur_line}"
+    end
+
     # Formats the source code for a compiled template proc.
     #
     # @param ast [Prism::Node] translated AST
@@ -92,6 +106,7 @@ module P2
     def format_compiled_template(ast, orig_ast, wrap:, binding:)
       # generate source code
       @binding = binding
+      update_source_map
       visit(ast)
       flush_html_parts!(semicolon_prefix: true)
       update_source_map
@@ -99,6 +114,7 @@ module P2
       source_code = @buffer
       @buffer = +''
       if wrap
+        @source_map[2] = "#{@orig_proc_fn}:#{loc_start(orig_ast.location).first}"
         emit("# frozen_string_literal: true\n->(__buffer__")
 
         params = orig_ast.parameters
@@ -108,11 +124,12 @@ module P2
           emit(format_code(params))
         end
 
-        if @yield_used
+        if @render_yield_used || @render_children_used
           emit(', &__block__')
         end
 
         emit(") {\n")
+
       end
       @buffer << source_code
       emit_defer_postlude if @defer_mode
@@ -120,8 +137,6 @@ module P2
         emit('; __buffer__')
         adjust_whitespace(orig_ast.closing_loc)
         emit('}')
-        # emit(";") if @buffer !~ /\n\s*$/m
-        # emit("rescue Exception => e; P2.translate_backtrace(e, src_map); raise e; end }")
       end
       update_source_map
       Compiler.store_source_map(@source_map)
@@ -134,10 +149,8 @@ module P2
     # @return [void]
     def visit_tag_node(node)
       tag = node.tag
-      if tag.is_a?(Symbol) && tag =~ /^[A-Z]/
-        return visit_const_tag_node(node.call_node)
-      end
 
+      # adjust_whitespace(node.location)
       is_void = is_void_element?(tag)
       emit_html(node.tag_location, format_html_tag_open(tag, node.attributes))
       return if is_void
@@ -170,14 +183,14 @@ module P2
     def visit_const_tag_node(node)
       flush_html_parts!
       adjust_whitespace(node.location)
-      if node.receiver
-        emit(node.receiver.location)
+      if node.call_node.receiver
+        emit(node.call_node.receiver.location)
         emit('::')
       end
-      emit("; #{node.name}.compiled_proc.(__buffer__")
-      if node.arguments
+      emit("; #{node.call_node.name}.compiled_proc.(__buffer__")
+      if node.call_node.arguments
         emit(', ')
-        visit(node.arguments)
+        visit(node.call_node.arguments)
       end
       emit(');')
     end
@@ -288,25 +301,109 @@ module P2
       end
     end
 
-    # Visits a yield node.
+    # Visits a extension tag node.
     #
-    # @param node [P2::YieldNode] node
+    # @param node [P2::ExtensionTagNode] node
     # @return [void]
-    def visit_yield_node(node)
+    def visit_extension_tag_node(node)
       flush_html_parts!
       adjust_whitespace(node.location)
-      @yield_used = true
-      emit("; (__block__ ? __block__.compiled_proc.(__buffer__")
-      if node.arguments
+      emit("; P2::Extensions[#{node.tag.inspect}].compiled_proc.(__buffer__")
+      if node.call_node.arguments
         emit(', ')
-        visit(node.arguments)
+        visit(node.call_node.arguments)
+      end
+      if node.block
+        block_body = format_inline_block(node.block.body)
+        block_params = []
+
+        if node.block.parameters.is_a?(Prism::ItParametersNode)
+          raise P2::Error, "Blocks passed to extensions cannot use it parameter"
+        end
+
+        if (params = node.block.parameters&.parameters)
+          params.requireds.each do
+            block_params << format_code(it) if !it.is_a?(Prism::ItParametersNode)
+          end
+          params.optionals.each do
+            block_params << format_code(it) if !it.is_a?(Prism::ItParametersNode)
+          end
+          block_params << format_code(params.rest) if params.rest
+          params.posts.each do
+            block_params << format_code(it) if !it.is_a?(Prism::ItParametersNode)
+          end
+          params.keywords.each do
+            block_params << format_code(it) if !it.is_a?(Prism::ItParametersNode)
+          end
+          block_params << format_code(params.keyword_rest) if params.keyword_rest
+        end
+        block_params = block_params.empty? ? '' : ", #{block_params.join(', ')}"
+        
+        emit(", &(proc { |__buffer__#{block_params}| #{block_body} }).compiled!")
       end
-      emit(") : raise(LocalJumpError, 'no block given (yield/emit_yield)'))")
+      emit(")")
+    end
+
+    # Visits a render_yield node.
+    #
+    # @param node [P2::RenderYieldNode] node
+    # @return [void]
+    def visit_render_yield_node(node)
+      flush_html_parts!
+      adjust_whitespace(node.location)
+      guard = @render_yield_used ?
+        '' : "; raise(LocalJumpError, 'no block given (render_yield)') if !__block__"
+      @render_yield_used = true
+      emit("#{guard}; __block__.compiled_proc.(__buffer__")
+      if node.call_node.arguments
+        emit(', ')
+        visit(node.call_node.arguments)
+      end
+      emit(")")
+    end
+
+    # Visits a render_children node.
+    #
+    # @param node [P2::RenderChildrenNode] node
+    # @return [void]
+    def visit_render_children_node(node)
+      flush_html_parts!
+      adjust_whitespace(node.location)
+      @render_children_used = true
+      emit("; __block__&.compiled_proc&.(__buffer__")
+      if node.call_node.arguments
+        emit(', ')
+        visit(node.call_node.arguments)
+      end
+      emit(")")
+    end
+
+    def visit_block_invocation_node(node)
+      flush_html_parts!
+      adjust_whitespace(node.location)
+
+      emit("; #{node.call_node.receiver.name}.compiled_proc.(__buffer__")
+      if node.call_node.arguments
+        emit(', ')
+        visit(node.call_node.arguments)
+      end
+      if node.call_node.block
+        emit(", &(->")
+        visit(node.call_node.block)
+        emit(").compiled_proc")
+      end
+      emit(")")
     end
 
     private
 
     # Overrides the Sourcifier behaviour to flush any buffered HTML parts.
+    #
+    # @param loc [Prism::Location] location
+    # @param semicolon [bool] prefix a semicolon before emitted code
+    # @param chomp [bool] chomp the emitted code
+    # @param flush_html [bool] flush pending HTML parts before emitting the code
+    # @return [void]
     def emit_code(loc, semicolon: false, chomp: false, flush_html: true)
       flush_html_parts! if flush_html
       super(loc, semicolon:, chomp: )
@@ -329,6 +426,10 @@ module P2
       Compiler.new(minimize_whitespace: true).to_source(node)
     end
 
+    def format_inline_block(node)
+      Compiler.new(minimize_whitespace: true).format_compiled_template(node, node, wrap: false, binding: @binding)
+    end
+
     # Formats a comma separated list of AST nodes. Used for formatting partial
     # argument lists.
     #
@@ -485,8 +586,8 @@ module P2
     # @return [void]
     def emit_html(loc, str)
       @html_loc_start ||= loc
-      @html_loc_end = loc
-      @pending_html_parts << str
+      @html_loc_end ||= loc
+      @pending_html_parts << [loc, str]
     end
 
     # Flushes pending HTML parts to the source code buffer.
@@ -495,31 +596,30 @@ module P2
     def flush_html_parts!(semicolon_prefix: true)
       return if @pending_html_parts.empty?
 
-      adjust_whitespace(@html_loc_start)
-
-      code = +''
-      part = +''
+      adjust_whitespace(@html_loc_start, advance_to_end: false)
+      concatenated = +''
 
-      @pending_html_parts.each do
-        if (m = it.match(/^#\{(.+)\}$/m))
-          emit_html_buffer_push(code, part, quotes: true) if !part.empty?
-          emit_html_buffer_push(code, m[1])
+      last_loc = @html_loc_start
+      @pending_html_parts.each do |(loc, part)|
+        if (m = part.match(/^#\{(.+)\}$/m))
+          emit_html_buffer_push(concatenated, quotes: true) if !concatenated.empty?
+          adjust_whitespace(loc, advance_to_end: false)
+          emit_html_buffer_push(m[1])
         else
-          part << it
+          concatenated << part
         end
+        last_loc = loc
       end
-      emit_html_buffer_push(code, part, quotes: true) if !part.empty?
+      emit_html_buffer_push(concatenated, quotes: true) if !concatenated.empty?
 
       @pending_html_parts.clear
 
-      @last_loc = @html_loc_end
-      @last_loc_start = loc_start(@html_loc_end)
-      @last_loc_end = loc_end(@html_loc_end)
+      @last_loc = last_loc
+      @last_loc_start = loc_start(@last_loc)
+      @last_loc_end = @last_loc_start
 
       @html_loc_start = nil
       @html_loc_end = nil
-
-      emit code
     end
 
     # Emits HTML buffer push code to the given source code buffer.
@@ -528,11 +628,11 @@ module P2
     # @param part [String] HTML part
     # @param quotes [bool] whether to wrap emitted HTML in double quotes
     # @return [void]
-    def emit_html_buffer_push(buf, part, quotes: false)
+    def emit_html_buffer_push(part, quotes: false)
       return if part.empty?
 
       q = quotes ? '"' : ''
-      buf << "; __buffer__ << #{q}#{part}#{q}"
+      emit("; __buffer__ << #{q}#{part}#{q}")
       part.clear
     end
 

data/lib/p2/proc_ext.rb

@@ -11,6 +11,16 @@ class ::Proc
     P2::Compiler.compile_to_code(self).last
   end
 
+  def source_map
+    loc = source_location
+    fn = compiled? ? loc.first : P2::Compiler.source_location_to_fn(loc)
+    P2::Compiler.source_map_store[fn]
+  end
+
+  def ast
+    Sirop.to_ast(self)
+  end
+
   # Returns true if proc is marked as compiled
   #
   # @return [bool] is the proc marked as compiled
@@ -40,7 +50,10 @@ class ::Proc
   # @return [Proc] compiled proc
   def compile
     P2::Compiler.compile(self).compiled!
-  rescue Sirop::Error
+  rescue Sirop::Error => e
+    puts '!' * 40
+    p self
+    p e
     raise P2::Error, "Dynamically defined procs cannot be compiled"
   end
 
@@ -50,8 +63,7 @@ class ::Proc
   def render(*a, **b, &c)
     compiled_proc.(+'', *a, **b, &c)
   rescue Exception => e
-    P2.translate_backtrace(e)
-    raise e
+    raise P2.translate_backtrace(e)
   end
 
   # Renders the proc into the given buffer
@@ -59,6 +71,8 @@ class ::Proc
   # @return [String] HTML string
   def render_to_buffer(buf, *a, **b, &c)
     compiled_proc.(buf, *a, **b, &c)
+  rescue Exception => e
+    raise P2.translate_backtrace(e)
   end
 
   # Returns a proc that applies the given arguments to the original proc
@@ -76,4 +90,11 @@ class ::Proc
       compiled.(__buffer__, *a, *x, **b, **y, &c_proc)
     }.compiled!
   end
+
+  # Caches and returns 
+  def render_cached(*args, **kargs)
+    @render_cache ||= {}
+    key = args.empty? && kargs.empty? ? nil : [args, kargs]
+    @render_cache[key] ||= render(*args, **kargs)
+  end
 end

data/lib/p2/template.rb

@@ -5,7 +5,9 @@ module P2
   # templates and other kinds of procs.
   class Template
     attr_reader :proc
-    def initialize(proc) = @proc = proc
-    def render(*, **, &) = @proc.render(*, **, &)
+    def initialize(proc)  = @proc = proc
+    def render(*, **, &)  = @proc.render(*, **, &)
+    def apply(*, **, &)   = Template.new(@proc.apply(*, **, &))
+    def compiled_proc     = @proc.compiled_proc
   end
 end

data/lib/p2/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module P2
-  VERSION = '2.4'
+  VERSION = '2.8'
 end

data/lib/p2.rb

@@ -12,6 +12,18 @@ module P2
 
   extend self
 
+  # Registry of P2 exgtensions
+  Extensions = {}
+
+  # Registers extensions to the P2 syntax.
+  # 
+  # @param spec [Hash] hash mapping symbols to procs
+  # @return [self]
+  def extension(spec)
+    Extensions.merge!(spec)
+    self
+  end
+
   # Formats the given string, converting underscores to dashes.
   #
   # @param tag [String, Symbol] input string
@@ -39,21 +51,23 @@ module P2
     end
   end
 
-  # Translates an exceptions backtrace using a source map.
-  #
-  # @param exception [Exception] raised exception
-  # @param source_map [Hash] source map
+  # Translates entries in exception's backtrace to point to original source code.
   #
+  # @param err [Exception] raised exception
   # @return [Exception] raised exception
-  def translate_backtrace(exception)
+  def translate_backtrace(err)
     cache = {}
-    backtrace = exception.backtrace.map { |e| compute_backtrace_entry(e, cache) }
-    exception.set_backtrace(backtrace)
-    exception
+    is_argument_error = err.is_a?(ArgumentError) && err.backtrace[0] =~ /^\:\:/
+    backtrace = err.backtrace.map { |e| compute_backtrace_entry(e, cache) }
+
+    return make_argument_error(err, backtrace) if is_argument_error
+
+    err.set_backtrace(backtrace)
+    err
   end
 
   # Computes a backtrace entry with caching.
-  # 
+  #
   # @param entry [String] backtrace entry
   # @param cache [Hash] cache store mapping compiled filename to source_map
   def compute_backtrace_entry(entry, cache)
@@ -65,8 +79,19 @@ module P2
     source_map = cache[fn] ||= Compiler.source_map_store[fn]
     return entry if !source_map
 
-    source_line = source_map[line] || "?(#{line})"
-    entry.sub(m[1], "#{source_map[:source_fn]}:#{source_line}")
+    ref = source_map[line] || "?(#{line})"
+    entry.sub(m[1], ref)
+  end
+
+  def make_argument_error(err, backtrace)
+    m = err.message.match(/(given (\d+), expected (\d+))/)
+    if m
+      rectified = format('given %d, expected %d', m[2].to_i - 1, m[3].to_i - 1)
+      message = err.message.gsub(m[1], rectified)
+    else
+      message = err.message
+    end
+    ArgumentError.new(message).tap { it.set_backtrace(backtrace) }
   end
 
   # Renders Markdown into HTML. The `opts` argument will be merged with the

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: p2
 version: !ruby/object:Gem::Version
-  version: '2.4'
+  version: '2.8'
 platform: ruby
 authors:
 - Sharon Rosner
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.3
+        version: '0.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.3
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: kramdown
   requirement: !ruby/object:Gem::Requirement