RubyGems - papercraft - Versions diffs - 1.4 → 2.13 - Mend

papercraft 1.4 → 2.13

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

checksums.yaml +4 -4
data/CHANGELOG.md +89 -0
data/README.md +246 -617
data/lib/papercraft/compiler/nodes.rb +223 -0
data/lib/papercraft/compiler/tag_translator.rb +93 -0
data/lib/papercraft/compiler.rb +657 -201
data/lib/papercraft/proc_ext.rb +118 -0
data/lib/papercraft/template.rb +16 -195
data/lib/papercraft/version.rb +1 -1
data/lib/papercraft.rb +111 -87
metadata +11 -60
data/lib/papercraft/compiler_old.rb +0 -701
data/lib/papercraft/extension_proxy.rb +0 -41
data/lib/papercraft/extensions/soap.rb +0 -42
data/lib/papercraft/html.rb +0 -173
data/lib/papercraft/json.rb +0 -128
data/lib/papercraft/renderer.rb +0 -190
data/lib/papercraft/tags.rb +0 -408
data/lib/papercraft/xml.rb +0 -47
data/lib/tilt/papercraft.rb +0 -25

data/lib/papercraft/extension_proxy.rb DELETED Viewed

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-module Papercraft
-  # An ExtensionProxy proxies method calls to a renderer. Extension proxies are
-  # used to provide an namespaced interface to Papercraft extensions. When an
-  # extension is installed using `Papercraft.extension`, a corresponding method
-  # is defined on the `Papercraft::Renderer` class that creates an extension
-  # proxy that gives access to the different extension methods.
-  class ExtensionProxy
-    # Initializes a new ExtensionProxy.
-    #
-    # @param renderer [Papercraft::Renderer] renderer to proxy to
-    # @param mod [Module] extension module
-    # @return [void]
-    def initialize(renderer, mod)
-      @renderer = renderer
-      extend(mod)
-    end
-    # Proxies missing methods to the renderer.
-    #
-    # @param sym [Symbol] method name
-    # @param *args [Array] arguments
-    # @param *props [Array] named arguments
-    # @return void
-    def method_missing(sym, *args, **props, &block)
-      @renderer.send(sym, *args, **props, &block)
-    end
-    # Overrides the `Kernel#p` method to emit a p tag.
-    #
-    # @param *args [Array] arguments
-    # @param *props [Array] named arguments
-    # @return void
-    def p(text = nil, **props, &block)
-      @renderer.p(text, **props, &block)
-    end
-  end
-end

data/lib/papercraft/extensions/soap.rb DELETED Viewed

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-module Papercraft
-  module Extensions
-    module Soap
-      # Emits a SOAP XML tag that identifies the XML document as a SOAP message.
-      #
-      # @param **props [Hash] tag attributes
-      # @return [void]
-      def Envelope(**props, &block)
-        props[:xmlns__soap] ||= 'http://schemas.xmlsoap.org/soap/envelope/'
-        tag('soap:Envelope', **props, &block)
-      end
-      # Emits a SOAP XML tag that contains header information.
-      #
-      # @param **props [Hash] tag attributes
-      # @return [void]
-      def Header(**props, &blk)
-        tag('soap:Header', **props, &blk)
-      end
-      # Emits a SOAP XML tag that contains header information.
-      #
-      # @param **props [Hash] tag attributes
-      # @return [void]
-      def Body(**props, &blk)
-        tag('soap:Body', **props, &blk)
-      end
-      # Emits a SOAP XML tag that contains errors and status information.
-      #
-      # @param **props [Hash] tag attributes
-      # @return [void]
-      def Fault(**props, &blk)
-        tag('soap:Fault', **props, &blk)
-      end
-    end
-  end
-end
-Papercraft.extension(soap: Papercraft::Extensions::Soap)

data/lib/papercraft/html.rb DELETED Viewed

