papercraft 0.18 → 0.22
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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +17 -0
- data/README.md +78 -36
- data/lib/papercraft/extension_proxy.rb +16 -3
- data/lib/papercraft/html.rb +32 -0
- data/lib/papercraft/json.rb +89 -36
- data/lib/papercraft/renderer.rb +10 -239
- data/lib/papercraft/tags.rb +260 -0
- data/lib/papercraft/{component.rb → template.rb} +29 -26
- data/lib/papercraft/version.rb +1 -1
- data/lib/papercraft/xml.rb +39 -0
- data/lib/papercraft.rb +17 -17
- data/papercraft.png +0 -0
- metadata +7 -3
@@ -4,30 +4,30 @@ require_relative './html'
|
|
4
4
|
|
5
5
|
module Papercraft
|
6
6
|
|
7
|
-
#
|
8
|
-
# include other
|
7
|
+
# Template represents a distinct, reusable HTML template. A template can
|
8
|
+
# include other templates, and also be nested inside other templates.
|
9
9
|
#
|
10
|
-
# Since in Papercraft HTML is expressed using blocks (or procs,) the
|
10
|
+
# Since in Papercraft HTML is expressed using blocks (or procs,) the Template
|
11
11
|
# class is simply a special kind of Proc, which has some enhanced
|
12
12
|
# capabilities, allowing it to be easily composed in a variety of ways.
|
13
13
|
#
|
14
|
-
#
|
14
|
+
# Templates are usually created using the class methods `html`, `xml` or
|
15
15
|
# `json`, for HTML, XML or JSON templates, respectively:
|
16
16
|
#
|
17
17
|
# greeter = Papercraft.html { |name| h1 "Hello, #{name}!" }
|
18
18
|
# greeter.render('world') #=> "<h1>Hello, world!</h1>"
|
19
19
|
#
|
20
|
-
#
|
20
|
+
# Templates can also be created using the normal constructor:
|
21
21
|
#
|
22
|
-
# greeter = Papercraft::
|
22
|
+
# greeter = Papercraft::Template.new(mode: :html) { |name| h1 "Hello, #{name}!" }
|
23
23
|
# greeter.render('world') #=> "<h1>Hello, world!</h1>"
|
24
24
|
#
|
25
|
-
# The different methods for creating
|
25
|
+
# The different methods for creating templates can also take a custom MIME
|
26
26
|
# type, by passing a `mime_type` named argument:
|
27
27
|
#
|
28
28
|
# json = Papercraft.json(mime_type: 'application/feed+json') { ... }
|
29
29
|
#
|
30
|
-
# In the
|
30
|
+
# In the template block, HTML elements are created by simply calling
|
31
31
|
# unqualified methods:
|
32
32
|
#
|
33
33
|
# page_layout = Papercraft.html {
|
@@ -41,20 +41,20 @@ module Papercraft
|
|
41
41
|
# }
|
42
42
|
# }
|
43
43
|
#
|
44
|
-
# Papercraft
|
44
|
+
# Papercraft templates can take explicit parameters in order to render
|
45
45
|
# dynamic content. This can be in the form of regular or named parameters. The
|
46
46
|
# `greeter` template shown above takes a single `name` parameter. Here's how a
|
47
|
-
# anchor
|
47
|
+
# anchor template could be implemented with named parameters:
|
48
48
|
#
|
49
49
|
# anchor = Papercraft.html { |uri: , text: | a(text, href: uri) }
|
50
50
|
#
|
51
|
-
# The above
|
51
|
+
# The above template could later be rendered by passing the needed arguments:
|
52
52
|
#
|
53
53
|
# anchor.render(uri: 'https://example.com', text: 'Example')
|
54
54
|
#
|
55
|
-
# ##
|
55
|
+
# ## Template Composition
|
56
56
|
#
|
57
|
-
# A
|
57
|
+
# A template can be included in another template using the `emit` method:
|
58
58
|
#
|
59
59
|
# links = Papercraft.html {
|
60
60
|
# emit anchor, uri: '/posts', text: 'Posts'
|
@@ -62,7 +62,7 @@ module Papercraft
|
|
62
62
|
# emit anchor, uri: '/about', text: 'About'
|
63
63
|
# }
|
64
64
|
#
|
65
|
-
# Another way of composing
|
65
|
+
# Another way of composing templates is to pass the templates themselves as
|
66
66
|
# parameters:
|
67
67
|
#
|
68
68
|
# links = Papercraft.html { |anchors|
|
@@ -74,8 +74,8 @@ module Papercraft
|
|
74
74
|
# anchor.apply(uri: '/about', text: 'About')
|
75
75
|
# ])
|
76
76
|
#
|
77
|
-
# The `#apply` method creates a new
|
78
|
-
# such that the
|
77
|
+
# The `#apply` method creates a new template, applying the given parameters
|
78
|
+
# such that the template can be rendered without parameters:
|
79
79
|
#
|
80
80
|
# links_with_anchors = links.apply([
|
81
81
|
# anchor.apply(uri: '/posts', text: 'Posts'),
|
@@ -84,7 +84,7 @@ module Papercraft
|
|
84
84
|
# ])
|
85
85
|
# links_with_anchors.render
|
86
86
|
#
|
87
|
-
class
|
87
|
+
class Template < Proc
|
88
88
|
|
89
89
|
# Determines the rendering mode: `:html` or `:xml`.
|
90
90
|
attr_accessor :mode
|
@@ -95,12 +95,12 @@ module Papercraft
|
|
95
95
|
json: 'application/json'
|
96
96
|
}.freeze
|
97
97
|
|
98
|
-
# Initializes a
|
98
|
+
# Initializes a template with the given block. The rendering mode (HTML or
|
99
99
|
# XML) can be passed in the `mode:` parameter. If `mode:` is not specified,
|
100
|
-
# the
|
100
|
+
# the template defaults to HTML.
|
101
101
|
#
|
102
102
|
# @param mode [:html, :xml] rendering mode
|
103
|
-
# @param mime_type [String, nil] the
|
103
|
+
# @param mime_type [String, nil] the template's mime type (nil for default)
|
104
104
|
# @param block [Proc] nested HTML block
|
105
105
|
def initialize(mode: :html, mime_type: nil, &block)
|
106
106
|
@mode = mode
|
@@ -124,9 +124,9 @@ module Papercraft
|
|
124
124
|
end.to_s
|
125
125
|
end
|
126
126
|
|
127
|
-
# Creates a new
|
127
|
+
# Creates a new template, applying the given parameters and or block to the
|
128
128
|
# current one. Application is one of the principal methods of composing
|
129
|
-
#
|
129
|
+
# templates, particularly when passing inner templates as blocks:
|
130
130
|
#
|
131
131
|
# article_wrapper = Papercraft.html {
|
132
132
|
# article {
|
@@ -141,19 +141,19 @@ module Papercraft
|
|
141
141
|
# @param *a [<any>] normal parameters
|
142
142
|
# @param **b [Hash] named parameters
|
143
143
|
# @param &block [Proc] inner block
|
144
|
-
# @return [Papercraft::
|
144
|
+
# @return [Papercraft::Template] applied template
|
145
145
|
def apply(*a, **b, &block)
|
146
146
|
template = self
|
147
|
-
|
147
|
+
Template.new(mode: @mode, mime_type: @mime_type, &proc do |*x, **y|
|
148
148
|
push_emit_yield_block(block) if block
|
149
149
|
instance_exec(*a, *x, **b, **y, &template)
|
150
150
|
end)
|
151
151
|
end
|
152
152
|
|
153
153
|
# Returns the Renderer class used for rendering the templates, according to
|
154
|
-
# the
|
154
|
+
# the template's mode.
|
155
155
|
#
|
156
|
-
# @return [Papercraft::Renderer] Renderer used for rendering the
|
156
|
+
# @return [Papercraft::Renderer] Renderer used for rendering the template
|
157
157
|
def renderer_class
|
158
158
|
case @mode
|
159
159
|
when :html
|
@@ -167,6 +167,9 @@ module Papercraft
|
|
167
167
|
end
|
168
168
|
end
|
169
169
|
|
170
|
+
# Returns the template's associated MIME type.
|
171
|
+
#
|
172
|
+
# @return [String] MIME type
|
170
173
|
def mime_type
|
171
174
|
@mime_type
|
172
175
|
end
|
data/lib/papercraft/version.rb
CHANGED
@@ -0,0 +1,39 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
require 'escape_utils'
|
4
|
+
require_relative './tags'
|
5
|
+
|
6
|
+
module Papercraft
|
7
|
+
# XML renderer extensions
|
8
|
+
module XML
|
9
|
+
include Tags
|
10
|
+
|
11
|
+
private
|
12
|
+
|
13
|
+
# Converts a tag to its string representation. Underscores will be converted
|
14
|
+
# to dashes, double underscores will be converted to colon.
|
15
|
+
#
|
16
|
+
# @param tag [Symbol, String] tag
|
17
|
+
# @return [String] tag string
|
18
|
+
def tag_repr(tag)
|
19
|
+
tag.to_s.gsub('__', ':').tr('_', '-')
|
20
|
+
end
|
21
|
+
|
22
|
+
# Converts an attribute to its string representation. Underscores will be
|
23
|
+
# converted to dashes, double underscores will be converted to colon.
|
24
|
+
#
|
25
|
+
# @param att [Symbol, String] attribute
|
26
|
+
# @return [String] attribute string
|
27
|
+
def att_repr(att)
|
28
|
+
att.to_s.gsub('__', ':').tr('_', '-')
|
29
|
+
end
|
30
|
+
|
31
|
+
# Escapes the given text using XML entities.
|
32
|
+
#
|
33
|
+
# @param text [String] text
|
34
|
+
# @return [String] escaped text
|
35
|
+
def escape_text(text)
|
36
|
+
EscapeUtils.escape_xml(text.to_s)
|
37
|
+
end
|
38
|
+
end
|
39
|
+
end
|
data/lib/papercraft.rb
CHANGED
@@ -4,13 +4,13 @@ require 'kramdown'
|
|
4
4
|
require 'rouge'
|
5
5
|
require 'kramdown-parser-gfm'
|
6
6
|
|
7
|
-
require_relative 'papercraft/
|
7
|
+
require_relative 'papercraft/template'
|
8
8
|
require_relative 'papercraft/renderer'
|
9
9
|
require_relative 'papercraft/encoding'
|
10
10
|
# require_relative 'papercraft/compiler'
|
11
11
|
|
12
12
|
|
13
|
-
# Papercraft is a
|
13
|
+
# Papercraft is a composable templating library
|
14
14
|
module Papercraft
|
15
15
|
# Exception class used to signal templating-related errors
|
16
16
|
class Error < RuntimeError; end
|
@@ -31,49 +31,49 @@ module Papercraft
|
|
31
31
|
Renderer.extension(map)
|
32
32
|
end
|
33
33
|
|
34
|
-
# Creates a new papercraft
|
34
|
+
# Creates a new papercraft template. `Papercraft.html` can take either a proc
|
35
35
|
# argument or a block. In both cases, the proc is converted to a
|
36
|
-
# `Papercraft::
|
36
|
+
# `Papercraft::Template`.
|
37
37
|
#
|
38
38
|
# Papercraft.html(proc { h1 'hi' }).render #=> "<h1>hi</h1>"
|
39
39
|
# Papercraft.html { h1 'hi' }.render #=> "<h1>hi</h1>"
|
40
40
|
#
|
41
41
|
# @param template [Proc] template block
|
42
|
-
# @return [Papercraft::
|
42
|
+
# @return [Papercraft::Template] Papercraft template
|
43
43
|
def html(o = nil, mime_type: nil, &template)
|
44
|
-
return o if o.is_a?(Papercraft::
|
44
|
+
return o if o.is_a?(Papercraft::Template)
|
45
45
|
template ||= o
|
46
|
-
Papercraft::
|
46
|
+
Papercraft::Template.new(mode: :html, mime_type: mime_type, &template)
|
47
47
|
end
|
48
48
|
|
49
|
-
# Creates a new
|
49
|
+
# Creates a new Papercraft template in XML mode. `Papercraft.xml` can take
|
50
50
|
# either a proc argument or a block. In both cases, the proc is converted to a
|
51
|
-
# `Papercraft::
|
51
|
+
# `Papercraft::Template`.
|
52
52
|
#
|
53
53
|
# Papercraft.xml(proc { item 'foo' }).render #=> "<item>foo</item>"
|
54
54
|
# Papercraft.xml { item 'foo' }.render #=> "<item>foo</item>"
|
55
55
|
#
|
56
56
|
# @param template [Proc] template block
|
57
|
-
# @return [Papercraft::
|
57
|
+
# @return [Papercraft::Template] Papercraft template
|
58
58
|
def xml(o = nil, mime_type: nil, &template)
|
59
|
-
return o if o.is_a?(Papercraft::
|
59
|
+
return o if o.is_a?(Papercraft::Template)
|
60
60
|
template ||= o
|
61
|
-
Papercraft::
|
61
|
+
Papercraft::Template.new(mode: :xml, mime_type: mime_type, &template)
|
62
62
|
end
|
63
63
|
|
64
|
-
# Creates a new
|
64
|
+
# Creates a new Papercraft template in JSON mode. `Papercraft.json` can take
|
65
65
|
# either a proc argument or a block. In both cases, the proc is converted to a
|
66
|
-
# `Papercraft::
|
66
|
+
# `Papercraft::Template`.
|
67
67
|
#
|
68
68
|
# Papercraft.json(proc { item 42 }).render #=> "[42]"
|
69
69
|
# Papercraft.json { foo 'bar' }.render #=> "{\"foo\": \"bar\"}"
|
70
70
|
#
|
71
71
|
# @param template [Proc] template block
|
72
|
-
# @return [Papercraft::
|
72
|
+
# @return [Papercraft::Template] Papercraft template
|
73
73
|
def json(o = nil, mime_type: nil, &template)
|
74
|
-
return o if o.is_a?(Papercraft::
|
74
|
+
return o if o.is_a?(Papercraft::Template)
|
75
75
|
template ||= o
|
76
|
-
Papercraft::
|
76
|
+
Papercraft::Template.new(mode: :json, mime_type: mime_type, &template)
|
77
77
|
end
|
78
78
|
|
79
79
|
# Renders Markdown into HTML. The `opts` argument will be merged with the
|
data/papercraft.png
ADDED
Binary file
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: papercraft
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: '0.
|
4
|
+
version: '0.22'
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Sharon Rosner
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2022-02-
|
11
|
+
date: 2022-02-14 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: escape_utils
|
@@ -128,18 +128,22 @@ executables: []
|
|
128
128
|
extensions: []
|
129
129
|
extra_rdoc_files:
|
130
130
|
- README.md
|
131
|
+
- papercraft.png
|
131
132
|
files:
|
132
133
|
- CHANGELOG.md
|
133
134
|
- README.md
|
134
135
|
- lib/papercraft.rb
|
135
136
|
- lib/papercraft/compiler.rb
|
136
|
-
- lib/papercraft/component.rb
|
137
137
|
- lib/papercraft/encoding.rb
|
138
138
|
- lib/papercraft/extension_proxy.rb
|
139
139
|
- lib/papercraft/html.rb
|
140
140
|
- lib/papercraft/json.rb
|
141
141
|
- lib/papercraft/renderer.rb
|
142
|
+
- lib/papercraft/tags.rb
|
143
|
+
- lib/papercraft/template.rb
|
142
144
|
- lib/papercraft/version.rb
|
145
|
+
- lib/papercraft/xml.rb
|
146
|
+
- papercraft.png
|
143
147
|
homepage: http://github.com/digital-fabric/papercraft
|
144
148
|
licenses:
|
145
149
|
- MIT
|