RubyGems - papercraft - Versions diffs - 0.13 → 0.17 - Mend

papercraft 0.13 → 0.17

Files changed (10) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +20 -1
data/README.md +78 -35
data/lib/papercraft/component.rb +35 -26
data/lib/papercraft/html.rb +1 -39
data/lib/papercraft/json.rb +73 -0
data/lib/papercraft/renderer.rb +25 -17
data/lib/papercraft/version.rb +1 -1
data/lib/papercraft.rb +94 -44
metadata +19 -18

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5250720b438ab385dca9f3b91487fc2e5c887ba7e709015f8e26a1a2e78fa8d6
-  data.tar.gz: '049f2399c403f55fdd0c0ee9de3b9bac5d314d0c57520184ddc59f361f7ec87d'
+  metadata.gz: 31c80224c2a9dc3a6d594d923e9a16ccd8127284bce501f1d7f1dc25386bf25c
+  data.tar.gz: 45dc43d353bc1f3c06e62d1b439751570ce7d46a915b0a72f1ce3ea182b0c225
 SHA512:
-  metadata.gz: 176f86dbf9e69deaf1fd60edbcba23401c1288a96d9eb5210175815e1ea1b297178daf2ba3533ae8020d18b8bc1b7003bcf39b2175c4ad95439982d622c01fad
-  data.tar.gz: 9f623e968a7462225e4f504c880a911557d024b45393658bec01426ebff934bfa9c94094ca52feae8c2a23b642054e9cd3b88df25644019a61f62c5fda4350ad
+  metadata.gz: 67529d1336456dded5d911548941c1accc695bd017b889b378ed008e177707b100e11e90b1adbe887d45530cfb94950808e21257955999d795b388dbeb13206e
+  data.tar.gz: 1caca448eb2a317b1616a529e82803f6571e26e8b0f36a19e771b2b4a9a96cabb8695ad5a01148acfa7481b016742e9c546c794fd2a9017ec54d299184d36c94

