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

papercraft 0.13 → 0.17

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 (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