RubyGems - p2 - Versions diffs - 2.0 → 2.1 - Mend

p2 2.0 → 2.1

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

Files changed (8) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37c651c3157074dde83015d5e4e6db8a44ef90b12a8dd890a585539e3eb80b4d
-  data.tar.gz: 384d6a649bc089c24d578185f75a7e5a09b22825d70f1367e55b0e8a7f0e3cd8
+  metadata.gz: c34fa05073968d2f8aed0d766ec9b59275fdb061ce2a328ad18038ce0f986068
+  data.tar.gz: c0bab8233ffc293432b33a531e554ebc379ec7d796c2f4046e105b185e0c5f5e
 SHA512:
-  metadata.gz: 6565857078969d64aced3c864d295ca9d4627b08bff842eda2578d8759022ac78c3553b3feef99550efee9498a5f0a943ffae2ca12f5dd001162165101bad557
-  data.tar.gz: d0b758535f27c4ec60dac2649d79504c01fcc3e021e318259ea475215cd3d62efec1e360a9529c2bdc6bc1068ed31c44d6339fd44e99aae1bcb4bd8eb97983e8
+  metadata.gz: bb711aac468494ad590779e45a97fa9593d9a7e0e172389ae14125ba1576a4dda90bf5f796c56592d8a1b939cf00d2a69cd91386f5ef583453b2045bee333f5d
+  data.tar.gz: 8a1ee9990feb82379a01bd1971b00c844d3b0f3f9f0cc6531596619f47abf0e56c629d04e34a54f12594e7a73718e88854ab6056b30ad8019ab9a63d133e2101

