papercraft 1.3 → 2.13

data/lib/papercraft/proc_ext.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative './compiler'
+
+# Extensions to the Proc class.
+class ::Proc
+  # 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
+  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
+    self
+  end
+
+  # 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(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.
+  #
+  # @return [Proc] applied proc
+  def apply(*a, **b, &c)
+    compiled = compiled_proc
+    c_compiled = c&.compiled_proc
+
+    ->(__buffer__, *x, **y, &z) {
+      c_proc = c_compiled && ->(__buffer__, *d, **e) {
+        c_compiled.(__buffer__, *a, *d, **b, **e, &z)
+      }.compiled!
+
+      compiled.(__buffer__, *a, *x, **b, **y, &c_proc)
+    }.compiled!
+  end
+
+  # 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? && !block ? nil : [args, kargs, block&.source_location]
+    @render_cache[key] ||= render(*args, **kargs, &block)
+  end
+end

data/lib/papercraft/template.rb

@@ -1,207 +1,28 @@
 # frozen_string_literal: true
 
-require_relative './html'
-
 module Papercraft
-
-  # Template represents a distinct, reusable HTML template. A template can
-  # include other templates, and also be nested inside other templates.
-  #
-  # Since in Papercraft HTML is expressed using blocks (or procs,) the Template
-  # class is simply a special kind of Proc, which has some enhanced
-  # capabilities, allowing it to be easily composed in a variety of ways.
-  #
-  # Templates are usually created using the class methods `html`, `xml` or
-  # `json`, for HTML, XML or JSON templates, respectively:
-  #
-  #   greeter = Papercraft.html { |name| h1 "Hello, #{name}!" }
-  #   greeter.render('world') #=> "<h1>Hello, world!</h1>"
-  #
-  # Templates can also be created using the normal constructor:
-  #
-  #   greeter = Papercraft::Template.new(mode: :html) { |name| h1 "Hello, #{name}!" }
-  #   greeter.render('world') #=> "<h1>Hello, world!</h1>"
-  #
-  # The different methods for creating templates can also take a custom MIME
-  # type, by passing a `mime_type` named argument:
-  #
-  #   json = Papercraft.json(mime_type: 'application/feed+json') { ... }
-  #
-  # In the template block, HTML elements are created by simply calling
-  # unqualified methods:
-  #
-  #   page_layout = Papercraft.html {
-  #     html5 {
-  #       head {
-  #         title 'foo'
-  #       }
-  #       body {
-  #         h1 "Hello, world!"
-  #       }
-  #     }
-  #   }
-  #
-  # Papercraft templates can take explicit parameters in order to render
-  # dynamic content. This can be in the form of regular or named parameters. The
-  # `greeter` template shown above takes a single `name` parameter. Here's how a
-  # anchor template could be implemented with named parameters:
-  #
-  #   anchor = Papercraft.html { |uri: , text: | a(text, href: uri) }
-  #
-  # The above template could later be rendered by passing the needed arguments:
-  #
-  #   anchor.render(uri: 'https://example.com', text: 'Example')
-  #
-  # ## Template Composition
-  #
-  # A template can be included in another template using the `emit` method:
-  #
-  #   links = Papercraft.html {
-  #     emit anchor, uri: '/posts',   text: 'Posts'
-  #     emit anchor, uri: '/archive', text: 'Archive'
-  #     emit anchor, uri: '/about',   text: 'About'
-  #   }
-  #
-  # Another way of composing templates is to pass the templates themselves as
-  # parameters:
-  #
-  #   links = Papercraft.html { |anchors|
-  #     anchors.each { |a| emit a }
-  #   }
-  #   links.render([
-  #     anchor.apply(uri: '/posts', text: 'Posts'),
-  #     anchor.apply(uri: '/archive', text: 'Archive'),
-  #     anchor.apply(uri: '/about', text: 'About')
-  #   ])
-  #
-  # The `#apply` method creates a new template, applying the given parameters
-  # such that the template can be rendered without parameters:
-  #
-  #   links_with_anchors = links.apply([
-  #     anchor.apply(uri: '/posts', text: 'Posts'),
-  #     anchor.apply(uri: '/archive', text: 'Archive'),
-  #     anchor.apply(uri: '/about', text: 'About')
-  #   ])
-  #   links_with_anchors.render
-  #
-  class Template < Proc
-
-    # Determines the rendering mode: `:html` or `:xml`.
-    attr_accessor :mode
-
-    STOCK_MIME_TYPE = {
-      html: 'text/html',
-      xml:  'application/xml',
-      json: 'application/json'
-    }.freeze
-
-    # Initializes a template with the given block. The rendering mode (HTML or
-    # XML) can be passed in the `mode:` parameter. If `mode:` is not specified,
-    # the template defaults to HTML.
-    #
-    # @param mode [:html, :xml] rendering mode
-    # @param mime_type [String, nil] the template's mime type (nil for default)
-    # @param block [Proc] nested HTML block
-    def initialize(mode: :html, mime_type: nil, &block)
+  # Template wrapper class. This class can be used to distinguish between Papercraft
+  # templates and other kinds of procs.
+  class Template
+    attr_reader :proc, :mode
+
+    # @param proc [Proc] template proc
+    # @param mode [Symbol] mode (:html, :xml)
+    def initialize(proc, mode: :html)
+      @proc = proc
       @mode = mode
