active-record-binder 1.1.0 → 1.2.0

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.
Files changed (47) hide show
  1. data/README.md +217 -0
  2. data/bin/arb +13 -0
  3. data/doc/Binder.html +150 -0
  4. data/doc/Binder/AR.html +1880 -0
  5. data/doc/Binder/Command.html +252 -0
  6. data/doc/Binder/Help.html +374 -0
  7. data/doc/Binder/Migrate.html +682 -0
  8. data/doc/Binder/Strategy.html +550 -0
  9. data/doc/Binder/Version.html +285 -0
  10. data/doc/Class.html +220 -0
  11. data/doc/CommandParser.html +268 -0
  12. data/doc/CommandParser/ParseError.html +123 -0
  13. data/doc/DeferedDelegator.html +414 -0
  14. data/doc/MigrationProcessError.html +123 -0
  15. data/doc/MigrationVersionError.html +123 -0
  16. data/doc/String.html +245 -0
  17. data/doc/_index.html +256 -0
  18. data/doc/class_list.html +53 -0
  19. data/doc/css/common.css +1 -0
  20. data/doc/css/full_list.css +57 -0
  21. data/doc/css/style.css +328 -0
  22. data/doc/file.README.html +300 -0
  23. data/doc/file_list.html +55 -0
  24. data/doc/frames.html +28 -0
  25. data/doc/index.html +300 -0
  26. data/doc/js/app.js +214 -0
  27. data/doc/js/full_list.js +173 -0
  28. data/doc/js/jquery.js +4 -0
  29. data/doc/method_list.html +348 -0
  30. data/doc/top-level-namespace.html +114 -0
  31. data/extras/cli_help.png +0 -0
  32. data/lib/active_record_binder.rb +21 -37
  33. data/lib/cli/command.rb +101 -0
  34. data/lib/cli/command_parser.rb +29 -0
  35. data/lib/cli/commands/commands.rb +4 -0
  36. data/lib/cli/commands/help.rb +35 -0
  37. data/lib/cli/commands/migrate.rb +77 -0
  38. data/lib/cli/commands/version.rb +16 -0
  39. data/lib/cli/core_ext.rb +21 -0
  40. data/lib/defered_delegator.rb +69 -0
  41. data/lib/version.rb +3 -0
  42. data/test/active_record_binder_test.rb +262 -0
  43. data/test/foo.sqlite3 +0 -0
  44. data/test/migrations.rb +29 -0
  45. data/test/minitest_helper.rb +15 -0
  46. data/test/mocks.rb +24 -0
  47. metadata +62 -5
