RubyGems - p2 - Versions diffs - 2.8 → 2.10 - Mend

p2 2.8 → 2.10

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

Files changed (9) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +19 -6
data/README.md +20 -39
data/lib/p2/compiler/tag_translator.rb +1 -1
data/lib/p2/compiler.rb +32 -18
data/lib/p2/proc_ext.rb +40 -22
data/lib/p2/version.rb +1 -1
data/lib/p2.rb +6 -5
metadata +2 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a84949b86e99acbe131d37cb624dbf60010fe720ce27081d5e5652b33f2de004
-  data.tar.gz: c03bef8c358bae1536c04739c2fa67bd3ce6e879fd036f2e7352c6291677b888
+  metadata.gz: 14c5c67f786953f8783be2cb53cb1eb4ad54be9f1ce769ce340cdc07d45b7a52
+  data.tar.gz: 1788cf26c810fa3f4d47b6db4b0de149b223e47d6a8356af7dea580190664da9
 SHA512:
-  metadata.gz: 2993a42368846048e02ca7cb01d2ba6f7be013870a5f39597478442d16659b730356443b1b77ee8bb36c6b9a3942bde7d8ef19e66ad087d2a69d9b686d5cc706
-  data.tar.gz: 7739be72dd3bdf195188339509a21e24bccbae6ac8efb140a16780445f71b60fea12ab0a87831f117422b620102c277391f33db944b94b7945088f16cf099d73
+  metadata.gz: c898b73cbfeffcc1227bc15889d43e78dd03f745a9aee584767f4e8c22ae25d698190454c5cea9600735dddcc2da91a95fb7324b5cf906ef19824ba3dce7020c
+  data.tar.gz: 6575f62f6158438bc95bea56d60d0f6fe4e11b1e45269584f6a644ffcd3d647e20bd712a869a556d882c4ff00a74a93f1bdefb5e8fe759787588bae9b3ba4abb

data/CHANGELOG.md CHANGED Viewed