data/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,22 @@
+## 0.17 2022-01-23
+- Refactor markdown code, add `Papercraft.markdown` method (#8)
+## 0.16 2022-01-23
+- Implement JSON templating (#7)
+- Add support for MIME types (#6)
+- Change entrypoint from `Kernel#H`, `Kernel#X` to `Papercraft.html`, `.xml` (#5)
+## 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)
@@ -33,7 +52,7 @@
 ## 0.8 2021-12-22
 - Cleanup and refactor code
-- Add X global method for XML templates
+- Add Papercraft.xml global method for XML templates
 - Make `Component` a descendant of `Proc`
 - Introduce new component API
 - Rename Rubyoshka to Papercraft

data/README.md CHANGED Viewed

@@ -1,8 +1,10 @@
 <h1 align="center">
+  <img src="papercraft.png">
+  <br>
   Papercraft
 </h1>
-<h4 align="center">Composable HTML templating for Ruby</h4>
+<h4 align="center">Composable templating for Ruby</h4>
 <p align="center">
   <a href="http://rubygems.org/gems/papercraft">
@@ -25,26 +27,28 @@
 ```ruby
 require 'papercraft'
-page = H { |*args|
+page = Papercraft.html { |*args|
   html {
     head { }
     body { emit_yield *args }
   }
 }
+page.render { p 'foo' }
+#=> "<html><head/><body><p>foo</p></body></html>"
-hello = H.apply { |name| h1 "Hello, #{name}!" }
+hello = page.apply { |name| h1 "Hello, #{name}!" }
 hello.render('world')
 #=> "<html><head/><body><h1>Hello, world!</h1></body></html>"
 ```
-Papercraft is an HTML templating engine for Ruby that offers the following
-features:
+Papercraft is a templating engine for Ruby that offers the following features:
-- HTML and XML templating using plain Ruby syntax
+- HTML, XML and JSON templating using plain Ruby syntax
 - Minimal boilerplate
 - Mix logic and tags freely
 - Automatic HTML and XML escaping
 - Composable components
+- Standard or custom MIME types
 - Explicit parameter passing to nested components
 - Higher order components
 - Built-in support for rendering [Markdown](#emitting-markdown)
@@ -71,7 +75,7 @@ To create a template use the global method `Kernel#H`:
 ```ruby
 require 'papercraft'
-html = H {
+html = Papercraft.html {
   div(id: 'greeter') { p 'Hello!' }
 }
 ```
@@ -87,7 +91,7 @@ html.render #=> "<div id="greeter"><p>Hello!</p></div>"
 Tags are added using unqualified method calls, and can be nested using blocks:
 ```ruby
-H {
+Papercraft.html {
   html {
     head {
       title 'page title'
@@ -104,19 +108,19 @@ H {
 Tag methods accept a string argument, a block, or no argument at all:
 ```ruby
-H { p 'hello' }.render #=> "<p>hello</p>"
+Papercraft.html { p 'hello' }.render #=> "<p>hello</p>"
-H { p { span '1'; span '2' } }.render #=> "<p><span>1</span><span>2</span></p>"
+Papercraft.html { p { span '1'; span '2' } }.render #=> "<p><span>1</span><span>2</span></p>"
-H { hr() }.render #=> "<hr/>"
+Papercraft.html { hr() }.render #=> "<hr/>"
 ```
 Tag methods also accept tag attributes, given as a hash:
 ```ruby
-H { img src: '/my.gif' }.render #=> "<img src="/my.gif"/>
+Papercraft.html { img src: '/my.gif' }.render #=> "<img src="/my.gif"/>
-H { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</p>"
+Papercraft.html { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</p>"
 ```
 ## Template parameters
@@ -126,14 +130,14 @@ parameters are specified as block parameters, and are passed to the template on
 rendering:
 ```ruby
-greeting = H { |name| h1 "Hello, #{name}!" }
+greeting = Papercraft.html { |name| h1 "Hello, #{name}!" }
 greeting.render('world') #=> "<h1>Hello, world!</h1>"
 ```
 Templates can also accept named parameters:
 ```ruby
-greeting = H { |name:| h1 "Hello, #{name}!" }
+greeting = Papercraft.html { |name:| h1 "Hello, #{name}!" }
 greeting.render(name: 'world') #=> "<h1>Hello, world!</h1>"
 ```
@@ -143,7 +147,7 @@ Since Papercraft templates are just a bunch of Ruby, you can easily write your
 view logic right in the template:
 ```ruby
-H { |user = nil|
+Papercraft.html { |user = nil|
   if user
     span "Hello, #{user.name}!"
   else
@@ -157,7 +161,7 @@ H { |user = nil|
 Templates can also accept and render blocks by using `emit_yield`:
 ```ruby
-page = H {
+page = Papercraft.html {
   html {
     body { emit_yield }
   }
@@ -174,14 +178,14 @@ it by passing it as a block to `H`:
 ```ruby
 greeting = proc { |name| h1 "Hello, #{name}!" }
-H(&greeting).render('world')
+Papercraft.html(&greeting).render('world')
 ```
 Components can also be expressed using lambda notation:
 ```ruby
 greeting = ->(name) { h1 "Hello, #{name}!" }
-H(&greeting).render('world')
+Papercraft.html(&greeting).render('world')
 ```
 ## Component composition
@@ -208,7 +212,7 @@ ItemList = ->(items) {
   }
 }
-page = H { |title, items|
+page = Papercraft.html { |title, items|
   html5 {
     head { Title(title) }
     body { ItemList(items) }
@@ -227,7 +231,7 @@ non-constant components by invoking the `#emit` method:
 ```ruby
 greeting = -> { span "Hello, world" }
-H {
+Papercraft.html {
   div {
     emit greeting
   }
@@ -245,12 +249,12 @@ or block to the original component:
 ```ruby
 # parameter application
-hello = H { |name| h1 "Hello, #{name}!" }
+hello = Papercraft.html { |name| h1 "Hello, #{name}!" }
 hello_world = hello.apply('world')
 hello_world.render #=> "<h1>Hello, world!</h1>"
 # block application
-div_wrap = H { div { emit_yield } }
+div_wrap = Papercraft.html { div { emit_yield } }
 wrapped_h1 = div_wrap.apply { h1 'hi' }
 wrapped_h1.render #=> "<div><h1>hi</h1></div>"
@@ -269,8 +273,8 @@ markup, enhancing components or injecting component parameters.
 Here is a HOC that takes a component as parameter:
 ```ruby
-div_wrap = H { |inner| div { emit inner } }
-greeter = H { h1 'hi' }
+div_wrap = Papercraft.html { |inner| div { emit inner } }
+greeter = Papercraft.html { h1 'hi' }
 wrapped_greeter = div_wrap.apply(greeter)
 wrapped_greeter.render #=> "<div><h1>hi</h1></div>"
 ```
@@ -278,7 +282,7 @@ wrapped_greeter.render #=> "<div><h1>hi</h1></div>"
 The inner component can also be passed as a block, as shown above:
 ```ruby
-div_wrap = H { div { emit_yield } }
+div_wrap = Papercraft.html { div { emit_yield } }
 wrapped_greeter = div_wrap.apply { h1 'hi' }
 wrapped_greeter.render #=> "<div><h1>hi</h1></div>"
 ```
@@ -292,7 +296,7 @@ this by creating a `default` page template that takes a block, then use `#apply`
 to create the other templates:
 ```ruby
-default_layout = H { |**params|
+default_layout = Papercraft.html { |**params|
   html5 {
     head {
       title: params[:title]
@@ -321,7 +325,7 @@ article_layout.render(
 Raw HTML can be emitted using `#emit`:
 ```ruby
-wrapped = H { |html| div { emit html } }
+wrapped = Papercraft.html { |html| div { emit html } }
 wrapped.render("<h1>hi</h1>") #=> "<div><h1>hi</h1></div>"
 ```
@@ -331,7 +335,7 @@ To emit a string with proper HTML encoding, without wrapping it in an HTML
 element, use `#text`:
 ```ruby
-H { str 'hi&lo' }.render #=> "hi&amp;lo"
+Papercraft.html { str 'hi&lo' }.render #=> "hi&amp;lo"
 ```
 ## Emitting Markdown
@@ -341,7 +345,7 @@ Markdown is rendered using the
 `#emit_markdown`:
 ```ruby
-template = H { |md| div { emit_markdown md } }
+template = Papercraft.html { |md| div { emit_markdown md } }
 template.render("Here's some *Markdown*") #=> "<div><p>Here's some <em>Markdown</em><p>\n</div>"
 ```
@@ -350,10 +354,18 @@ options](https://kramdown.gettalong.org/options.html#available-options) can be
 specified by adding them to the `#emit_markdown` call:
 ```ruby
-template = H { |md| div { emit_markdown md, auto_ids: false } }
+template = Papercraft.html { |md| div { emit_markdown md, auto_ids: false } }
 template.render("# title") #=> "<div><h1>title</h1></div>"
 ```
+The `#emit_markdown` method is available only to HTML templates. If you need to
+render markdown in XML or JSON templates (usually for implementing RSS or JSON
+feeds), you can use `Papercraft.markdown` directly:
+```ruby
+Papercraft.markdown('# title') #=> "<h1>title</h1>"
+```
 The default Kramdown options are:
 ```ruby
@@ -366,10 +378,10 @@ The default Kramdown options are:
 ```
 The deafult options can be configured by accessing
-`Papercraft::HTML.kramdown_options`, e.g.:
+`Papercraft.default_kramdown_options`, e.g.:
 ```ruby
-Papercraft::HTML.kramdown_options[:auto_ids] = false
+Papercraft.default_kramdown_options[:auto_ids] = false
 ```
 ## Deferred evaluation
@@ -393,7 +405,7 @@ class that can collect JS and CSS dependencies from the different components
 integrated into the page, and adds them to the page's `<head>` element:
 ```ruby
-default_layout = H { |**args|
+default_layout = Papercraft.html { |**args|
   @dependencies = DependencyMananger.new
   head {
     defer { emit @dependencies.head_markup }
@@ -479,7 +491,7 @@ The call to `Papercraft::extension` lets us access the different methods of
 we'll be able to express the above markup as follows:
 ```ruby
-H {
+Papercraft.html {
   bootstrap.card(style: 'width: 18rem') {
     bootstrap.card_title 'Card title'
     bootstrap.card_subtitle 'Card subtitle'
@@ -490,6 +502,37 @@ H {
 }
 ```
+## JSON templating
+You can create a JSON template using the same API used for HTML and XML
+templating. The only difference is that for adding array items you'll need to
+use the `#item` method:
+```ruby
+Papercraft.json {
+  item 1
+  item 2
+  item 3
+}.render #=> "[1,2,3]"
+```
+Otherwise, you can create arbitrarily complex JSON structures by mixing hashes
+and arrays:
+```Ruby
+Papercraft.json {
+  foo {
+    bar {
+      item nil
+      item true
+      item 123.456
+    }
+  }
+}.render #=> "{\"foo\":{\"bar\":[null,true,123.456]}}"
+```
+Papercraft uses the [JSON gem](https://rubyapi.org/3.1/o/json) under the hood.
 ## API Reference
 The API reference for this library can be found

data/lib/papercraft/component.rb CHANGED Viewed

@@ -11,21 +11,26 @@ module Papercraft
   # 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 global methods `H` or `X`, for HTML
-  # or XML templates, respectively:
+  # Components are usually created using the class methods `html`, `xml` or
+  # `json`, for HTML, XML or JSON templates, respectively:
   #
-  #   greeter = H { |name| h1 "Hello, #{name}!" }
+  #   greeter = Papercraft.html { |name| h1 "Hello, #{name}!" }
   #   greeter.render('world') #=> "<h1>Hello, world!</h1>"
   #
   # Components can also be created using the normal constructor:
   #
-  #   greeter = Papercraft::Component.new { |name| h1 "Hello, #{name}!" }
+  #   greeter = Papercraft::Component.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
+  # 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
   # unqualified methods:
   #
-  #   page_layout = H {
+  #   page_layout = Papercraft.html {
   #     html5 {
   #       head {
   #         title 'foo'
@@ -41,7 +46,7 @@ module Papercraft
   # `greeter` template shown above takes a single `name` parameter. Here's how a
   # anchor component could be implemented with named parameters:
   #
-  #   anchor = H { |uri: , text: | a(text, href: uri) }
+  #   anchor = Papercraft.html { |uri: , text: | a(text, href: uri) }
   #
   # The above component could later be rendered by passing the needed arguments:
   #
@@ -51,7 +56,7 @@ module Papercraft
   #
   # A component can be included in another component using the `emit` method:
   #
-  #   links = H {
+  #   links = Papercraft.html {
   #     emit anchor, uri: '/posts',   text: 'Posts'
   #     emit anchor, uri: '/archive', text: 'Archive'
   #     emit anchor, uri: '/about',   text: 'About'
@@ -60,7 +65,7 @@ module Papercraft
   # Another way of composing components is to pass the components themselves as
   # parameters:
   #
-  #   links = H { |anchors|
+  #   links = Papercraft.html { |anchors|
   #     anchors.each { |a| emit a }
   #   }
   #   links.render([
@@ -84,14 +89,22 @@ module Papercraft
     # 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 component 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.
     #
     # @param mode [:html, :xml] rendering mode
+    # @param mime_type [String, nil] the component's mime type (nil for default)
     # @param block [Proc] nested HTML block
-    def initialize(mode: :html, &block)
+    def initialize(mode: :html, mime_type: nil, &block)
       @mode = mode
+      @mime_type = mime_type || STOCK_MIME_TYPE[mode]
       super(&block)
     end
@@ -106,21 +119,16 @@ 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
     # current one. Application is one of the principal methods of composing
     # components, particularly when passing inner components as blocks:
     #
-    #   article_wrapper = H {
+    #   article_wrapper = Papercraft.html {
     #     article {
     #       emit_yield
     #     }
@@ -136,15 +144,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(*a, *x, **b, **y, &template) }
-        end)
-      else
-        Component.new(&proc do |*x, **y|
-          instance_exec(*a, *x, **b, **y, &template)
-        end)
-      end
+      Component.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
@@ -157,10 +160,16 @@ module Papercraft
         HTMLRenderer
       when :xml
         XMLRenderer
+      when :json
+        JSONRenderer
       else
         raise "Invalid mode #{@mode.inspect}"
       end
     end
+    def mime_type
+      @mime_type
+    end
     # def compile
     #   Papercraft::Compiler.new.compile(self)

data/lib/papercraft/html.rb CHANGED Viewed

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
-require 'kramdown'
-require 'rouge'
-require 'kramdown-parser-gfm'
 module Papercraft
   # HTML Markup extensions
   module HTML
@@ -83,41 +79,7 @@ module Papercraft
     # @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,
-          syntax_highlighter: :rouge,
-          input: 'GFM',
-          hard_wrap: false
-        }
-      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)
+      emit Papercraft.markdown(markdown, **opts)
     end
   end
 end

data/lib/papercraft/json.rb ADDED Viewed

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+require 'json'
+module Papercraft
+  # JSON renderer extensions
+  module JSON
+    def object_stack
+      @object_stack ||= [nil]
+    end
+    def with_object(&block)
+      object_stack << nil
+      instance_eval(&block)
+    end
+    def verify_array_target
+      case object_stack[-1]
+      when nil
+        object_stack[-1] = []
+      when Hash
+        raise "Mixing array and hash values"
+      end
+    end
+    def verify_hash_target
+      case object_stack[-1]
+      when nil
+        object_stack[-1] = {}
+      when Array
+        raise "Mixing array and hash values"
+      end
+    end
+    def push_array_item(value)
+      object_stack[-1] << value
+    end
+    def push_kv_item(key, value)
+      object_stack[-1][key] = value
+    end
+    def enter_object(&block)
+      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
+  end
+end

data/lib/papercraft/renderer.rb CHANGED Viewed

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
+require 'escape_utils'
 require_relative './html'
+require_relative './json'
 require_relative './extension_proxy'
 module Papercraft
@@ -55,7 +58,7 @@ module Papercraft
       # end
       #
       # Papercraft.extension(components: ComponentLibrary)
-      # H { components.card('Foo', '**Bar**') }
+      # Papercraft.html { components.card('Foo', '**Bar**') }
       #
       # @param map [Hash] hash mapping methods to extension modules
       # @return [void]
@@ -112,7 +115,7 @@ module Papercraft
     # The tag method template below is optimized for performance. Do not touch!
-    S_TAG_METHOD_LINE = __LINE__ + 1
+    S_TAG_METHOD_LINE = __LINE__ + 2
     S_TAG_METHOD = <<~EOF
       S_TAG_%<TAG>s_PRE = %<tag_pre>s
       S_TAG_%<TAG>s_CLOSE = %<tag_close>s
@@ -210,11 +213,11 @@ module Papercraft
     # `#to_s` which is then added to the rendering buffer, without any escaping.
     #
     #   greeter = proc { |name| h1 "Hello, #{name}!" }
-    #   H { emit(greeter, 'world') }.render #=> "<h1>Hello, world!</h1>"
+    #   Papercraft.html { emit(greeter, 'world') }.render #=> "<h1>Hello, world!</h1>"
     #
-    #   H { emit 'hi&<bye>' }.render #=> "hi&<bye>"
+    #   Papercraft.html { emit 'hi&<bye>' }.render #=> "hi&<bye>"
     #
-    #   H { emit nil }.render #=> ""
+    #   Papercraft.html { emit nil }.render #=> ""
     #
     # @param o [Proc, Papercraft::Component, String] emitted object
     # @param *a [Array<any>] arguments to pass to a proc
@@ -234,7 +237,7 @@ module Papercraft
     # Emits a block supplied using `Component#apply` or `Component#render`.
     #
-    #   div_wrap = H { |*args| div { emit_yield(*args) } }
+    #   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>"
     #
@@ -242,9 +245,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
@@ -255,7 +259,7 @@ module Papercraft
     # adding elements to the `<head>` section. Here's how a title can be
     # controlled from a nested component:
     #
-    #   layout = H {
+    #   layout = Papercraft.html {
     #     html {
     #       head {
     #         defer { title @title }
@@ -304,19 +308,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]
@@ -379,4 +383,8 @@ module Papercraft
       EscapeUtils.escape_xml(text.to_s)
     end
   end
+  class JSONRenderer < Renderer
+    include JSON
+  end
 end

data/lib/papercraft/version.rb CHANGED Viewed

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

data/lib/papercraft.rb CHANGED Viewed

@@ -1,60 +1,110 @@
 # frozen_string_literal: true
-require 'escape_utils'
+require 'kramdown'
+require 'rouge'
+require 'kramdown-parser-gfm'
 require_relative 'papercraft/component'
 require_relative 'papercraft/renderer'
 require_relative 'papercraft/encoding'
 # require_relative 'papercraft/compiler'
 # Papercraft is a component-based HTML templating library
 module Papercraft
   # Exception class used to signal templating-related errors
   class Error < RuntimeError; end
-  # 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 self.extension(map)
-    Renderer.extension(map)
-  end
-end
-# Kernel extensions
-module ::Kernel
-  # Creates a new papercraft component. `#H` can take either a proc argument or
-  # a block. In both cases, the proc is converted to a `Papercraft::Component`.
-  #
-  # H(proc { h1 'hi' }).render #=> "<h1>hi</h1>"
-  # H { h1 'hi' }.render #=> "<h1>hi</h1>"
-  #
-  # @param template [Proc] template block
-  # @return [Papercraft::Component] Papercraft component
-  def H(o = nil, &template)
-    return o if o.is_a?(Papercraft::Component)
-    template ||= o
-    Papercraft::Component.new(mode: :html, &template)
-  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
+    # Creates a new papercraft component. `Papercraft.html` can take either a proc
+    # argument or a block. In both cases, the proc is converted to a
+    # `Papercraft::Component`.
+    #
+    # 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
+    def html(o = nil, mime_type: nil, &template)
+      return o if o.is_a?(Papercraft::Component)
+      template ||= o
+      Papercraft::Component.new(mode: :html, mime_type: mime_type, &template)
+    end
+    # Creates a new papercraft component 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.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
+    def xml(o = nil, mime_type: nil, &template)
+      return o if o.is_a?(Papercraft::Component)
+      template ||= o
+      Papercraft::Component.new(mode: :xml, mime_type: mime_type, &template)
+    end
+    # Creates a new papercraft component 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.json(proc { item 42 }).render #=> "[42]"
+    # Papercraft.json { foo 'bar' }.render #=> "{\"foo\": \"bar\"}"
+    #
+    # @param template [Proc] template block
+    # @return [Papercraft::Component] Papercraft component
+    def json(o = nil, mime_type: nil, &template)
+      return o if o.is_a?(Papercraft::Component)
+      template ||= o
+      Papercraft::Component.new(mode: :json, mime_type: mime_type, &template)
+    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
+    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
-  # Creates a new papercraft component in XML mode. `#X` can take either a proc argument or
-  # a block. In both cases, the proc is converted to a `Papercraft::Component`.
-  #
-  # X(proc { item 'foo' }).render #=> "<item>foo</item>"
-  # X { item 'foo' }.render #=> "<item>foo</item>"
-  #
-  # @param template [Proc] template block
-  # @return [Papercraft::Component] Papercraft component
-  def X(o = nil, &template)
-    return o if o.is_a?(Papercraft::Component)
-    template ||= o
-    Papercraft::Component.new(mode: :xml, &template)
+    # 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
+    end
   end
 end

metadata CHANGED Viewed

@@ -1,27 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '0.13'
+  version: '0.17'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-19 00:00:00.000000000 Z
+date: 2022-01-23 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:
@@ -137,6 +137,7 @@ files:
 - lib/papercraft/encoding.rb
 - lib/papercraft/extension_proxy.rb
 - lib/papercraft/html.rb
+- lib/papercraft/json.rb
 - lib/papercraft/renderer.rb
 - lib/papercraft/version.rb
 homepage: http://github.com/digital-fabric/papercraft