RubyGems - papercraft - Versions diffs - 2.23 → 3.0 - Mend

papercraft 2.23 → 3.0

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 CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f77a2ff47a98a713d1449c0ae27d4a250e478e5455257955fc5e7af34a8331b
-  data.tar.gz: 6893f861f98361f48fdd0b0c2648c687d24149df217e0125da0ccc4795e40c69
+  metadata.gz: ac74fb8004af29f1b15e8ca36de8039d3e47c6642105032fa1a51ec46bda100a
+  data.tar.gz: 2b5fcf6bc6d472c33033381577b62e0875594a56e3a8f9f1d769b64d4a6ec2ce
 SHA512:
-  metadata.gz: b76597b671e62bdb67483c0cd30e4c716084655d0a80cad41c4a77405c97e8300712201f3cf2215584f979b7ae2d3c7e29770868bbda753b9faca88f633101a7
-  data.tar.gz: 5bbb94d2ec5c13ab5da17c4474d0338d195abd5149dbddb75d1e0fbcb371c1e620c9666169233dad04cc4b8b6265bfc13d9d41c1115fe37a61e30549e0f06ea2
+  metadata.gz: 390c81c371d17216134e931b26e1d6c9728c54e2c8db220b0d21761f9ed7d21b12f784b5642e7473e55c1f65f2bad4fe07f9afa09d78c04b7d54569ed7cc5ebf
+  data.tar.gz: 9801c61a0a9788a563396bed4064b0b0f4aeacb82e43677c52bfc83ed1d25d7b001af4915c3bdb86b6191b1f5681bd1b54460fbaaa626bfde32e471cb12a830f

data/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,19 @@
+# 3.0.0 2025-10-19
+- Improve implementation of `Papercraft.apply`
+- Add support for rendering self-closing XML tags
+- Streamline Papercraft API
+- Add support for `Papercraft.render { ... }`
+- Prefix internal Proc extensions with `__papercraft_`
+- Change API to use `Papercraft.html` instead of `Proc#render`. Same for
+  `apple`, `render_xml` etc.
+# 2.24 2025-10-14
+- Update gem links
+- Simplify `render_cache`, caller must provide cache key
+- Reduce surface area of Proc extensions
 # 2.23 2025-10-12
 - Update ERB to version 5.1.1

data/README.md CHANGED Viewed

@@ -18,603 +18,31 @@
   </a>
 </p>
-<p align="center">
-  <a href="https://www.rubydoc.info/gems/papercraft">API reference</a>
-</p>
-## What is Papercraft?
 ```ruby
 require 'papercraft'
-page = ->(**props) {
-  html {
-    head { title 'My Title' }
-    body { render_children **props }
+Papercraft.html {
+  div {
+    h1 "Hello from Papercraft!"
   }
 }
-page.render {
-  p 'foo'
-}
-#=> "<html><head><title>Title</title></head><body><p>foo</p></body></html>"
+#=> "<div><h1>Hello from Papercraft</h1></div>"
 ```
-Papercraft is a templating engine for dynamically producing HTML in Ruby apps. Papercraft
-templates are expressed as Ruby procs, leading to easier debugging, better
-protection against HTML injection attacks, and better code reuse.
+Papercraft is a templating engine for dynamically producing HTML in Ruby apps.
+Papercraft templates are expressed as Ruby procs, leading to easier debugging,
+better protection against HTML injection attacks, and better code reuse.
-Papercraft templates can be composed in a variety of ways, facilitating the usage of
-layout templates, and enabling a component-oriented approach to building web
-interfaces of arbitrary complexity.
+Papercraft templates can be composed in a variety of ways, facilitating the
+usage of layout templates, and enabling a component-oriented approach to
+building web interfaces of arbitrary complexity.
 In Papercraft, dynamic data is passed explicitly to the template as block/lambda
-arguments, making the data flow easy to follow and understand. Papercraft also lets
-developers create derivative templates using full or partial parameter
+arguments, making the data flow easy to follow and understand. Papercraft also
+lets developers create derivative templates using full or partial parameter
 application.
