RubyGems - p2 - Versions diffs - 2.0.1 → 2.2 - Mend

p2 2.0.1 → 2.2

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 (10) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +19 -0
data/README.md +56 -66
data/lib/p2/compiler/nodes.rb +139 -0
data/lib/p2/compiler/tag_translator.rb +44 -0
data/lib/p2/compiler.rb +226 -237
data/lib/p2/proc_ext.rb +32 -42
data/lib/p2/version.rb +1 -1
data/lib/p2.rb +85 -79
metadata +5 -17

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a0a95331ecb304e4fb0ae830d5c1f30a160a4ec9d26d86de8b22454fbef21e2
-  data.tar.gz: 49ecb084b5881d3f8287c4af46edfbf9b83930438baddafb3502ddf44b2a8b24
+  metadata.gz: b35bc76b761dd22bacd7e2b8844f3be20cabdb38ee6174d4e4eaeb144f5562d8
+  data.tar.gz: d677436567940ef41f922892b55844685d31fc52a8287c06f2ea0d89d2f1db55
 SHA512:
-  metadata.gz: 3b4aae65ebce0e4e87adf6e19e7c7731aa481dfeb3d6efb66c2ae345c704f828d0d2143a147e49f49061e0ad30c1b48209d198ffa9aaeca1cd743167257e297b
-  data.tar.gz: 6efe1aedca928c95a0102e1192c3406f8657c54536f18c0db741f86b8b365c9a178565171d7f5476f78ebb47b566a6d075c5dad674d6c4ae41fc995f603a0ce5
+  metadata.gz: 37dd322edd50f7061e4375dbc8cb06a22d137106757250d99bc58b625e2dae8c7ea8fc00990e801caee03bae5fe59ba040b8456ef4e14b632874c30cf0784476
+  data.tar.gz: fe24352b6bbc3843c0213e842f07cd094ae83bbb6475f86174e43dd8a55ba9497b832e9b195ef8364f7c5984dc60c4370fc971a7297a79c8d692e9453456d63a

data/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,22 @@
+# 2.2 2025-08-09
+- Update docs
+- Refactor code
+# 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

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,21 +24,34 @@
 ## What is P2?
-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.
+```ruby
+require 'p2'
+page = ->(**props) {
+  html {
+    head { title 'My Title' }
+    body { emit_yield **props }
+  }
+}
+page.render {
+  p 'foo'
+}
+#=> "<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.
 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.
-In P2, dynamic data is passed explicitly to the template as block arguments,
-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 also automatically
-escapes all text emitted in templates.
+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
+developers create derivative templates using full or partial parameter
+application.
 ```ruby
 require 'p2'
@@ -50,9 +63,9 @@ page = ->(**props) {
   }
 }
 page.render {
-  p 'foo'
+  p(class: 'big') 'foo'
 }
-#=> "<html><head><title>Title</title></head><body><p>foo</p></body></html>"
+#=> "<html><head><title>Title</title></head><body><p class="big">foo</p></body></html>"
 hello_page = page.apply ->(name:, **) {
   h1 "Hello, #{name}!"
@@ -64,16 +77,15 @@ hello.render(name: 'world')
 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.
+- 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).
 ## Table of Content