-      @mime_type = mime_type || STOCK_MIME_TYPE[mode]
-      super(&block)
     end
 
-    H_EMPTY = {}.freeze
-
-    # Renders the template with the given parameters and or block, and returns
-    # the string result.
-    #
-    # @param *params [any] unnamed parameters
-    # @param **named_params [any] named parameters
-    # @return [String] rendered string
-    def render(*a, **b, &block)
-      template = self
-      Renderer.verify_proc_parameters(template, a, b)
-      renderer_class.new do
-        push_emit_yield_block(block) if block
-        instance_exec(*a, **b, &template)
-      end.to_s
+    def render(*, **, &)
+      (mode == :xml) ? @proc.render_xml(*, **, &) : @proc.render(*, **, &)
     end
 
-    # Renders a template fragment. Any given parameters are passed to the
-    # template just like with {Template#render}. See also
-    # {https://htmx.org/essays/template-fragments/ HTMX template fragments}.
-    #
-    #   form = Papercraft.html { |action|
-    #     h1 'Hello'
-    #     fragment(:buttons) {
-    #       button action
-    #       button 'Cancel'
-    #     }
-    #   }
-    #   form.render_fragment(:buttons, 'foo') #=> "<button>foo</button><button>Cancel</buttons>"
-    #
-    # @param name [Symbol, String] fragment name
-    # @param *params [any] unnamed parameters
-    # @param **named_params [any] named parameters
-    # @return [String] rendered string
-    def render_fragment(name, *a, **b, &block)
-      template = self
-      Renderer.verify_proc_parameters(template, a, b)
-      renderer_class.new(name) do
-        push_emit_yield_block(block) if block
-        instance_exec(*a, **b, &template)
-      end.to_s
+    def apply(*, **, &)
+      Template.new(@proc.apply(*, **, &), mode: @mode)
     end
-
-    # Creates a new template, applying the given parameters and or block to the
-    # current one. Application is one of the principal methods of composing
-    # templates, particularly when passing inner templates as blocks:
-    #
-    #   article_wrapper = Papercraft.html {
-    #     article {
-    #       emit_yield
-    #     }
-    #   }
-    #   wrapped_article = article_wrapper.apply {
-    #     h1 'Article title'
-    #   }
-    #   wrapped_article.render #=> "<article><h1>Article title</h1></article>"
-    #
-    # @param *a [<any>] normal parameters
-    # @param **b [Hash] named parameters
-    # @return [Papercraft::Template] applied template
-    def apply(*a, **b, &block)
-      template = self
-      Template.new(mode: @mode, mime_type: @mime_type, &proc do |*x, **y|
-        push_emit_yield_block(block) if block
-        instance_exec(*a, *x, **b, **y, &template)
-      end)
-    end
-
-    # Returns the Renderer class used for rendering the templates, according to
-    # the template's mode.
-    #
-    # @return [Papercraft::Renderer] Renderer used for rendering the template
-    def renderer_class
-      case @mode
-      when :html
-        HTMLRenderer
-      when :xml
-        XMLRenderer
-      when :json
-        JSONRenderer
-      else
-        raise "Invalid mode #{@mode.inspect}"
-      end
-    end
-
-    # Returns the template's associated MIME type.
-    #
-    # @return [String] MIME type
-    def mime_type
-      @mime_type
-    end
-
-    def compile(*args)
-      Papercraft::Compiler.new.compile(self, *args)
+    
+    def compiled_proc
+      @proc.compiled_proc(mode: @mode)
     end
   end
 end

data/lib/papercraft/version.rb

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

data/lib/papercraft.rb

@@ -1,109 +1,133 @@
 # frozen_string_literal: true
 
-require 'kramdown'
-require 'rouge'
-require 'kramdown-parser-gfm'
-
 require_relative 'papercraft/template'
-require_relative 'papercraft/renderer'
 require_relative 'papercraft/compiler'
+require_relative 'papercraft/proc_ext'
 
-
-# Papercraft is a composable templating library
+# Papercraft is a functional templating library. In Papercraft, templates are expressed as plain
+# Ruby procs.
 module Papercraft
   # Exception class used to signal templating-related errors
   class Error < RuntimeError; end
 
-  class << self
-
-    # Installs one or more extensions. Extensions enhance templating capabilities
-    # by adding namespaced methods to emplates. An extension is implemented as a
-    # Ruby module containing one or more methods. Each method in the extension
-    # module can be used to render a specific HTML element or a set of elements.
-    #
-    # This is a convenience method. For more information on using Papercraft
-    # extensions, see `Papercraft::Renderer::extension`
-    #
-    # @param map [Hash] hash mapping methods to extension modules
-    # @return [void]
-    def extension(map)
-      Renderer.extension(map)
-    end
+  extend self
 
