blobject 0.3.3 → 0.3.7

Sign up to get free protection for your applications and to get access to all the features.
Files changed (25) hide show
  1. data/.gitignore +1 -0
  2. data/Gemfile.lock +1 -1
  3. data/README.markdown +67 -13
  4. data/{blob_defn.png → assets/blob_defn.png} +0 -0
  5. data/{blobject.png → assets/blobject.png} +0 -0
  6. data/doc/Blobject.html +1393 -0
  7. data/doc/_index.html +110 -0
  8. data/doc/class_list.html +53 -0
  9. data/doc/css/common.css +1 -0
  10. data/doc/css/full_list.css +57 -0
  11. data/doc/css/style.css +328 -0
  12. data/doc/file.README.html +269 -0
  13. data/doc/file_list.html +55 -0
  14. data/doc/frames.html +28 -0
  15. data/doc/index.html +269 -0
  16. data/doc/js/app.js +208 -0
  17. data/doc/js/full_list.js +173 -0
  18. data/doc/js/jquery.js +4 -0
  19. data/doc/method_list.html +172 -0
  20. data/doc/top-level-namespace.html +112 -0
  21. data/lib/blobject/version.rb +2 -2
  22. data/lib/blobject.rb +73 -61
  23. data/spec/blobject_spec.rb +50 -6
  24. metadata +28 -13
  25. data/README.md_ +0 -145
