papercraft 0.17 → 0.21

data/lib/papercraft/{component.rb → template.rb}

@@ -4,30 +4,30 @@ require_relative './html'
 
 module Papercraft
 
-  # Component represents a distinct, reusable HTML template. A component can
-  # include other components, and also be nested inside other components.
+  # 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 Component
+  # 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.
   #
-  # Components are usually created using the class methods `html`, `xml` or
+  # 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>"
   #
-  # Components can also be created using the normal constructor:
+  # Templates can also be created using the normal constructor:
   #
-  #   greeter = Papercraft::Component.new(mode: :html) { |name| h1 "Hello, #{name}!" }
+  #   greeter = Papercraft::Template.new(mode: :html) { |name| h1 "Hello, #{name}!" }
   #   greeter.render('world') #=> "<h1>Hello, world!</h1>"
   #
-  # The different methods for creating components can also take a custom MIME
+  # 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 component block, HTML elements are created by simply calling
+  # In the template block, HTML elements are created by simply calling
   # unqualified methods:
   #
   #   page_layout = Papercraft.html {
@@ -41,20 +41,20 @@ module Papercraft
   #     }
   #   }
   #
-  # Papercraft components can take explicit parameters in order to render
+  # 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 component could be implemented with named parameters:
+  # anchor template could be implemented with named parameters:
   #
   #   anchor = Papercraft.html { |uri: , text: | a(text, href: uri) }
   #
-  # The above component could later be rendered by passing the needed arguments:
+  # The above template could later be rendered by passing the needed arguments:
   #
   #   anchor.render(uri: 'https://example.com', text: 'Example')
   #
-  # ## Component Composition
+  # ## Template Composition
   #
-  # A component can be included in another component using the `emit` method:
+  # A template can be included in another template using the `emit` method:
   #
   #   links = Papercraft.html {
   #     emit anchor, uri: '/posts',   text: 'Posts'
@@ -62,7 +62,7 @@ module Papercraft
   #     emit anchor, uri: '/about',   text: 'About'
   #   }
   #
-  # Another way of composing components is to pass the components themselves as
+  # Another way of composing templates is to pass the templates themselves as
   # parameters:
   #
   #   links = Papercraft.html { |anchors|
@@ -74,8 +74,8 @@ module Papercraft
   #     anchor.apply(uri: '/about', text: 'About')
   #   ])
   #
-  # The `#apply` method creates a new component, applying the given parameters
-  # such that the component can be rendered without parameters:
+  # 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'),
@@ -84,7 +84,7 @@ module Papercraft
   #   ])
   #   links_with_anchors.render
   #
-  class Component < Proc
+  class Template < Proc
     
     # Determines the rendering mode: `:html` or `:xml`.
     attr_accessor :mode
@@ -95,12 +95,12 @@ module Papercraft
       json: 'application/json'
     }.freeze
 
-    # Initializes a component with the given block. The rendering mode (HTML or
+    # 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 component defaults to HTML.
+    # the template defaults to HTML.
     #
     # @param mode [:html, :xml] rendering mode
-    # @param mime_type [String, nil] the component's mime type (nil for default)
+    # @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)
       @mode = mode
@@ -124,9 +124,9 @@ module Papercraft
       end.to_s
     end
   
-    # Creates a new component, applying the given parameters and or block to the
+    # Creates a new template, applying the given parameters and or block to the
     # current one. Application is one of the principal methods of composing
-    # components, particularly when passing inner components as blocks:
+    # templates, particularly when passing inner templates as blocks:
     #
     #   article_wrapper = Papercraft.html {
     #     article {
@@ -141,19 +141,19 @@ module Papercraft
     # @param *a [<any>] normal parameters
     # @param **b [Hash] named parameters
     # @param &block [Proc] inner block
-    # @return [Papercraft::Component] applied component
+    # @return [Papercraft::Template] applied template
     def apply(*a, **b, &block)
       template = self
