ox-builder 0.1.0 → 1.0.1
Sign up to get free protection for your applications and to get access to all the features.
- 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
|
|