ox-builder 0.1.0 → 1.0.1
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 +8 -8
- data/.travis.yml +7 -0
- data/CHANGELOG.md +4 -0
- data/Gemfile +0 -2
- data/README.md +197 -8
- data/benchmarks/data/countries.yml +2503 -0
- data/benchmarks/huge.rb +25 -0
- data/benchmarks/medium.rb +27 -0
- data/benchmarks/runner.rb +6 -0
- data/benchmarks/small.rb +20 -0
- data/benchmarks/templates/large.builder +20 -0
- data/benchmarks/templates/large.ox +20 -0
- data/benchmarks/templates/small.builder +7 -0
- data/benchmarks/templates/small.ox +7 -0
- data/bin/console +4 -0
- data/lib/ox/builder/action_view/template_handler.rb +21 -0
- data/lib/ox/builder/dsl.rb +42 -0
- data/lib/ox/builder/factory.rb +39 -0
- data/lib/ox/builder/fallback_context_proxy.rb +30 -0
- data/lib/ox/builder/version.rb +1 -1
- data/lib/ox/builder.rb +29 -2
- data/lib/tilt/ox_builder_template.rb +28 -0
- data/ox-builder.gemspec +9 -1
- metadata +116 -3
checksums.yaml
CHANGED
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
---
|
|
2
2
|
!binary "U0hBMQ==":
|
|
3
3
|
metadata.gz: !binary |-
|
|
4
|
-
|
|
4
|
+
ZTA5YzU5MzYxYTZlMDQ5YjE0NWU4ODhlNTc2MDI5OTNmODllZTdjYg==
|
|
5
5
|
data.tar.gz: !binary |-
|
|
6
|
-
|
|
6
|
+
NzYzOGQ4ZjAwZjdmMTVjMjY3ZWZmZTFjYmQxNTQ1MDhhNWFiNzY1Nw==
|
|
7
7
|
SHA512:
|
|
8
8
|
metadata.gz: !binary |-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
YzZhYzU4YjUyMDllYTZmYmZhMGFmNzE2N2I5ZjA5NDFlNDc4ZmZjM2MyZWVi
|
|
10
|
+
NDMxZTc2ZmYyOTNkY2FiMDUyZTBjOGE1Y2NjYmM1YWZkMTlmYjk5MWEyODM3
|
|
11
|
+
N2E2NWI4ZjE1NDYxOGQyNzNmZjZjOTI4NTgwMjBhZjg0YWY2NTI=
|
|
12
12
|
data.tar.gz: !binary |-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
MzFlNjkxN2Q0NzQ1YTM3ZThlOWY1ZTA0ZWIyNWE5NjIzNTEzNDcyZGQ0ZjYx
|
|
14
|
+
OGQ2ZjYyYjJlYjVlZWQ1ZGJlZDk2YWU3MTgyOWQwN2NjNjgwZTZiNjUzMmNj
|
|
15
|
+
MGM2NDUwNzY3NGMyMzNhZDExMjQzZjEyZjI0M2Q5NzJmYjk4OTc=
|
data/.travis.yml
CHANGED
data/CHANGELOG.md
ADDED
data/Gemfile
CHANGED
data/README.md
CHANGED
|
@@ -1,8 +1,202 @@
|
|
|
1
1
|
# Ox::Builder
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://travis-ci.org/dvandersluis/ox-builder)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Ox::Builder provides a DSL for quickly building XML documents using the [`ox`](https://github.com/ohler55/ox) gem.
|
|
6
|
+
It is intended to be a practically plug-in replacement for [`builder`](https://rubygems.org/gems/builder) gem for
|
|
7
|
+
constructing XML documents.
|
|
8
|
+
|
|
9
|
+
The DSL verbs are meant to map closely to those provided by `builder` so that an existing builder template can be
|
|
10
|
+
ported to use `Ox::Builder` with minimum effort.
|
|
11
|
+
|
|
12
|
+
In addition to providing a DSL for `ox`, this library provides template handlers for `action_view` and `tilt`,
|
|
13
|
+
so that a template file can be rendered in Rails and/or via Tilt. The template handlers are activated automatically
|
|
14
|
+
when rendering a file named `filename.ox`.
|
|
15
|
+
|
|
16
|
+
## Usage
|
|
17
|
+
|
|
18
|
+
An XML document can be generated by passing a block to `Ox::Builder.build`:
|
|
19
|
+
|
|
20
|
+
<table>
|
|
21
|
+
<tr><th>Ruby Code:</th><th>Generated XML:</th></tr>
|
|
22
|
+
<tr>
|
|
23
|
+
<td>
|
|
24
|
+
<pre lang="ruby">
|
|
25
|
+
doc = Ox::Builder.build do
|
|
26
|
+
instruct!
|
|
27
|
+
|
|
28
|
+
person id: 123 do
|
|
29
|
+
name { cdata!('John Smith') }
|
|
30
|
+
age 37
|
|
31
|
+
nationality 'Canadian'
|
|
32
|
+
end
|
|
33
|
+
end
|
|
34
|
+
</pre>
|
|
35
|
+
</td>
|
|
36
|
+
<td>
|
|
37
|
+
<pre lang="xml">
|
|
38
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
39
|
+
<person id="123">
|
|
40
|
+
<name>
|
|
41
|
+
<![CDATA[John Smith]]>
|
|
42
|
+
</name>
|
|
43
|
+
<age>37</age>
|
|
44
|
+
<nationality>Canadian</nationality>
|
|
45
|
+
</person>
|
|
46
|
+
</pre>
|
|
47
|
+
</td>
|
|
48
|
+
</tr>
|
|
49
|
+
</table>
|
|
50
|
+
|
|
51
|
+
### Methods
|
|
52
|
+
|
|
53
|
+
The following methods are available within the `Ox::Builder.build` DSL:
|
|
54
|
+
|
|
55
|
+
#### `instruct!(name = :xml, attributes = { version: '1.0', encoding: 'UTF-8' })`
|
|
56
|
+
|
|
57
|
+
Creates an XML processing instruction. The name or attributes can be overridden.
|
|
58
|
+
|
|
59
|
+
| Ruby Code:| Generated XML: |
|
|
60
|
+
|-----------|----------------|
|
|
61
|
+
| <pre lang="ruby">instruct!</pre> | <pre lang="xml"><?xml version="1.0" encoding="UTF-8"?></pre> |
|
|
62
|
+
| <pre lang="ruby">instruct! version: 2.0</pre>| <pre lang="xml"><?xml version="2.0"></pre> |
|
|
63
|
+
| <pre lang="ruby">instruct! 'xml-stylesheet', type: 'text/xsl', href: 'style.xsl'</pre> | <pre lang="xml"><?xml-stylesheet type="text/xsl" href="style.xsl"?></pre> |
|
|
64
|
+
|
|
65
|
+
#### `tag!(name, content = nil, attributes = {})`
|
|
66
|
+
|
|
67
|
+
Creates an arbitrary XML node with a given name and any attributes. If content is passed in, it will be inserted into the tag; otherwise the tag will be empty. A block can be given to create nested tags (and there is no limit to how deep nesting can be).
|
|
68
|
+
|
|
69
|
+
If passing content to a tag, any object can be given but note that `to_s` will be called.
|
|
70
|
+
|
|
71
|
+
Nodes can also be created dynamically by name (assuming the name is a valid ruby method name). You can also append `!` to the name in case there is a conflict with an existing method (see examples below).
|
|
72
|
+
|
|
73
|
+
| Ruby Code:| Generated XML: |
|
|
74
|
+
|-----------|----------------|
|
|
75
|
+
| <pre lang="ruby">tag! :person</pre> | <pre lang="xml"><person/></pre> |
|
|
76
|
+
| <pre lang="ruby">tag! :person, 'John Smith', id: '123'</pre>|<pre lang="xml"><person id="123">John Smith</person></pre>|
|
|
77
|
+
| <pre lang="ruby">person 'John Smith', id: '123'</pre> | <pre lang="xml"><person id="123">John Smith</person></pre> |
|
|
78
|
+
| <pre lang="ruby">person! 'John Smith', id: '123'</pre> | <pre lang="xml"><person id="123">John Smith</person></pre> |
|
|
79
|
+
| <pre lang="ruby">person do first_name, 'John' last_name, 'Smith' address do country, 'Canada' state, 'Ontario' end end</pre> | <pre lang="xml"><person> <first_name>John</first_name> <last_name>Smith</last_name> <address> <country>Canada</country> <state>Ontario</state> </address> </person> </pre> |
|
|
80
|
+
|
|
81
|
+
#### `comment!(text)`
|
|
82
|
+
|
|
83
|
+
Creates an XML comment with the given text.
|
|
84
|
+
|
|
85
|
+
| Ruby Code: | Generated XML: |
|
|
86
|
+
|------------|----------------|
|
|
87
|
+
| <pre lang="ruby">comment!('comment goes here')</pre> | <pre lang="xml"><!-- comment goes here --></pre> |
|
|
88
|
+
|
|
89
|
+
#### `doctype!(text)`
|
|
90
|
+
|
|
91
|
+
Creates a doctype element with the given text.
|
|
92
|
+
|
|
93
|
+
| Ruby Code: | Generated XML: |
|
|
94
|
+
|------------|----------------|
|
|
95
|
+
| <pre lang="ruby">doctype!('html')</pre> | <pre lang="xml"><!DOCTYPE html ></pre> |
|
|
96
|
+
|
|
97
|
+
#### `cdata!(text)`
|
|
98
|
+
|
|
99
|
+
Create a CDATA node (ie. text wrapped in `<![CDATA[]]>`)
|
|
100
|
+
|
|
101
|
+
| Ruby Code: | Generated XML: |
|
|
102
|
+
|------------|----------------|
|
|
103
|
+
| <pre lang="ruby">cdata! 'John Smith'</pre> | <pre lang="xml"><![CDATA[John Smith]]></pre> |
|
|
104
|
+
| <pre lang="ruby">tag! :name do cdata!('John Smith') end</pre> | <pre lang="xml"><name> <![CDATA[John Smith]]> <name></pre> |
|
|
105
|
+
|
|
106
|
+
### Using in a Rails view
|
|
107
|
+
|
|
108
|
+
Any view file with the extension `.ox` or `.xml.ox` will be picked up by `Ox::Builder` and rendered as an XML file, with MIME type `application/xml`. There is no setup needed to get this to work. The view should not contain `Ox::Builder.build`, but rather the contents of the block that you would pass to it.
|
|
109
|
+
|
|
110
|
+
```ruby
|
|
111
|
+
# test.xml.ox
|
|
112
|
+
instruct!
|
|
113
|
+
|
|
114
|
+
person id: 123 do
|
|
115
|
+
name { cdata!('John Smith') }
|
|
116
|
+
age 37
|
|
117
|
+
nationality 'Canadian'
|
|
118
|
+
end
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Migrating from builder
|
|
122
|
+
|
|
123
|
+
Using `Ox::Builder` instead of `Builder` is straightforward:
|
|
124
|
+
|
|
125
|
+
1. Rename the view file from `filename.builder` to `filename.ox`.
|
|
126
|
+
2. Remove any block parameters from the view code. As well, any code where the block parameter was used as a message receiver, use an implicit receiver instead.
|
|
127
|
+
3. Remove any instances of the special `xml` receiver.
|
|
128
|
+
4. `declare!` is not currently supported as it's not implemented in `ox`.
|
|
129
|
+
|
|
130
|
+
Therefore, the following template:
|
|
131
|
+
|
|
132
|
+
```ruby
|
|
133
|
+
# filename.builder
|
|
134
|
+
xml.people do
|
|
135
|
+
xml.person do |person|
|
|
136
|
+
person.name { xml.cdata! 'John Smith' }
|
|
137
|
+
person.age 37
|
|
138
|
+
end
|
|
139
|
+
end
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
would be converted to:
|
|
143
|
+
|
|
144
|
+
```ruby
|
|
145
|
+
# filename.ox
|
|
146
|
+
people do
|
|
147
|
+
person do
|
|
148
|
+
name { cdata! 'John Smith' }
|
|
149
|
+
age 37
|
|
150
|
+
end
|
|
151
|
+
end
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
## Benchmarks
|
|
155
|
+
|
|
156
|
+
Benchmarks which compare `Ox::Builder` to `Builder` can be found in `benchmarks/`. There are three benchmarks, for
|
|
157
|
+
various XML output sizes.
|
|
158
|
+
|
|
159
|
+
### Small file (~170 bytes)
|
|
160
|
+
```
|
|
161
|
+
Calculating -------------------------------------
|
|
162
|
+
builder 412.000 i/100ms
|
|
163
|
+
ox 640.000 i/100ms
|
|
164
|
+
-------------------------------------------------
|
|
165
|
+
builder 4.230k (± 6.7%) i/s - 42.436k
|
|
166
|
+
ox 10.413k (±18.5%) i/s - 100.480k
|
|
167
|
+
|
|
168
|
+
Comparison:
|
|
169
|
+
ox: 10413.5 i/s
|
|
170
|
+
builder: 4230.5 i/s - 2.46x slower
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
### Medium file (107K)
|
|
174
|
+
```
|
|
175
|
+
Calculating -------------------------------------
|
|
176
|
+
builder 1.000 i/100ms
|
|
177
|
+
ox 2.000 i/100ms
|
|
178
|
+
-------------------------------------------------
|
|
179
|
+
builder 11.153 (± 9.0%) i/s - 223.000
|
|
180
|
+
ox 23.454 (± 8.5%) i/s - 468.000
|
|
181
|
+
|
|
182
|
+
Comparison:
|
|
183
|
+
ox: 23.5 i/s
|
|
184
|
+
builder: 11.2 i/s - 2.10x slower
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### Huge file (11M)
|
|
188
|
+
```
|
|
189
|
+
Calculating -------------------------------------
|
|
190
|
+
builder 1.000 i/100ms
|
|
191
|
+
ox 1.000 i/100ms
|
|
192
|
+
-------------------------------------------------
|
|
193
|
+
builder 0.117 (± 0.0%) i/s - 8.000 in 68.435529s
|
|
194
|
+
ox 0.221 (± 0.0%) i/s - 14.000 in 63.819146s
|
|
195
|
+
|
|
196
|
+
Comparison:
|
|
197
|
+
ox: 0.2 i/s
|
|
198
|
+
builder: 0.1 i/s - 1.88x slower
|
|
199
|
+
```
|
|
6
200
|
|
|
7
201
|
## Installation
|
|
8
202
|
|
|
@@ -20,10 +214,6 @@ Or install it yourself as:
|
|
|
20
214
|
|
|
21
215
|
$ gem install ox-builder
|
|
22
216
|
|
|
23
|
-
## Usage
|
|
24
|
-
|
|
25
|
-
TODO: Write usage instructions here
|
|
26
|
-
|
|
27
217
|
## Development
|
|
28
218
|
|
|
29
219
|
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
|
|
@@ -32,8 +222,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
|
|
|
32
222
|
|
|
33
223
|
## Contributing
|
|
34
224
|
|
|
35
|
-
Bug reports and pull requests are welcome on GitHub at https://github.com/
|
|
36
|
-
|
|
225
|
+
Bug reports and pull requests are welcome on GitHub at https://github.com/dvandersluis/ox-builder.
|
|
37
226
|
|
|
38
227
|
## License
|
|
39
228
|
|