@@ -1,173 +0,0 @@
-# frozen_string_literal: true
-require_relative './tags'
-require 'cgi'
-module Papercraft
-  # HTML Markup extensions
-  module HTML
-    include Tags
-    # Emits the p tag (overrides Object#p)
-    #
-    # @param text [String] text content of tag
-    # @param **attributes [Hash] tag attributes
-    # @para block [Proc] nested HTML block
-    # @return [void]
-    def p(text = nil, **attributes, &block)
-      method_missing(:p, text, **attributes, &block)
-    end
-    S_HTML5_DOCTYPE = '<!DOCTYPE html>'
-    # Emits an HTML5 doctype tag and an html tag with the given block.
-    #
-    # @param block [Proc] nested HTML block
-    # @return [void]
-    def html5(&block)
-      @buffer << S_HTML5_DOCTYPE
-      self.html(&block)
-    end
-    # Emits a link element with a stylesheet.
-    #
-    # @param href [String] stylesheet URL
-    # @param custom_attributes [Hash] optional custom attributes for the link element
-    # @return [void]
-    def link_stylesheet(href, custom_attributes = nil)
-      attributes = {
-        rel: 'stylesheet',
-        href: href
-      }
-      if custom_attributes
-        attributes = custom_attributes.merge(attributes)
-      end
-      link(**attributes)
-    end
-    # Emits an inline CSS style element.
-    #
-    # @param css [String] CSS code
-    # @param **attributes [Hash] optional element attributes
-    # @return [void]
-    def style(css, **attributes, &block)
-      @buffer << '<style'
-      emit_attributes(attributes) unless attributes.empty?
-      @buffer << '>' << css << '</style>'
-    end
-    # Emits an inline JS script element.
-    #
-    # @param js [String, nil] Javascript code
-    # @param **attributes [Hash] optional element attributes
-    # @return [void]
-    def script(js = nil, **attributes, &block)
-      @buffer << '<script'
-      emit_attributes(attributes) unless attributes.empty?
-      if js
-        @buffer << '>' << js << '</script>'
-      else
-        @buffer << '></script>'
-      end
-    end
-    # Returns a versioned URL for the given file spec.
-    #
-    # @param href [String] relative file path
-    # @param root_path [String] root path for file
-    # @param root_url [String] root URL
-    # @return [String] versioned URL
-    def versioned_file_href(href, root_path, root_url = '')
-      fn = File.join(root_path, href)
-      version = File.stat(fn).mtime.to_i rescue 0
-      "#{root_url}/#{href}?v=#{version}"
-    end
-    # Emits an import map scrit tag. If a hash is given, emits the hash as is.
-    # If a string is given, searches for all *.js files under the given path,
-    # and emits an import map including all found files, with versioned URLs.
-    #
-    # @param root_path [String, Hash] root path or hash
-    # @param root_url [String] root URL to construct URLs against
-    # @return [void]
-    def import_map(root_path, root_url = '')
-      if root_path.is_a?(Hash)
-        script(root_path.to_json, type: 'importmap')
-      else
-        map = Dir["#{root_path}/*.js"].sort.each_with_object({}) do |fn, h|
-          name = File.basename(fn)
-          m = fn.match(/\/([^\/]+)\.js$/)
-          h[m[1]] = versioned_file_href(name, root_path, root_url)
-        end
-        script(map.to_json, type: 'importmap')
-      end
-    end
-    # Emits a script tag with type attribute set to module.
-    #
-    # @param code [String] JS code
-    # @return [void]
-    def js_module(code)
-      script code, type: 'module'
-    end
-    # Converts and emits the given markdown. Papercraft uses
-    # [Kramdown](https://github.com/gettalong/kramdown/) to do the Markdown to
-    # HTML conversion. Optional Kramdown settings can be provided in order to
-    # control the conversion. Those are merged with the default Kramdown
-    # settings, which can be controlled using
-    # `Papercraft::HTML.kramdown_options`.
-    #
-    # @param markdown [String] Markdown content
-    # @param **opts [Hash] Kramdown options
-    # @return [void]
-    def emit_markdown(markdown, **opts)
-      emit Papercraft.markdown(markdown, **opts)
-    end
-    private
-    # Returns true if the given tag is a void element, in order to render a self
-    # closing tag. See spec: https://html.spec.whatwg.org/multipage/syntax.html#void-elements.
-    #
-    # @param tag [String] tag
-    # @return [Bool] is it a void element
-    def is_void_element_tag?(tag)
-      case tag
-      #
-      when 'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr'
-        true
-      else
-        false
-      end
-    end
-    # Escapes the given text using HTML entities.
-    #
-    # @param text [String] text
-    # @return [String] escaped text
-    def escape_text(text)
-      CGI.escapeHTML(text.to_s)
-    end
-    # Converts a tag to its string representation. Underscores will be converted
-    # to dashes.
-    #
-    # @param tag [Symbol, String] tag
-    # @return [String] tag string
-    def tag_repr(tag)
-      tag.to_s.tr('_', '-')
-    end
-    # Converts an attribute to its string representation. Underscores will be
-    # converted to dashes.
-    #
-    # @param att [Symbol, String] attribute
-    # @return [String] attribute string
-    def att_repr(att)
-      att.to_s.tr('_', '-')
-    end
-  end
-end

data/lib/papercraft/json.rb DELETED Viewed