-- [Installing P2](#installing-p2)
 - [Basic Usage](#basic-usage)
 - [Adding Tags](#adding-tags)
 - [Tag and Attribute Formatting](#tag-and-attribute-formatting)
@@ -86,27 +98,11 @@ P2 features:
 - [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)
-## Installing P2
-**Note**: P2 requires Ruby version 3.4 or newer.
-Using bundler:
-```ruby
-gem 'p2'
-```
-Or manually:
-```bash
-$ gem install p2
-```
 ## Basic Usage
 In P2, an HTML template is expressed as a proc:
@@ -125,7 +121,7 @@ require 'p2'
 html.render #=> "<div id="greeter"><p>Hello!</p></div>"
 ```
-## Adding Tags
+## Expressing HTML Using Ruby
 Tags are added using unqualified method calls, and can be nested using blocks:
@@ -298,14 +294,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
   }
 }
 ```
@@ -345,7 +341,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>"
@@ -382,7 +378,7 @@ default_layout = -> { |**params|
 article_layout = default_layout.apply { |title:, body:|
   article {
     h1 title
-    emit_markdown body
+    markdown body
   }
 }
@@ -394,16 +390,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
@@ -414,19 +410,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>"
 ```
@@ -443,7 +439,7 @@ The default Kramdown options are:
   entity_output: :numeric,
   syntax_highlighter: :rouge,
   input: 'GFM',
-  hard_wrap: false
+  hard_wrap: false
 }
 ```
@@ -475,34 +471,35 @@ class that can collect JS and CSS dependencies from the different templates
 integrated into the page, and adds them to the page's `<head>` element:
 ```ruby
+deps = DependencyMananger.new
 default_layout = -> { |**args|
-  @dependencies = DependencyMananger.new
   head {
-    defer { emit @dependencies.head_markup }
+    defer { render deps.head_markup }
   }
   body { emit_yield **args }
 }
 button = proc { |text, onclick|
-  @dependencies.js '/static/js/button.js'
-  @dependencies.css '/static/css/button.css'
+  deps.js '/static/js/button.js'
+  deps.css '/static/css/button.css'
   button text, onclick: onclick
 }
 heading = proc { |text|
-  @dependencies.js '/static/js/heading.js'
-  @dependencies.css '/static/css/heading.css'
+  deps.js '/static/js/heading.js'
+  deps.css '/static/css/heading.css'
   h1 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()'
 }
 ```
@@ -521,10 +518,3 @@ HTML:
 - `style(css, **attributes)` - emits an inline `<style>` element
 - `versioned_file_href(href, root_path, root_url)` - calculates a versioned href
   for the given file
-[HTML docs](https://www.rubydoc.info/gems/p2/P2/HTML)
-## API Reference
-The API reference for this library can be found
-[here](https://www.rubydoc.info/gems/p2).

data/lib/p2/compiler/nodes.rb ADDED Viewed

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+module P2
+  # Represents a tag call
+  class TagNode
+    attr_reader :call_node, :location, :tag, :tag_location, :inner_text, :attributes, :block
+    def initialize(call_node, translator)
+      @call_node = call_node
+      @location = call_node.location
+      @tag = call_node.name
+      prepare_block(translator)
+      args = call_node.arguments&.arguments
+      return if !args
+      if @tag == :tag
+        @tag = args[0]
+        args = args[1..]
+      end
+      if args.size == 1 && args.first.is_a?(Prism::KeywordHashNode)
+        @inner_text = nil
+        @attributes = args.first
+      else
+        @inner_text = args.first
+        @attributes = args[1].is_a?(Prism::KeywordHashNode) ? args[1] : nil
+      end
+    end
+    def accept(visitor)
+      visitor.visit_tag_node(self)
+    end
+    def prepare_block(translator)
+      @block = call_node.block
+      if @block.is_a?(Prism::BlockNode)
+        @block = translator.visit(@block)
+        offset = @location.start_offset
+        length = @block.opening_loc.start_offset - offset
+        @tag_location = @location.copy(start_offset: offset, length: length)
+      else
+        @tag_location = @location
+      end
+    end
+  end
+  # Represents a render call
+  class RenderNode
+    attr_reader :call_node, :location, :block
+    include Prism::DSL
+    def initialize(call_node, translator)
+      @call_node = call_node
+      @location = call_node.location
+      @translator = translator
+      @block = call_node.block && translator.visit(call_node.block)
+      lambda = call_node.arguments && call_node.arguments.arguments[0]
+    end
+    def ad_hoc_string_location(str)
+      src = source(str)
+      Prism::DSL.location(source: src, start_offset: 0, length: str.bytesize)
+    end
+    def transform(node)
+      node && @translator.visit(node)
+    end
+    def transform_array(array)
+      array ? array.map { @translator.visit(it) } : []
+    end
+    def accept(visitor)
+      visitor.visit_render_node(self)
+    end
+  end
+  # Represents a text call
+  class TextNode
+    attr_reader :call_node, :location
+    def initialize(call_node, _translator)
+      @call_node = call_node
+      @location = call_node.location
+    end
+    def accept(visitor)
+      visitor.visit_text_node(self)
+    end
+  end
+  # Represents a raw call
+  class RawNode
+    attr_reader :call_node, :location
+    def initialize(call_node, _translator)
+      @call_node = call_node
+      @location = call_node.location
+    end
+    def accept(visitor)
+      visitor.visit_raw_node(self)
+    end
+  end
+  # Represents a defer call
+  class DeferNode
+    attr_reader :call_node, :location, :block
+    def initialize(call_node, translator)
+      @call_node = call_node
+      @location = call_node.location
+      @block = call_node.block && translator.visit(call_node.block)
+    end
+    def accept(visitor)
+      visitor.visit_defer_node(self)
+    end
+  end
+  # Represents a builtin call
+  class BuiltinNode
+    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_builtin_node(self)
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+require 'prism'
+require_relative './nodes'
+module P2
+  # Translates a normal proc AST into an AST containing custom nodes used for
+  # generating HTML. This translation is the first step in compiling templates
+  # into procs that generate HTML.
+  class TagTranslator < Prism::MutationCompiler
+    include Prism::DSL
+    def self.transform(ast)
+      ast.accept(new)
+    end
+    def visit_call_node(node)
+      # We're only interested in compiling method calls without a receiver
+      return super(node) if node.receiver
+      case node.name
+      when :emit_yield
+        yield_node(
+          location: node.location,
+          arguments: node.arguments
+        )
+      when :raise
+        super(node)
+      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, :markdown
+        BuiltinNode.new(node, self)
+      else
+        TagNode.new(node, self)
+      end
+    end
+  end
+end