papercraft 0.20 → 0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2eaf6ba31b9300176af0bf55b76f7bbdc16508d0e495ed1d76f9f273ea88f250
-  data.tar.gz: 90e132928ebfe78e577e71c8dc498f0ce1b1f2c58f453fbedaad96121c448a48
+  metadata.gz: a23bf614d84747a18eecf84545604c9c2f58710dc3fa0e0c651a863a53c919b0
+  data.tar.gz: 6b1ca8f4a90801beff11807dd357ce801b7526b5d114d5cca5f41f41aec69958
 SHA512:
-  metadata.gz: fcada325a3f8cd1c4cbe38674efaf6a86d0eb947ad5815d07778e2a09a54bee2c7d6b731e87d110390e9c87abc0a61f81cbc4cb30fdce11a4fc8a8cd322466a0
-  data.tar.gz: 031c86f7dade95af3dca979b4543fcb26e1fab2eb98c5642746d6efcf8b4bd56fe30b70f2f5aa8309352f421cae9f116a901f464216f54a0be50630dcc52815f
+  metadata.gz: dcd7eada8280cb0fcd68528eaea0d2500ff99ac149c8495dd5a3955a93c3f181301a4decc9eeb4d7efdd8cfe2c4f6047c9f838e5084b413c1118a76d6abc4252
+  data.tar.gz: 840ce0fc2a83de9b5a83bb10a5f4ed98986f7201737d6e31a4e89877aeb6bb22b2f2449c6efa08302473c073e26c830cfbe9e267456b450a56222b57a429fd15

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.21 2022-02-13
+
+- Refactor and improve documentation
+
 ## 0.20 2022-02-13
 
 - Add support for XML namespaced tags and attributes (#9)

data/lib/papercraft/extension_proxy.rb

@@ -10,6 +10,7 @@ module Papercraft
   class ExtensionProxy
 
     # Initializes a new ExtensionProxy.
+    #
     # @param renderer [Papercraft::Renderer] renderer to proxy to
     # @param mod [Module] extension module
     # @return [void]
@@ -18,7 +19,8 @@ module Papercraft
       extend(mod)
     end
   
-    # Proxies missing methods to the renderer
+    # Proxies missing methods to the renderer.
+    #
     # @param sym [Symbol] method name
     # @param *args [Array] arguments
     # @param &block [Proc] block

data/lib/papercraft/html.rb

@@ -88,9 +88,30 @@ module Papercraft
 
     private
 
-    # Escapes the given text using XML entities.
+    # Escapes the given text using HTML entities.
+    #
+    # @param text [String] text
+    # @return [String] escaped text
     def escape_text(text)
       EscapeUtils.escape_html(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

@@ -5,69 +5,122 @@ require 'json'
 module Papercraft  
   # JSON renderer extensions
   module JSON
-    def object_stack
-      @object_stack ||= [nil]
+    # 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.
+    #
+    # @param value [Object] item
+    # @param &block [Proc] template block
+    # @return [void]
+    def item(value = nil, &block)
+      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
+    # @param &block [Proc] template block
+    # @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 [Object] key
+    # @param value [Object] value
+    # @param &block [Proc] template block
+    # @return [void]
+    def method_missing(sym, value = nil, &block)
+      kv(sym, 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.
+    #
+    # @param &block [Proc] template block
+    # @return [void]
     def with_object(&block)
-      object_stack << nil
+      @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]
+      case @object_stack[-1]
       when nil
-        object_stack[-1] = []
+        @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]
+      case @object_stack[-1]
       when nil
-        object_stack[-1] = {}
+        @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
+      @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
+      @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.
+    #
+    # @param &block [Proc] template block
+    # @return [void]
     def enter_object(&block)
-      object_stack << nil
+      @object_stack << nil
       instance_eval(&block)
-      object_stack.pop
-    end
-
-    def item(value = nil, &block)
-      verify_array_target
-      if block
-        value = enter_object(&block)
-      end
-      push_array_item(value)
-    end
-
-    def kv(key, value, &block)
-      verify_hash_target
-      if block
-        value = enter_object(&block)
-      end
-      push_kv_item(key, value)
-    end
-
-    def method_missing(sym, value = nil, &block)
-      kv(sym, value, &block)
-    end
-
-    def to_s
-      object_stack[0].to_json
-    end
+      @object_stack.pop
+    end    
   end
 end

data/lib/papercraft/renderer.rb

@@ -80,38 +80,14 @@ module Papercraft
       end
     end
 
-    INITIAL_BUFFER_CAPACITY = 8192
-
     # Initializes the renderer and evaulates the given template in the
     # renderer's scope.
     #
     # @param &template [Proc] template block
     def initialize(&template)
-      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
       instance_eval(&template)
     end
 
-    # Returns the rendered template.
-    #
-    # @return [String]
-    def to_s
-      if @parts
-        last = @buffer
-        @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
-        parts = @parts
-        @parts = nil
-        parts.each do |p|
-          if Proc === p
-            render_deferred_proc(&p)
-          else
-            @buffer << p
-          end
-        end
-        @buffer << last unless last.empty?
-      end
-      @buffer
-    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,
@@ -136,8 +112,9 @@ module Papercraft
         push_emit_yield_block(block) if block
         instance_exec(*a, **b, &o)
       when nil
+        # do nothing
       else
-        @buffer << o.to_s
+        emit_object(o)
       end
     end
     alias_method :e, :emit
@@ -157,75 +134,15 @@ module Papercraft
       
       instance_exec(*a, **b, &block)
     end
-
-    # Defers the given block to be evaluated later. Deferred evaluation allows
-    # Papercraft templates to inject state into sibling components, regardless
-    # of the component's order in the container component. For example, a nested
-    # component may set an instance variable used by another component. This is
-    # an elegant solution to the problem of setting the XML page's title, or
-    # adding elements to the `<head>` section. Here's how a title can be
-    # controlled from a nested component:
-    #
-    #   layout = Papercraft.html {
-    #     html {
-    #       head {
-    #         defer { title @title }
-    #       }
-    #       body {
-    #         emit_yield
-    #       }
-    #     }
-    #   }
-    #
-    #   html.render {
-    #     @title = 'My super page'
-    #     h1 'content'
-    #   }
-    #
-    # @param &block [Proc] Deferred block to be emitted
-    # @return [void]
-    def defer(&block)
-      if !@parts
-        @parts = [@buffer, block]
-      else
-        @parts << @buffer unless @buffer.empty?
-        @parts << block
-      end
-      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
-    end
     
     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
-
     # Pushes the given block onto the emit_yield stack.
     #
     # @param block [Proc] block
     def push_emit_yield_block(block)
       (@emit_yield_stack ||= []) << block
     end
-
-    # Renders a deferred proc by evaluating it, then adding the rendered result
-    # to the buffer.
-    #
-    # @param &block [Proc] deferred proc
-    # @return [void]
-    def render_deferred_proc(&block)
-      old_buffer = @buffer
-      
-      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
-      @parts = nil
-
-      instance_eval(&block)
-
-      old_buffer << to_s
-      @buffer = old_buffer
-    end
   end
 
   # Implements an HTML renderer
@@ -238,6 +155,7 @@ module Papercraft
     include XML
   end
 
+  # Implements a JSON renderer
   class JSONRenderer < Renderer
     include JSON
   end

data/lib/papercraft/tags.rb

@@ -44,6 +44,72 @@ module Papercraft
       end
     EOF
 
+    INITIAL_BUFFER_CAPACITY = 8192
+
+    # Initializes a tag renderer.
+    def initialize(&template)
+      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
+      super
+    end
+
+    # Returns the rendered template.
+    #
+    # @return [String]
+    def to_s
+      if @parts
+        last = @buffer
+        @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
+        parts = @parts
+        @parts = nil
+        parts.each do |p|
+          if Proc === p
+            render_deferred_proc(&p)
+          else
+            @buffer << p
+          end
+        end
+        @buffer << last unless last.empty?
+      end
+      @buffer
+    end
+
+    # Defers the given block to be evaluated later. Deferred evaluation allows
+    # Papercraft templates to inject state into sibling components, regardless
+    # of the component's order in the container component. For example, a nested
+    # component may set an instance variable used by another component. This is
+    # an elegant solution to the problem of setting the XML page's title, or
+    # adding elements to the `<head>` section. Here's how a title can be
+    # controlled from a nested component:
+    #
+    #   layout = Papercraft.html {
+    #     html {
+    #       head {
+    #         defer { title @title }
+    #       }
+    #       body {
+    #         emit_yield
+    #       }
+    #     }
+    #   }
+    #
+    #   html.render {
+    #     @title = 'My super page'
+    #     h1 'content'
+    #   }
+    #
+    # @param &block [Proc] Deferred block to be emitted
+    # @return [void]
+    def defer(&block)
+      if !@parts
+        @parts = [@buffer, block]
+      else
+        @parts << @buffer unless @buffer.empty?
+        @parts << block
+      end
+      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
+    end
+    
+    
     # Emits an XML tag with the given content, properties and optional block.
     # This method is an alternative to emitting XML tags using dynamically
     # created methods. This is particularly useful when using extensions that
@@ -118,15 +184,58 @@ module Papercraft
 
     private
 
+    # Emits an arbitrary object by converting it to string, then adding it to
+    # the internal buffer. This method is called internally by `Renderer#emit`.
+    #
+    # @param obj [Object] emitted object
+    # @return [void]
+    def emit_object(obj)
+      @buffer << obj.to_s
+    end
+
+    # Renders a deferred proc by evaluating it, then adding the rendered result
+    # to the buffer.
+    #
+    # @param &block [Proc] deferred proc
+    # @return [void]
+    def render_deferred_proc(&block)
+      old_buffer = @buffer
+      
+      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
+      @parts = nil
+
+      instance_eval(&block)
+
+      old_buffer << to_s
+      @buffer = old_buffer
+    end
+
+    # Escapes text. This method must be overriden in Renderers which include
+    # this module.
+    #
+    # @param text [String] text to be escaped
+    def escape_text(text)
+      raise NotImplementedError
+    end
+
+    # Converts a tag to its string representation. This method must be overriden
+    # in Renderers which include this module.
+    #
+    # @param tag [Symbol, String] tag
     def tag_repr(tag)
-      tag.to_s.tr('_', '-')
+      raise NotImplementedError
     end
 
+    # Converts an attribute to its string representation. This method must be
+    # overriden in Renderers which include this module.
+    #
+    # @param att [Symbol, String] attribute
     def att_repr(att)
-      att.to_s.tr('_', '-')
+      raise NotImplementedError
     end
 
-    # Emits tag attributes into the rendering buffer
+    # Emits tag attributes into the rendering buffer.
+    #
     # @param props [Hash] tag attributes
     # @return [void]
     def emit_props(props)

data/lib/papercraft/template.rb

@@ -167,6 +167,9 @@ module Papercraft
       end
     end
 
+    # Returns the template's associated MIME type.
+    #
+    # @return [String] MIME type
     def mime_type
       @mime_type
     end

data/lib/papercraft/version.rb

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

data/lib/papercraft/xml.rb

@@ -10,15 +10,28 @@ module Papercraft
 
     private
 
+    # Converts a tag to its string representation. Underscores will be converted
+    # to dashes, double underscores will be converted to colon.
+    #
+    # @param tag [Symbol, String] tag
+    # @return [String] tag string
     def tag_repr(tag)
       tag.to_s.gsub('__', ':').tr('_', '-')
     end
 
+    # Converts an attribute to its string representation. Underscores will be
+    # converted to dashes, double underscores will be converted to colon.
+    #
+    # @param att [Symbol, String] attribute
+    # @return [String] attribute string
     def att_repr(att)
       att.to_s.gsub('__', ':').tr('_', '-')
     end
 
     # Escapes the given text using XML entities.
+    #
+    # @param text [String] text
+    # @return [String] escaped text
     def escape_text(text)
       EscapeUtils.escape_xml(text.to_s)
     end

metadata

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