@@ -1,128 +0,0 @@
-# frozen_string_literal: true
-require 'json'
-module Papercraft
-  # JSON renderer extensions
-  module JSON
-    # Initializes a JSON renderer, setting up an object stack.
-    def initialize(&template)
-      @object_stack = [nil]
-      super
-    end
-    # Adds an array item to the current object target. If a block is given, the
-    # block is evaulated against a new object target, then added to the current
-    # array.
-    #
-    #   Papercraft.json {
-    #     item 'foo'
-    #     item 'bar'
-    #   }.render #=> "[\"foo\", \"bar\"]"
-    #
-    # @param value [Object] item
-    # @return [void]
-    def item(value = nil, _for: nil, &block)
-      return _for.each { |*a| item(value) { block.(*a)} } if _for
-      verify_array_target
-      if block
-        value = enter_object(&block)
-      end
-      push_array_item(value)
-    end
-    # Adds a key-value item to the current object target. If a block is given,
-    # the block is evaulated against a new object target, then used as the
-    # value.
-    #
-    # @param key [Object] key
-    # @param value [Object] value
-    # @return [void]
-    def kv(key, value = nil, &block)
-      verify_hash_target
-      if block
-        value = enter_object(&block)
-      end
-      push_kv_item(key, value)
-    end
-    # Intercepts method calls by adding key-value pairs to the current object
-    # target.
-    #
-    # @param key [Symbol] key
-    # @param value [Object] value
-    # @return [void]
-    def method_missing(key, value = nil, &block)
-      kv(key, value, &block)
-    end
-    # Converts the root object target to JSON.
-    #
-    # @return [String] JSON template result
-    def to_s
-      @object_stack[0].to_json
-    end
-    private
-    # Adds a new entry to the object stack and evaluates the given block.
-    #
-    # @return [void]
-    def with_object(&block)
-      @object_stack << nil
-      instance_eval(&block)
-    end
-    # Verifies that the current object target is not a hash.
-    #
-    # @return [bool]
-    def verify_array_target
-      case @object_stack[-1]
-      when nil
-        @object_stack[-1] = []
-      when Hash
-        raise "Mixing array and hash values"
-      end
-    end
-    # Verifies that the current object target is not an array.
-    #
-    # @return [bool]
-    def verify_hash_target
-      case @object_stack[-1]
-      when nil
-        @object_stack[-1] = {}
-      when Array
-        raise "Mixing array and hash values"
-      end
-    end
-    # Pushes an array item to the current object target.
-    #
-    # @param value [Object] item
-    # @return [void]
-    def push_array_item(value)
-      @object_stack[-1] << value
-    end
-    # Pushes a key value into the current object target.
-    #
-    # @param key [Object] key
-    # @param value [Object] value
-    # @return [void]
-    def push_kv_item(key, value)
-      @object_stack[-1][key] = value
-    end
-    # Adds a new object to the object stack, evaluates the given template block,
-    # then pops the object off the stack.
-    #
-    # @return [void]
-    def enter_object(&block)
-      @object_stack << nil
-      instance_eval(&block)
-      @object_stack.pop
-    end
-  end
-end

data/lib/papercraft/renderer.rb DELETED Viewed