data/doc/file.README.html ADDED
@@ -0,0 +1,300 @@
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=US-ASCII" />
6
+ <title>
7
+ File: README
8
+
9
+ &mdash; Documentation by YARD 0.8.4.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'><h1><a href="https://rubygems.org/gems/active-record-binder">ActiveRecordBinder</a></h1>
65
+
66
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_arb'>arb</span> <span class='op'>-</span><span class='id identifier rubyid_v'>v</span>
67
+ <span class='comment'># =&gt; 1.2.0
68
+ </span>
69
+ <span class='id identifier rubyid_arb'>arb</span> <span class='op'>-</span><span class='op'>-</span><span class='id identifier rubyid_changelog'>changelog</span>
70
+ <span class='comment'># V 1.2.0 : Bug fixes, refactoring and introduction of the new command-line-tool : `arb`
71
+ </span><span class='comment'># V 1.1.0 : Introducing delegation for ActiveRecord::Base relation methods.
72
+ </span><span class='comment'># V 1.0.1 : Minor fixes and Documentation creation.
73
+ </span><span class='comment'># V 1.0.0 : Release
74
+ </span><span class='comment'>#
75
+ </span></code></pre>
76
+
77
+ <p>A Ruby library for an easier interfacing with ActiveRecord. And an easier way to create elegant migrations.</p>
78
+
79
+ <h1>Installation</h1>
80
+
81
+ <p><code>gem install active-record-binder</code></p>
82
+
83
+ <h1>Why Binder ? What the frak is this ?</h1>
84
+
85
+ <p>I needed a tool to ease the creation of little Plugs and Adapters for ActiveRecord.</p>
86
+
87
+ <p>The idea is that you Bind a class to ActiveRecord by subclassing it with Binder::AR.
88
+ You can specify your own methods and delegate to ActiveRecord whenever you need.</p>
89
+
90
+ <p>It&#39;s kind of a Proxy on steroids, that will do a lot for you.</p>
91
+
92
+ <h2>Show me !</h2>
93
+
94
+ <p>You want to create a Plug for your sqlite database :</p>
95
+
96
+ <pre class="code ruby"><code class="ruby"> <span class='kw'>class</span> <span class='const'>SqlitePlug</span> <span class='op'>&lt;</span> <span class='const'>Binder</span><span class='op'>::</span><span class='const'>AR</span>
97
+ <span class='kw'>end</span>
98
+ </code></pre>
99
+
100
+ <p>Those lines will create a new <code>MySqlPlug</code>, and it will connect to the database specified by your <code>ENV[&#39;APP_DB&#39;]</code>.
101
+ Also, the database adapter defaults to <code>:sqlite3</code>.</p>
102
+
103
+ <p>Now. All this is fine. But you want more :
104
+ * You want to select a precise database without using <code>ENV[&#39;APP_DB&#39;]</code>;
105
+ * Your application uses MySQL.</p>
106
+
107
+ <pre class="code ruby"><code class="ruby"> <span class='kw'>class</span> <span class='const'>MySqlPlug</span> <span class='op'>&lt;</span> <span class='const'>Binder</span><span class='op'>::</span><span class='const'>AR</span>
108
+ <span class='id identifier rubyid_database'>database</span> <span class='symbol'>:db</span>
109
+ <span class='id identifier rubyid_adapter'>adapter</span> <span class='symbol'>:mysql</span>
110
+ <span class='id identifier rubyid_connect_with'>connect_with</span> <span class='label'>user:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Foo</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>password:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Bar</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>host:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>localhost</span><span class='tstring_end'>'</span></span>
111
+ <span class='kw'>end</span>
112
+ </code></pre>
113
+
114
+ <p>As you can see : you can specify a database or an adapter by passing a <code>Symbol</code> or a <code>String</code> to both the
115
+ * <code>database()</code> and the
116
+ * <code>adapter()</code> methods.</p>
117
+
118
+ <p>The <code>connect_with()</code> method can be used to pass a <code>Hash</code> of options to the <code>ActiveRecord::Base.establish_connexion()</code> call.</p>
119
+
120
+ <p><em>Please notice that all your instances of MySqlPlug will use those values once defined this way.</em></p>
121
+
122
+ <h2>How do we use this ?</h2>
123
+
124
+ <pre class="code ruby"><code class="ruby"> <span class='kw'>class</span> <span class='const'>MySqlPlug</span> <span class='op'>&lt;</span> <span class='const'>Binder</span><span class='op'>::</span><span class='const'>AR</span>
125
+ <span class='id identifier rubyid_database'>database</span> <span class='symbol'>:db</span>
126
+ <span class='id identifier rubyid_adapter'>adapter</span> <span class='symbol'>:mysql</span>
127
+ <span class='id identifier rubyid_connect_with'>connect_with</span> <span class='label'>user:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Foo</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>password:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Bar</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>host:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>localhost</span><span class='tstring_end'>'</span></span>
128
+
129
+ <span class='kw'>def</span> <span class='id identifier rubyid_find'>find</span> <span class='id identifier rubyid_args'>args</span>
130
+ <span class='comment'># But you could use a delegator
131
+ </span> <span class='id identifier rubyid_table'>table</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span> <span class='id identifier rubyid_args'>args</span>
132
+ <span class='kw'>end</span>
133
+ <span class='kw'>end</span>
134
+
135
+ <span class='comment'># A Model
136
+ </span> <span class='kw'>class</span> <span class='const'>Foo</span>
137
+ <span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span>
138
+ <span class='comment'># Will bind this instance of the MySqlPlug to the `foos` table
139
+ </span> <span class='ivar'>@plug</span> <span class='op'>=</span> <span class='const'>MySqlPlug</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> <span class='symbol'>:foo</span>
140
+ <span class='kw'>end</span>
141
+
142
+ <span class='kw'>def</span> <span class='id identifier rubyid_find'>find</span>
143
+ <span class='comment'># But you could use a delegator
144
+ </span> <span class='ivar'>@plug</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span>
145
+ <span class='kw'>end</span>
146
+ <span class='kw'>end</span>
147
+ </code></pre>
148
+
149
+ <p><strong>Note :</strong> You can use the <code>table</code> method on any instance of your Plug to get the table class (An ActiveRecord Class Object).</p>
150
+
151
+ <pre class="code ruby"><code class="ruby"> <span class='ivar'>@plug</span> <span class='op'>=</span> <span class='const'>MySqlPlug</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> <span class='symbol'>:foo</span>
152
+ <span class='id identifier rubyid_table'>table</span> <span class='op'>=</span> <span class='ivar'>@plug</span><span class='period'>.</span><span class='id identifier rubyid_table'>table</span>
153
+ <span class='comment'># =&gt; MySqlPlug::Foo
154
+ </span> <span class='id identifier rubyid_table'>table</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span> <span class='comment'># ActiveRecord method call.
155
+ </span> <span class='comment'># =&gt; [&lt;FooObject#1&gt;, &lt;FooObject#2, ...]
156
+ </span></code></pre>
157
+
158
+ <p>Notice how neatly namespaced is the ActiveRecord table class. This way we won&#39;t step over our <code>Foo</code> model.</p>
159
+
160
+ <h1>Relations</h1>
161
+
162
+ <p>If it pleases you, you can create your relations directly in the Binder class. Those methods call are delegated to the underlying table model when initiated.</p>
163
+
164
+ <pre class="code ruby"><code class="ruby"> <span class='kw'>class</span> <span class='const'>FooBinder</span> <span class='op'>&lt;</span> <span class='const'>Binder</span><span class='op'>::</span><span class='const'>AR</span>
165
+ <span class='id identifier rubyid_has_one'>has_one</span> <span class='symbol'>:bar</span>
166
+ <span class='kw'>end</span>
167
+ <span class='kw'>class</span> <span class='const'>BarBinder</span> <span class='op'>&lt;</span> <span class='const'>Binder</span><span class='op'>::</span><span class='const'>AR</span>
168
+ <span class='id identifier rubyid_belongs_to'>belongs_to</span> <span class='symbol'>:foo</span>
169
+ <span class='kw'>end</span>
170
+
171
+ <span class='comment'># And (if the table are accordingly populated, see &quot;The Migration System&quot;, below) :
172
+ </span> <span class='id identifier rubyid_foo'>foo</span> <span class='op'>=</span> <span class='const'>FooBinder</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='symbol'>:foo</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_table'>table</span>
173
+ <span class='id identifier rubyid_foo'>foo</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span><span class='period'>.</span><span class='id identifier rubyid_bar'>bar</span> <span class='comment'># =&gt; &lt;BarObject&gt;
174
+ </span></code></pre>
175
+
176
+ <p>Delegated methods are the following : <code>has_many</code>, <code>has_one</code>, <code>has_and_belongs_to_many</code>, <code>belongs_to</code>.</p>
177
+
178
+ <h1>The Migration System</h1>
179
+
180
+ <p>I&#39;ve always found the ActiveRecord::Migration system a bit of a pain to use.</p>
181
+
182
+ <p>Therefore, I took the liberty of using pieces of <a href="https://github.com/camping/camping/"><code>_Why&#39;s Camping Web Framework&#39;s</code></a> migration system.
183
+ You can now create your migrations this way :</p>
184
+
185
+ <pre class="code ruby"><code class="ruby"> <span class='kw'>class</span> <span class='const'>CreateFooTable</span> <span class='op'>&lt;</span> <span class='const'>MySqlPlug</span><span class='op'>::</span><span class='const'>Version</span> <span class='float'>1.0</span>
186
+ <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_up'>up</span>
187
+ <span class='id identifier rubyid_create_table'>create_table</span> <span class='symbol'>:foos</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_t'>t</span><span class='op'>|</span>
188
+ <span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_string'>string</span> <span class='symbol'>:name</span>
189
+ <span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_timestamps'>timestamps</span>
190
+ <span class='kw'>end</span>
191
+ <span class='kw'>end</span>
192
+
193
+ <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_down'>down</span>
194
+ <span class='id identifier rubyid_drop_table'>drop_table</span> <span class='symbol'>:foos</span>
195
+ <span class='kw'>end</span>
196
+ <span class='kw'>end</span>
197
+
198
+ <span class='kw'>class</span> <span class='const'>CreateBarTable</span> <span class='op'>&lt;</span> <span class='const'>MySqlPlug</span><span class='op'>::</span><span class='const'>Version</span> <span class='float'>1.1</span>
199
+ <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_up'>up</span>
200
+ <span class='id identifier rubyid_create_table'>create_table</span> <span class='symbol'>:bars</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_t'>t</span><span class='op'>|</span>
201
+ <span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_string'>string</span> <span class='symbol'>:title</span>
202
+ <span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_timestamps'>timestamps</span>
203
+ <span class='kw'>end</span>
204
+ <span class='kw'>end</span>
205
+
206
+ <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_down'>down</span>
207
+ <span class='id identifier rubyid_drop_table'>drop_table</span> <span class='symbol'>:bars</span>
208
+ <span class='kw'>end</span>
209
+ <span class='kw'>end</span>
210
+
211
+ <span class='comment'># You can get the migration version for a pecular migration class.
212
+ </span> <span class='const'>CreateFooTable</span><span class='period'>.</span><span class='id identifier rubyid_version'>version</span> <span class='comment'># =&gt; 1.0
213
+ </span> <span class='const'>CreateBarTable</span><span class='period'>.</span><span class='id identifier rubyid_version'>version</span> <span class='comment'># =&gt; 1.1
214
+ </span></code></pre>
215
+
216
+ <p>Isn&#39;t it neat ?.</p>
217
+
218
+ <p>Now, boy : just use the <code>migrate</code> method to execute your migrations.</p>
219
+
220
+ <pre class="code ruby"><code class="ruby"> <span class='const'>MySqlPlug</span><span class='period'>.</span><span class='id identifier rubyid_migrate'>migrate</span>
221
+ <span class='comment'># =&gt; 1.1
222
+ </span></code></pre>
223
+
224
+ <p>This executes everything up to the latest migration.
225
+ But <code>migrate()</code> can also take a version number as an argument.</p>
226
+
227
+ <pre class="code ruby"><code class="ruby"> <span class='const'>MySqlPlug</span><span class='period'>.</span><span class='id identifier rubyid_migrate'>migrate</span> <span class='int'>0</span>
228
+ <span class='comment'># =&gt; 0.0
229
+ </span></code></pre>
230
+
231
+ <p>This, will migrate everything down, reverting the changes as specified in each reverted migration <code>self.down</code> method.
232
+ <code>ruby
233
+ MySqlPlug.migrate 1.0
234
+ # =&gt; 1.0
235
+ </code>
236
+ And finally, this will migrate up until it hits 1.0.</p>
237
+
238
+ <h1>The Command Line Tool</h1>
239
+
240
+ <p>Active Record Binder ships with a neat little CLI : <code>arb</code></p>
241
+
242
+ <p>ARB is a small easily extandable Command Line Interface. And it&#39;s pretty. Beautiful colors everywhere. Awesome. Seriously.
243
+ To use it :
244
+ ```
245
+ $ arb version</p>
246
+
247
+ <h1>=&gt; Binder::AR::Version =&gt; 1.2.0</h1>
248
+
249
+ <pre class="code ruby"><code class="ruby">
250
+ You can display the help using `arb help` or `arb -h`
251
+
252
+ But, the most intersting part of this CLI is the migrate command. You can easily run your migrations for a specific plug :
253
+ </code></pre>
254
+
255
+ <p>$ arb migrate --version 1.1 --directory migrations/ --adapter MySqlitePlug
256
+ ``<code>
257
+ Will migrate to 1.1, using the migrations found in the</code>migrations/<code>directory and calling</code>MySqlitePlug.migrate`.</p>
258
+
259
+ <p>You can specify multiples options, and there is an alternative syntax :
260
+ ```</p>
261
+
262
+ <h1>=&gt; You can specify multiple directories through <code>--directory</code> or <code>--d</code></h1>
263
+
264
+ <p>$ arb migrate -v 0 -d migrations/foo/ migrations/bar -a MySqlitePlug</p>
265
+
266
+ <h1>=&gt; You can load directories recursively with <code>-r</code> or <code>--recursive</code></h1>
267
+
268
+ <p>$ arb migrate -v 0 --recursive migrations/ --plug MySqlitePlug</p>
269
+
270
+ <h1>=&gt; You can can also load files using <code>-f</code> or <code>--file</code></h1>
271
+
272
+ <p>$ arb migrate -v 1.0 -f migrations/foo/create_foo_table.rb --adapter MySqlitePlug
273
+ ```</p>
274
+
275
+ <p><img src="https://raw.github.com/gabriel-dehan/ActiveRecordBinder/master/extras/cli_help.png" alt="Command Line Interface screenshot"/></p>
276
+
277
+ <h1>Want to know more ?</h1>
278
+
279
+ <p><a href="http://rubydoc.info/gems/active-record-binder/1.0.1/frames">Checkout the documentation !</a>
280
+ Or dive in, the code is pretty straightforward and well documented. And there is a lot of tests.</p>
281
+
282
+ <h1>Want to contribute ?</h1>
283
+
284
+ <p>Please, do fork and pull request !</p>
285
+
286
+ <h2>Road map:</h2>
287
+
288
+ <ul>
289
+ <li>Maybe create other Binder, like MongoDB, Datamapper, like <code>Binder::Mongo</code>, <code>Binder::DataMapper</code>. But the gem&#39;s name would have to change.</li>
290
+ </ul>
291
+ </div></div>
292
+
293
+ <div id="footer">
294
+ Generated on Thu Feb 21 02:06:16 2013 by
295
+ <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
296
+ 0.8.4.1 (ruby-1.9.3).
297
+ </div>
298
+
299
+ </body>
300
+ </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.4.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,300 @@
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=US-ASCII" />
6
+ <title>
7
+ File: README
8
+
9
+ &mdash; Documentation by YARD 0.8.4.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'><h1><a href="https://rubygems.org/gems/active-record-binder">ActiveRecordBinder</a></h1>
65
+
66
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_arb'>arb</span> <span class='op'>-</span><span class='id identifier rubyid_v'>v</span>
67
+ <span class='comment'># =&gt; 1.2.0
68
+ </span>
69
+ <span class='id identifier rubyid_arb'>arb</span> <span class='op'>-</span><span class='op'>-</span><span class='id identifier rubyid_changelog'>changelog</span>
70
+ <span class='comment'># V 1.2.0 : Bug fixes, refactoring and introduction of the new command-line-tool : `arb`
71
+ </span><span class='comment'># V 1.1.0 : Introducing delegation for ActiveRecord::Base relation methods.
72
+ </span><span class='comment'># V 1.0.1 : Minor fixes and Documentation creation.
73
+ </span><span class='comment'># V 1.0.0 : Release
74
+ </span><span class='comment'>#
75
+ </span></code></pre>
76
+
77
+ <p>A Ruby library for an easier interfacing with ActiveRecord. And an easier way to create elegant migrations.</p>
78
+
79
+ <h1>Installation</h1>
80
+
81
+ <p><code>gem install active-record-binder</code></p>
82
+
83
+ <h1>Why Binder ? What the frak is this ?</h1>
84
+
85
+ <p>I needed a tool to ease the creation of little Plugs and Adapters for ActiveRecord.</p>
86
+
87
+ <p>The idea is that you Bind a class to ActiveRecord by subclassing it with Binder::AR.
88
+ You can specify your own methods and delegate to ActiveRecord whenever you need.</p>
89
+
90
+ <p>It&#39;s kind of a Proxy on steroids, that will do a lot for you.</p>
91
+
92
+ <h2>Show me !</h2>
93
+
94
+ <p>You want to create a Plug for your sqlite database :</p>
95
+
96
+ <pre class="code ruby"><code class="ruby"> <span class='kw'>class</span> <span class='const'>SqlitePlug</span> <span class='op'>&lt;</span> <span class='const'>Binder</span><span class='op'>::</span><span class='const'>AR</span>
97
+ <span class='kw'>end</span>
98
+ </code></pre>
99
+
100
+ <p>Those lines will create a new <code>MySqlPlug</code>, and it will connect to the database specified by your <code>ENV[&#39;APP_DB&#39;]</code>.
101
+ Also, the database adapter defaults to <code>:sqlite3</code>.</p>
102
+
103
+ <p>Now. All this is fine. But you want more :
104
+ * You want to select a precise database without using <code>ENV[&#39;APP_DB&#39;]</code>;
105
+ * Your application uses MySQL.</p>
106
+
107
+ <pre class="code ruby"><code class="ruby"> <span class='kw'>class</span> <span class='const'>MySqlPlug</span> <span class='op'>&lt;</span> <span class='const'>Binder</span><span class='op'>::</span><span class='const'>AR</span>
108
+ <span class='id identifier rubyid_database'>database</span> <span class='symbol'>:db</span>
109
+ <span class='id identifier rubyid_adapter'>adapter</span> <span class='symbol'>:mysql</span>
110
+ <span class='id identifier rubyid_connect_with'>connect_with</span> <span class='label'>user:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Foo</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>password:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Bar</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>host:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>localhost</span><span class='tstring_end'>'</span></span>
111
+ <span class='kw'>end</span>
112
+ </code></pre>
113
+
114
+ <p>As you can see : you can specify a database or an adapter by passing a <code>Symbol</code> or a <code>String</code> to both the
115
+ * <code>database()</code> and the
116
+ * <code>adapter()</code> methods.</p>
117
+
118
+ <p>The <code>connect_with()</code> method can be used to pass a <code>Hash</code> of options to the <code>ActiveRecord::Base.establish_connexion()</code> call.</p>
119
+
120
+ <p><em>Please notice that all your instances of MySqlPlug will use those values once defined this way.</em></p>
121
+
122
+ <h2>How do we use this ?</h2>
123
+
124
+ <pre class="code ruby"><code class="ruby"> <span class='kw'>class</span> <span class='const'>MySqlPlug</span> <span class='op'>&lt;</span> <span class='const'>Binder</span><span class='op'>::</span><span class='const'>AR</span>
125
+ <span class='id identifier rubyid_database'>database</span> <span class='symbol'>:db</span>
126
+ <span class='id identifier rubyid_adapter'>adapter</span> <span class='symbol'>:mysql</span>
127
+ <span class='id identifier rubyid_connect_with'>connect_with</span> <span class='label'>user:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Foo</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>password:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Bar</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>host:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>localhost</span><span class='tstring_end'>'</span></span>
128
+
129
+ <span class='kw'>def</span> <span class='id identifier rubyid_find'>find</span> <span class='id identifier rubyid_args'>args</span>
130
+ <span class='comment'># But you could use a delegator
131
+ </span> <span class='id identifier rubyid_table'>table</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span> <span class='id identifier rubyid_args'>args</span>
132
+ <span class='kw'>end</span>
133
+ <span class='kw'>end</span>
134
+
135
+ <span class='comment'># A Model
136
+ </span> <span class='kw'>class</span> <span class='const'>Foo</span>
137
+ <span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span>
138
+ <span class='comment'># Will bind this instance of the MySqlPlug to the `foos` table
139
+ </span> <span class='ivar'>@plug</span> <span class='op'>=</span> <span class='const'>MySqlPlug</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> <span class='symbol'>:foo</span>
140
+ <span class='kw'>end</span>
141
+
142
+ <span class='kw'>def</span> <span class='id identifier rubyid_find'>find</span>
143
+ <span class='comment'># But you could use a delegator
144
+ </span> <span class='ivar'>@plug</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span>
145
+ <span class='kw'>end</span>
146
+ <span class='kw'>end</span>
147
+ </code></pre>
148
+
149
+ <p><strong>Note :</strong> You can use the <code>table</code> method on any instance of your Plug to get the table class (An ActiveRecord Class Object).</p>
150
+
151
+ <pre class="code ruby"><code class="ruby"> <span class='ivar'>@plug</span> <span class='op'>=</span> <span class='const'>MySqlPlug</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> <span class='symbol'>:foo</span>
152
+ <span class='id identifier rubyid_table'>table</span> <span class='op'>=</span> <span class='ivar'>@plug</span><span class='period'>.</span><span class='id identifier rubyid_table'>table</span>
153
+ <span class='comment'># =&gt; MySqlPlug::Foo
154
+ </span> <span class='id identifier rubyid_table'>table</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span> <span class='comment'># ActiveRecord method call.
155
+ </span> <span class='comment'># =&gt; [&lt;FooObject#1&gt;, &lt;FooObject#2, ...]
156
+ </span></code></pre>
157
+
158
+ <p>Notice how neatly namespaced is the ActiveRecord table class. This way we won&#39;t step over our <code>Foo</code> model.</p>
159
+
160
+ <h1>Relations</h1>
161
+
162
+ <p>If it pleases you, you can create your relations directly in the Binder class. Those methods call are delegated to the underlying table model when initiated.</p>
163
+
164
+ <pre class="code ruby"><code class="ruby"> <span class='kw'>class</span> <span class='const'>FooBinder</span> <span class='op'>&lt;</span> <span class='const'>Binder</span><span class='op'>::</span><span class='const'>AR</span>
165
+ <span class='id identifier rubyid_has_one'>has_one</span> <span class='symbol'>:bar</span>
166
+ <span class='kw'>end</span>
167
+ <span class='kw'>class</span> <span class='const'>BarBinder</span> <span class='op'>&lt;</span> <span class='const'>Binder</span><span class='op'>::</span><span class='const'>AR</span>
168
+ <span class='id identifier rubyid_belongs_to'>belongs_to</span> <span class='symbol'>:foo</span>
169
+ <span class='kw'>end</span>
170
+
171
+ <span class='comment'># And (if the table are accordingly populated, see &quot;The Migration System&quot;, below) :
172
+ </span> <span class='id identifier rubyid_foo'>foo</span> <span class='op'>=</span> <span class='const'>FooBinder</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='symbol'>:foo</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_table'>table</span>
173
+ <span class='id identifier rubyid_foo'>foo</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span><span class='period'>.</span><span class='id identifier rubyid_bar'>bar</span> <span class='comment'># =&gt; &lt;BarObject&gt;
174
+ </span></code></pre>
175
+
176
+ <p>Delegated methods are the following : <code>has_many</code>, <code>has_one</code>, <code>has_and_belongs_to_many</code>, <code>belongs_to</code>.</p>
177
+
178
+ <h1>The Migration System</h1>
179
+
180
+ <p>I&#39;ve always found the ActiveRecord::Migration system a bit of a pain to use.</p>
181
+
182
+ <p>Therefore, I took the liberty of using pieces of <a href="https://github.com/camping/camping/"><code>_Why&#39;s Camping Web Framework&#39;s</code></a> migration system.
183
+ You can now create your migrations this way :</p>
184
+
185
+ <pre class="code ruby"><code class="ruby"> <span class='kw'>class</span> <span class='const'>CreateFooTable</span> <span class='op'>&lt;</span> <span class='const'>MySqlPlug</span><span class='op'>::</span><span class='const'>Version</span> <span class='float'>1.0</span>
186
+ <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_up'>up</span>
187
+ <span class='id identifier rubyid_create_table'>create_table</span> <span class='symbol'>:foos</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_t'>t</span><span class='op'>|</span>
188
+ <span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_string'>string</span> <span class='symbol'>:name</span>
189
+ <span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_timestamps'>timestamps</span>
190
+ <span class='kw'>end</span>
191
+ <span class='kw'>end</span>
192
+
193
+ <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_down'>down</span>
194
+ <span class='id identifier rubyid_drop_table'>drop_table</span> <span class='symbol'>:foos</span>
195
+ <span class='kw'>end</span>
196
+ <span class='kw'>end</span>
197
+
198
+ <span class='kw'>class</span> <span class='const'>CreateBarTable</span> <span class='op'>&lt;</span> <span class='const'>MySqlPlug</span><span class='op'>::</span><span class='const'>Version</span> <span class='float'>1.1</span>
199
+ <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_up'>up</span>
200
+ <span class='id identifier rubyid_create_table'>create_table</span> <span class='symbol'>:bars</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_t'>t</span><span class='op'>|</span>
201
+ <span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_string'>string</span> <span class='symbol'>:title</span>
202
+ <span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_timestamps'>timestamps</span>
203
+ <span class='kw'>end</span>
204
+ <span class='kw'>end</span>
205
+
206
+ <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_down'>down</span>
207
+ <span class='id identifier rubyid_drop_table'>drop_table</span> <span class='symbol'>:bars</span>
208
+ <span class='kw'>end</span>
209
+ <span class='kw'>end</span>
210
+
211
+ <span class='comment'># You can get the migration version for a pecular migration class.
212
+ </span> <span class='const'>CreateFooTable</span><span class='period'>.</span><span class='id identifier rubyid_version'>version</span> <span class='comment'># =&gt; 1.0
213
+ </span> <span class='const'>CreateBarTable</span><span class='period'>.</span><span class='id identifier rubyid_version'>version</span> <span class='comment'># =&gt; 1.1
214
+ </span></code></pre>
215
+
216
+ <p>Isn&#39;t it neat ?.</p>
217
+
218
+ <p>Now, boy : just use the <code>migrate</code> method to execute your migrations.</p>
219
+
220
+ <pre class="code ruby"><code class="ruby"> <span class='const'>MySqlPlug</span><span class='period'>.</span><span class='id identifier rubyid_migrate'>migrate</span>
221
+ <span class='comment'># =&gt; 1.1
222
+ </span></code></pre>
223
+
224
+ <p>This executes everything up to the latest migration.
225
+ But <code>migrate()</code> can also take a version number as an argument.</p>
226
+
227
+ <pre class="code ruby"><code class="ruby"> <span class='const'>MySqlPlug</span><span class='period'>.</span><span class='id identifier rubyid_migrate'>migrate</span> <span class='int'>0</span>
228
+ <span class='comment'># =&gt; 0.0
229
+ </span></code></pre>
230
+
231
+ <p>This, will migrate everything down, reverting the changes as specified in each reverted migration <code>self.down</code> method.
232
+ <code>ruby
233
+ MySqlPlug.migrate 1.0
234
+ # =&gt; 1.0
235
+ </code>
236
+ And finally, this will migrate up until it hits 1.0.</p>
237
+
238
+ <h1>The Command Line Tool</h1>
239
+
240
+ <p>Active Record Binder ships with a neat little CLI : <code>arb</code></p>
241
+
242
+ <p>ARB is a small easily extandable Command Line Interface. And it&#39;s pretty. Beautiful colors everywhere. Awesome. Seriously.
243
+ To use it :
244
+ ```
245
+ $ arb version</p>
246
+
247
+ <h1>=&gt; Binder::AR::Version =&gt; 1.2.0</h1>
248
+
249
+ <pre class="code ruby"><code class="ruby">
250
+ You can display the help using `arb help` or `arb -h`
251
+
252
+ But, the most intersting part of this CLI is the migrate command. You can easily run your migrations for a specific plug :
253
+ </code></pre>
254
+
255
+ <p>$ arb migrate --version 1.1 --directory migrations/ --adapter MySqlitePlug
256
+ ``<code>
257
+ Will migrate to 1.1, using the migrations found in the</code>migrations/<code>directory and calling</code>MySqlitePlug.migrate`.</p>
258
+
259
+ <p>You can specify multiples options, and there is an alternative syntax :
260
+ ```</p>
261
+
262
+ <h1>=&gt; You can specify multiple directories through <code>--directory</code> or <code>--d</code></h1>
263
+
264
+ <p>$ arb migrate -v 0 -d migrations/foo/ migrations/bar -a MySqlitePlug</p>
265
+
266
+ <h1>=&gt; You can load directories recursively with <code>-r</code> or <code>--recursive</code></h1>
267
+
268
+ <p>$ arb migrate -v 0 --recursive migrations/ --plug MySqlitePlug</p>
269
+
270
+ <h1>=&gt; You can can also load files using <code>-f</code> or <code>--file</code></h1>
271
+
272
+ <p>$ arb migrate -v 1.0 -f migrations/foo/create_foo_table.rb --adapter MySqlitePlug
273
+ ```</p>
274
+
275
+ <p><img src="https://raw.github.com/gabriel-dehan/ActiveRecordBinder/master/extras/cli_help.png" alt="Command Line Interface screenshot"/></p>
276
+
277
+ <h1>Want to know more ?</h1>
278
+
279
+ <p><a href="http://rubydoc.info/gems/active-record-binder/1.0.1/frames">Checkout the documentation !</a>
280
+ Or dive in, the code is pretty straightforward and well documented. And there is a lot of tests.</p>
281
+
282
+ <h1>Want to contribute ?</h1>
283
+
284
+ <p>Please, do fork and pull request !</p>
285
+
286
+ <h2>Road map:</h2>
287
+
288
+ <ul>
289
+ <li>Maybe create other Binder, like MongoDB, Datamapper, like <code>Binder::Mongo</code>, <code>Binder::DataMapper</code>. But the gem&#39;s name would have to change.</li>
290
+ </ul>
291
+ </div></div>
292
+
293
+ <div id="footer">
294
+ Generated on Thu Feb 21 02:06:16 2013 by
295
+ <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
296
+ 0.8.4.1 (ruby-1.9.3).
297
+ </div>
298
+
299
+ </body>
300
+ </html>