-```ruby
-require 'papercraft'
-page = ->(**props) {
-  html {
-    head { title 'My Title' }
-    body { render_children **props }
-  }
-}
-page.render {
-  p(class: 'big') 'foo'
-}
-#=> "<html><head><title>Title</title></head><body><p class="big">foo</p></body></html>"
-hello_page = page.apply ->(name:, **) {
-  h1 "Hello, #{name}!"
-}
-hello.render(name: 'world')
-#=> "<html><head><title>Title</title></head><body><h1>Hello, world!</h1></body></html>"
-```
-Papercraft features:
-- Express HTML using plain Ruby procs.
-- Automatic compilation for super-fast execution (about as
-  [fast](https://github.com/digital-fabric/papercraft/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/).
-- Rudimentary support for generating XML.
-- Support for extensions.
-- Simple caching API for caching the rendering result.
-## Table of Content
-- [Getting Started](#getting-started)
-- [Basic Markup](#basic-markup)
-- [Builtin Methods](#builtin-methods)
-- [Template Parameters](#template-parameters)
-- [Template Logic](#template-logic)
-- [Template Blocks](#template-blocks)
-- [Template Composition](#template-composition)
-- [Parameter and Block Application](#parameter-and-block-application)
-- [Higher-Order Templates](#higher-order-templates)
-- [Layout Template Composition](#layout-template-composition)
-- [Rendering Markdown](#rendering-markdown)
-- [Deferred Evaluation](#deferred-evaluation)
-- [Cached Rendering](#cached-rendering)
-A typical example for a dashboard-type app markup can be found here:
-https://github.com/digital-fabric/papercraft/blob/master/examples/dashboard.rb
-## Getting Started
-In Papercraft, an HTML template is expressed as a proc:
-```ruby
-html = -> {
-  div(id: 'greeter') { p 'Hello!' }
-}
-```
-Rendering a template is done using `Proc#render`:
-```ruby
-require 'papercraft'
-html.render #=> "<div id="greeter"><p>Hello!</p></div>"
-```
-## Basic Markup
-Tags are added using unqualified method calls, and can be nested using blocks:
-```ruby
--> {
-  html {
-    head {
-      title 'page title'
-    }
-    body {
-      article {
-        h1 'article title'
-      }
-    }
-  }
-}
-```
-Tag methods accept a string argument, a block, or no argument at all:
-```ruby
--> { p 'hello' }.render #=> "<p>hello</p>"
--> { p { span '1'; span '2' } }.render #=> "<p><span>1</span><span>2</span></p>"
--> { hr() }.render #=> "<hr/>"
-```
-Tag methods also accept tag attributes, given as a hash:
-```ruby
--> { img src: '/my.gif' }.render #=> "<img src=\"/my.gif\"/>"
--> { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</p>"
-```
-A `true` attribute value will emit a valueless attribute. A `nil` or `false`
-attribute value will emit nothing:
-```ruby
--> { button disabled: nil }.render #=> "<button></button>"
--> { button disabled: true }.render #=> "<button disabled></button>"
-```
-An attribute value given as an array will be joined by space characters:
-```ruby
--> { div class: [:foo, :bar] }.render #=> "<div class=\"foo bar\"></div>"
-```
-### Tag and Attribute Formatting
-Papercraft 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
-in tag and attribute names. However, in order to best adhere to the HTML specs
-and common practices, tag names and attributes will be formatted according to
-the following rules, depending on the template type:
-- HTML: underscores are converted to dashes:
-  ```ruby
-  -> {
-    foo_bar { p 'Hello', data_name: 'world' }
-  }.render #=> '<foo-bar><p data-name="world">Hello</p></foo-bar>'
-  ```
+## Documentation
-If you need more precise control over tag names, you can use the `#tag` method,
-which takes the tag name as its first parameter, then the rest of the parameters
-normally used for tags:
-```ruby
--> {
-  tag 'cra_zy__:!tag', 'foo'
-}.render #=> '<cra_zy__:!tag>foo</cra_zy__:!tag>'
-```
-### Escaping Content
-Papercraft automatically escapes all text content emitted in a template. The specific
-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, Papercraft 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_children` - render the given block
-`#render_children` is used to emit a given block. If no block is given, a
-`LocalJumpError` exception is raised:
-```ruby
-Card = ->(**props) {
-  card { render_children(**props) }
-}
-Card.render(foo: 'bar') { |foo|
-  h1 foo
-} #=> <card><h1>bar</h1></card>
-```
-`render_children` can be called with or without arguments, which are passed to the
-given block.
-### `#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_children
-  }
-}
-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:
-```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') }
--> {
-  render large_button, 'foo'
-}.render #=> <button class="large">foo</button>
-```
-### `#html`/`#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
-In Papercraft, parameters are always passed explicitly. This means that template
-parameters are specified as block parameters, and are passed to the template on
-rendering:
-```ruby
-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.render(name: 'world') #=> "<h1>Hello, world!</h1>"
-```
-## Template Logic
-Since Papercraft templates are just a bunch of Ruby, you can easily embed your view
-logic right in the template:
-```ruby
-->(user = nil) {
-  if user
-    span "Hello, #{user.name}!"
-  else
-    span "Hello, guest!"
-  end
-}
-```
-## Template Blocks
-Templates can also accept and render blocks by using `render_children`:
-```ruby
-page = -> {
-  html {
-    body { render_children }
-  }
-}
-# we pass the inner HTML
-page.render { h1 'hi' }
-```
-## Template Composition
-Papercraft makes it easy to compose multiple templates into a whole HTML document. A Papercraft
-template can contain other templates, 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 = ->(title, items) {
-  html5 {
-    head { Title(title) }
-    body { ItemList(items) }
-  }
-}
-page.render('Hello from composed templates', [
-  { id: 1, text: 'foo', checked: false },
-  { id: 2, text: 'bar', checked: true }
-])
-```
-In addition to using templates defined as constants, you can also use
-non-constant templates by invoking the `#render` method:
-```ruby
-greeting = -> { span "Hello, world" }
--> {
-  div {
-    render 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 template composition and the
-creation of higher-order templates.
-The `#apply` method returns a new template which applies the given parameters
-and or block to the original template:
-```ruby
-# parameter application
-hello = -> { |name| h1 "Hello, #{name}!" }
-hello_world = hello.apply('world')
-hello_world.render #=> "<h1>Hello, world!</h1>"
-# block application
-div_wrap = -> { div { render_children } }
-wrapped_h1 = div_wrap.apply { h1 'hi' }
-wrapped_h1.render #=> "<div><h1>hi</h1></div>"
-# wrap a template
-wrapped_hello_world = div_wrap.apply(&hello_world)
-wrapped_hello_world.render #=> "<div><h1>Hello, world!</h1></div>"
-```
-## Higher-Order Templates
-Papercraft also lets you create higher-order templates, that is, templates that take
-other templates as parameters, or as blocks. Higher-order templates are handy
-for creating layouts, wrapping templates in arbitrary markup, enhancing
-templates or injecting template parameters.
-Here is a higher-order template that takes a template as parameter:
-```ruby
-div_wrap = -> { |inner| div { render inner } }
-greeter = -> { h1 'hi' }
-wrapped_greeter = div_wrap.apply(greeter)
-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 { render_children } }
-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 templates 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 = -> { |**params|
-  html5 {
-    head {
-      title: params[:title]
-    }
-    body {
-      render_children(**params)
-    }
-  }
-}
-article_layout = default_layout.apply { |title:, body:|
-  article {
-    h1 title
-    markdown body
-  }
-}
-article_layout.render(
-  title: 'This is a title',
-  body: 'Hello from *markdown body*'
-)
-```
-## Rendering Markdown
-Markdown is rendered using the
-[Kramdown](https://kramdown.gettalong.org/index.html) gem. To emit Markdown, use
-`#markdown`:
-```ruby
-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 `#markdown` call:
-```ruby
-template = -> { |md| div { markdown md, auto_ids: false } }
-template.render("# title") #=> "<div><h1>title</h1></div>"
-```
-You can also use `Papercraft.markdown` directly:
-```ruby
-Papercraft.markdown('# title') #=> "<h1>title</h1>"
-```
-The default Kramdown options are:
-```ruby
-{
-  entity_output: :numeric,
-  syntax_highlighter: :rouge,
-  input: 'GFM',
-  hard_wrap: false
-}
-```
-The deafult options can be configured by accessing
-`Papercraft.default_kramdown_options`, e.g.:
-```ruby
-Papercraft.default_kramdown_options[:auto_ids] = false
-```
-## Deferred Evaluation
-Deferred evaluation allows deferring the rendering of parts of a template until
-the last moment, thus allowing an inner template to manipulate the state of the
-outer template. To in order to defer a part of a template, use `#defer`, and
-include any markup in the provided block. This technique, in in conjunction with
-holding state in instance variables, is an alternative to passing parameters,
-which can be limiting in some situations.
-A few use cases for deferred evaulation come to mind:
-- Setting the page title.
-- Adding a flash message to a page.
-- Using templates that dynamically add static dependencies (JS and CSS) to the
-  page.
-The last use case is particularly interesting. Imagine a `DependencyMananger`
-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|
-  head {
-    defer { render deps.head_markup }
-  }
-  body { render_children **args }
-}
-button = proc { |text, onclick|
-  deps.js '/static/js/button.js'
-  deps.css '/static/css/button.css'
-  button text, onclick: onclick
-}
-heading = proc { |text|
-  deps.js '/static/js/heading.js'
-  deps.css '/static/css/heading.css'
-  h1 text
-}
-page = default_layout.apply {
-  render heading, "What's your favorite cheese?"
-  render button, 'Beaufort', 'eat_beaufort()'
-  render button, 'Mont d''or', 'eat_montdor()'
-  render button, 'Époisses', 'eat_epoisses()'
-}
-```
-## Cached Rendering
-Papercraft 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`:
-```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)
-```
+For more information, please consult the [Papercraft
+website](https://papercraft.noteflakes.com/).

data/lib/papercraft/compiler.rb CHANGED Viewed

@@ -164,12 +164,23 @@ module Papercraft
       # adjust_whitespace(node.location)
       is_void = is_void_element?(tag)
       is_raw_inner_text = is_raw_inner_text_element?(tag)
+      is_empty = !node.block && !node.inner_text
-      if is_void && (node.block || node.inner_text)
+      if is_void && !is_empty
         raise Papercraft::Error, "Void element #{tag} cannot contain child nodes or inner text"
       end
-      emit_html(node.tag_location, format_html_tag_open(node.tag_location, tag, node.attributes))
+      if @mode == :xml && is_empty
+        emit_html(
+          node.tag_location,
+          format_xml_tag_self_closing(node.tag_location, tag, node.attributes)
+        )
+        return
+      end
+      emit_html(
+        node.tag_location, format_html_tag_open(node.tag_location, tag, node.attributes)
+      )
       return if is_void
       case node.block
@@ -178,7 +189,7 @@ module Papercraft
       when Prism::BlockArgumentNode
         flush_html_parts!
         adjust_whitespace(node.block)
-        emit("; #{format_code(node.block.expression)}.compiled_proc.(__buffer__)")
+        emit("; #{format_code(node.block.expression)}.__papercraft_compiled_proc.(__buffer__)")
       end
       if node.inner_text
@@ -213,7 +224,7 @@ module Papercraft
         emit(format_code(node.call_node.receiver))
         emit('::')
       end
-      emit("#{node.call_node.name}.compiled_proc.(__buffer__")
+      emit("#{node.call_node.name}.__papercraft_compiled_proc.(__buffer__")
       if node.call_node.arguments
         emit(', ')
         visit(node.call_node.arguments)
@@ -229,17 +240,17 @@ module Papercraft
       args = node.call_node.arguments.arguments
       first_arg = args.first
-      block_embed = node.block && "&(->(__buffer__) #{format_code(node.block)}.compiled!)"
+      block_embed = node.block && "&(->(__buffer__) #{format_code(node.block)}.__papercraft_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})")
+        emit("; #{format_code(first_arg)}.__papercraft_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})")
+        emit("; #{format_code(first_arg)}.__papercraft_compiled_proc.(__buffer__, #{args_code}#{block_embed})")
       end
     end
@@ -336,7 +347,7 @@ module Papercraft
     def visit_extension_tag_node(node)
       flush_html_parts!
       adjust_whitespace(node.location)
-      emit("; Papercraft::Extensions[#{node.tag.inspect}].compiled_proc.(__buffer__")
+      emit("; Papercraft::Extensions[#{node.tag.inspect}].__papercraft_compiled_proc.(__buffer__")
       if node.call_node.arguments
         emit(', ')
         visit(node.call_node.arguments)
@@ -367,7 +378,7 @@ module Papercraft
         end
         block_params = block_params.empty? ? '' : ", #{block_params.join(', ')}"
-        emit(", &(proc { |__buffer__#{block_params}| #{block_body} }).compiled!")
+        emit(", &(proc { |__buffer__#{block_params}| #{block_body} }).__papercraft_compiled!")
       end
       emit(")")
     end
@@ -382,7 +393,7 @@ module Papercraft
       guard = @render_yield_used ?
         '' : "; raise(LocalJumpError, 'no block given (render_yield)') if !__block__"
       @render_yield_used = true
-      emit("#{guard}; __block__.compiled_proc.(__buffer__")
+      emit("#{guard}; __block__.__papercraft_compiled_proc.(__buffer__")
       if node.call_node.arguments
         emit(', ')
         visit(node.call_node.arguments)
@@ -398,7 +409,7 @@ module Papercraft
       flush_html_parts!
       adjust_whitespace(node.location)
       @render_children_used = true
-      emit("; __block__&.compiled_proc&.(__buffer__")
+      emit("; __block__&.__papercraft_compiled_proc&.(__buffer__")
       if node.call_node.arguments
         emit(', ')
         visit(node.call_node.arguments)
@@ -410,7 +421,7 @@ module Papercraft
       flush_html_parts!
       adjust_whitespace(node.location)
-      emit("; #{node.call_node.receiver.name}.compiled_proc.(__buffer__")
+      emit("; #{node.call_node.receiver.name}.__papercraft_compiled_proc.(__buffer__")
       if node.call_node.arguments
         emit(', ')
         visit(node.call_node.arguments)
@@ -418,7 +429,7 @@ module Papercraft
       if node.call_node.block
         emit(", &(->")
         visit(node.call_node.block)
-        emit(").compiled_proc")
+        emit(").__papercraft_compiled_proc")
       end
       emit(")")
     end
@@ -489,6 +500,15 @@ module Papercraft
       RAW_INNER_TEXT_TAGS.include?(tag.to_s)
     end
+    def format_xml_tag_self_closing(loc, tag, attributes)
+      tag = convert_tag(tag)
+      if attributes && attributes&.elements.size > 0 || @@html_debug_attribute_injector
+        "<#{tag} #{format_html_attributes(loc, attributes)}/>"
+      else
+        "<#{tag}/>"
+      end
+    end
     # Formats an open tag with optional attributes.
     #
     # @param loc [Prism::Location] tag location

data/lib/papercraft/proc_ext.rb CHANGED Viewed

@@ -5,122 +5,37 @@ require_relative './compiler'
 module Papercraft
   # Extensions to the Proc class.
   module ProcExtensions
-    # Returns the compiled form code for the proc.
-    #
-    # @return [String] compiled proc code
-    def compiled_code
-      Papercraft::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 : Papercraft::Compiler.source_location_to_fn(loc)
-      Papercraft::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.
     #
     # @return [bool] is the proc marked as compiled
-    def compiled?
-      @is_compiled
+    def __papercraft_compiled?
+      @__papercraft_compiled
     end
     # Marks the proc as compiled, i.e. can render directly and takes a string
     # buffer as first argument.
     #
     # @return [self]
-    def compiled!
-      @is_compiled = true
+    def __papercraft_compiled!
+      @__papercraft_compiled = true
       self
     end
-    # Returns the compiled proc for the given proc. If marked as compiled, returns
+    # Returns the compiled proc for the proc. If marked as compiled, returns
     # self.
     #
     # @param mode [Symbol] compilation mode (:html, :xml)
     # @return [Proc] compiled proc or self
-    def compiled_proc(mode: :html)
-      @compiled_proc ||= @is_compiled ? self : compile(mode:)
-    end
-    # Compiles the proc into the compiled form.
-    #
-    # @param mode [Symbol] compilation mode (:html, :xml)
-    # @return [Proc] compiled proc
-    def compile(mode: :html)
-      Papercraft::Compiler.compile(self, mode:).compiled!
-    rescue Sirop::Error
-      raise Papercraft::Error, "Dynamically defined procs cannot be compiled"
-    end
-    # 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
-      e.is_a?(Papercraft::Error) ? raise : raise(Papercraft.translate_backtrace(e))
-    end
-    # 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?(Papercraft::Error) ? raise : raise(Papercraft.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)
-    rescue Exception => e
-      raise Papercraft.translate_backtrace(e)
-    end
-    # Returns a proc that applies the given arguments to the original proc. The
-    # returned proc calls the *compiled* form of the proc, merging the
-    # positional and keywords parameters passed to `#apply` with parameters
-    # passed to the applied proc. If a block is given, it is wrapped in a proc
-    # that passed merged parameters to the block.
-    #
-    # @param *pos1 [Array<any>] applied positional parameters
-    # @param **kw1 [Hash<any, any] applied keyword parameters
-    # @return [Proc] applied proc
-    def apply(*pos1, **kw1, &block)
-      compiled = compiled_proc
-      c_compiled = block&.compiled_proc
-      ->(__buffer__, *pos2, **kw2, &block2) {
-        c_proc = c_compiled && ->(__buffer__, *pos3, **kw3) {
-          c_compiled.(__buffer__, *pos3, **kw3, &block2)
-        }.compiled!
-        compiled.(__buffer__, *pos1, *pos2, **kw1, **kw2, &c_proc)
-      }.compiled!
+    def __papercraft_compiled_proc(mode: :html)
+      @__papercraft_compiled_proc ||= @__papercraft_compiled ?
+        self : Papercraft.compile(self, mode:)
     end
-    # Caches and returns the rendered HTML for the template with the given
-    # arguments.
+    # Returns the render cache for the proc.
     #
-    # @return [String] HTML string
-    def render_cached(*args, **kargs, &block)
-      @render_cache ||= {}
-      key = args.empty? && kargs.empty? && !block ? nil : [args, kargs, block&.source_location]
-      @render_cache[key] ||= render(*args, **kargs, &block)
+    # @return [Hash] cache hash
+    def __papercraft_render_cache
+      @__papercraft_render_cache ||= {}
     end
   end
 end

data/lib/papercraft/template.rb CHANGED Viewed

@@ -8,21 +8,34 @@ module Papercraft
     # @param proc [Proc] template proc
     # @param mode [Symbol] mode (:html, :xml)
-    def initialize(proc, mode: :html)
-      @proc = proc
+    def initialize(proc = nil, mode: :html, &block)
+      @proc = proc || block
+      raise ArgumentError, "No template proc given" if !@proc
       @mode = mode
     end
+    # Renders the template.
+    #
+    # @return [String] generated HTML
     def render(*, **, &)
-      (mode == :xml) ? @proc.render_xml(*, **, &) : @proc.render(*, **, &)
+      (mode == :xml) ? Papercraft.xml(@proc, *, **, &) : Papercraft.html(@proc, *, **, &)
     end
+    alias_method :call, :render
+    # Applies the given parameters and block to the template, returning an
+    # applied template.
+    #
+    # @return [Papercraft::Template] applied template
     def apply(*, **, &)
-      Template.new(@proc.apply(*, **, &), mode: @mode)
+      Template.new(Papercraft.apply(@proc, *, **, &), mode: @mode)
     end
-    def compiled_proc
-      @proc.compiled_proc(mode: @mode)
+    # Returns the compiled proc for the template.
+    #
+    # @return [Proc] compiled proc
+    def __papercraft_compiled_proc
+      @proc.__papercraft_compiled_proc(mode: @mode)
     end
   end
 end

data/lib/papercraft/version.rb CHANGED Viewed

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

data/lib/papercraft.rb CHANGED Viewed

@@ -114,10 +114,11 @@ module Papercraft
   # @param opts [Hash] Kramdown option overrides
   # @return [Kramdown::Document] Kramdown document
   def markdown_doc(markdown, **opts)
-    @markdown_deps_loaded ||= true.tap do
+    @markdown_deps_loaded ||= begin
       require 'kramdown'
       require 'rouge'
       require 'kramdown-parser-gfm'
+      true
     end
     opts = default_kramdown_options.merge(opts)
@@ -153,4 +154,129 @@ module Papercraft
   def default_kramdown_options=(opts)
     @default_kramdown_options = opts
   end
+  # Returns the compiled form code for the given proc.
+  #
+  # @param proc [Proc] template proc
+  # @return [String] compiled proc code
+  def compiled_code(proc)
+    Papercraft::Compiler.compile_to_code(proc).last
+  end
+  # Returns the source map for the given proc.
+  #
+  # @param proc [Proc] template proc
+  # @return [Array<String>] source map
+  def source_map(proc)
+    loc = proc.source_location
+    fn = proc.__papercraft_compiled? ? loc.first : Papercraft::Compiler.source_location_to_fn(loc)
+    Papercraft::Compiler.source_map_store[fn]
+  end
+  # Returns the AST for the given proc.
+  #
+  # @param proc [Proc] template proc
+  # @return [Prism::Node] AST root
+  def ast(proc)
+    Sirop.to_ast(proc)
+  end
+  # Compiles the given template.
+  #
+  # @param proc [Proc] template proc
+  # @param mode [Symbol] compilation mode (:html, :xml)
+  # @return [Proc] compiled proc
+  def compile(proc, mode: :html)
+    Papercraft::Compiler.compile(proc, mode:).__papercraft_compiled!
+  rescue Sirop::Error
+    raise Papercraft::Error, "Can't compile eval'd template"
+  end
+  # Renders the given template to HTML with the given arguments. The template
+  # can be passed either as the first parameter, or as a block, if no parameter
+  # is given.
+  #
+  # @param template [Proc] template proc
+  # @return [String] HTML string
+  def html(template = nil, *pos, **kw, &block)
+    if !template
+      template = block
+    elsif template.is_a?(Template)
+      template = template.proc
+    end
+    raise ArgumentError, "No template given" if !template
+    template.__papercraft_compiled_proc.(+'', *pos, **kw, &block)
+  rescue Exception => e
+    e.is_a?(Papercraft::Error) ? raise : raise(Papercraft.translate_backtrace(e))
+  end
+  # Renders the given template to XML with the given arguments. The template can
+  # be passed either as the first parameter, or as a block, if no parameter is
+  # given.
+  #
+  # @param template [Proc] template proc
+  # @return [String] XML string
+  def xml(template = nil, *pos, **kw, &block)
+    if !template
+      template = block
+    elsif template.is_a?(Template)
+      template = template.proc
+    end
+    raise ArgumentError, "No template given" if !template
+    template = template.proc if template.is_a?(Template)
+    template.__papercraft_compiled_proc(mode: :xml).(+'', *pos, **kw, &block)
+  rescue Exception => e
+    e.is_a?(Papercraft::Error) ? raise : raise(Papercraft.translate_backtrace(e))
+  end
+  # Returns a proc that applies the given arguments to the original proc. The
+  # returned proc calls the *compiled* form of the proc, merging the
+  # positional and keywords parameters passed to `#apply` with parameters
+  # passed to the applied proc. If a block is given, it is wrapped in a proc
+  # that passed merged parameters to the block.
+  #
+  # @param template [Proc] template proc
+  # @param *pos1 [Array<any>] applied positional parameters
+  # @param **kw1 [Hash<any, any] applied keyword parameters
+  # @return [Proc] applied proc
+  def apply(template, *pos1, **kw1, &block1)
+    template = template.proc if template.is_a?(Template)
+    compiled = template.__papercraft_compiled_proc
+    block1_compiled = block1&.__papercraft_compiled_proc
+    ->(__buffer__, *pos2, **kw2, &block2) {
+      if block2
+        block2_compiled = block1_compiled ?
+          ->(__buffer__, *pos3, **kw3) {
+            block1_compiled.(__buffer__, *pos3, **kw3, &block2)
+          }.__papercraft_compiled! :
+          block2.__papercraft_compiled_proc
+        compiled.(__buffer__, *pos1, *pos2, **kw1, **kw2, &block2_compiled)
+      else
+        compiled.(__buffer__, *pos1, *pos2, **kw1, **kw2, &block1_compiled)
+      end
+    }.__papercraft_compiled!
+  end
+  # Caches and returns the rendered HTML for the template with the given
+  # arguments.
+  #
+  # @param template [Proc] template proc
+  # @param key [any] Cache key
+  # @return [String] HTML string
+  def cache_html(template, key, *, **, &)
+    template.__papercraft_render_cache[key] ||= html(template, *, **, &)
+  end
+  # Caches and returns the rendered XML for the template with the given
+  # arguments.
+  #
+  # @param template [Proc] template proc
+  # @param key [any] Cache key
+  # @return [String] XML string
+  def cache_xml(template, key, *, **, &)
+    template.__papercraft_render_cache[key] ||= xml(template, *, **, &)
+  end
 end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '2.23'
+  version: '3.0'
 platform: ruby
 authors:
 - Sharon Rosner
@@ -142,8 +142,8 @@ homepage: http://github.com/digital-fabric/papercraft
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/digital-fabric/papercraft
-  documentation_uri: https://www.rubydoc.info/gems/papercraft
+  homepage_uri: https://papercraft.noteflakes.com/
+  source_code_uri: https://github.com/digital-fabric/papercraft
   changelog_uri: https://github.com/digital-fabric/papercraft/blob/master/CHANGELOG.md
 rdoc_options:
 - "--title"