@@ -1,190 +0,0 @@
-# frozen_string_literal: true
-require_relative './html'
-require_relative './xml'
-require_relative './json'
-require_relative './extension_proxy'
-module Papercraft
-  # A Renderer renders a Papercraft template into a string
-  class Renderer
-    class << self
-      # Verifies that the given template proc can be called with the given
-      # arguments and named arguments. If the proc demands named argument keys
-      # that do not exist in `named_args`, `Papercraft::Error` is raised.
-      #
-      # @param template [Proc] proc to verify
-      # @param args [Array<any>] arguments passed to proc
-      # @param named_args [Hash] named arguments passed to proc
-      def verify_proc_parameters(template, args, named_args)
-        param_count = 0
-        template.parameters.each do |(type, name)|
-          case type
-          when :req
-            param_count += 1
-          when :keyreq
-            if !named_args.has_key?(name)
-              raise Papercraft::Error, "Missing template parameter #{name.inspect}"
-            end
-          end
-        end
-        if param_count > args.size
-          raise Papercraft::Error, "Missing template parameters"
-        end
-      end
-      # call_seq:
-      #   Papercraft::Renderer.extension(name => mod, ...)
-      #   Papercraft.extension(name => mod, ...)
-      #
-      # Installs the given extensions, passed in the form of a Ruby hash mapping
-      # methods to extension modules. The methods will be available to all
-      # Papercraft templates. Extension methods are executed in the context of
-      # the the renderer instance, so they can look just like normal proc
-      # components. In cases where method names in the module clash with XML
-      # tag names, you can use the `#tag` method to emit the relevant tag.
-      #
-      #   module ComponentLibrary
-      #     def card(title, content)
-      #       div(class: 'card') {
-      #         h3 title
-      #         div(class: 'card-content') { emit_markdown content }
-      #       }
-      #     end
-      #   end
-      #
-      #   Papercraft.extension(components: ComponentLibrary)
-      #   Papercraft.html { components.card('Foo', '**Bar**') }
-      #
-      # @param map [Hash] hash mapping methods to extension modules
-      # @return [void]
-      def extension(map)
-        map.each do |sym, mod|
-          define_extension_method(sym, mod)
-        end
-      end
-      private
-      # Defines a method returning an extension proxy for the given module
-      # @param sym [Symbol] method name
-      # @param mod [Module] extension module
-      # @return [void]
-      def define_extension_method(sym, mod)
-        define_method(sym) do
-          (@extension_proxies ||= {})[mod] ||= ExtensionProxy.new(self, mod)
-        end
-      end
-    end
-    # Initializes the renderer and evaulates the given template in the
-    # renderer's scope.
-    #
-    # @param &template [Proc] template block
-    def initialize(render_fragment = nil, &template)
-      @render_fragment = render_fragment
-      instance_eval(&template)
-    end
-    # Emits the given object into the rendering buffer. If the given object is a
-    # proc or a component, `emit` will passes any additional arguments and named
-    # arguments to the object when rendering it. If the given object is nil,
-    # nothing is emitted. Otherwise, the object is converted into a string using
-    # `#to_s` which is then added to the rendering buffer, without any escaping.
-    #
-    #   greeter = proc { |name| h1 "Hello, #{name}!" }
-    #   Papercraft.html { emit(greeter, 'world') }.render #=> "<h1>Hello, world!</h1>"
-    #
-    #   Papercraft.html { emit 'hi&<bye>' }.render #=> "hi&<bye>"
-    #
-    #   Papercraft.html { emit nil }.render #=> ""
-    #
-    # @param o [Proc, Papercraft::Template, String] emitted object
-    # @param *a [Array<any>] arguments to pass to a proc
-    # @param **b [Hash] named arguments to pass to a proc
-    # @return [void]
-    def emit(o, *a, **b, &block)
-      case o
-      when ::Proc
-        Renderer.verify_proc_parameters(o, a, b)
-        push_emit_yield_block(block) if block
-        instance_exec(*a, **b, &o)
-      when nil
-        # do nothing
-      else
-        emit_object(o)
-      end
-    end
-    alias_method :e, :emit
-    # Emits a block supplied using {Template#apply} or {Template#render}.
-    #
-    #   div_wrap = Papercraft.html { |*args| div { emit_yield(*args) } }
-    #   greeter = div_wrap.apply { |name| h1 "Hello, #{name}!" }
-    #   greeter.render('world') #=> "<div><h1>Hello, world!</h1></div>"
-    #
-    # @param *a [Array<any>] arguments to pass to a proc
-    # @param **b [Hash] named arguments to pass to a proc
-    # @return [void]
-    def emit_yield(*a, **b)
-      block = @emit_yield_stack&.pop
-      raise Papercraft::Error, "No block given" unless block
-      instance_exec(*a, **b, &block)
-    end
-    # Defines a named template fragment. Template fragments allow rendering
-    # specific parts of the same template. A template fragment can be rendered
-    # using {Template#render_fragment}. See also
-    # {https://htmx.org/essays/template-fragments/ HTMX template fragments}.
-    #
-    #   form = Papercraft.html {
-    #     h1 'Hello'
-    #     fragment(:buttons) {
-    #       button 'OK'
-    #       button 'Cancel'
-    #     }
-    #   }
-    #   form.render_fragment(:buttons) #=> "<button>OK</button><button>Cancel</buttons>"
-    #
-    # @param name [Symbol, String] fragment name
-    # @return [void]
-    def fragment(name, &block)
-      raise Papercraft::Error, "Already in fragment" if @fragment
-      begin
-        @fragment = name
-        emit(block)
-      ensure
-        @fragment = nil
-      end
-    end
-    private
-    # Pushes the given block onto the emit_yield stack.
-    #
-    # @param block [Proc] block
-    def push_emit_yield_block(block)
-      (@emit_yield_stack ||= []) << block
-    end
-  end
-  # Implements an HTML renderer
-  class HTMLRenderer < Renderer
-    include HTML
-  end
-  # Implements an XML renderer
-  class XMLRenderer < Renderer
-    include XML
-  end
-  # Implements a JSON renderer
-  class JSONRenderer < Renderer
-    include JSON
-  end
-end