-      Component.new(mode: @mode, mime_type: @mime_type, &proc do |*x, **y|
+      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 component's mode.
+    # the template's mode.
     #
-    # @return [Papercraft::Renderer] Renderer used for rendering the component
+    # @return [Papercraft::Renderer] Renderer used for rendering the template
     def renderer_class
       case @mode
       when :html
@@ -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.17'
+  VERSION = '0.21'
 end

data/lib/papercraft/xml.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'escape_utils'
+require_relative './tags'
+
+module Papercraft  
+  # XML renderer extensions
+  module XML
+    include Tags
+
+    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
+  end
+end

data/lib/papercraft.rb

@@ -4,13 +4,13 @@ require 'kramdown'
 require 'rouge'
 require 'kramdown-parser-gfm'
 
-require_relative 'papercraft/component'
+require_relative 'papercraft/template'
 require_relative 'papercraft/renderer'
 require_relative 'papercraft/encoding'
 # require_relative 'papercraft/compiler'
 
 
-# Papercraft is a component-based HTML templating library
+# Papercraft is a composable templating library
 module Papercraft
   # Exception class used to signal templating-related errors
   class Error < RuntimeError; end
@@ -31,49 +31,49 @@ module Papercraft
       Renderer.extension(map)
     end
     
-    # Creates a new papercraft component. `Papercraft.html` can take either a proc
+    # 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::Component`.
+    # `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::Component] Papercraft component
+    # @return [Papercraft::Template] Papercraft template
     def html(o = nil, mime_type: nil, &template)
-      return o if o.is_a?(Papercraft::Component)
+      return o if o.is_a?(Papercraft::Template)
       template ||= o
-      Papercraft::Component.new(mode: :html, mime_type: mime_type, &template)
+      Papercraft::Template.new(mode: :html, mime_type: mime_type, &template)
     end
     
-    # Creates a new papercraft component in XML mode. `Papercraft.xml` can take
+    # 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::Component`.
+    # `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::Component] Papercraft component
+    # @return [Papercraft::Template] Papercraft template
     def xml(o = nil, mime_type: nil, &template)
-      return o if o.is_a?(Papercraft::Component)
+      return o if o.is_a?(Papercraft::Template)
       template ||= o
-      Papercraft::Component.new(mode: :xml, mime_type: mime_type, &template)
+      Papercraft::Template.new(mode: :xml, mime_type: mime_type, &template)
     end
     
-    # Creates a new papercraft component in JSON mode. `Papercraft.json` can take
+    # 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::Component`.
+    # `Papercraft::Template`.
     #
     # Papercraft.json(proc { item 42 }).render #=> "[42]"
     # Papercraft.json { foo 'bar' }.render #=> "{\"foo\": \"bar\"}"
     #
     # @param template [Proc] template block
-    # @return [Papercraft::Component] Papercraft component
+    # @return [Papercraft::Template] Papercraft template
     def json(o = nil, mime_type: nil, &template)
-      return o if o.is_a?(Papercraft::Component)
+      return o if o.is_a?(Papercraft::Template)
       template ||= o
-      Papercraft::Component.new(mode: :json, mime_type: mime_type, &template)
+      Papercraft::Template.new(mode: :json, mime_type: mime_type, &template)
     end
 
     # Renders Markdown into HTML. The `opts` argument will be merged with the

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '0.17'
+  version: '0.21'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-23 00:00:00.000000000 Z
+date: 2022-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils
@@ -128,18 +128,22 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - README.md
+- papercraft.png
 files:
 - CHANGELOG.md
 - README.md
 - lib/papercraft.rb
 - lib/papercraft/compiler.rb
-- lib/papercraft/component.rb
 - lib/papercraft/encoding.rb
 - lib/papercraft/extension_proxy.rb
 - lib/papercraft/html.rb
 - lib/papercraft/json.rb
 - lib/papercraft/renderer.rb
+- lib/papercraft/tags.rb
+- lib/papercraft/template.rb
 - lib/papercraft/version.rb
+- lib/papercraft/xml.rb
+- papercraft.png
 homepage: http://github.com/digital-fabric/papercraft
 licenses:
 - MIT