data/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,21 @@
+# 2.1 2025-08-08
+- Optimize output code: directly invoke component templates instead of calling
+  `P2.render_emit_call`. P2 is now
+- Optimize output code: use separate pushes to buffer instead of interpolated
+  strings.
+- Streamline API: `emit proc` => `render`, `emit str` => `raw`, `emit_markdown`
+  => `markdown`
+- Optimize output code: add `frozen_string_literal` to top of compiled code
+- Add more benchmarks (#1)
+- Optimize output code: use ERB::Escape.html_escape instead of CGI.escape_html
+  (#2)
+- Fix source map calculation
+## 2.0.1 2025-08-07
+- Fix source map calculation
 ## 2.0 2025-08-07
 - Passes all HTML, compilation tests from Papercraft

data/README.md CHANGED Viewed

@@ -4,7 +4,7 @@
   P2
 </h1>
-<h4 align="center">Composable templating for Ruby</h4>
+<h4 align="center">Functional HTML templating for Ruby</h4>
 <p align="center">
   <a href="http://rubygems.org/gems/p2">
@@ -24,9 +24,9 @@
 ## What is P2?
-P2 is a templating engine for dynamically producing [HTML](#html-templates). P2
-templates are expressed as Ruby procs, leading to easier debugging, better
-protection against HTML/XML injection attacks, and better code reuse.
+P2 is a templating engine for dynamically producing HTML. P2 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
@@ -37,11 +37,8 @@ making the data flow easy to follow and understand. P2 also lets developers
 create derivative templates using full or partial parameter application.
 P2 includes built-in support for rendering Markdown (using
-[Kramdown](https://github.com/gettalong/kramdown/)).
-P2 automatically escapes all text emitted in templates according to the template
-type. For more information see the section on [escaping
-content](#escaping-content).
+[Kramdown](https://github.com/gettalong/kramdown/)). P2 also automatically
+escapes all text emitted in templates.
 ```ruby
 require 'p2'
@@ -64,6 +61,16 @@ hello.render(name: 'world')
 #=> "<html><head><title>Title</title></head><body><h1>Hello, world!</h1></body></html>"
 ```
+P2 features:
+- Express HTML using plain Ruby procs.
+- Automatic compilation for super-fast execution (up to 2X faster than ERB templates).
+- Deferred rendering using `defer`.
+- Template composition (for uses such as layouts).
+- Automatic conversion of backtraces for exceptions occurring while rendering,
+  in order to point to the correct spot in the original template code.
 ## Table of Content
 - [Installing P2](#installing-p2)
@@ -79,7 +86,7 @@ hello.render(name: 'world')
 - [Higher-Order Templates](#higher-order-templates)
 - [Layout Template Composition](#layout-template-composition)
 - [Emitting Raw HTML](#emitting-raw-html)
-- [Emitting a String with HTML Encoding](#emitting-a-string-with-html-encoding)
+- [Emitting a String with HTML Escaping](#emitting-a-string-with-html-escaping)
 - [Emitting Markdown](#emitting-markdown)
 - [Deferred Evaluation](#deferred-evaluation)
 - [API Reference](#api-reference)
@@ -291,14 +298,14 @@ page.render('Hello from composed templates', [
 ```
 In addition to using templates defined as constants, you can also use
-non-constant templates by invoking the `#emit` method:
+non-constant templates by invoking the `#render` method:
 ```ruby
 greeting = -> { span "Hello, world" }
 -> {
   div {
-    emit greeting
+    render greeting
   }
 }
 ```
@@ -338,7 +345,7 @@ templates or injecting template parameters.
 Here is a higher-order template that takes a template as parameter:
 ```ruby
-div_wrap = -> { |inner| div { emit inner } }
+div_wrap = -> { |inner| div { render inner } }
 greeter = -> { h1 'hi' }
 wrapped_greeter = div_wrap.apply(greeter)
 wrapped_greeter.render #=> "<div><h1>hi</h1></div>"
@@ -375,7 +382,7 @@ default_layout = -> { |**params|
 article_layout = default_layout.apply { |title:, body:|
   article {
     h1 title
-    emit_markdown body
+    markdown body
   }
 }
@@ -387,16 +394,16 @@ article_layout.render(
 ## Emitting Raw HTML
-Raw HTML can be emitted using `#emit`:
+Raw HTML can be emitted using `#raw`:
 ```ruby
-wrapped = -> { |html| div { emit html } }
+wrapped = -> { |html| div { raw html } }
 wrapped.render("<h1>hi</h1>") #=> "<div><h1>hi</h1></div>"
 ```
-## Emitting a String with HTML Encoding
+## Emitting a String with HTML Escaping
-To emit a string with proper HTML encoding, without wrapping it in an HTML
+To emit a string with proper HTML escaping, without wrapping it in an HTML
 element, use `#text`:
 ```ruby
@@ -407,19 +414,19 @@ element, use `#text`:
 Markdown is rendered using the
 [Kramdown](https://kramdown.gettalong.org/index.html) gem. To emit Markdown, use
-`#emit_markdown`:
+`#markdown`:
 ```ruby
-template = -> { |md| div { emit_markdown md } }
+template = -> { |md| div { markdown md } }
 template.render("Here's some *Markdown*") #=> "<div><p>Here's some <em>Markdown</em><p>\n</div>"
 ```
 [Kramdown
 options](https://kramdown.gettalong.org/options.html#available-options) can be
-specified by adding them to the `#emit_markdown` call:
+specified by adding them to the `#markdown` call:
 ```ruby
-template = -> { |md| div { emit_markdown md, auto_ids: false } }
+template = -> { |md| div { markdown md, auto_ids: false } }
 template.render("# title") #=> "<div><h1>title</h1></div>"
 ```
@@ -471,7 +478,7 @@ integrated into the page, and adds them to the page's `<head>` element:
 default_layout = -> { |**args|
   @dependencies = DependencyMananger.new
   head {
-    defer { emit @dependencies.head_markup }
+    defer { render @dependencies.head_markup }
   }
   body { emit_yield **args }
 }
@@ -491,11 +498,11 @@ heading = proc { |text|
 }
 page = default_layout.apply {
-  emit heading, "What's your favorite cheese?"
+  render heading, "What's your favorite cheese?"
-  emit button, 'Beaufort', 'eat_beaufort()'
-  emit button, 'Mont d''or', 'eat_montdor()'
-  emit button, 'Époisses', 'eat_epoisses()'
+  render button, 'Beaufort', 'eat_beaufort()'
+  render button, 'Mont d''or', 'eat_montdor()'
+  render button, 'Époisses', 'eat_epoisses()'
 }
 ```

data/lib/p2/compiler.rb CHANGED Viewed

@@ -2,7 +2,7 @@
 require 'cgi'
 require 'sirop'
-require 'digest/md5'
+require 'erb/escape'
 module P2
   class TagNode
@@ -48,7 +48,7 @@ module P2
     end
   end
-  class EmitNode
+  class RenderNode
     attr_reader :call_node, :location, :block
     include Prism::DSL
@@ -107,7 +107,7 @@ module P2
     end
     def accept(visitor)
-      visitor.visit_emit_node(self)
+      visitor.visit_render_node(self)
     end
   end
@@ -124,6 +124,19 @@ module P2
     end
   end
+  class RawNode
+    attr_reader :call_node, :location
+    def initialize(call_node, _compiler)
+      @call_node = call_node
+      @location = call_node.location
+    end
+    def accept(visitor)
+      visitor.visit_raw_node(self)
+    end
+  end
   class DeferNode
     attr_reader :call_node, :location, :block
@@ -172,13 +185,15 @@ module P2
         )
       when :raise
         super(node)
-      when :emit, :e
-        EmitNode.new(node, self)
+      when :render
+        RenderNode.new(node, self)
+      when :raw
+        RawNode.new(node, self)
       when :text
         TextNode.new(node, self)
       when :defer
         DeferNode.new(node, self)
-      when :html5, :emit_markdown, :markdown
+      when :html5, :markdown
         CustomTagNode.new(node, self)
       else
         TagNode.new(node, self)
@@ -207,6 +222,10 @@ module P2
     def self.compile(proc, wrap: true)
       source_map, code = compile_to_code(proc, wrap:)
+      if ENV['DEBUG'] == '1'
+        puts '*' * 40
+        puts code
+      end
       eval(code, proc.binding, source_map[:compiled_fn])
     end
@@ -221,12 +240,12 @@ module P2
     end
     def with_source_map(orig_proc, orig_ast)
-      ast_digest = Digest::MD5.hexdigest(orig_ast.inspect)
+      compiled_fn = "::(#{orig_proc.source_location.join(':')})"
       @source_map = {
         source_fn: orig_proc.source_location.first,
-        compiled_fn: "::#{ast_digest}"
+        compiled_fn: compiled_fn
       }
-      @source_map_line_ofs = 1
+      @source_map_line_ofs = 2
       self
     end
@@ -235,11 +254,12 @@ module P2
       @binding = binding
       visit(ast)
       flush_html_parts!(semicolon_prefix: true)
+      update_source_map
       source_code = @buffer
       @buffer = +''
       if wrap
-        emit("(#{@source_map.inspect}).then { |src_map| ->(__buffer__")
+        emit("# frozen_string_literal: true\n(#{@source_map.inspect}).then { |src_map| ->(__buffer__")
         params = orig_ast.parameters
         params = params&.parameters
@@ -291,13 +311,13 @@ module P2
       if node.inner_text
         if is_static_node?(node.inner_text)
-          emit_html(node.location, CGI.escape_html(format_literal(node.inner_text)))
+          emit_html(node.location, ERB::Escape.html_escape(format_literal(node.inner_text)))
         else
           convert_to_s = !is_string_type_node?(node.inner_text)
           if convert_to_s
-            emit_html(node.location, "#\{CGI.escape_html((#{format_code(node.inner_text)}).to_s)}")
+            emit_html(node.location, interpolated("ERB::Escape.html_escape((#{format_code(node.inner_text)}).to_s)"))
           else
-            emit_html(node.location, "#\{CGI.escape_html(#{format_code(node.inner_text)})}")
+            emit_html(node.location, interpolated("ERB::Escape.html_escape(#{format_code(node.inner_text)})"))
           end
         end
       end
@@ -319,34 +339,50 @@ module P2
       emit(');')
     end
-    def visit_emit_node(node)
+    def visit_render_node(node)
+      args = node.call_node.arguments.arguments
+      first_arg = args.first
+      block_embed = node.block && "&(->(__buffer__) #{format_code(node.block)}.compiled!)"
+      block_embed = ", #{block_embed}" if block_embed && node.call_node.arguments
+      flush_html_parts!
+      adjust_whitespace(node.location)
+      if args.length == 1
+        emit("; #{format_code(first_arg)}.compiled_proc.(__buffer__#{block_embed})")
+      else
+        args_code = format_code_comma_separated_nodes(args[1..])
+        emit("; #{format_code(first_arg)}.compiled_proc.(__buffer__, #{args_code}#{block_embed})")
+      end
+    end
+    def visit_text_node(node)
+      return if !node.call_node.arguments
       args = node.call_node.arguments.arguments
       first_arg = args.first
       if args.length == 1
         if is_static_node?(first_arg)
-          emit_html(node.location, format_literal(first_arg))
-        elsif first_arg.is_a?(Prism::LambdaNode)
-          visit(first_arg.body)
+          emit_html(node.location, ERB::Escape.html_escape(format_literal(first_arg)))
         else
-          emit_html(node.location, "#\{P2.render_emit_call(#{format_code(first_arg)})}")
+          emit_html(node.location, interpolated("ERB::Escape.html_escape(#{format_code(first_arg)}.to_s)"))
         end
       else
-        block_embed = node.block ? "&(->(__buffer__) #{format_code(node.block)}.compiled!)" : nil
-        block_embed = ", #{block_embed}" if block_embed && node.call_node.arguments
-        emit_html(node.location, "#\{P2.render_emit_call(#{format_code(node.call_node.arguments)}#{block_embed})}")
+        raise "Don't know how to compile #{node}"
       end
     end
-    def visit_text_node(node)
+    def visit_raw_node(node)
       return if !node.call_node.arguments
       args = node.call_node.arguments.arguments
       first_arg = args.first
       if args.length == 1
         if is_static_node?(first_arg)
-          emit_html(node.location, CGI.escape_html(format_literal(first_arg)))
+          emit_html(node.location, format_literal(first_arg))
         else
-          emit_html(node.location, "#\{CGI.escape_html(#{format_code(first_arg)}.to_s)}")
+          emit_html(node.location, interpolated("(#{format_code(first_arg)}).to_s"))
         end
       else
         raise "Don't know how to compile #{node}"
@@ -381,11 +417,11 @@ module P2
         emit_html(node.location, '<!DOCTYPE html><html>')
         visit(node.block.body) if node.block
         emit_html(node.block.closing_loc, '</html>')
-      when :emit_markdown, :markdown
+      when :markdown
         args = node.call_node.arguments
         return if !args
-        emit_html(node.location, "#\{P2.markdown(#{format_code(args)})}")
+        emit_html(node.location, interpolated("P2.markdown(#{format_code(args)})"))
       end
     end
@@ -403,10 +439,20 @@ module P2
     private
-    def format_code(node, klass = TemplateCompiler)
+    def interpolated(str)
+      "#\{#{str}}"
+    end
+    def format_code(node, klass = self.class)
       klass.new(minimize_whitespace: true).to_source(node)
     end
+    def format_code_comma_separated_nodes(list)
+      compiler = self.class.new(minimize_whitespace: true)
+      compiler.visit_comma_separated_nodes(list)
+      compiler.buffer
+    end
     VOID_TAGS = %w(area base br col embed hr img input link meta param source track wbr)
     def is_void_element?(tag)
@@ -487,7 +533,7 @@ module P2
           !is_static_node?(it.key) || !is_static_node?(it.value)
       end
-      return "#\{P2.format_html_attrs(#{format_code(node)})}" if dynamic_attributes
+      return interpolated("P2.format_html_attrs(#{format_code(node)})") if dynamic_attributes
       parts = elements.map do
         key = it.key
@@ -521,11 +567,20 @@ module P2
       return if @pending_html_parts.empty?
       adjust_whitespace(@html_loc_start)
-      if semicolon_prefix && @buffer =~ /[^\s]\s*$/m
-        emit '; '
+      code = +''
+      part = +''
+      @pending_html_parts.each do
+        if (m = it.match(/^#\{(.+)\}$/m))
+          emit_buffer_push(code, part, quotes: true) if !part.empty?
+          emit_buffer_push(code, m[1])
+        else
+          part << it
+        end
       end
+      emit_buffer_push(code, part, quotes: true) if !part.empty?
-      str = @pending_html_parts.join
       @pending_html_parts.clear
       @last_loc = @html_loc_end
@@ -535,7 +590,15 @@ module P2
       @html_loc_start = nil
       @html_loc_end = nil
-      emit "__buffer__ << \"#{str}\""
+      emit code
+    end
+    def emit_buffer_push(buf, part, quotes: false)
+      return if part.empty?
+      q = quotes ? '"' : ''
+      buf << "; __buffer__ << #{q}#{part}#{q}"
+      part.clear
     end
     def emit_postlude

data/lib/p2/proc_ext.rb CHANGED Viewed

@@ -5,13 +5,15 @@ require_relative './compiler'
 # Extensions to the Proc class
 class ::Proc
   def compiled_code
-    P2::TemplateCompiler.compile_to_code(self)
+    P2::TemplateCompiler.compile_to_code(self).last
   end
   def compiled?
     @is_compiled
   end
+  # marks the proc as compiled, i.e. can render directly and takes a string
+  # buffer as first argument
   def compiled!
     @is_compiled = true
     self
@@ -22,7 +24,7 @@ class ::Proc
   end
   def compile
-    P2.compile(self).compiled!
+    P2::TemplateCompiler.compile(self).compiled!
   rescue Sirop::Error
     uncompiled_renderer
   end

data/lib/p2/version.rb CHANGED Viewed

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

data/lib/p2.rb CHANGED Viewed

@@ -8,94 +8,84 @@ module P2
   # Exception class used to signal templating-related errors
   class Error < RuntimeError; end
-  class << self
-    def compile(proc)
-      P2::TemplateCompiler.compile(proc)
-    end
+  extend self
-    def format_tag(tag)
-      tag.to_s.gsub('_', '-')
-    end
+  def format_tag(tag)
+    tag.to_s.gsub('_', '-')
+  end
-    def format_html_attr_key(tag)
-      tag.to_s.tr('_', '-')
-    end
+  def format_html_attr_key(tag)
+    tag.to_s.tr('_', '-')
+  end
-    def format_html_attrs(attrs)
-      attrs.each_with_object(+'') do |(k, v), html|
-        case v
-        when nil, false
-        when true
-          html << ' ' if !html.empty?
-          html << format_html_attr_key(k)
-        else
-          html << ' ' if !html.empty?
-          v = v.join(' ') if v.is_a?(Array)
-          html << "#{format_html_attr_key(k)}=\"#{v}\""
-        end
+  def format_html_attrs(attrs)
+    attrs.each_with_object(+'') do |(k, v), html|
+      case v
+      when nil, false
+      when true
+        html << ' ' if !html.empty?
+        html << format_html_attr_key(k)
+      else
+        html << ' ' if !html.empty?
+        v = v.join(' ') if v.is_a?(Array)
+        html << "#{format_html_attr_key(k)}=\"#{v}\""
       end
     end
+  end
-    def render_emit_call(o, *a, **b, &block)
-      case o
-      when nil
-        # do nothing
-      when ::Proc
-        o.render(*a, **b, &block)
+  def translate_backtrace(e, source_map)
+    re = compute_source_map_re(source_map)
+    source_fn = source_map[:source_fn]
+    backtrace = e.backtrace.map {
+      if (m = it.match(re))
+        line = m[2].to_i
+        source_line = source_map[line] || "?(#{line})"
+        it.sub(m[1], "#{source_fn}:#{source_line}")
       else
-        o.to_s
+        it
       end
-    end
+    }
+    e.set_backtrace(backtrace)
+  end
-    def translate_backtrace(e, source_map)
-      re = /^(#{source_map[:compiled_fn]}\:(\d+))/
-      source_fn = source_map[:source_fn]
-      backtrace = e.backtrace.map {
-        if (m = it.match(re))
-          line = m[2].to_i
-          source_line = source_map[line] || "?(#{line})"
-          it.sub(m[1], "#{source_fn}:#{source_line}")
-        else
-          it
-        end
-      }
-      e.set_backtrace(backtrace)
-    end
+  def compute_source_map_re(source_map)
+    escaped = source_map[:compiled_fn].gsub(/[\(\)]/) { "\\#{it[0]}" }
+    /^(#{escaped}\:(\d+))/
+  end
-    # Renders Markdown into HTML. The `opts` argument will be merged with the
-    # default Kramdown options in order to change the rendering behaviour.
-    #
-    # @param markdown [String] Markdown
-    # @param opts [Hash] Kramdown option overrides
-    # @return [String] HTML
-    def markdown(markdown, **opts)
-      # require relevant deps on use
-      require 'kramdown'
-      require 'rouge'
-      require 'kramdown-parser-gfm'
-      opts = default_kramdown_options.merge(opts)
-      Kramdown::Document.new(markdown, **opts).to_html
-    end
+  # Renders Markdown into HTML. The `opts` argument will be merged with the
+  # default Kramdown options in order to change the rendering behaviour.
+  #
+  # @param markdown [String] Markdown
+  # @param opts [Hash] Kramdown option overrides
+  # @return [String] HTML
+  def markdown(markdown, **opts)
+    # require relevant deps on use
+    require 'kramdown'
+    require 'rouge'
+    require 'kramdown-parser-gfm'
+    opts = default_kramdown_options.merge(opts)
+    Kramdown::Document.new(markdown, **opts).to_html
+  end
-    # Returns the default Kramdown options used for rendering Markdown.
-    #
-    # @return [Hash] Kramdown options
-    def default_kramdown_options
-      @default_kramdown_options ||= {
-        entity_output: :numeric,
-        syntax_highlighter: :rouge,
-        input: 'GFM',
-        hard_wrap: false
-      }
-    end
+  # Returns the default Kramdown options used for rendering Markdown.
+  #
+  # @return [Hash] Kramdown options
+  def default_kramdown_options
+    @default_kramdown_options ||= {
+      entity_output: :numeric,
+      syntax_highlighter: :rouge,
+      input: 'GFM',
+      hard_wrap: false
+    }
+  end
-    # Sets the default Kramdown options used for rendering Markdown.
-    #
-    # @param opts [Hash] Kramdown options
-    # @return [void]
-    def default_kramdown_options=(opts)
-      @default_kramdown_options = opts
-    end
+  # Sets the default Kramdown options used for rendering Markdown.
+  #
+  # @param opts [Hash] Kramdown options
+  # @return [void]
+  def default_kramdown_options=(opts)
+    @default_kramdown_options = opts
   end
 end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: p2
 version: !ruby/object:Gem::Version
-  version: '2.0'
+  version: '2.1'
 platform: ruby
 authors:
 - Sharon Rosner
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.1
+        version: 0.8.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.1
+        version: 0.8.3
 - !ruby/object:Gem::Dependency
   name: kramdown
   requirement: !ruby/object:Gem::Requirement
@@ -111,9 +111,8 @@ homepage: http://github.com/digital-fabric/p2
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/digital-fabric/p2
-  documentation_uri: https://www.rubydoc.info/gems/p2
   homepage_uri: https://github.com/digital-fabric/p2
+  documentation_uri: https://www.rubydoc.info/gems/p2
   changelog_uri: https://github.com/digital-fabric/p2/blob/master/CHANGELOG.md
 rdoc_options:
 - "--title"