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.
@@ -4,30 +4,30 @@ require_relative './html'
4
4
 
5
5
  module Papercraft
6
6
 
7
- # Component represents a distinct, reusable HTML template. A component can
8
- # include other components, and also be nested inside other components.
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 Component
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
- # Components are usually created using the class methods `html`, `xml` or
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
- # Components can also be created using the normal constructor:
20
+ # Templates can also be created using the normal constructor:
21
21
  #
22
- # greeter = Papercraft::Component.new(mode: :html) { |name| h1 "Hello, #{name}!" }
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 components can also take a custom MIME
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 component block, HTML elements are created by simply calling
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 components can take explicit parameters in order to render
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 component could be implemented with named parameters:
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 component could later be rendered by passing the needed arguments:
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
- # ## Component Composition
55
+ # ## Template Composition
56
56
  #
57
- # A component can be included in another component using the `emit` method:
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 components is to pass the components themselves as
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 component, applying the given parameters
78
- # such that the component can be rendered without parameters:
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 Component < Proc
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 component with the given block. The rendering mode (HTML or
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 component defaults to HTML.
100
+ # the template defaults to HTML.
101
101
  #
102
102
  # @param mode [:html, :xml] rendering mode
103
- # @param mime_type [String, nil] the component's mime type (nil for default)
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 component, applying the given parameters and or block to the
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
- # components, particularly when passing inner components as blocks:
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::Component] applied component
144
+ # @return [Papercraft::Template] applied template
145
145
  def apply(*a, **b, &block)
146
146
  template = self
147
- Component.new(mode: @mode, mime_type: @mime_type, &proc do |*x, **y|
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 component's mode.
154
+ # the template's mode.
155
155
  #
156
- # @return [Papercraft::Renderer] Renderer used for rendering the component
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
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Papercraft
4
- VERSION = '0.18'
4
+ VERSION = '0.22'
5
5
  end
@@ -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/component'
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 component-based HTML templating library
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 component. `Papercraft.html` can take either a proc
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::Component`.
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::Component] Papercraft component
42
+ # @return [Papercraft::Template] Papercraft template
43
43
  def html(o = nil, mime_type: nil, &template)
44
- return o if o.is_a?(Papercraft::Component)
44
+ return o if o.is_a?(Papercraft::Template)
45
45
  template ||= o
46
- Papercraft::Component.new(mode: :html, mime_type: mime_type, &template)
46
+ Papercraft::Template.new(mode: :html, mime_type: mime_type, &template)
47
47
  end
48
48
 
49
- # Creates a new papercraft component in XML mode. `Papercraft.xml` can take
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::Component`.
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::Component] Papercraft component
57
+ # @return [Papercraft::Template] Papercraft template
58
58
  def xml(o = nil, mime_type: nil, &template)
59
- return o if o.is_a?(Papercraft::Component)
59
+ return o if o.is_a?(Papercraft::Template)
60
60
  template ||= o
61
- Papercraft::Component.new(mode: :xml, mime_type: mime_type, &template)
61
+ Papercraft::Template.new(mode: :xml, mime_type: mime_type, &template)
62
62
  end
63
63
 
64
- # Creates a new papercraft component in JSON mode. `Papercraft.json` can take
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::Component`.
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::Component] Papercraft component
72
+ # @return [Papercraft::Template] Papercraft template
73
73
  def json(o = nil, mime_type: nil, &template)
74
- return o if o.is_a?(Papercraft::Component)
74
+ return o if o.is_a?(Papercraft::Template)
75
75
  template ||= o
76
- Papercraft::Component.new(mode: :json, mime_type: mime_type, &template)
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.18'
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-04 00:00:00.000000000 Z
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