papercraft 0.11 → 0.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3452d115d85742018d1497b369ea27970f0c144e3dcb1772f4d81e33315dce51
-  data.tar.gz: e7217a9d9bcfd7af0dc92482650bc03392b0406cf4f3d6141c253a2918638545
+  metadata.gz: 2200153b1b339d33c7e9e81c45c23bd4c117c274a52b1d1bfc97f83995727697
+  data.tar.gz: 3dae3cf3b6ea2530df8c498cdafb876e06d45d527b6e2bbbcb6302e6ef0842e9
 SHA512:
-  metadata.gz: 8f76b9e73aa48f91af932af3308d3dd43239c3d5ca39e305cb1535417b5997483aa884f0e34ed128800b07a3135ebc1d18ea81d0df64e6170726a66c86969288
-  data.tar.gz: dbe744ca25996c3d263ff609ca26f42076784fdbceabd2dd1604dd1016e2d840830230f4205a673b9e5ba14eb8e480627612971b71ca6631e0a6e473d59ccb73
+  metadata.gz: 5f9727de69aac6d48de53ca174280c68dce7825b9a4aa6f8c955b6122f30d9f4541a7d47e7ed7caa319feda5659b14b73a3ad343db2733b4bb9518e9ade94f8c
+  data.tar.gz: 765e786959a6fdda6c25cddda11f5f987837d6853245e5bc8533dbe7b904792b09fc39e726371c81981275ef0abdb8d1d95de63a76889af34b037f34d01c6c3a

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## 0.15 2022-01-20
+
+- Fix tag method line reference
+- Don't clobber ArgumentError exception
+
+## 0.14 2022-01-19
+
+- Add support for #emit_yield in applied component (#4)
+
+## 0.13 2022-01-19
+
+- Add support for partial parameter application (#3)
+
+## 0.12 2022-01-06
+
+- Improve documentation
+- Add `Renderer#tag` method
+- Add `HTML#style`, `HTML#script` methods
+
 ## 0.11 2022-01-04
 
 - Add deferred evaluation

data/README.md

@@ -1,4 +1,6 @@
 <h1 align="center">
+  <img src="papercraft.png">
+  <br>
   Papercraft
 </h1>
 
@@ -20,8 +22,6 @@
   <a href="https://www.rubydoc.info/gems/papercraft">API reference</a>
 </p>
 
-# Papercraft - Composable HTML templating for Ruby
-
 ## What is Papercraft?
 
 ```ruby
@@ -368,7 +368,7 @@ The default Kramdown options are:
 ```
 
 The deafult options can be configured by accessing
-`Papercraft::HTML.kramdown_options`:
+`Papercraft::HTML.kramdown_options`, e.g.:
 
 ```ruby
 Papercraft::HTML.kramdown_options[:auto_ids] = false
@@ -430,7 +430,7 @@ page = default_layout.apply {
 
 Papercraft extensions are modules that contain one or more methods that can be
 used to render complex HTML components. Extension modules can be used by
-installing them as a namespaced extension using `Papercraft.extension`.
+installing them as a namespaced extension using `Papercraft::extension`.
 Extensions are particularly useful when you work with CSS frameworks such as
 [Bootstrap](https://getbootstrap.com/), [Tailwind](https://tailwindui.com/) or
 [Primer](https://primer.style/).
@@ -476,7 +476,7 @@ end
 Papercraft.extension(bootstrap: BootstrapComponents)
 ```
 
-The call to `Papercraft.extension` lets us access the different methods of
+The call to `Papercraft::extension` lets us access the different methods of
 `BootstrapComponents` by calling `#bootstrap` inside a template. With this,
 we'll be able to express the above markup as follows:
 

data/lib/papercraft/component.rb

@@ -106,14 +106,9 @@ module Papercraft
       template = self
       Renderer.verify_proc_parameters(template, a, b)
       renderer_class.new do
-        if block
-          with_block(block) { instance_exec(*a, **b, &template) }
-        else
-          instance_exec(*a, **b, &template)
-        end
+        push_emit_yield_block(block) if block
+        instance_exec(*a, **b, &template)
       end.to_s
-    rescue ArgumentError => e
-      raise Papercraft::Error, e.message
     end
   
     # Creates a new component, applying the given parameters and or block to the
@@ -136,15 +131,10 @@ module Papercraft
     # @return [Papercraft::Component] applied component
     def apply(*a, **b, &block)
       template = self
-      if block
-        Component.new(&proc do |*x, **y|
-          with_block(block) { instance_exec(*x, **y, &template) }
-        end)
-      else
-        Component.new(&proc do |*x, **y|
-          instance_exec(*a, **b, &template)
-        end)
-      end
+      Component.new(&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

data/lib/papercraft/html.rb

@@ -44,15 +44,53 @@ module Papercraft
       link(**attributes)
     end
 
-    def emit_markdown(markdown, **opts)
-      emit Kramdown::Document.new(markdown, **kramdown_options(opts)).to_html
+    # Emits an inline CSS style element.
+    #
+    # @param css [String] CSS code
+    # @param **props [Hash] optional element attributes
+    # @return [void]
+    def style(css, **props, &block)
+      @buffer << '<style'
+      emit_props(props) unless props.empty?
+
+      @buffer << '>' << css << '</style>'
     end
+  
+    # Emits an inline JS script element.
+    #
+    # @param js [String, nil] Javascript code
+    # @param **props [Hash] optional element attributes
+    # @return [void]
+    def script(js = nil, **props, &block)
+      @buffer << '<script'
+      emit_props(props) unless props.empty?
 
-    def kramdown_options(opts)
-      HTML.kramdown_options.merge(**opts)
+      if js
+        @buffer << '>' << js << '</script>'
+      else
+        @buffer << '></script>'
+      end
+    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 Kramdown::Document.new(markdown, **kramdown_options(opts)).to_html
     end
 
     class << self
+      # Returns the default Kramdown options used for converting Markdown to
+      # HTML.
+      #
+      # @return [Hash] Default Kramdown options
       def kramdown_options
         @kramdown_options ||= {
           entity_output: :numeric,
@@ -62,9 +100,24 @@ module Papercraft
         }
       end
 
+      # Sets the default Kramdown options used for converting Markdown to
+      # HTML.
+      #
+      # @param opts [Hash] New deafult Kramdown options
+      # @return [Hash] New default Kramdown options
       def kramdown_options=(opts)
         @kramdown_options = opts
       end
     end
+
+    private
+
+    # Returns the default Kramdown options, merged with the given overrides.
+    # 
+    # @param opts [Hash] Kramdown option overrides
+    # @return [Hash] Merged Kramdown options
+    def kramdown_options(opts)
+      HTML.kramdown_options.merge(**opts)
+    end
   end
 end

data/lib/papercraft/renderer.rb

@@ -34,8 +34,29 @@ module Papercraft
         end
       end
 
-      # Installs the given extensions, mapping a method name to the extension
-      # module.
+      # 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 components. 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 HTML
+      # 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)
+      # H { components.card('Foo', '**Bar**') }
+      #
       # @param map [Hash] hash mapping methods to extension modules
       # @return [void]
       def extension(map)
@@ -89,10 +110,12 @@ module Papercraft
       @buffer
     end
 
-    S_TAG_METHOD_LINE = __LINE__ + 1
+    # The tag method template below is optimized for performance. Do not touch!
+
+    S_TAG_METHOD_LINE = __LINE__ + 2
     S_TAG_METHOD = <<~EOF
-      S_TAG_%<TAG>s_PRE = '<%<tag>s'.tr('_', '-')
-      S_TAG_%<TAG>s_CLOSE = '</%<tag>s>'.tr('_', '-')
+      S_TAG_%<TAG>s_PRE = %<tag_pre>s
+      S_TAG_%<TAG>s_CLOSE = %<tag_close>s
 
       def %<tag>s(text = nil, **props, &block)
         if text.is_a?(Hash) && props.empty?
@@ -119,6 +142,48 @@ module Papercraft
       end
     EOF
 
+    # Emits an HTML tag with the given content, properties and optional block.
+    # This method is an alternative to emitting HTML tags using dynamically
+    # created methods. This is particularly useful when using extensions that
+    # have method names that clash with HTML tags, such as `button` or `a`, or
+    # when you need to override the behaviour of a particular HTML tag.
+    #
+    # The following two method calls have the same effect:
+    #
+    # button 'text', id: 'button1'
+    # tag :button, 'text', id: 'button1'
+    #
+    # @param sym [Symbol, String] HTML tag
+    # @param text [String, nil] tag content
+    # @param **props [Hash] tag attributes
+    # @param &block [Proc] optional inner HTML
+    # @return [void]
+    def tag(sym, text = nil, **props, &block)
+      if text.is_a?(Hash) && props.empty?
+        props = text
+        text = nil
+      end
+
+      tag = sym.to_s.tr('_', '-')
+
+      @buffer << S_LT << tag
+      emit_props(props) unless props.empty?
+
+      if block
+        @buffer << S_GT
+        instance_eval(&block)
+        @buffer << S_LT_SLASH << tag << S_GT
+      elsif Proc === text
+        @buffer << S_GT
+        emit(text)
+        @buffer << S_LT_SLASH << tag << S_GT
+      elsif text
+        @buffer << S_GT << escape_text(text.to_s) << S_LT_SLASH << tag << S_GT
+      else
+        @buffer << S_SLASH_GT
+      end
+    end
+
     # Catches undefined tag method call and handles it by defining the method.
     #
     # @param sym [Symbol] HTML tag or component identifier
@@ -128,7 +193,12 @@ module Papercraft
     # @return [void]
     def method_missing(sym, *args, **opts, &block)
       tag = sym.to_s
-      code = S_TAG_METHOD % { tag: tag, TAG: tag.upcase }
+      code = S_TAG_METHOD % {
+        tag: tag,
+        TAG: tag.upcase,
+        tag_pre: "<#{tag.tr('_', '-')}".inspect,
+        tag_close: "</#{tag.tr('_', '-')}>".inspect
+      }
       self.class.class_eval(code, __FILE__, S_TAG_METHOD_LINE)
       send(sym, *args, **opts, &block)
     end
@@ -172,9 +242,10 @@ module Papercraft
     # @param **b [Hash] named arguments to pass to a proc
     # @return [void]
     def emit_yield(*a, **b)
-      raise Papercraft::Error, "No block given" unless @inner_block
+      block = @emit_yield_stack&.pop
+      raise Papercraft::Error, "No block given" unless block
       
-      instance_exec(*a, **b, &@inner_block)
+      instance_exec(*a, **b, &block)
     end
 
     # Defers the given block to be evaluated later. Deferred evaluation allows
@@ -234,19 +305,19 @@ module Papercraft
     private
 
     # Escapes text. This method must be overriden in descendant classes.
+    #
+    # @param text [String] text to be escaped
     def escape_text(text)
       raise NotImplementedError
     end
 
-    # Sets up a block to be called with `#emit_yield`
-    def with_block(block, &run_block)
-      old_block = @inner_block
-      @inner_block = block
-      instance_eval(&run_block)
-    ensure
-      @inner_block = old_block
+    # Pushes the given block onto the emit_yield stack.
+    #
+    # @param block [Proc] block
+    def push_emit_yield_block(block)
+      (@emit_yield_stack ||= []) << block
     end
-  
+
     # Emits tag attributes into the rendering buffer
     # @param props [Hash] tag attributes
     # @return [void]

data/lib/papercraft/version.rb

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

data/lib/papercraft.rb

@@ -16,6 +16,12 @@ module Papercraft
   # 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 self.extension(map)
     Renderer.extension(map)
   end

metadata

@@ -1,27 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '0.11'
+  version: '0.15'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-04 00:00:00.000000000 Z
+date: 2022-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 1.2.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 1.2.1
 - !ruby/object:Gem::Dependency
@@ -30,28 +30,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: 2.3.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: 2.3.1
 - !ruby/object:Gem::Dependency
   name: rouge
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.26.0
+        version: 3.27.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.26.0
+        version: 3.27.0
 - !ruby/object:Gem::Dependency
   name: kramdown-parser-gfm
   requirement: !ruby/object:Gem::Requirement
@@ -70,56 +70,56 @@ dependencies:
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.11.3
+        version: '5.15'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.11.3
+        version: '5.15'
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 2.7.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 2.7.2
 - !ruby/object:Gem::Dependency
   name: erubis
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 2.7.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 2.7.0
 - !ruby/object:Gem::Dependency
   name: tilt
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 2.0.9
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 2.0.9
 description: