berns 4.1.2 → 4.3.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/{README.org → README.md} +98 -90
- data/ext/berns/berns.c +589 -583
- data/ext/berns/strxcat.c +20 -0
- data/ext/berns/strxcat.h +11 -0
- data/ext/berns/strxcpy.c +50 -0
- data/ext/berns/strxcpy.h +32 -0
- data/ext/berns/strxempty.c +9 -0
- data/ext/berns/strxempty.h +9 -0
- data/ext/berns/strxfree.c +6 -0
- data/ext/berns/strxfree.h +9 -0
- data/ext/berns/strxnew.c +8 -0
- data/ext/berns/strxnew.h +11 -0
- data/ext/berns/strxresize.c +6 -0
- data/ext/berns/strxresize.h +10 -0
- data/lib/berns/berns.bundle +0 -0
- data/lib/berns/version.rb +1 -1
- metadata +17 -5
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: d21f3c4cd314834b56c13b9471da34320c996ecb526bcf13ea07728f8bf1d380
|
4
|
+
data.tar.gz: 8626b4f6b721d7f972d4436600d7264ca1e4cc4262af19a386ba95552f8bd944
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 06e239a9dceeeab18d0e5ec5255d6d587d4bfeb9c20ef3cd1605242da54de2b2ad448df8f60dbfb9b33c75ae54c08677cfc9b76c6e3b79f9a073913134a33621
|
7
|
+
data.tar.gz: c4d7991a61b3d2fce79b85bec27253ffefe380cbd7a4495934e8eff1ebec65e2e237e0a3f9e816f89754fd32ddcf819e1b859b88204fb33c1e2cf69029641fc0
|
data/{README.org → README.md}
RENAMED
@@ -1,117 +1,119 @@
|
|
1
|
-
|
1
|
+
# Berns
|
2
2
|
|
3
|
-
[[https://badge.fury.io/rb/berns]
|
4
|
-
[[https://github.com/evanleck/berns/actions/workflows/main.yml]
|
3
|
+
[![](https://badge.fury.io/rb/berns.svg)](https://badge.fury.io/rb/berns)
|
4
|
+
[![](https://github.com/evanleck/berns/actions/workflows/main.yml/badge.svg)](https://github.com/evanleck/berns/actions/workflows/main.yml)
|
5
5
|
|
6
6
|
A utility library for generating HTML strings.
|
7
7
|
|
8
|
-
|
8
|
+
## Installation
|
9
9
|
|
10
10
|
Add this line to your application's Gemfile:
|
11
11
|
|
12
|
-
|
12
|
+
``` ruby
|
13
13
|
gem 'berns'
|
14
|
-
|
14
|
+
```
|
15
15
|
|
16
16
|
And then execute:
|
17
17
|
|
18
|
-
|
18
|
+
``` sh
|
19
19
|
bundle
|
20
|
-
|
20
|
+
```
|
21
21
|
|
22
22
|
Or install it yourself as:
|
23
23
|
|
24
|
-
|
24
|
+
``` sh
|
25
25
|
gem install berns
|
26
|
-
|
26
|
+
```
|
27
27
|
|
28
|
-
|
28
|
+
## Usage
|
29
29
|
|
30
30
|
Note that all return string values will be UTF-8 encoded.
|
31
31
|
|
32
|
-
|
32
|
+
### `void(tag, attributes)`
|
33
33
|
|
34
|
-
The
|
34
|
+
The `void` method generates a void HTML element i.e. one without any content. It
|
35
35
|
takes either a symbol or a string and an optional hash of HTML attributes.
|
36
36
|
|
37
|
-
|
37
|
+
``` ruby
|
38
38
|
Berns.void('br') # => '<br>'
|
39
39
|
Berns.void('br', class: 'br-class') # => '<br class="br-class">'
|
40
|
-
|
40
|
+
```
|
41
41
|
|
42
|
-
|
42
|
+
### `element(tag, attributes) { content }`
|
43
43
|
|
44
|
-
The
|
44
|
+
The `element` method generates a standard HTML element i.e. one with optional
|
45
45
|
content. It takes either a symbol or a string, an optional hash of HTML
|
46
46
|
attributes, and an optional block of content. If provided, the block should
|
47
47
|
return a string.
|
48
48
|
|
49
|
-
|
49
|
+
``` ruby
|
50
50
|
Berns.element('div') # => '<div></div>'
|
51
51
|
Berns.element('div', class: 'div-class') # => '<div class="div-class"></div>'
|
52
52
|
Berns.element('div', class: 'div-class') { 'Content' } # => '<div class="div-class">Content</div>'
|
53
|
-
|
53
|
+
```
|
54
54
|
|
55
|
-
|
55
|
+
### `to_attribute(attribute, value)`
|
56
56
|
|
57
|
-
The
|
57
|
+
The `to_attribute` method generates an HTML attribute string. If the value is a
|
58
58
|
hash then the attribute is treated as a prefix.
|
59
59
|
|
60
|
-
|
60
|
+
``` ruby
|
61
61
|
Berns.to_attribute('class', 'my-class another-class') # => 'class="my-class another-class"'
|
62
62
|
Berns.to_attribute('data', { foo: 'bar' }) # => 'data-foo="bar"'
|
63
|
-
|
63
|
+
```
|
64
64
|
|
65
|
-
All attribute values are HTML-escaped using [
|
66
|
-
Kokubun.
|
65
|
+
All attribute values are HTML-escaped using [k0kubun/hescape](hescape) written
|
66
|
+
by Takashi Kokubun.
|
67
67
|
|
68
|
-
|
68
|
+
### `to_attributes(attributes)`
|
69
69
|
|
70
|
-
The
|
71
|
-
calling
|
70
|
+
The `to_attributes` method generates an HTML attribute string from a hash by
|
71
|
+
calling `to_attribute` for each key/value pair.
|
72
72
|
|
73
|
-
|
73
|
+
``` ruby
|
74
74
|
Berns.to_attributes({ 'data' => { foo: 'bar' }, 'class' => 'my-class another-class' }) # => 'data-foo="bar" class="my-class another-class"'
|
75
|
-
|
75
|
+
```
|
76
76
|
|
77
|
-
|
77
|
+
### `escape_html(string)`
|
78
78
|
|
79
|
-
The
|
80
|
-
written by Takashi Kokubun. As noted in the hescape
|
81
|
-
same as
|
79
|
+
The `escape_html` method escapes HTML entities in strings using
|
80
|
+
[k0kubun/hescape](hescape) written by Takashi Kokubun. As noted in the hescape
|
81
|
+
repository, it should be the same as `CGI.escapeHTML`.
|
82
82
|
|
83
|
-
|
83
|
+
``` ruby
|
84
84
|
Berns.escape_html('<"tag"') # => '<"tag"'
|
85
|
-
|
85
|
+
```
|
86
86
|
|
87
|
-
|
87
|
+
### `sanitize(string)`
|
88
88
|
|
89
|
-
The
|
89
|
+
The `sanitize` method strips HTML tags from strings.
|
90
90
|
|
91
|
-
|
91
|
+
``` ruby
|
92
92
|
Berns.sanitize('This <span>should be clean</span>') # => 'This should be clean'
|
93
|
-
|
93
|
+
```
|
94
94
|
|
95
95
|
Note that this is an extremely naive implementation of HTML sanitization that
|
96
96
|
literally just looks for "<" and ">" characters and removes the contents between
|
97
97
|
them. This should probably only be used on trusted strings.
|
98
98
|
|
99
|
-
|
99
|
+
### `build { content }`
|
100
100
|
|
101
|
-
The
|
101
|
+
The `build` method uses `Berns::Builder` to let you create HTML strings using a
|
102
|
+
DSL.
|
102
103
|
|
103
|
-
|
104
|
+
``` ruby
|
104
105
|
Berns.build { h1 { 'Heading' } } # => '<h1>Heading</h1>'
|
105
|
-
|
106
|
+
```
|
106
107
|
|
107
|
-
See below for more on
|
108
|
+
See below for more on `Berns::Builder`.
|
108
109
|
|
109
|
-
|
110
|
+
### `Berns::Builder` HTML DSL
|
110
111
|
|
111
|
-
Added in version 3.4.0 and heavily inspired by the likes of
|
112
|
-
|
112
|
+
Added in version 3.4.0 and heavily inspired by the likes of
|
113
|
+
[Papercraft](papercraft), [Markaby](markaby), and [Arbre](arbre), the
|
114
|
+
`Berns::Builder` class lets you create HTML strings using a DSL.
|
113
115
|
|
114
|
-
|
116
|
+
``` ruby
|
115
117
|
template = Berns::Builder.new do
|
116
118
|
h1 { 'Heading' }
|
117
119
|
p(class: 'paragraph') do
|
@@ -120,18 +122,18 @@ template = Berns::Builder.new do
|
|
120
122
|
b { 'Bold text here' }
|
121
123
|
end
|
122
124
|
end
|
123
|
-
|
125
|
+
```
|
124
126
|
|
125
|
-
Within the block provided to
|
126
|
-
void element method,
|
127
|
+
Within the block provided to `Berns::Builder.new` every standard element method,
|
128
|
+
void element method, `#element`, and `#void` are available as methods and each
|
127
129
|
time you use one of those methods the result is appended to an internal buffer.
|
128
|
-
In addition, the
|
129
|
-
|
130
|
+
In addition, the `#text` method appends HTML escaped text to the buffer and
|
131
|
+
`#raw` appends text to the buffer without modification.
|
130
132
|
|
131
|
-
The block provided to
|
133
|
+
The block provided to `Berns::Builder.new` can take both positional and keyword
|
132
134
|
arguments.
|
133
135
|
|
134
|
-
|
136
|
+
``` ruby
|
135
137
|
template = Berns::Builder.new do |content, title:|
|
136
138
|
h1 { title }
|
137
139
|
p(class: 'paragraph') { content }
|
@@ -144,13 +146,13 @@ template.call('Some text.', title: 'The title') # =>
|
|
144
146
|
# <p>
|
145
147
|
# Some text.
|
146
148
|
# </p>
|
147
|
-
|
149
|
+
```
|
148
150
|
|
149
|
-
Once initialized, the
|
151
|
+
Once initialized, the `#call` method will render the template to a string. Any
|
150
152
|
arguments, positional or keyword, are passed through as-is to the block provided
|
151
|
-
to
|
153
|
+
to `#new`.
|
152
154
|
|
153
|
-
|
155
|
+
``` ruby
|
154
156
|
string = template.call # =>
|
155
157
|
# <h1>
|
156
158
|
# Heading
|
@@ -161,12 +163,12 @@ string = template.call # =>
|
|
161
163
|
# Bold text here.
|
162
164
|
# </b>
|
163
165
|
# </p>
|
164
|
-
|
166
|
+
```
|
165
167
|
|
166
|
-
In addition to initializing a new instance of
|
167
|
-
construct and render a template to a string all at once with
|
168
|
+
In addition to initializing a new instance of `Berns::Builder`, you can
|
169
|
+
construct and render a template to a string all at once with `Berns.build`.
|
168
170
|
|
169
|
-
|
171
|
+
``` ruby
|
170
172
|
Berns.build do
|
171
173
|
h1 { 'Heading' }
|
172
174
|
p(class: 'paragraph') do
|
@@ -184,43 +186,41 @@ end # =>
|
|
184
186
|
# Bold text here.
|
185
187
|
# </b>
|
186
188
|
# </p>
|
187
|
-
|
189
|
+
```
|
188
190
|
|
189
|
-
|
190
|
-
*** Standard and void elements
|
191
|
+
### Standard and void elements
|
191
192
|
|
192
193
|
All standard and void HTML elements are defined as methods on Berns, so you can
|
193
|
-
create e.g. a link with
|
194
|
-
which are also available in the constant
|
194
|
+
create e.g. a link with `Berns.a`. Below is the full list of standard elements
|
195
|
+
which are also available in the constant `Berns::STANDARD` as an array of
|
195
196
|
symbols.
|
196
197
|
|
197
|
-
|
198
|
-
a abbr address article aside audio b bdi bdo blockquote body button
|
199
|
-
|
200
|
-
|
201
|
-
|
202
|
-
|
203
|
-
|
204
|
-
|
205
|
-
|
206
|
-
#+end_example
|
198
|
+
```
|
199
|
+
a abbr address article aside audio b bdi bdo blockquote body button canvas
|
200
|
+
caption cite code colgroup datalist dd del details dfn dialog div dl dt em
|
201
|
+
fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6 head header html i
|
202
|
+
iframe ins kbd label legend li main map mark menu meter nav noscript object ol
|
203
|
+
optgroup option output p picture pre progress q rp rt ruby s samp script section
|
204
|
+
select small span strong style sub summary table tbody td template textarea
|
205
|
+
tfoot th thead time title tr u ul var video
|
206
|
+
```
|
207
207
|
|
208
208
|
Below is the full list of void elements that are defined as singleton methods on
|
209
|
-
Berns which are also available in the constant
|
209
|
+
Berns which are also available in the constant `Berns::VOID` as an array of
|
210
210
|
symbols.
|
211
211
|
|
212
|
-
|
212
|
+
```
|
213
213
|
area base br col embed hr img input link menuitem meta param source track wbr
|
214
|
-
|
214
|
+
```
|
215
215
|
|
216
|
-
|
216
|
+
## Performance
|
217
217
|
|
218
218
|
Berns 3 was a total rewrite from a pure Ruby implementation to one powered by a
|
219
219
|
C extension. That rewrite is about three times faster than the pure Ruby
|
220
|
-
implementation used in version 2. See the file
|
221
|
-
benchmark code.
|
220
|
+
implementation used in version 2. See the file
|
221
|
+
[benchmarks/performance.rb](benchmarks/performance.rb) for the benchmark code.
|
222
222
|
|
223
|
-
|
223
|
+
``` example
|
224
224
|
Warming up --------------------------------------
|
225
225
|
ruby 27.521k i/100ms
|
226
226
|
c-ext 74.915k i/100ms
|
@@ -231,9 +231,17 @@ Calculating -------------------------------------
|
|
231
231
|
Comparison:
|
232
232
|
c-ext: 813113.3 i/s
|
233
233
|
ruby: 275913.5 i/s - 2.95x (± 0.00) slower
|
234
|
-
|
234
|
+
```
|
235
|
+
|
236
|
+
## Trivia
|
235
237
|
|
236
|
-
|
238
|
+
The name "Berns" is taken from the name of [the inventor of HTML](html), [Sir
|
239
|
+
Tim Berners-Lee](tim).
|
237
240
|
|
238
|
-
|
239
|
-
[
|
241
|
+
<!-- Links -->
|
242
|
+
[arbre]: https://github.com/activeadmin/arbre
|
243
|
+
[hescape]: https://github.com/k0kubun/hescape
|
244
|
+
[html]: https://en.wikipedia.org/wiki/HTML#Development
|
245
|
+
[markaby]: https://github.com/markaby/markaby
|
246
|
+
[papercraft]: https://github.com/digital-fabric/papercraft
|
247
|
+
[tim]: https://en.wikipedia.org/wiki/Tim_Berners-Lee
|