inquery 0.0.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (58) hide show
  1. checksums.yaml +7 -0
  2. data/.gitignore +16 -0
  3. data/.releaser_config +4 -0
  4. data/.rubocop.yml +42 -0
  5. data/.travis.yml +9 -0
  6. data/.yardopts +1 -0
  7. data/Gemfile +4 -0
  8. data/LICENSE +21 -0
  9. data/README.md +288 -0
  10. data/RUBY_VERSION +1 -0
  11. data/Rakefile +36 -0
  12. data/VERSION +1 -0
  13. data/doc/Inquery.html +119 -0
  14. data/doc/Inquery/Exceptions.html +115 -0
  15. data/doc/Inquery/Exceptions/Base.html +127 -0
  16. data/doc/Inquery/Exceptions/InvalidRelation.html +131 -0
  17. data/doc/Inquery/Exceptions/UnknownCallSignature.html +131 -0
  18. data/doc/Inquery/Mixins.html +117 -0
  19. data/doc/Inquery/Mixins/RelationValidation.html +334 -0
  20. data/doc/Inquery/Mixins/RelationValidation/ClassMethods.html +190 -0
  21. data/doc/Inquery/Mixins/SchemaValidation.html +124 -0
  22. data/doc/Inquery/Mixins/SchemaValidation/ClassMethods.html +192 -0
  23. data/doc/Inquery/Query.html +736 -0
  24. data/doc/Inquery/Query/Chainable.html +476 -0
  25. data/doc/_index.html +254 -0
  26. data/doc/class_list.html +58 -0
  27. data/doc/css/common.css +1 -0
  28. data/doc/css/full_list.css +57 -0
  29. data/doc/css/style.css +339 -0
  30. data/doc/file.README.html +365 -0
  31. data/doc/file_list.html +60 -0
  32. data/doc/frames.html +26 -0
  33. data/doc/index.html +365 -0
  34. data/doc/js/app.js +219 -0
  35. data/doc/js/full_list.js +181 -0
  36. data/doc/js/jquery.js +4 -0
  37. data/doc/method_list.html +147 -0
  38. data/doc/top-level-namespace.html +112 -0
  39. data/inquery.gemspec +58 -0
  40. data/lib/inquery.rb +10 -0
  41. data/lib/inquery/exceptions.rb +7 -0
  42. data/lib/inquery/mixins/relation_validation.rb +100 -0
  43. data/lib/inquery/mixins/schema_validation.rb +27 -0
  44. data/lib/inquery/query.rb +50 -0
  45. data/lib/inquery/query/chainable.rb +53 -0
  46. data/test/db/models.rb +20 -0
  47. data/test/db/schema.rb +20 -0
  48. data/test/inquery/query/chainable_test.rb +67 -0
  49. data/test/inquery/query_test.rb +47 -0
  50. data/test/queries/group/fetch_as_json.rb +13 -0
  51. data/test/queries/group/fetch_green.rb +11 -0
  52. data/test/queries/group/fetch_red.rb +11 -0
  53. data/test/queries/group/filter_with_color.rb +12 -0
  54. data/test/queries/user/fetch_all.rb +9 -0
  55. data/test/queries/user/fetch_in_group.rb +13 -0
  56. data/test/queries/user/fetch_in_group_rel.rb +17 -0
  57. data/test/test_helper.rb +26 -0
  58. metadata +265 -0
