papercraft 2.24 → 3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea6b8d53d5110e44678302644fef523e5e9735b7f862f67b20a9f1bb4883c8b8
-  data.tar.gz: 3aacb8f0fb578c691230aefc5a1c0c16b1ddae30666004e977094f1f4a7793da
+  metadata.gz: ac74fb8004af29f1b15e8ca36de8039d3e47c6642105032fa1a51ec46bda100a
+  data.tar.gz: 2b5fcf6bc6d472c33033381577b62e0875594a56e3a8f9f1d769b64d4a6ec2ce
 SHA512:
-  metadata.gz: 3014b7b8a22b5128f5aecb7fd7e7c181d6af5fd1f0727f71dafaa1994f16fda643c6f80aad04fcffc332042e392c11803d9f75d4b18ec8704edc94f374a927ab
-  data.tar.gz: e8d2017554d39c57d18ccd4ddf3a39f5fc4592d1c16584c47f5c31028a131c28379b43adad55557b70191df34d32f28d4e78989ed8d59700fc0f78bfd69dfcde
+  metadata.gz: 390c81c371d17216134e931b26e1d6c9728c54e2c8db220b0d21761f9ed7d21b12f784b5642e7473e55c1f65f2bad4fe07f9afa09d78c04b7d54569ed7cc5ebf
+  data.tar.gz: 9801c61a0a9788a563396bed4064b0b0f4aeacb82e43677c52bfc83ed1d25d7b001af4915c3bdb86b6191b1f5681bd1b54460fbaaa626bfde32e471cb12a830f

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 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

data/README.md

@@ -21,10 +21,12 @@
 ```ruby
 require 'papercraft'
 
--> {
-  h1 "Hello from Papercraft!"
-}.render
-#=> "<h1>Hello from Papercraft</h1>"
+Papercraft.html {
+  div {
+    h1 "Hello from Papercraft!"
+  }
+}
+#=> "<div><h1>Hello from Papercraft</h1></div>"
 ```
 
 Papercraft is a templating engine for dynamically producing HTML in Ruby apps.

data/lib/papercraft/compiler.rb

@@ -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

@@ -8,76 +8,34 @@ module Papercraft
     # Returns true if proc is marked as compiled.
     #
     # @return [bool] is the proc marked as compiled
-    def __compiled__?
-      @__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__!
-      @__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__ ||= @__compiled__ ? self : Papercraft.compile(self, mode:)
+    def __papercraft_compiled_proc(mode: :html)
+      @__papercraft_compiled_proc ||= @__papercraft_compiled ?
+        self : Papercraft.compile(self, mode:)
     end
 
-    # Renders the proc to HTML with the given arguments.
+    # Returns the render cache for the proc.
     #
-    # @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
-
-    # 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__!
-    end
-
-    # Caches and returns the rendered HTML for the template with the given
-    # arguments.
-    #
-    # @param key [any] Cache key
-    # @return [String] HTML string
-    def render_cache(key, *args, **kargs, &block)
-      @render_cache ||= {}
-      @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

@@ -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

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

data/lib/papercraft.rb

@@ -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)
@@ -168,7 +169,7 @@ module Papercraft
   # @return [Array<String>] source map
   def source_map(proc)
     loc = proc.source_location
-    fn = proc.__compiled__? ? loc.first : Papercraft::Compiler.source_location_to_fn(loc)
+    fn = proc.__papercraft_compiled? ? loc.first : Papercraft::Compiler.source_location_to_fn(loc)
     Papercraft::Compiler.source_map_store[fn]
   end
 
@@ -186,8 +187,96 @@ module Papercraft
   # @param mode [Symbol] compilation mode (:html, :xml)
   # @return [Proc] compiled proc
   def compile(proc, mode: :html)
-    Papercraft::Compiler.compile(proc, mode:).__compiled__!
+    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

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '2.24'
+  version: '3.0'
 platform: ruby
 authors:
 - Sharon Rosner