-    # Creates a new papercraft template. `Papercraft.html` can take either a proc
-    # argument or a block. In both cases, the proc is converted to a
-    # `Papercraft::Template`.
-    #
-    # Papercraft.html(proc { h1 'hi' }).render #=> "<h1>hi</h1>"
-    # Papercraft.html { h1 'hi' }.render #=> "<h1>hi</h1>"
-    #
-    # @param template [Proc] template block
-    # @return [Papercraft::Template] Papercraft template
-    def html(o = nil, mime_type: nil, &template)
-      return o if o.is_a?(Papercraft::Template)
-      template ||= o
-      Papercraft::Template.new(mode: :html, mime_type: mime_type, &template)
-    end
+  # Registry of Papercraft exgtensions
+  Extensions = {}
 
-    # Creates a new Papercraft template in XML mode. `Papercraft.xml` can take
-    # either a proc argument or a block. In both cases, the proc is converted to a
-    # `Papercraft::Template`.
-    #
-    # Papercraft.xml(proc { item 'foo' }).render #=> "<item>foo</item>"
-    # Papercraft.xml { item 'foo' }.render #=> "<item>foo</item>"
-    #
-    # @param template [Proc] template block
-    # @return [Papercraft::Template] Papercraft template
-    def xml(o = nil, mime_type: nil, &template)
-      return o if o.is_a?(Papercraft::Template)
-      template ||= o
-      Papercraft::Template.new(mode: :xml, mime_type: mime_type, &template)
-    end
+  # Registers extensions to the Papercraft syntax.
+  #
+  # @param spec [Hash] hash mapping symbols to procs
+  # @return [self]
+  def extension(spec)
+    Extensions.merge!(spec)
+    self
+  end
 
-    # Creates a new Papercraft template in JSON mode. `Papercraft.json` can take
-    # either a proc argument or a block. In both cases, the proc is converted to a
-    # `Papercraft::Template`.
-    #
-    # Papercraft.json(proc { item 42 }).render #=> "[42]"
-    # Papercraft.json { foo 'bar' }.render #=> "{\"foo\": \"bar\"}"
-    #
-    # @param template [Proc] template block
-    # @return [Papercraft::Template] Papercraft template
-    def json(o = nil, mime_type: nil, &template)
-      return o if o.is_a?(Papercraft::Template)
-      template ||= o
-      Papercraft::Template.new(mode: :json, mime_type: mime_type, &template)
-    end
+  # Formats the given string, converting underscores to dashes.
+  #
+  # @param tag [String, Symbol] input string
+  # @return [String] output string
+  def underscores_to_dashes(tag)
+    tag.to_s.gsub('_', '-')
+  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)
-      opts = default_kramdown_options.merge(opts)
-      Kramdown::Document.new(markdown, **opts).to_html
+  # Formats the given hash as tag attributes.
+  #
+  # @param attrs [Hash] input hash
+  # @return [String] formatted attributes
+  def format_tag_attrs(attrs)
+    attrs.each_with_object(+'') do |(k, v), html|
+      case v
+      when nil, false
+      when true
+        html << ' ' if !html.empty?
+        html << underscores_to_dashes(k)
+      else
+        html << ' ' if !html.empty?
+        v = v.join(' ') if v.is_a?(Array)
+        html << "#{underscores_to_dashes(k)}=\"#{v}\""
+      end
     end
+  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
-      }
+  # Translates entries in exception's backtrace to point to original source code.
+  #
+  # @param err [Exception] raised exception
+  # @return [Exception] raised exception
+  def translate_backtrace(err)
+    cache = {}
+    is_argument_error = err.is_a?(ArgumentError) && err.backtrace[0] =~ /^\:\:/
+    backtrace = err.backtrace.map { |e| compute_backtrace_entry(e, cache) }
+
+    return make_argument_error(err, backtrace) if is_argument_error
+
+    err.set_backtrace(backtrace)
+    err
+  end
+
+  # Computes a backtrace entry with caching.
+  #
+  # @param entry [String] backtrace entry
+  # @param cache [Hash] cache store mapping compiled filename to source_map
+  def compute_backtrace_entry(entry, cache)
+    m = entry.match(/^((\:\:\(.+\:.+\))\:(\d+))/)
+    return entry if !m
+
+    fn = m[2]
+    line = m[3].to_i
+    source_map = cache[fn] ||= Compiler.source_map_store[fn]
+    return entry if !source_map
+
+    ref = source_map[line] || "?(#{line})"
+    entry.sub(m[1], ref)
+  end
+
+  def make_argument_error(err, backtrace)
+    m = err.message.match(/(given (\d+), expected (\d+))/)
+    if m
+      rectified = format('given %d, expected %d', m[2].to_i - 1, m[3].to_i - 1)
+      message = err.message.gsub(m[1], rectified)
+    else
+      message = err.message
     end
+    ArgumentError.new(message).tap { it.set_backtrace(backtrace) }
+  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
+  # 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)
+    @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
+  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 [Hash] Kramdown options
+  def default_kramdown_options=(opts)
+    @default_kramdown_options = opts
   end
 end