data/doc/file.README.html ADDED
@@ -0,0 +1,269 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4
+ <head>
5
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6
+ <title>
7
+ File: README
8
+
9
+ &mdash; Documentation by YARD 0.8.1
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
16
+
17
+ <script type="text/javascript" charset="utf-8">
18
+ hasFrames = window.top.frames.main ? true : false;
19
+ relpath = '';
20
+ framesUrl = "frames.html#!" + escape(window.location.href);
21
+ </script>
22
+
23
+
24
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
25
+
26
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
27
+
28
+
29
+ </head>
30
+ <body>
31
+ <div id="header">
32
+ <div id="menu">
33
+
34
+ <a href="_index.html">Index</a> &raquo;
35
+ <span class="title">File: README</span>
36
+
37
+
38
+ <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
39
+ </div>
40
+
41
+ <div id="search">
42
+
43
+ <a class="full_list_link" id="class_list_link"
44
+ href="class_list.html">
45
+ Class List
46
+ </a>
47
+
48
+ <a class="full_list_link" id="method_list_link"
49
+ href="method_list.html">
50
+ Method List
51
+ </a>
52
+
53
+ <a class="full_list_link" id="file_list_link"
54
+ href="file_list.html">
55
+ File List
56
+ </a>
57
+
58
+ </div>
59
+ <div class="clear"></div>
60
+ </div>
61
+
62
+ <iframe id="search_frame"></iframe>
63
+
64
+ <div id="content"><div id='filecontents'><p><img src="https://github.com/sjltaylor/blobject/raw/master/blobject.png" alt="">
65
+ <img src="https://github.com/sjltaylor/blobject/raw/master/blob_defn.png" alt=""></p>
66
+
67
+ <pre class="code ruby"><code># Wrapper around a hash to provide arbitrarily nested object style access to attributes
68
+ class Blobject
69
+ </code></pre>
70
+
71
+ <h1>LINK TO FULL RDOCS</h1>
72
+
73
+ <h1>LINK TO NARRATIVE</h1>
74
+
75
+ <h2>About</h2>
76
+
77
+ <p>A Blobject is a thin wrapper around a hash</p>
78
+
79
+ <p>They are <em>freeform</em> which means you can do this...</p>
80
+
81
+ <pre class="code ruby"><code><span class='id identifier rubyid_data'>data</span> <span class='op'>=</span> <span class='const'>Blobject</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
82
+
83
+ <span class='id identifier rubyid_data'>data</span><span class='period'>.</span><span class='id identifier rubyid_name'>name</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Johnny</span><span class='tstring_end'>&quot;</span></span>
84
+ <span class='id identifier rubyid_data'>data</span><span class='period'>.</span><span class='id identifier rubyid_number'>number</span> <span class='op'>=</span> <span class='int'>316</span>
85
+ </code></pre>
86
+
87
+ <p>like an OpenStruct, the members are not predefined attributes</p>
88
+
89
+ <p>unlike OpenStruct, Blobjects can be arbitrarily <em>complex</em> which means you can do this...</p>
90
+
91
+ <pre class="code ruby"><code><span class='id identifier rubyid_data'>data</span> <span class='op'>=</span> <span class='const'>Blobject</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
92
+
93
+ <span class='id identifier rubyid_data'>data</span><span class='period'>.</span><span class='id identifier rubyid_name'>name</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Johnny</span><span class='tstring_end'>&quot;</span></span>
94
+ <span class='id identifier rubyid_data'>data</span><span class='period'>.</span><span class='id identifier rubyid_name'>name</span><span class='period'>.</span><span class='id identifier rubyid_surname'>surname</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Begood</span><span class='tstring_end'>&quot;</span></span>
95
+
96
+ <span class='id identifier rubyid_data'>data</span><span class='period'>.</span><span class='id identifier rubyid_my'>my</span><span class='period'>.</span><span class='id identifier rubyid_object'>object</span><span class='period'>.</span><span class='id identifier rubyid_with'>with</span><span class='period'>.</span><span class='id identifier rubyid_deep'>deep</span><span class='period'>.</span><span class='id identifier rubyid_nested'>nested</span><span class='period'>.</span><span class='id identifier rubyid_members'>members</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>happy place</span><span class='tstring_end'>&quot;</span></span>
97
+ </code></pre>
98
+
99
+ <p>or assign hashes which become nested blobjects</p>
100
+
101
+ <p>data.details = { code: 41239, ref: &quot;#22322&quot; }</p>
102
+
103
+ <p>data.details.code
104
+ =&gt; 41239
105
+ data.details.ref
106
+ =&gt; &quot;#22322&quot;</p>
107
+
108
+ <p>You can test to see if a member is defined:</p>
109
+
110
+ <pre class="code ruby"><code>data.something_here?
111
+ =&gt; false
112
+ </code></pre>
113
+
114
+ <h2>Used for Configuration</h2>
115
+
116
+ <p>Consider a configuration object which contains credentials for a third-party api.</p>
117
+
118
+ <pre class="code ruby"><code>third_party_api:
119
+ secret_key: 'S3CR3T'
120
+ endpoint: 'http://services.thirdparty.net/api'
121
+ </code></pre>
122
+
123
+ <p>With a hash, usage looks like this:</p>
124
+
125
+ <pre class="code ruby"><code><span class='const'>CONFIG</span><span class='lbracket'>[</span><span class='symbol'>:third_party_api</span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='symbol'>:endpoint</span><span class='rbracket'>]</span>
126
+ </code></pre>
127
+
128
+ <p>With a Blobject, usage looks like this:</p>
129
+
130
+ <pre class="code ruby"><code><span class='const'>CONFIG</span><span class='period'>.</span><span class='id identifier rubyid_third_party_api'>third_party_api</span><span class='period'>.</span><span class='id identifier rubyid_endpoint'>endpoint</span>
131
+ </code></pre>
132
+
133
+ <p>References to the endpoint are scattered throughout the codebase, then one day the endpoint is separated into its constituent parts to aide in testing and staging.</p>
134
+
135
+ <pre class="code ruby"><code>third_party_api:
136
+ secret_key: 'S3CR3T'
137
+ protocol: 'http'
138
+ hostname: 'services.thirdparty.net'
139
+ path: '/api'
140
+ </code></pre>
141
+
142
+ <p>Using a blobject we can easily avoid having to refactor our code...</p>
143
+
144
+ <pre class="code ruby"><code><span class='const'>CONFIG</span> <span class='op'>=</span> <span class='const'>Blobject</span><span class='period'>.</span><span class='id identifier rubyid_from_yaml'>from_yaml</span><span class='lparen'>(</span><span class='const'>File</span><span class='period'>.</span><span class='id identifier rubyid_read'>read</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>./config.yml</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='rparen'>)</span>
145
+
146
+ <span class='const'>CONFIG</span><span class='period'>.</span><span class='id identifier rubyid_third_party_api'>third_party_api</span><span class='period'>.</span><span class='id identifier rubyid_instance_eval'>instance_eval</span> <span class='kw'>do</span>
147
+ <span class='kw'>def</span> <span class='id identifier rubyid_endpoint'>endpoint</span>
148
+ <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_protocol'>protocol</span><span class='rbrace'>}</span><span class='tstring_content'>://</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_hostname'>hostname</span><span class='rbrace'>}</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_path'>path</span><span class='rbrace'>}</span><span class='tstring_end'>&quot;</span></span>
149
+ <span class='kw'>end</span>
150
+ <span class='kw'>end</span>
151
+ </code></pre>
152
+
153
+ <h2>Serializing &amp; Deserializing</h2>
154
+
155
+ <p>Blobjects can be used to easily build complex payloads.</p>
156
+
157
+ <pre class="code ruby"><code>person = Blobject.new
158
+
159
+ person.name = first: 'David', last: 'Platt'
160
+
161
+ person.address.tap do |address|
162
+ address.street = &quot;...&quot;
163
+ address.city = &quot;...&quot;
164
+ end
165
+
166
+ person.next_of_kin.address.city = '...'
167
+
168
+ # after the payload is constructed it can be frozen to prevent modification
169
+ person.freeze
170
+ </code></pre>
171
+
172
+ <p>A nice pattern in most cases is to use an initialization block...</p>
173
+
174
+ <pre class="code ruby"><code>Blobject.new optional_hash_of_initial_data do |b|
175
+ b.name = ...
176
+ end.freeze
177
+ </code></pre>
178
+
179
+ <p>Suppose you receive a payload from an api which may or may not contain an address and city...</p>
180
+
181
+ <pre class="code ruby"><code>payload = Blobject.from_json request[:payload]
182
+
183
+ # if the payload does have an address...
184
+ city = payload.address.city
185
+ =&gt; 'Liverpool'
186
+
187
+ # if the payload does not have an address or city
188
+ city = payload.address.city
189
+ =&gt; nil
190
+ # rather than request[:payload][:address][:city] which would raise
191
+ # NoMethodError: undefined method `[]' for nil:NilClass
192
+ </code></pre>
193
+
194
+ <p>Also, you don&#39;t need to concern yourself whether hash keys are symbols or strings.</p>
195
+
196
+ <h2>Performance</h2>
197
+
198
+ <p>The runtime performance of something as low level as blobject deserves consideration.</p>
199
+
200
+ <p>see <code>/benchmarks</code></p>
201
+
202
+ <pre class="code ruby"><code>ITERATIONS: 1000000
203
+
204
+
205
+ BENCHMARK: assign
206
+
207
+ user system total real
208
+ Object: 0.190000 0.000000 0.190000 ( 0.229685)
209
+ Hash: 0.220000 0.000000 0.220000 ( 0.230500)
210
+ OpenStruct: 0.520000 0.000000 0.520000 ( 0.529861)
211
+ Blobject: 0.790000 0.000000 0.790000 ( 0.808610)
212
+ Hashie: 8.270000 0.030000 8.300000 ( 9.291184)
213
+
214
+
215
+ BENCHMARK: read
216
+
217
+ user system total real
218
+ Hash: 0.160000 0.000000 0.160000 ( 0.165141)
219
+ Object: 0.170000 0.000000 0.170000 ( 0.170228)
220
+ OpenStruct: 0.340000 0.000000 0.340000 ( 0.342430)
221
+ Blobject: 0.410000 0.000000 0.410000 ( 0.410574)
222
+ Hashie: 1.880000 0.000000 1.880000 ( 1.921718)
223
+ </code></pre>
224
+
225
+ <p>Host CPU: 2.13GHz Core2</p>
226
+
227
+ <p>A Blobject is three-four times slower than an equivalent Object.</p>
228
+
229
+ <h2>Limitations</h2>
230
+
231
+ <ul>
232
+ <li>will not work with basic objects unless #class and #freeze are implemented</li>
233
+ <li>cyclic blobject graphs result in infinite recursion StackOverflow</li>
234
+ <li>Ruby 1.8.7 is not supported. Testing rubies...
235
+
236
+ <ul>
237
+ <li>mri 1.9.3-p194</li>
238
+ <li>mri 1.9.2-p290</li>
239
+ </ul></li>
240
+ </ul>
241
+
242
+ <h2>Disclaimer</h2>
243
+
244
+ <p>Blobject provides a convenient way to create large freeform data structures; With great power comes great blah blah blah blah...</p>
245
+
246
+ <h2>License</h2>
247
+
248
+ <p>(The MIT License)</p>
249
+
250
+ <p>Copyright © 2012 <a href="http://sjltaylor.com/">Sam Taylor</a></p>
251
+
252
+ <p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p>
253
+
254
+ <p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p>
255
+
256
+ <p>THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
257
+
258
+ <p>Copyright (c) 2012 Sam Taylor. See LICENSE.txt for
259
+ further details.</p>
260
+ </div></div>
261
+
262
+ <div id="footer">
263
+ Generated on Thu Jun 7 00:25:31 2012 by
264
+ <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
265
+ 0.8.1 (ruby-1.9.3).
266
+ </div>
267
+
268
+ </body>
269
+ </html>
data/doc/file_list.html ADDED
@@ -0,0 +1,55 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
+ <html>
4
+ <head>
5
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6
+
7
+ <link rel="stylesheet" href="css/full_list.css" type="text/css" media="screen" charset="utf-8" />
8
+
9
+ <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
10
+
11
+
12
+
13
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
14
+
15
+ <script type="text/javascript" charset="utf-8" src="js/full_list.js"></script>
16
+
17
+
18
+ <base id="base_target" target="_parent" />
19
+ </head>
20
+ <body>
21
+ <script type="text/javascript" charset="utf-8">
22
+ if (window.top.frames.main) {
23
+ document.getElementById('base_target').target = 'main';
24
+ document.body.className = 'frames';
25
+ }
26
+ </script>
27
+ <div id="content">
28
+ <h1 id="full_list_header">File List</h1>
29
+ <div id="nav">
30
+
31
+ <span><a target="_self" href="class_list.html">
32
+ Classes
33
+ </a></span>
34
+
35
+ <span><a target="_self" href="method_list.html">
36
+ Methods
37
+ </a></span>
38
+
39
+ <span><a target="_self" href="file_list.html">
40
+ Files
41
+ </a></span>
42
+
43
+ </div>
44
+ <div id="search">Search: <input type="text" /></div>
45
+
46
+ <ul id="full_list" class="file">
47
+
48
+
49
+ <li class="r1"><a href="index.html" title="README">README</a></li>
50
+
51
+
52
+ </ul>
53
+ </div>
54
+ </body>
55
+ </html>
data/doc/frames.html ADDED
@@ -0,0 +1,28 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN"
2
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
3
+
4
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5
+ <head>
6
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
7
+ <title>Documentation by YARD 0.8.1</title>
8
+ </head>
9
+ <script type="text/javascript" charset="utf-8">
10
+ window.onload = function() {
11
+ var match = window.location.hash.match(/^#!(.+)/);
12
+ var name = 'index.html';
13
+ if (match) {
14
+ name = unescape(match[1]);
15
+ }
16
+ document.writeln('<frameset cols="20%,*">' +
17
+ '<frame name="list" src="class_list.html" />' +
18
+ '<frame name="main" src="' + name + '" />' +
19
+ '</frameset>');
20
+ }
21
+ </script>
22
+ <noscript>
23
+ <frameset cols="20%,*">
24
+ <frame name="list" src="class_list.html" />
25
+ <frame name="main" src="index.html" />
26
+ </frameset>
27
+ </noscript>
28
+ </html>
data/doc/index.html ADDED
@@ -0,0 +1,269 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4
+ <head>
5
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6
+ <title>
7
+ File: README
8
+
9
+ &mdash; Documentation by YARD 0.8.1
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
16
+
17
+ <script type="text/javascript" charset="utf-8">
18
+ hasFrames = window.top.frames.main ? true : false;
19
+ relpath = '';
20
+ framesUrl = "frames.html#!" + escape(window.location.href);
21
+ </script>
22
+
23
+
24
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
25
+
26
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
27
+
28
+
29
+ </head>
30
+ <body>
31
+ <div id="header">
32
+ <div id="menu">
33
+
34
+ <a href="_index.html">Index</a> &raquo;
35
+ <span class="title">File: README</span>
36
+
37
+
38
+ <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
39
+ </div>
40
+
41
+ <div id="search">
42
+
43
+ <a class="full_list_link" id="class_list_link"
44
+ href="class_list.html">
45
+ Class List
46
+ </a>
47
+
48
+ <a class="full_list_link" id="method_list_link"
49
+ href="method_list.html">
50
+ Method List
51
+ </a>
52
+
53
+ <a class="full_list_link" id="file_list_link"
54
+ href="file_list.html">
55
+ File List
56
+ </a>
57
+
58
+ </div>
59
+ <div class="clear"></div>
60
+ </div>
61
+
62
+ <iframe id="search_frame"></iframe>
63
+
64
+ <div id="content"><div id='filecontents'><p><img src="https://github.com/sjltaylor/blobject/raw/master/blobject.png" alt="">
65
+ <img src="https://github.com/sjltaylor/blobject/raw/master/blob_defn.png" alt=""></p>
66
+
67
+ <pre class="code ruby"><code># Wrapper around a hash to provide arbitrarily nested object style access to attributes
68
+ class Blobject
69
+ </code></pre>
70
+
71
+ <h1>LINK TO FULL RDOCS</h1>
72
+
73
+ <h1>LINK TO NARRATIVE</h1>
74
+
75
+ <h2>About</h2>
76
+
77
+ <p>A Blobject is a thin wrapper around a hash</p>
78
+
79
+ <p>They are <em>freeform</em> which means you can do this...</p>
80
+
81
+ <pre class="code ruby"><code><span class='id identifier rubyid_data'>data</span> <span class='op'>=</span> <span class='const'>Blobject</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
82
+
83
+ <span class='id identifier rubyid_data'>data</span><span class='period'>.</span><span class='id identifier rubyid_name'>name</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Johnny</span><span class='tstring_end'>&quot;</span></span>
84
+ <span class='id identifier rubyid_data'>data</span><span class='period'>.</span><span class='id identifier rubyid_number'>number</span> <span class='op'>=</span> <span class='int'>316</span>
85
+ </code></pre>
86
+
87
+ <p>like an OpenStruct, the members are not predefined attributes</p>
88
+
89
+ <p>unlike OpenStruct, Blobjects can be arbitrarily <em>complex</em> which means you can do this...</p>
90
+
91
+ <pre class="code ruby"><code><span class='id identifier rubyid_data'>data</span> <span class='op'>=</span> <span class='const'>Blobject</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
92
+
93
+ <span class='id identifier rubyid_data'>data</span><span class='period'>.</span><span class='id identifier rubyid_name'>name</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Johnny</span><span class='tstring_end'>&quot;</span></span>
94
+ <span class='id identifier rubyid_data'>data</span><span class='period'>.</span><span class='id identifier rubyid_name'>name</span><span class='period'>.</span><span class='id identifier rubyid_surname'>surname</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Begood</span><span class='tstring_end'>&quot;</span></span>
95
+
96
+ <span class='id identifier rubyid_data'>data</span><span class='period'>.</span><span class='id identifier rubyid_my'>my</span><span class='period'>.</span><span class='id identifier rubyid_object'>object</span><span class='period'>.</span><span class='id identifier rubyid_with'>with</span><span class='period'>.</span><span class='id identifier rubyid_deep'>deep</span><span class='period'>.</span><span class='id identifier rubyid_nested'>nested</span><span class='period'>.</span><span class='id identifier rubyid_members'>members</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>happy place</span><span class='tstring_end'>&quot;</span></span>
97
+ </code></pre>
98
+
99
+ <p>or assign hashes which become nested blobjects</p>
100
+
101
+ <p>data.details = { code: 41239, ref: &quot;#22322&quot; }</p>
102
+
103
+ <p>data.details.code
104
+ =&gt; 41239
105
+ data.details.ref
106
+ =&gt; &quot;#22322&quot;</p>
107
+
108
+ <p>You can test to see if a member is defined:</p>
109
+
110
+ <pre class="code ruby"><code>data.something_here?
111
+ =&gt; false
112
+ </code></pre>
113
+
114
+ <h2>Used for Configuration</h2>
115
+
116
+ <p>Consider a configuration object which contains credentials for a third-party api.</p>
117
+
118
+ <pre class="code ruby"><code>third_party_api:
119
+ secret_key: 'S3CR3T'
120
+ endpoint: 'http://services.thirdparty.net/api'
121
+ </code></pre>
122
+
123
+ <p>With a hash, usage looks like this:</p>
124
+
125
+ <pre class="code ruby"><code><span class='const'>CONFIG</span><span class='lbracket'>[</span><span class='symbol'>:third_party_api</span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='symbol'>:endpoint</span><span class='rbracket'>]</span>
126
+ </code></pre>
127
+
128
+ <p>With a Blobject, usage looks like this:</p>
129
+
130
+ <pre class="code ruby"><code><span class='const'>CONFIG</span><span class='period'>.</span><span class='id identifier rubyid_third_party_api'>third_party_api</span><span class='period'>.</span><span class='id identifier rubyid_endpoint'>endpoint</span>
131
+ </code></pre>
132
+
133
+ <p>References to the endpoint are scattered throughout the codebase, then one day the endpoint is separated into its constituent parts to aide in testing and staging.</p>
134
+
135
+ <pre class="code ruby"><code>third_party_api:
136
+ secret_key: 'S3CR3T'
137
+ protocol: 'http'
138
+ hostname: 'services.thirdparty.net'
139
+ path: '/api'
140
+ </code></pre>
141
+
142
+ <p>Using a blobject we can easily avoid having to refactor our code...</p>
143
+
144
+ <pre class="code ruby"><code><span class='const'>CONFIG</span> <span class='op'>=</span> <span class='const'>Blobject</span><span class='period'>.</span><span class='id identifier rubyid_from_yaml'>from_yaml</span><span class='lparen'>(</span><span class='const'>File</span><span class='period'>.</span><span class='id identifier rubyid_read'>read</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>./config.yml</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='rparen'>)</span>
145
+
146
+ <span class='const'>CONFIG</span><span class='period'>.</span><span class='id identifier rubyid_third_party_api'>third_party_api</span><span class='period'>.</span><span class='id identifier rubyid_instance_eval'>instance_eval</span> <span class='kw'>do</span>
147
+ <span class='kw'>def</span> <span class='id identifier rubyid_endpoint'>endpoint</span>
148
+ <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_protocol'>protocol</span><span class='rbrace'>}</span><span class='tstring_content'>://</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_hostname'>hostname</span><span class='rbrace'>}</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_path'>path</span><span class='rbrace'>}</span><span class='tstring_end'>&quot;</span></span>
149
+ <span class='kw'>end</span>
150
+ <span class='kw'>end</span>
151
+ </code></pre>
152
+
153
+ <h2>Serializing &amp; Deserializing</h2>
154
+
155
+ <p>Blobjects can be used to easily build complex payloads.</p>
156
+
157
+ <pre class="code ruby"><code>person = Blobject.new
158
+
159
+ person.name = first: 'David', last: 'Platt'
160
+
161
+ person.address.tap do |address|
162
+ address.street = &quot;...&quot;
163
+ address.city = &quot;...&quot;
164
+ end
165
+
166
+ person.next_of_kin.address.city = '...'
167
+
168
+ # after the payload is constructed it can be frozen to prevent modification
169
+ person.freeze
170
+ </code></pre>
171
+
172
+ <p>A nice pattern in most cases is to use an initialization block...</p>
173
+
174
+ <pre class="code ruby"><code>Blobject.new optional_hash_of_initial_data do |b|
175
+ b.name = ...
176
+ end.freeze
177
+ </code></pre>
178
+
179
+ <p>Suppose you receive a payload from an api which may or may not contain an address and city...</p>
180
+
181
+ <pre class="code ruby"><code>payload = Blobject.from_json request[:payload]
182
+
183
+ # if the payload does have an address...
184
+ city = payload.address.city
185
+ =&gt; 'Liverpool'
186
+
187
+ # if the payload does not have an address or city
188
+ city = payload.address.city
189
+ =&gt; nil
190
+ # rather than request[:payload][:address][:city] which would raise
191
+ # NoMethodError: undefined method `[]' for nil:NilClass
192
+ </code></pre>
193
+
194
+ <p>Also, you don&#39;t need to concern yourself whether hash keys are symbols or strings.</p>
195
+
196
+ <h2>Performance</h2>
197
+
198
+ <p>The runtime performance of something as low level as blobject deserves consideration.</p>
199
+
200
+ <p>see <code>/benchmarks</code></p>
201
+
202
+ <pre class="code ruby"><code>ITERATIONS: 1000000
203
+
204
+
205
+ BENCHMARK: assign
206
+
207
+ user system total real
208
+ Object: 0.190000 0.000000 0.190000 ( 0.229685)
209
+ Hash: 0.220000 0.000000 0.220000 ( 0.230500)
210
+ OpenStruct: 0.520000 0.000000 0.520000 ( 0.529861)
211
+ Blobject: 0.790000 0.000000 0.790000 ( 0.808610)
212
+ Hashie: 8.270000 0.030000 8.300000 ( 9.291184)
213
+
214
+
215
+ BENCHMARK: read
216
+
217
+ user system total real
218
+ Hash: 0.160000 0.000000 0.160000 ( 0.165141)
219
+ Object: 0.170000 0.000000 0.170000 ( 0.170228)
220
+ OpenStruct: 0.340000 0.000000 0.340000 ( 0.342430)
221
+ Blobject: 0.410000 0.000000 0.410000 ( 0.410574)
222
+ Hashie: 1.880000 0.000000 1.880000 ( 1.921718)
223
+ </code></pre>
224
+
225
+ <p>Host CPU: 2.13GHz Core2</p>
226
+
227
+ <p>A Blobject is three-four times slower than an equivalent Object.</p>
228
+
229
+ <h2>Limitations</h2>
230
+
231
+ <ul>
232
+ <li>will not work with basic objects unless #class and #freeze are implemented</li>
233
+ <li>cyclic blobject graphs result in infinite recursion StackOverflow</li>
234
+ <li>Ruby 1.8.7 is not supported. Testing rubies...
235
+
236
+ <ul>
237
+ <li>mri 1.9.3-p194</li>
238
+ <li>mri 1.9.2-p290</li>
239
+ </ul></li>
240
+ </ul>
241
+
242
+ <h2>Disclaimer</h2>
243
+
244
+ <p>Blobject provides a convenient way to create large freeform data structures; With great power comes great blah blah blah blah...</p>
245
+
246
+ <h2>License</h2>
247
+
248
+ <p>(The MIT License)</p>
249
+
250
+ <p>Copyright © 2012 <a href="http://sjltaylor.com/">Sam Taylor</a></p>
251
+
252
+ <p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p>
253
+
254
+ <p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p>
255
+
256
+ <p>THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
257
+
258
+ <p>Copyright (c) 2012 Sam Taylor. See LICENSE.txt for
259
+ further details.</p>
260
+ </div></div>
261
+
262
+ <div id="footer">
263
+ Generated on Thu Jun 7 00:25:31 2012 by
264
+ <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
265
+ 0.8.1 (ruby-1.9.3).
266
+ </div>
267
+
268
+ </body>
269
+ </html>