data/doc/index.html ADDED
@@ -0,0 +1,365 @@
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.7.6
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" 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#!file.README.html";
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'>
65
+ <h1 id="label-Inquery">Inquery</h1>
66
+
67
+ <p>A skeleton that allows extracting queries into atomic, reusable classes.</p>
68
+
69
+ <h2 id="label-Installation">Installation</h2>
70
+
71
+ <p>To install the <strong>Inquery</strong> gem:</p>
72
+
73
+ <pre class="code ruby"><code class="ruby">$ gem install inquery</code></pre>
74
+
75
+ <p>To install it using <code>bundler</code> (recommended for any application),
76
+ add it to your <code>Gemfile</code>:</p>
77
+
78
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>inquery</span><span class='tstring_end'>&#39;</span></span>
79
+ </code></pre>
80
+
81
+ <h2 id="label-Basic+usage">Basic usage</h2>
82
+
83
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>FetchUsersWithACar</span> <span class='op'>&lt;</span> <span class='const'>Inquery</span><span class='op'>::</span><span class='const'>Query</span>
84
+ <span class='id identifier rubyid_schema'>schema</span><span class='lparen'>(</span>
85
+ <span class='label'>color:</span> <span class='symbol'>:symbol</span>
86
+ <span class='rparen'>)</span>
87
+
88
+ <span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
89
+ <span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_joins'>joins</span><span class='lparen'>(</span><span class='symbol'>:cars</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='label'>cars:</span> <span class='lbrace'>{</span> <span class='label'>color:</span> <span class='id identifier rubyid_osparams'>osparams</span><span class='period'>.</span><span class='id identifier rubyid_color'>color</span> <span class='rbrace'>}</span><span class='rparen'>)</span>
90
+ <span class='kw'>end</span>
91
+ <span class='kw'>end</span>
92
+
93
+ <span class='const'>FetchUsersWithACar</span><span class='period'>.</span><span class='id identifier rubyid_run'>run</span>
94
+ <span class='comment'># =&gt; [&lt;User id: 1 ...]
95
+ </span></code></pre>
96
+
97
+ <p>Inquery offers its functionality trough two query base classes:
98
+ <span class='object_link'><a href="Inquery/Query.html" title="Inquery::Query (class)">Inquery::Query</a></span> and <span class='object_link'><a href="Inquery/Query/Chainable.html" title="Inquery::Query::Chainable (class)">Inquery::Query::Chainable</a></span>. See the following
99
+ sections for detailed explanations.</p>
100
+
101
+ <h2 id="label-Basic+queries">Basic queries</h2>
102
+
103
+ <p>Basic queries inherit from <span class='object_link'><a href="Inquery/Query.html" title="Inquery::Query (class)">Inquery::Query</a></span>. They receive an optional set
104
+ of parameters and commonly return a relation / AR result. An optional
105
+ <code>process</code> method lets you perform additional result processing
106
+ steps if needed (i.e. converting the result to a hash or similar).</p>
107
+
108
+ <p>For this basic functionality, inherit from <span class='object_link'><a href="Inquery/Query.html" title="Inquery::Query (class)">Inquery::Query</a></span> and overwrite
109
+ the <code>call</code> and optionally the <code>process</code> method:</p>
110
+
111
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>FetchRedCarsAsJson</span>
112
+ <span class='comment'># The `call` method must be overwritten for every query. It is usually called
113
+ </span> <span class='comment'># via `run`.
114
+ </span> <span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
115
+ <span class='const'>Car</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='label'>color:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>red</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
116
+ <span class='kw'>end</span>
117
+
118
+ <span class='comment'># The `process` method can optionally be overwritten. The base implementation
119
+ </span> <span class='comment'># just returns the unprocessed `results` argument.
120
+ </span> <span class='kw'>def</span> <span class='id identifier rubyid_process'>process</span><span class='lparen'>(</span><span class='id identifier rubyid_results'>results</span><span class='rparen'>)</span>
121
+ <span class='id identifier rubyid_results'>results</span><span class='period'>.</span><span class='id identifier rubyid_to_json'>to_json</span>
122
+ <span class='kw'>end</span>
123
+ <span class='kw'>end</span>
124
+ </code></pre>
125
+
126
+ <p>Queries can be called in various ways:</p>
127
+
128
+ <pre class="code ruby"><code class="ruby"><span class='comment'># Instantiates the query class and runs `call` and `process`.
129
+ </span><span class='const'>FetchRedCarsAsJson</span><span class='period'>.</span><span class='id identifier rubyid_run'>run</span><span class='lparen'>(</span><span class='id identifier rubyid_params'>params</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>
130
+
131
+ <span class='comment'># Instantiates the query class and runs `call`. No result processing
132
+ </span><span class='comment'># is done.
133
+ </span><span class='const'>FetchRedCarsAsJson</span><span class='period'>.</span><span class='id identifier rubyid_call'>call</span><span class='lparen'>(</span><span class='id identifier rubyid_params'>params</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>
134
+
135
+ <span class='comment'># You can also instantiate the query class manually.
136
+ </span><span class='const'>FetchRedCarsAsJson</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='id identifier rubyid_params'>params</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_run'>run</span>
137
+
138
+ <span class='comment'># Or just run the `call` method without `process`.
139
+ </span><span class='const'>FetchRedCarsAsJson</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='id identifier rubyid_params'>params</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_call'>call</span>
140
+ </code></pre>
141
+
142
+ <p>Note that it&#39;s perfectly fine for some queries to return
143
+ <code>nil</code>, i.e. if they&#39;re writing queries that don&#39;t fetch
144
+ any results.</p>
145
+
146
+ <h2 id="label-Chainable+queries">Chainable queries</h2>
147
+
148
+ <p>Chainable queries are queries that input and output an Active Record
149
+ relation. You can access the given relation using the method
150
+ <code>relation</code>:</p>
151
+
152
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>Queries</span><span class='op'>::</span><span class='const'>User</span><span class='op'>::</span><span class='const'>FetchActive</span> <span class='op'>&lt;</span> <span class='const'>Inquery</span><span class='op'>::</span><span class='const'>Query</span><span class='op'>::</span><span class='const'>Chainable</span>
153
+ <span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
154
+ <span class='id identifier rubyid_relation'>relation</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='label'>active:</span> <span class='int'>1</span><span class='rparen'>)</span>
155
+ <span class='kw'>end</span>
156
+ <span class='kw'>end</span>
157
+ </code></pre>
158
+
159
+ <p>Input and output relations may or may not be of the same AR class (i.e. you
160
+ could pass a relation of <code>Group</code>s and receive back a relation of
161
+ corresponding <code>User</code>s).</p>
162
+
163
+ <h3 id="label-Relation+validation">Relation validation</h3>
164
+
165
+ <p>Chainable queries allow you to further specify and validate the relation it
166
+ receives. This is done using the static <code>relation</code> method:</p>
167
+
168
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>Queries</span><span class='op'>::</span><span class='const'>User</span><span class='op'>::</span><span class='const'>FetchActive</span> <span class='op'>&lt;</span> <span class='const'>Inquery</span><span class='op'>::</span><span class='const'>Query</span><span class='op'>::</span><span class='const'>Chainable</span>
169
+ <span class='comment'># This will raise an exception when passing a relation which does not
170
+ </span> <span class='comment'># correspond to the `User` model.
171
+ </span> <span class='id identifier rubyid_relation'>relation</span> <span class='label'>class:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>User</span><span class='tstring_end'>&#39;</span></span>
172
+
173
+ <span class='comment'># ....
174
+ </span><span class='kw'>end</span>
175
+ </code></pre>
176
+
177
+ <p>The <code>relation</code> method accepts the following options:</p>
178
+ <ul><li>
179
+ <p><code>class</code></p>
180
+
181
+ <p>Allows to restrict the class (attribute <code>klass</code>) of the
182
+ relation. Use <code>nil</code> to not perform any checks. The
183
+ <code>class</code> attribute will also be taken to infer a default if no
184
+ relation is given and you didn&#39;t specify any <code>default</code>.</p>
185
+ </li><li>
186
+ <p><code>default</code></p>
187
+
188
+ <p>This allows to specify a default relation that will be taken if no relation
189
+ is given. This must be specified as a Proc returning the relation. Set this
190
+ to <code>false</code> for no default. If this is set to <code>nil</code>,
191
+ it will try to infer the default from the option <code>class</code> (if
192
+ given).</p>
193
+ </li><li>
194
+ <p><code>fields</code></p>
195
+
196
+ <p>Allows to restrict the number of fields / values the relation must select.
197
+ This is particularly useful if you&#39;re using the query as a subquery and
198
+ need it to return exactly one field. Use <code>nil</code> to not perform
199
+ any checks.</p>
200
+ </li><li>
201
+ <p><code>default_select</code></p>
202
+
203
+ <p>If this is set to a symbol, the relation does not have any select fields
204
+ specified (<code>select_values</code> is empty) and <code>fields</code> is
205
+ &gt; 0, it will automatically select the given field. This option defaults
206
+ to <code>:id</code>. Use <code>nil</code> to disable this behavior.</p>
207
+ </li></ul>
208
+
209
+ <h3 id="label-Using+query+classes+as+regular+scopes">Using query classes as regular scopes</h3>
210
+
211
+ <p>Chainable queries can also be used as regular AR model scopes:</p>
212
+
213
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>User</span> <span class='op'>&lt;</span> <span class='const'>ActiveRecord</span><span class='op'>::</span><span class='const'>Base</span>
214
+ <span class='id identifier rubyid_scope'>scope</span> <span class='symbol'>:active</span><span class='comma'>,</span> <span class='const'>Queries</span><span class='op'>::</span><span class='const'>User</span><span class='op'>::</span><span class='const'>FetchActive</span>
215
+ <span class='kw'>end</span>
216
+
217
+ <span class='kw'>class</span> <span class='const'>Queries</span><span class='op'>::</span><span class='const'>User</span><span class='op'>::</span><span class='const'>FetchActive</span> <span class='op'>&lt;</span> <span class='const'>Inquery</span><span class='op'>::</span><span class='const'>Query</span><span class='op'>::</span><span class='const'>Chainable</span>
218
+ <span class='comment'># Note that specifying either `class` or `default` is mandatory when using
219
+ </span> <span class='comment'># this query class as a scope. The reason for this is that, if the scope is
220
+ </span> <span class='comment'># otherwise empty, the class will receive `nil` from AR and therefore has no
221
+ </span> <span class='comment'># way of knowing which default class to take.
222
+ </span> <span class='id identifier rubyid_relation'>relation</span> <span class='label'>class:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>User</span><span class='tstring_end'>&#39;</span></span>
223
+
224
+ <span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
225
+ <span class='id identifier rubyid_relation'>relation</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='label'>active:</span> <span class='int'>1</span><span class='rparen'>)</span>
226
+ <span class='kw'>end</span>
227
+ <span class='kw'>end</span>
228
+ </code></pre>
229
+
230
+ <p>This approach allows to you use short and descriptive code like
231
+ <code>User.active</code> but have the possibly complex query code hidden in
232
+ a separate, reusable class.</p>
233
+
234
+ <p>Note that when using classes as scopes, the <code>process</code> method
235
+ will be ignored.</p>
236
+
237
+ <h3 id="label-Using+the+given+relation+as+subquery">Using the given relation as subquery</h3>
238
+
239
+ <p>In simple cases and all the examples above, we just extend the given
240
+ relation and return it again. It is also possible however to just use the
241
+ given relation as a subquery and return a completely new relation:</p>
242
+
243
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>FetchUsersInGroup</span> <span class='op'>&lt;</span> <span class='const'>Inquery</span><span class='op'>::</span><span class='const'>Query</span><span class='op'>::</span><span class='const'>Chainable</span>
244
+ <span class='comment'># Here we do not specify any specific class, as we don&#39;t care for it as long
245
+ </span> <span class='comment'># as the relation returns exactly one field.
246
+ </span> <span class='id identifier rubyid_relation'>relation</span> <span class='label'>fields:</span> <span class='int'>1</span>
247
+
248
+ <span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
249
+ <span class='kw'>return</span> <span class='op'>::</span><span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>%(</span><span class='tstring_content'>
250
+ id IN (
251
+ SELECT user_id FROM GROUPS_USERS WHERE group_id IN (
252
+ </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_relation'>relation</span><span class='period'>.</span><span class='id identifier rubyid_to_sql'>to_sql</span><span class='embexpr_end'>}</span><span class='tstring_content'>
253
+ )
254
+ )
255
+ </span><span class='tstring_end'>)</span></span><span class='rparen'>)</span>
256
+ <span class='kw'>end</span>
257
+ <span class='kw'>end</span>
258
+ </code></pre>
259
+
260
+ <p>This query could then be called in the following ways:</p>
261
+
262
+ <pre class="code ruby"><code class="ruby"><span class='const'>FetchUsersInGroup</span><span class='period'>.</span><span class='id identifier rubyid_run'>run</span><span class='lparen'>(</span>
263
+ <span class='const'>GroupsUser</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='label'>user_id:</span> <span class='int'>1</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_select'>select</span><span class='lparen'>(</span><span class='symbol'>:group_id</span><span class='rparen'>)</span>
264
+ <span class='rparen'>)</span>
265
+
266
+ <span class='comment'># In this example, we&#39;re not specifying any select for the relation we pass to
267
+ </span><span class='comment'># the query class. This is fine because the query automatically defaults to
268
+ </span><span class='comment'># selecting `id` if exactly one field is required (`fields: 1`) and no select is
269
+ </span><span class='comment'># specifyed. You can control this further with the option `default_select`.
270
+ </span><span class='const'>FetchUsersInGroup</span><span class='period'>.</span><span class='id identifier rubyid_run'>run</span><span class='lparen'>(</span><span class='const'>Group</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='label'>color:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>red</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span><span class='rparen'>)</span>
271
+ </code></pre>
272
+
273
+ <h2 id="label-Parameters">Parameters</h2>
274
+
275
+ <p>Both query classes can be parameterized using a hash called
276
+ <code>params</code>. It is recommended to specify and validate input
277
+ parameters in every query. For this purpose, Inquery provides the
278
+ <code>schema</code> method witch integrates the <a
279
+ href="https://github.com/sitrox/schemacop">Schemacop</a> validation Gem:</p>
280
+
281
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>SomeQueryClass</span> <span class='op'>&lt;</span> <span class='const'>Inquery</span><span class='op'>::</span><span class='const'>Query</span>
282
+ <span class='id identifier rubyid_schema'>schema</span><span class='lparen'>(</span>
283
+ <span class='label'>some_param:</span> <span class='symbol'>:integer</span><span class='comma'>,</span>
284
+ <span class='label'>some_other_param:</span> <span class='lbrace'>{</span>
285
+ <span class='label'>hash:</span> <span class='lbrace'>{</span>
286
+ <span class='label'>some_field:</span> <span class='symbol'>:string</span>
287
+ <span class='rbrace'>}</span>
288
+ <span class='rbrace'>}</span>
289
+ <span class='rparen'>)</span>
290
+
291
+ <span class='comment'># ...
292
+ </span><span class='kw'>end</span>
293
+ </code></pre>
294
+
295
+ <p>The schema is validated at query class instantiation. An exception will be
296
+ raised if the given params do not match the schema specified. See
297
+ documentation of the Schemacop Gem for more information on how to specify
298
+ schemas.</p>
299
+
300
+ <p>Parameters can be accessed using either <code>params</code> or
301
+ <code>osparams</code>. The method <code>osparams</code> automatically wraps
302
+ <code>params</code> in an <code>OpenStruct</code> for more convenient
303
+ access.</p>
304
+
305
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>SomeQueryClass</span> <span class='op'>&lt;</span> <span class='const'>Inquery</span><span class='op'>::</span><span class='const'>Query</span>
306
+ <span class='kw'>def</span> <span class='id identifier rubyid_run'>run</span>
307
+ <span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span>
308
+ <span class='label'>active:</span> <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='symbol'>:active</span><span class='rbracket'>]</span><span class='comma'>,</span>
309
+ <span class='label'>username:</span> <span class='id identifier rubyid_osparams'>osparams</span><span class='period'>.</span><span class='id identifier rubyid_search'>search</span>
310
+ <span class='rparen'>)</span>
311
+ <span class='kw'>end</span>
312
+ <span class='kw'>end</span>
313
+ </code></pre>
314
+
315
+ <h2 id="label-Rails+integration">Rails integration</h2>
316
+
317
+ <p>While it is optional, Inquery has been written from the ground up to be
318
+ perfectly integrated into any Rails application. It has proven to be a
319
+ winning concept to extract all complex queries into separate classes that
320
+ are independently executable and testable.</p>
321
+
322
+ <h3 id="label-Directory+structure">Directory structure</h3>
323
+
324
+ <p>While not enforced, it is encouraged to use the following structure for
325
+ storing your query classes:</p>
326
+ <ul><li>
327
+ <p>All domain-specific query classes reside in <code>app/queries</code>.</p>
328
+ </li><li>
329
+ <p>They&#39;re in the module <code>Queries</code>.</p>
330
+ </li><li>
331
+ <p>Queries are further grouped by the model they return (and not the model
332
+ they receive). For instance, a class fetching all active users could be
333
+ located at <code>Queries::User::FetchActive</code> and would reside under
334
+ <code>app/queries/user/fetch_active.rb</code>.</p>
335
+ </li></ul>
336
+
337
+ <p>There are some key benefits to this approach:</p>
338
+ <ul><li>
339
+ <p>As it should, domain-specific code is located within <code>app/</code>.</p>
340
+ </li><li>
341
+ <p>As queries are grouped by the model they return and consistently named,
342
+ they&#39;re easy to locate and it does not take much thought where to put
343
+ and how to name new query classes.</p>
344
+ </li><li>
345
+ <p>As there is a single file per query class, it&#39;s a breeze to list all
346
+ queries, i.e. to check their naming for consistency.</p>
347
+ </li><li>
348
+ <p>If you&#39;re using the same layout for your unit tests, it is absolutely
349
+ clear where to find the corresponding unit tests for each one of your
350
+ query classes.</p>
351
+ </li></ul>
352
+
353
+ <h2 id="label-Copyright">Copyright</h2>
354
+
355
+ <p>Copyright © 2016 Sitrox. See <code>LICENSE</code> for further details.</p>
356
+ </div></div>
357
+
358
+ <div id="footer">
359
+ Generated on Thu Jun 9 10:26:30 2016 by
360
+ <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
361
+ 0.8.7.6 (ruby-2.2.3).
362
+ </div>
363
+
364
+ </body>
365
+ </html>
data/doc/js/app.js ADDED
@@ -0,0 +1,219 @@
1
+ function createSourceLinks() {
2
+ $('.method_details_list .source_code').
3
+ before("<span class='showSource'>[<a href='#' class='toggleSource'>View source</a>]</span>");
4
+ $('.toggleSource').toggle(function() {
5
+ $(this).parent().nextAll('.source_code').slideDown(100);
6
+ $(this).text("Hide source");
7
+ },
8
+ function() {
9
+ $(this).parent().nextAll('.source_code').slideUp(100);
10
+ $(this).text("View source");
11
+ });
12
+ }
13
+
14
+ function createDefineLinks() {
15
+ var tHeight = 0;
16
+ $('.defines').after(" <a href='#' class='toggleDefines'>more...</a>");
17
+ $('.toggleDefines').toggle(function() {
18
+ tHeight = $(this).parent().prev().height();
19
+ $(this).prev().show();
20
+ $(this).parent().prev().height($(this).parent().height());
21
+ $(this).text("(less)");
22
+ },
23
+ function() {
24
+ $(this).prev().hide();
25
+ $(this).parent().prev().height(tHeight);
26
+ $(this).text("more...");
27
+ });
28
+ }
29
+
30
+ function createFullTreeLinks() {
31
+ var tHeight = 0;
32
+ $('.inheritanceTree').toggle(function() {
33
+ tHeight = $(this).parent().prev().height();
34
+ $(this).parent().toggleClass('showAll');
35
+ $(this).text("(hide)");
36
+ $(this).parent().prev().height($(this).parent().height());
37
+ },
38
+ function() {
39
+ $(this).parent().toggleClass('showAll');
40
+ $(this).parent().prev().height(tHeight);
41
+ $(this).text("show all");
42
+ });
43
+ }
44
+
45
+ function fixBoxInfoHeights() {
46
+ $('dl.box dd.r1, dl.box dd.r2').each(function() {
47
+ $(this).prev().height($(this).height());
48
+ });
49
+ }
50
+
51
+ function searchFrameLinks() {
52
+ $('.full_list_link').click(function() {
53
+ toggleSearchFrame(this, $(this).attr('href'));
54
+ return false;
55
+ });
56
+ }
57
+
58
+ function toggleSearchFrame(id, link) {
59
+ var frame = $('#search_frame');
60
+ $('#search a').removeClass('active').addClass('inactive');
61
+ if (frame.attr('src') == link && frame.css('display') != "none") {
62
+ frame.slideUp(100);
63
+ $('#search a').removeClass('active inactive');
64
+ }
65
+ else {
66
+ $(id).addClass('active').removeClass('inactive');
67
+ frame.attr('src', link).slideDown(100);
68
+ }
69
+ }
70
+
71
+ function linkSummaries() {
72
+ $('.summary_signature').click(function() {
73
+ document.location = $(this).find('a').attr('href');
74
+ });
75
+ }
76
+
77
+ function framesInit() {
78
+ if (hasFrames) {
79
+ document.body.className = 'frames';
80
+ $('#menu .noframes a').attr('href', document.location);
81
+ try {
82
+ window.top.document.title = $('html head title').text();
83
+ } catch(error) {
84
+ // some browsers will not allow this when serving from file://
85
+ // but we don't want to stop the world.
86
+ }
87
+ }
88
+ else {
89
+ $('#menu .noframes a').text('frames').attr('href', framesUrl);
90
+ }
91
+ }
92
+
93
+ function keyboardShortcuts() {
94
+ if (window.top.frames.main) return;
95
+ $(document).keypress(function(evt) {
96
+ if (evt.altKey || evt.ctrlKey || evt.metaKey || evt.shiftKey) return;
97
+ if (typeof evt.target !== "undefined" &&
98
+ (evt.target.nodeName == "INPUT" ||
99
+ evt.target.nodeName == "TEXTAREA")) return;
100
+ switch (evt.charCode) {
101
+ case 67: case 99: $('#class_list_link').click(); break; // 'c'
102
+ case 77: case 109: $('#method_list_link').click(); break; // 'm'
103
+ case 70: case 102: $('#file_list_link').click(); break; // 'f'
104
+ default: break;
105
+ }
106
+ });
107
+ }
108
+
109
+ function summaryToggle() {
110
+ $('.summary_toggle').click(function() {
111
+ if (localStorage) {
112
+ localStorage.summaryCollapsed = $(this).text();
113
+ }
114
+ $('.summary_toggle').each(function() {
115
+ $(this).text($(this).text() == "collapse" ? "expand" : "collapse");
116
+ var next = $(this).parent().parent().nextAll('ul.summary').first();
117
+ if (next.hasClass('compact')) {
118
+ next.toggle();
119
+ next.nextAll('ul.summary').first().toggle();
120
+ }
121
+ else if (next.hasClass('summary')) {
122
+ var list = $('<ul class="summary compact" />');
123
+ list.html(next.html());
124
+ list.find('.summary_desc, .note').remove();
125
+ list.find('a').each(function() {
126
+ $(this).html($(this).find('strong').html());
127
+ $(this).parent().html($(this)[0].outerHTML);
128
+ });
129
+ next.before(list);
130
+ next.toggle();
131
+ }
132
+ });
133
+ return false;
134
+ });
135
+ if (localStorage) {
136
+ if (localStorage.summaryCollapsed == "collapse") {
137
+ $('.summary_toggle').first().click();
138
+ }
139
+ else localStorage.summaryCollapsed = "expand";
140
+ }
141
+ }
142
+
143
+ function fixOutsideWorldLinks() {
144
+ $('a').each(function() {
145
+ if (window.location.host != this.host) this.target = '_parent';
146
+ });
147
+ }
148
+
149
+ function generateTOC() {
150
+ if ($('#filecontents').length === 0) return;
151
+ var _toc = $('<ol class="top"></ol>');
152
+ var show = false;
153
+ var toc = _toc;
154
+ var counter = 0;
155
+ var tags = ['h2', 'h3', 'h4', 'h5', 'h6'];
156
+ var i;
157
+ if ($('#filecontents h1').length > 1) tags.unshift('h1');
158
+ for (i = 0; i < tags.length; i++) { tags[i] = '#filecontents ' + tags[i]; }
159
+ var lastTag = parseInt(tags[0][1], 10);
160
+ $(tags.join(', ')).each(function() {
161
+ if ($(this).parents('.method_details .docstring').length != 0) return;
162
+ if (this.id == "filecontents") return;
163
+ show = true;
164
+ var thisTag = parseInt(this.tagName[1], 10);
165
+ if (this.id.length === 0) {
166
+ var proposedId = $(this).attr('toc-id');
167
+ if (typeof(proposedId) != "undefined") this.id = proposedId;
168
+ else {
169
+ var proposedId = $(this).text().replace(/[^a-z0-9-]/ig, '_');
170
+ if ($('#' + proposedId).length > 0) { proposedId += counter; counter++; }
171
+ this.id = proposedId;
172
+ }
173
+ }
174
+ if (thisTag > lastTag) {
175
+ for (i = 0; i < thisTag - lastTag; i++) {
176
+ var tmp = $('<ol/>'); toc.append(tmp); toc = tmp;
177
+ }
178
+ }
179
+ if (thisTag < lastTag) {
180
+ for (i = 0; i < lastTag - thisTag; i++) toc = toc.parent();
181
+ }
182
+ var title = $(this).attr('toc-title');
183
+ if (typeof(title) == "undefined") title = $(this).text();
184
+ toc.append('<li><a href="#' + this.id + '">' + title + '</a></li>');
185
+ lastTag = thisTag;
186
+ });
187
+ if (!show) return;
188
+ html = '<div id="toc"><p class="title"><a class="hide_toc" href="#"><strong>Table of Contents</strong></a> <small>(<a href="#" class="float_toc">left</a>)</small></p></div>';
189
+ $('#content').prepend(html);
190
+ $('#toc').append(_toc);
191
+ $('#toc .hide_toc').toggle(function() {
192
+ $('#toc .top').slideUp('fast');
193
+ $('#toc').toggleClass('hidden');
194
+ $('#toc .title small').toggle();
195
+ }, function() {
196
+ $('#toc .top').slideDown('fast');
197
+ $('#toc').toggleClass('hidden');
198
+ $('#toc .title small').toggle();
199
+ });
200
+ $('#toc .float_toc').toggle(function() {
201
+ $(this).text('float');
202
+ $('#toc').toggleClass('nofloat');
203
+ }, function() {
204
+ $(this).text('left');
205
+ $('#toc').toggleClass('nofloat');
206
+ });
207
+ }
208
+
209
+ $(framesInit);
210
+ $(createSourceLinks);
211
+ $(createDefineLinks);
212
+ $(createFullTreeLinks);
213
+ $(fixBoxInfoHeights);
214
+ $(searchFrameLinks);
215
+ $(linkSummaries);
216
+ $(keyboardShortcuts);
217
+ $(summaryToggle);
218
+ $(fixOutsideWorldLinks);
219
+ $(generateTOC);