RubyGems - papercraft - Versions diffs - 0.8.3 → 0.9 - Mend

papercraft 0.8.3 → 0.9

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 (6) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 125df0455a1b4c3373b36b3f52b6d965249a7ddf470439ec48df3f7216ea3991
-  data.tar.gz: be9cea2084785a3dc135b852b66f0d91375cafd6050834d06f26f8a6b497f95f
+  metadata.gz: e1f7aa5872a78830c1a5662f055639ae2012b5b9d0f029640dce041f58d1ef4e
+  data.tar.gz: 0c5acc8b14254c63db2132caab42ce003a8ae4713ae6daea7225d0390a420219
 SHA512:
-  metadata.gz: f45e9101d8bb14bfdde19958988343d6e4d87e270462a0db13630860aff5d6adc560df90aefd78317642f6987d3853cc68ad8adb7d0b74e381b43930424d7a79
-  data.tar.gz: c7a153329948a8fa5dbe90602a293b22e060f0118cc3cdfd629f9af9644f57bea4add8ec13e40a5194178bdebc5dd43a26c0507f03e8dd78e3a3a5662968e390
+  metadata.gz: 02bf1f7bc1300f4fa7871a6942c6a2eae2dd2f8202c7f3cc354171806f82e8a68262c3ca5e2232b7b6dcf6788a33b134b5811641561fa5baba3b7c342643b082
+  data.tar.gz: 97a68a0f854f631a6a36b52a350faae4b1da1e337b27701209c6eec9dc16c62856555fdff3ab3d8f33e144e7fed8dc892b22433f38dd3f951a04010f710b63c4

data/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,9 @@
+## 0.9 2021-12-23
+- Add support for emitting Markdown
+- Add support for passing proc as argument to `#H` and `#X`
+- Deprecate `Encoding` module
 ## 0.8.1 2021-12-22
 - Fix gemspec

data/README.md CHANGED Viewed

