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

papercraft 0.8.3 → 0.9

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