@@ -1,7 +1,20 @@
+# 2.10 2025-09-11
+- Add support for rendering XML, implement `Proc#render_xml`
+- Fix handling of literal strings with double quotes
+- Improve error handling for `P2::Error` exceptions
+# 2.9 2025-09-02
+- Tweak generated code to incorporate @byroot's
+  [recommendations](https://www.reddit.com/r/ruby/comments/1mtj7bx/comment/n9ckbvt/):
+  - Remove call to to_s coercion before calling html_escape
+  - Chain calls to `#<<` with emitted HTML parts
 # 2.8 2025-08-17
-- Add render_children builtin
-- Rename emit_yield to render_yield
+- Add `#render_children` builtin
+- Rename `#emit_yield` to `#render_yield`
 - Add `Proc#render_cached` for caching render result
 # 2.7 2025-08-17
@@ -12,13 +25,13 @@
 # 2.6 2025-08-16
-- Add support for block invocation.
+- 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.
+- 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

data/README.md CHANGED Viewed

@@ -10,8 +10,8 @@
   <a href="http://rubygems.org/gems/p2">
     <img src="https://badge.fury.io/rb/p2.svg" alt="Ruby gem">
   </a>
-  <a href="https://github.com/digital-fabric/p2/actions?query=workflow%3ATests">
-    <img src="https://github.com/digital-fabric/p2/workflows/Tests/badge.svg" alt="Tests">
+  <a href="https://github.com/digital-fabric/p2/actions/workflows/test.yml">
+    <img src="https://github.com/digital-fabric/p2/actions/workflows/test.yml/badge.svg" alt="Tests">
   </a>
   <a href="https://github.com/digital-fabric/p2/blob/master/LICENSE">
     <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
@@ -39,7 +39,6 @@ page.render {
 #=> "<html><head><title>Title</title></head><body><p>foo</p></body></html>"
 ```
 P2 is a templating engine for dynamically producing HTML in Ruby apps. P2
 templates are expressed as Ruby procs, leading to easier debugging, better
 protection against HTML injection attacks, and better code reuse.
@@ -90,7 +89,7 @@ P2 features:
 ## Table of Content
 - [Getting Started](#getting-started)
-- [Basic Markup](#markup)
+- [Basic Markup](#basic-markup)
 - [Builtin Methods](#builtin-methods)
 - [Template Parameters](#template-parameters)
 - [Template Logic](#template-logic)
@@ -99,11 +98,12 @@ P2 features:
 - [Parameter and Block Application](#parameter-and-block-application)
 - [Higher-Order Templates](#higher-order-templates)
 - [Layout Template Composition](#layout-template-composition)
-- [Emitting Raw HTML](#emitting-raw-html)
-- [Emitting a String with HTML Escaping](#emitting-a-string-with-html-escaping)
 - [Emitting Markdown](#emitting-markdown)
 - [Deferred Evaluation](#deferred-evaluation)
-- [API Reference](#api-reference)
+- [Cached Rendering](#cached-rendering)
+A typical example for a dashboard-type app markup can be found here:
+https://github.com/digital-fabric/p2/blob/master/examples/dashboard.rb
 ## Getting Started
@@ -123,7 +123,7 @@ require 'p2'
 html.render #=> "<div id="greeter"><p>Hello!</p></div>"
 ```
-## Markup
+## Basic Markup
 Tags are added using unqualified method calls, and can be nested using blocks:
@@ -511,24 +511,6 @@ article_layout.render(
 )
 ```
-## Emitting Raw HTML
-Raw HTML can be emitted using `#raw`:
-```ruby
-wrapped = -> { |html| div { raw html } }
-wrapped.render("<h1>hi</h1>") #=> "<div><h1>hi</h1></div>"
-```
-## Emitting a String with HTML Escaping
-To emit a string with proper HTML escaping, without wrapping it in an HTML
-element, use `#text`:
-```ruby
--> { text 'hi&lo' }.render #=> "hi&amp;lo"
-```
 ## Emitting Markdown
 Markdown is rendered using the
@@ -626,18 +608,17 @@ page = default_layout.apply {
 }
 ```
-## HTML Utility methods
+## Cached Rendering
-HTML templates include a few HTML-specific methods to facilitate writing modern
-HTML:
+P2 provides a simple API for caching the result of a rendering. The cache stores
+renderings of a template respective to the given arguments. To automatically
+retrieve the cached rendered HTML, or generate it for the first time, use
+`Proc#render_cached`:
-- `html5 { ... }` - emits an HTML 5 DOCTYPE (`<!DOCTYPE html>`)
-- `import_map(root_path, root_url)` - emits an import map including all files
-  matching `<root_path>/*.js`, based on the given `root_url`
-- `js_module(js)` - emits a `<script type="module">` element
-- `link_stylesheet(href, **attributes)` - emits a `<link rel="stylesheet" ...>`
-  element
-- `script(js, **attributes)` - emits an inline `<script>` element
-- `style(css, **attributes)` - emits an inline `<style>` element
-- `versioned_file_href(href, root_path, root_url)` - calculates a versioned href
-  for the given file
+```ruby
+template = ->(title) { div { h1 title } }
+template.render_cached('foo') #=> <div><h1>foo</h1></div>
+template.render_cached('foo') #=> <div><h1>foo</h1></div> (from cache)
+template.render_cached('bar') #=> <div><h1>bar</h1></div>
+template.render_cached('bar') #=> <div><h1>bar</h1></div> (from cache)
+```

data/lib/p2/compiler/tag_translator.rb CHANGED Viewed

@@ -58,7 +58,7 @@ module P2
     def match_extension(node)
       return if node.receiver
       return if !P2::Extensions[node.name]
       ExtensionTagNode.new(node, self)
     end

data/lib/p2/compiler.rb CHANGED Viewed

@@ -14,15 +14,16 @@ module P2
     # generated optimized source code.
     #
     # @param proc [Proc] template
+    # @param mode [Symbol] compilation mode (:html, :xml)
     # @param wrap [bool] whether to wrap the generated code with a literal Proc definition
     # @return [Array] array containing the source map and generated code
-    def self.compile_to_code(proc, wrap: true)
+    def self.compile_to_code(proc, mode: :html, wrap: true)
       ast = Sirop.to_ast(proc)
       # adjust ast root if proc is defined with proc {} / lambda {} syntax
       ast = ast.block if ast.is_a?(Prism::CallNode)
-      compiler = new.with_source_map(proc, ast)
+      compiler = new(mode:).with_source_map(proc, ast)
       transformed_ast = TagTranslator.transform(ast.body, ast)
       compiler.format_compiled_template(transformed_ast, ast, wrap:, binding: proc.binding)
       [compiler.source_map, compiler.buffer]
@@ -37,10 +38,11 @@ module P2
     #     compiled.render #=> '<h1>Hello, world!'
     #
     # @param proc [Proc] template
+    # @param mode [Symbol] compilation mode (:html, :xml)
     # @param wrap [bool] whether to wrap the generated code with a literal Proc definition
     # @return [Proc] compiled proc
-    def self.compile(proc, wrap: true)
-      source_map, code = compile_to_code(proc, wrap:)
+    def self.compile(proc, mode: :html, wrap: true)
+      source_map, code = compile_to_code(proc, mode:, wrap:)
       if ENV['DEBUG'] == '1'
         puts '*' * 40
         puts code
@@ -66,8 +68,9 @@ module P2
     attr_reader :source_map
     # Initializes a compiler.
-    def initialize(**)
+    def initialize(mode:, **)
       super(**)
+      @mode = mode
       @pending_html_parts = []
     end
@@ -168,9 +171,7 @@ module P2
         if is_static_node?(node.inner_text)
           emit_html(node.location, ERB::Escape.html_escape(format_literal(node.inner_text)))
         else
-          to_s = is_string_type_node?(node.inner_text) ? '' : '.to_s'
-          emit_html(node.location, interpolated("ERB::Escape.html_escape((#{format_code(node.inner_text)})#{to_s})"))
+          emit_html(node.location, interpolated("ERB::Escape.html_escape((#{format_code(node.inner_text)}))"))
         end
       end
       emit_html(node.location, format_html_tag_close(tag))
@@ -230,7 +231,7 @@ module P2
         if is_static_node?(first_arg)
           emit_html(node.location, ERB::Escape.html_escape(format_literal(first_arg)))
         else
-          emit_html(node.location, interpolated("ERB::Escape.html_escape(#{format_code(first_arg)}.to_s)"))
+          emit_html(node.location, interpolated("ERB::Escape.html_escape(#{format_code(first_arg)})"))
         end
       else
         raise "Don't know how to compile #{node}"
@@ -338,7 +339,7 @@ module P2
           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(")")
@@ -423,11 +424,11 @@ module P2
     # @param node [Prism::Node] AST
     # @return [String] generated source code
     def format_code(node)
-      Compiler.new(minimize_whitespace: true).to_source(node)
+      Compiler.new(mode: @mode, 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)
+      Compiler.new(mode: @mode, 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
@@ -436,7 +437,7 @@ module P2
     # @param list [Array<Prism::Node>] node list
     # @return [String] generated source code
     def format_code_comma_separated_nodes(list)
-      compiler = self.class.new(minimize_whitespace: true)
+      compiler = Compiler.new(mode: @mode, minimize_whitespace: true)
       compiler.visit_comma_separated_nodes(list)
       compiler.buffer
     end
@@ -448,6 +449,8 @@ module P2
     # @param tag [String, Symbol] HTML tag
     # @return [bool] void or not
     def is_void_element?(tag)
+      return false if @mode == :xml
       VOID_TAGS.include?(tag.to_s)
     end
@@ -497,7 +500,9 @@ module P2
     def format_literal(node)
       case node
       when Prism::SymbolNode, Prism::StringNode
-        node.unescaped
+        # since the value is copied verbatim into a quoted string, we need to
+        # add a backslash before any double quote.
+        node.unescaped.gsub('"', '\"')
       when Prism::IntegerNode, Prism::FloatNode
         node.value.to_s
       when Prism::InterpolatedStringNode
@@ -597,14 +602,16 @@ module P2
       return if @pending_html_parts.empty?
       adjust_whitespace(@html_loc_start, advance_to_end: false)
+      emit('; __buffer__')
       concatenated = +''
       last_loc = @html_loc_start
       @pending_html_parts.each do |(loc, part)|
         if (m = part.match(/^#\{(.+)\}$/m))
+          # interpolated part
           emit_html_buffer_push(concatenated, quotes: true) if !concatenated.empty?
-          adjust_whitespace(loc, advance_to_end: false)
-          emit_html_buffer_push(m[1])
+          # adjust_whitespace(loc, advance_to_end: false)
+          emit_html_buffer_push(m[1], loc:)
         else
           concatenated << part
         end
@@ -628,11 +635,18 @@ 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(part, quotes: false)
+    def emit_html_buffer_push(part, quotes: false, loc: nil)
       return if part.empty?
       q = quotes ? '"' : ''
-      emit("; __buffer__ << #{q}#{part}#{q}")
+      if loc
+        emit(".<<(")
+        adjust_whitespace(loc, advance_to_end: false)
+        emit("#{q}#{part}#{q}")
+        emit(")")
+      else
+        emit(".<<(#{q}#{part}#{q})")
+      end
       part.clear
     end

data/lib/p2/proc_ext.rb CHANGED Viewed

@@ -2,34 +2,40 @@
 require_relative './compiler'
-# Extensions to the Proc class
+# Extensions to the Proc class.
 class ::Proc
-  # Returns the compiled form code for the proc
+  # Returns the compiled form code for the proc.
   #
   # @return [String] compiled proc code
   def compiled_code
     P2::Compiler.compile_to_code(self).last
   end
+  # Returns the source map for the compiled proc.
+  #
+  # @return [Array<String>] source map
   def source_map
     loc = source_location
     fn = compiled? ? loc.first : P2::Compiler.source_location_to_fn(loc)
     P2::Compiler.source_map_store[fn]
   end
+  # Returns the AST for the proc.
+  #
+  # @return [Prism::Node] AST root
   def ast
     Sirop.to_ast(self)
   end
-  # Returns true if proc is marked as compiled
+  # Returns true if proc is marked as compiled.
   #
   # @return [bool] is the proc marked as compiled
   def compiled?
     @is_compiled
   end
-  # marks the proc as compiled, i.e. can render directly and takes a string
-  # buffer as first argument
+  # Marks the proc as compiled, i.e. can render directly and takes a string
+  # buffer as first argument.
   #
   # @return [self]
   def compiled!
@@ -40,34 +46,43 @@ class ::Proc
   # Returns the compiled proc for the given proc. If marked as compiled, returns
   # self.
   #
+  # @param mode [Symbol] compilation mode (:html, :xml)
   # @return [Proc] compiled proc or self
-  def compiled_proc
-    @compiled_proc ||= @is_compiled ? self : compile
+  def compiled_proc(mode: :html)
+    @compiled_proc ||= @is_compiled ? self : compile(mode:)
   end
-  # Compiles the proc into the compiled form
+  # Compiles the proc into the compiled form.
   #
+  # @param mode [Symbol] compilation mode (:html, :xml)
   # @return [Proc] compiled proc
-  def compile
-    P2::Compiler.compile(self).compiled!
-  rescue Sirop::Error => e
-    puts '!' * 40
-    p self
-    p e
+  def compile(mode: :html)
+    P2::Compiler.compile(self, mode:).compiled!
+  rescue Sirop::Error
     raise P2::Error, "Dynamically defined procs cannot be compiled"
   end
-  # Renders the proc to HTML with the given arguments
+  # Renders the proc to HTML with the given arguments.
   #
   # @return [String] HTML string
   def render(*a, **b, &c)
     compiled_proc.(+'', *a, **b, &c)
   rescue Exception => e
-    raise P2.translate_backtrace(e)
+    e.is_a?(P2::Error) ? raise : raise(P2.translate_backtrace(e))
   end
-  # Renders the proc into the given buffer
+  # Renders the proc to XML with the given arguments.
   #
+  # @return [String] XML string
+  def render_xml(*a, **b, &c)
+    compiled_proc(mode: :xml).(+'', *a, **b, &c)
+  rescue Exception => e
+    e.is_a?(P2::Error) ? raise : raise(P2.translate_backtrace(e))
+  end
+  # Renders the proc to HTML with the given arguments into the given buffer.
+  #
+  # @param buf [String] buffer
   # @return [String] HTML string
   def render_to_buffer(buf, *a, **b, &c)
     compiled_proc.(buf, *a, **b, &c)
@@ -75,7 +90,7 @@ class ::Proc
     raise P2.translate_backtrace(e)
   end
-  # Returns a proc that applies the given arguments to the original proc
+  # Returns a proc that applies the given arguments to the original proc.
   #
   # @return [Proc] applied proc
   def apply(*a, **b, &c)
@@ -91,10 +106,13 @@ class ::Proc
     }.compiled!
   end
-  # Caches and returns
-  def render_cached(*args, **kargs)
+  # Caches and returns the rendered HTML for the template with the given
+  # arguments.
+  #
+  # @return [String] HTML string
+  def render_cached(*args, **kargs, &block)
     @render_cache ||= {}
-    key = args.empty? && kargs.empty? ? nil : [args, kargs]
-    @render_cache[key] ||= render(*args, **kargs)
+    key = args.empty? && kargs.empty? && !block ? nil : [args, kargs, block&.source_location]
+    @render_cache[key] ||= render(*args, **kargs, &block)
   end
 end

data/lib/p2/version.rb CHANGED Viewed

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

data/lib/p2.rb CHANGED Viewed

@@ -16,7 +16,7 @@ module P2
   Extensions = {}
   # Registers extensions to the P2 syntax.
-  #
+  #
   # @param spec [Hash] hash mapping symbols to procs
   # @return [self]
   def extension(spec)
@@ -101,10 +101,11 @@ module P2
   # @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'
+    @markdown_deps_loaded ||= true.tap do
+      require 'kramdown'
+      require 'rouge'
+      require 'kramdown-parser-gfm'
+    end
     opts = default_kramdown_options.merge(opts)
     Kramdown::Document.new(markdown, **opts).to_html

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: p2
 version: !ruby/object:Gem::Version
-  version: '2.8'
+  version: '2.10'
 platform: ruby
 authors:
 - Sharon Rosner
@@ -135,7 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.0.dev
 specification_version: 4
 summary: 'P2: component-based HTML templating for Ruby'
 test_files: []