@@ -2,26 +2,36 @@
 [INSTALL](#installing-papercraft) |
 [TUTORIAL](#getting-started) |
-[EXAMPLES](examples) |
-[REFERENCE](#api-reference)
+[DOCS](https://www.rubydoc.info/gems/papercraft)
 ## What is Papercraft?
+```ruby
+require 'papercraft'
+page = H { |*args|
+  html {
+    head { }
+    body { emit_yield *args }
+  }
+}
+hello = H.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:
-- HTML templating using plain Ruby syntax
+- HTML and XML templating using plain Ruby syntax
 - Minimal boilerplate
 - Mix logic and tags freely
-- Use global and local contexts to pass values to reusable components
-- Automatic HTML escaping
+- Automatic HTML and XML escaping
 - Composable components
+- Explicit parameter passing to nested components
 - Higher order components
-- Built-in support for rendering Markdown
-> **Note** Papercraft is a new library and as such may be missing features and
-> contain bugs. Also, its API may change unexpectedly. Your issue reports and
-> code contributions are most welcome!
+- Built-in support for rendering [Markdown](#emitting-markdown)
 With Papercraft you can structure your templates as nested HTML components, in a
 somewhat similar fashion to React.
@@ -48,7 +58,8 @@ To use Papercraft in your code just require it:
 require 'papercraft'
 ```
-To create a template use `Papercraft.new` or the global method `Kernel#H`:
+To create a template use `Papercraft::Component.new` or the global method
+`Kernel#H`:
 ```ruby
 # can also use Papercraft.new
@@ -114,8 +125,9 @@ H { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</
 ## Template parameters
-Template parameters are specified as block parameters, and are passed to the
-template on rendering:
+In Papercraft, parameters are always passed explicitly. This means that template
+parameters are specified as block parameters, and are passed to the template on
+rendering:
 ```ruby
 greeting = H { |name| h1 "Hello, #{name}!" }
@@ -328,110 +340,43 @@ H { str 'hi&lo' }.render #=> "hi&amp;lo"
 ## Emitting Markdown
-To emit Markdown, use `#emit_markdown`:
+Markdown is rendered using the
+[Kramdown](https://kramdown.gettalong.org/index.html) gem. To emit Markdown, use
+`#emit_markdown`:
 ```ruby
 template = H { |md| div { emit_markdown md } }
-template.render("Here's some *Markdown*") #=> "<div>Here's some <em>Markdown</em></div>"
+template.render("Here's some *Markdown*") #=> "<div><p>Here's some <em>Markdown</em><p>\n</div>"
 ```
-## Some interesting use cases
-Papercraft opens up all kinds of new possibilities when it comes to putting
-together pieces of HTML. Feel free to explore the API!
+[Kramdown
+options](https://kramdown.gettalong.org/options.html#available-options) can be
+specified by adding them to the `#emit_markdown` call:
-### A higher-order list component
+```ruby
+template = H { |md| div { emit_markdown md, auto_ids: false } }
+template.render("# title") #=> "<div><h1>title</h1></div>"
+```
-Here's another demonstration of a higher-order component, a list component that
-takes an item component as an argument. The `List` component can be reused for
-rendering any kind of unordered list, and with any kind of item component:
+The default Kramdown options are:
 ```ruby
-List = ->(items, item_component) {
-  H {
-    ul {
-      items.each { |item|
-        with(item: item) {
-          li { emit item_component }
-        }
-      }
-    }
-  }
+{
+  entity_output: :numeric,
+  syntax_highlighter: :rouge,
+  input: 'GFM',
+  hard_wrap: false
 }
-TodoItem = H {
-  span item.text, class: item.completed ? 'completed' : 'pending'
-}
-def todo_list(items)
-  H {
-    div { List(items, TodoItem) }
-  }
-end
 ```
-## API Reference
-#### `Papercraft#initialize(**context, &block)` a.k.a. `Kernel#H`
-- `context`: local context hash
-- `block`: template block
+The deafult options can be configured by accessing
+`Papercraft::HTML.kramdown_options`:
-Initializes a new Papercraft instance. This method takes a block of template
-code, and an optional [local context](#local-context) in the form of a hash.
-The `Kernel#H` method serves as a shortcut for creating Papercraft instances.
-#### `Papercraft#render(**context)`
-- `context`: global context hash
-Renders the template with an optional [global context](#global-context)
-hash.
-#### Methods accessible inside template blocks
-#### `#<tag/component>(*args, **props, &block)`
-- `args`: tag arguments. For an HTML tag Papercraft expects a single `String`
-  argument containing the inner text of the tag.
-- `props`: hash of tag attributes
-- `block`: inner HTML block
-Adds a tag or component to the current template. If the method name starts with
-an upper-case letter, it is considered a [component](#templates-as-components).
-If a text argument is given for a tag, it will be escaped.
-#### `#cache(*vary, &block)`
-- `vary`: variables used in cached block. The given values will be used to
-  create a separate cache entry.
-- `block`: inner HTML block
-Caches the markup in the given block, storing it in the Papercraft cache store.
-If a cache entry for the given block is found, it will be used instead of
-invoking the block. If one or more variables given, those will be used to create
-a separate cache entry.
-#### `#context`
-Accesses the [global context](#global-context).
-#### `#emit(object)` a.k.a. `#e(object)`
-- `object`: `Proc`, `Papercraft` instance or `String`
-Adds the given object to the current template. If a `String` is given, it is
-rendered verbatim, i.e. without escaping.
-#### `html5(&block)`
-- `block`: inner HTML block
-Adds an HTML5 `doctype` tag, followed by an `html` tag with the given block.
-#### `#text(data)`
+```ruby
+Papercraft::HTML.kramdown_options[:auto_ids] = false
+```
-- `data` - text to add
+## Documentation
-Adds text without wrapping it in a tag. The text will be escaped.
+The complete documentation for this library can be found
+[here](https://www.rubydoc.info/gems/papercraft).

data/lib/papercraft/html.rb CHANGED Viewed

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
-require_relative './html'
+require 'kramdown'
+require 'rouge'
+require 'kramdown-parser-gfm'
-module Papercraft
+module Papercraft
   # HTML Markup extensions
   module HTML
     # Emits the p tag (overrides Object#p)
@@ -42,5 +43,28 @@ module Papercraft
       end
       link(**attributes)
     end
+    def emit_markdown(markdown, **opts)
+      emit Kramdown::Document.new(markdown, **kramdown_options(opts)).to_html
+    end
+    def kramdown_options(opts)
+      HTML.kramdown_options.merge(**opts)
+    end
+    class << self
+      def kramdown_options
+        @kramdown_options ||= {
+          entity_output: :numeric,
+          syntax_highlighter: :rouge,
+          input: 'GFM',
+          hard_wrap: false
+        }
+      end
+      def kramdown_options=(opts)
+        @kramdown_options = opts
+      end
+    end
   end
 end

data/lib/papercraft/version.rb CHANGED Viewed

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

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: '0.9'
 platform: ruby
 authors:
 - Sharon Rosner
@@ -24,6 +24,48 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 1.2.1
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+- !ruby/object:Gem::Dependency
+  name: rouge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.26.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.26.0
+- !ruby/object:Gem::Dependency
+  name: kramdown-parser-gfm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement