mongous 0.1.8 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. checksums.yaml +4 -4
  2. data/README.adoc +286 -48
  3. data/README.ja.adoc +288 -50
  4. data/lib/mongous/base.rb +45 -2
  5. data/lib/mongous/document.rb +75 -32
  6. data/lib/mongous/extention.rb +74 -55
  7. data/lib/mongous/filter.rb +316 -233
  8. data/lib/mongous/version.rb +1 -1
  9. data/mongous.gemspec +1 -1
  10. data/sample/connect_auto_0.rb +9 -0
  11. data/sample/declare_compact_1.rb +7 -9
  12. data/sample/declare_compact_2.rb +38 -0
  13. data/sample/declare_label_1.rb +10 -8
  14. data/sample/declare_ndex_1.rb +9 -7
  15. data/sample/declare_ndex_2.rb +10 -8
  16. data/sample/declare_strict_1.rb +14 -12
  17. data/sample/declare_strict_2.rb +5 -5
  18. data/sample/{multi_docs_1.rb → multi_collection_1.rb} +0 -2
  19. data/sample/multi_collection_2.rb +61 -0
  20. data/sample/multi_collection_3.rb +24 -0
  21. data/sample/query_basic_1.rb +8 -3
  22. data/sample/query_basic_2.rb +11 -6
  23. data/sample/query_basic_3.rb +2 -5
  24. data/sample/query_basic_4.rb +3 -6
  25. data/sample/query_basic_5.rb +2 -5
  26. data/sample/query_basic_6.rb +35 -22
  27. data/sample/query_detail_1.rb +3 -3
  28. data/sample/query_detail_2.rb +3 -3
  29. data/sample/query_detail_3.rb +5 -5
  30. data/sample/query_filter_1.rb +44 -0
  31. data/sample/query_filter_2.rb +48 -0
  32. data/sample/{query_super_1.rb → query_find_1.rb} +6 -6
  33. data/sample/query_select_1.rb +54 -0
  34. data/sample/query_skip_limit_1.rb +48 -0
  35. data/sample/query_skip_limit_2.rb +58 -0
  36. data/sample/query_sort_1.rb +43 -0
  37. data/sample/save_basic_1.rb +2 -7
  38. data/sample/save_basic_2.rb +2 -7
  39. data/sample/save_basic_3.rb +2 -7
  40. data/sample/save_detail_1.rb +7 -6
  41. data/sample/save_detail_2.rb +7 -6
  42. data/sample/save_detail_3.rb +11 -10
  43. data/sample/save_verify_1.rb +7 -6
  44. data/sample/save_verify_2.rb +0 -2
  45. data/sample/save_verify_3.rb +1 -3
  46. data/sample/save_verify_4.rb +0 -2
  47. data/sample/save_verify_5.rb +3 -5
  48. data/sample/save_verify_6.rb +3 -5
  49. data/sample/save_verify_7.rb +21 -0
  50. data/sample/update_basic_1.rb +9 -0
  51. data/sample/zap_basic_1.rb +1 -5
  52. data/sample/zap_basic_2.rb +2 -6
  53. data/sample/zap_basic_3.rb +2 -6
  54. data/sample/zbenchmark_search_1.rb +114 -0
  55. data/sample/zbenchmark_search_2.rb +114 -0
  56. data/sample/zbenchmark_search_3.rb +88 -0
  57. metadata +20 -12
  58. data/sample/multi_docs_2.rb +0 -58
  59. data/sample/query_basic_7.rb +0 -38
  60. data/sample/query_limit_1.rb +0 -44
  61. data/sample/query_order_1.rb +0 -49
  62. data/sample/query_projection_1.rb +0 -44
  63. data/sample/template_article.rb +0 -5
  64. data/sample/template_person.rb +0 -12
@@ -4,10 +4,12 @@
4
4
 
5
5
  == 特徴
6
6
 
7
- * 組込みと標準添付を除いて、mongo driver と bson のみに依存する軽いライブラリである。
8
- * 項目デフォルト値をブロックで記述できる.
9
- * 項目制約条件を Array, Range, Proc で記述できる.
10
- * 保存時および値設定時に制約条件を満たすか検査する.
7
+ * 組込みと標準添付を除いて、mongo driver と bson のみに依存する軽いライブラリである.
8
+ * ドキュメント項目の制約条件を Array, Range, Regexp, Proc インスタンスまたは基本クラスで記述できる.
9
+ * ドキュメント保存時に制約条件を満たすか検査する.
10
+ * ドキュメントの項目値設定時に制約条件を満たすか検査する.
11
+ * ドキュメントの未定義項目の内容を値または Proc で記述できる.
12
+ * ドキュメント作成時および更新時の項目内容を値または Proc で記述できる.
11
13
 
12
14
  == 導入
13
15
 
@@ -30,17 +32,13 @@ gem 'mongous'
30
32
 
31
33
  == 使い方
32
34
 
33
- === 簡素な定義
35
+ === 簡潔な定義
34
36
 
35
37
  [source,ruby]
36
38
  ----
37
39
  require "mongous"
38
40
 
39
- Mongous.connect!
40
-
41
- class Book
42
- include Mongous::Document
43
- end
41
+ Mongous.document! :Book
44
42
  ----
45
43
 
46
44
  === 詳細な定義
@@ -54,15 +52,19 @@ Mongous.connect! ["localhost:27017"], database: "test"
54
52
  class Book
55
53
  include Mongous::Document
56
54
 
57
- field :title, String, :must
55
+ field :title, String, :must
58
56
  field :author, String
59
57
  field :publisher, String
60
- field :style, String, ["A4","B5","A5","B6"]
61
- field :price, Integer, (0..1_000_000)
62
- field :page, Integer, proc{ page % 4 == 0 }
63
- field :publish_at, Date, &proc{ Date.today }
64
- field :isbn, String, proc{ isbn? }
65
- field :lang, String, &proc{ "ja" }
58
+ field :style, String, %w[hardcover, softcover, paperback]
59
+ field :size, String, /[AB]\d/
60
+ field :price, Integer, (0..1_000_000)
61
+ field :page, Integer, proc{ page % 4 == 0 }
62
+ field :isbn, String, proc{ isbn? }
63
+ field :lang, String, default: "en"
64
+ field :created_at, Time, create: proc{ Time.now }
65
+ field :updated_at, Time, update: proc{ Time.now }
66
+
67
+ filter :foobar, {title: /foobar/}
66
68
 
67
69
  verify :strict
68
70
  verify do
@@ -84,13 +86,13 @@ end
84
86
  book = Book.new
85
87
  book.title = "title 1"
86
88
  book.price = 1000
87
- book.style = "A4"
89
+ book.size = "A4"
88
90
  book.save
89
91
 
90
- book = Book.new( title: "title 2", price: 2000, style: "A5" )
92
+ book = Book.new( title: "title 2", price: 2000, size: "A5" )
91
93
  book.save
92
94
 
93
- doc = { title: "title 3", price: 3000, style: "A6" }
95
+ doc = { title: "title 3", price: 3000, size: "A6" }
94
96
  Book.create( **doc )
95
97
  ----
96
98
 
@@ -100,31 +102,34 @@ Book.create( **doc )
100
102
  ----
101
103
  pp books = Book.all
102
104
 
103
- p book = Book.filter( title: "title 1" ).first
105
+ p book = Book.where( title: /title/ ).first
106
+ p book = Book.where( title: /title/ ).last
104
107
 
105
- books = Book.filter( title: /title/ ).all
108
+ books = Book.where( title: /title/ ).all
106
109
  books.each do |book|
107
110
  p book
108
111
  end
109
112
 
110
- Book.filter( title: /title/ ).projection( _id: 0 ).each do |book|
113
+ Book.where( title: /title/ ).projection( _id: 0 ).each do |book|
111
114
  p book
112
115
  end
113
116
 
114
- Book.filter( price: (1..2000), style: ["A4","A5"] ).each do |book|
117
+ Book.where( price: (1..2000), size: ["A4","A5"] ).each do |book|
115
118
  p book
116
119
  end
117
120
 
118
- filter1 = Book.filter( title: /title/ )
119
- filter2 = Book.filter( price: (1..2000) )
120
- filter3 = Book.filter( style: ["A4","A5"] )
121
+ filter1 = Book.where( title: /title/ )
122
+ filter2 = Book.where( :foobar )
123
+ filter3 = Book.where( price: (1..2000) )
124
+ filter4 = Book.where( size: ["A4","A5"] )
125
+
121
126
  Book.not( filter1 ).each do |book|
122
127
  p book
123
128
  end
124
- Book.and( filter1, filter2 ).each do |book|
129
+ Book.and( filter1, filter3 ).each do |book|
125
130
  p book
126
131
  end
127
- Book.or( filter1, filter3 ).each do |book|
132
+ Book.or( filter2, filter4 ).each do |book|
128
133
  p book
129
134
  end
130
135
 
@@ -132,14 +137,22 @@ Book.find( { title: /title/ }, { projection: {_id: 0} } ).each do |book|
132
137
  p book
133
138
  end
134
139
 
135
- pp Book.filter( title: /title/ )[0, 5].all
140
+ Book.where( title: /title/ ).select( _id: 0 ).each do |book|
141
+ p book
142
+ end
143
+
144
+ Book.select( _id: 0 )[0, 5].each do |book|
145
+ p book
146
+ end
147
+
148
+ pp Book.select( :title, :price, :size )[5, 5].all
136
149
  ----
137
150
 
138
151
  === ドキュメント更新
139
152
 
140
153
  [source,ruby]
141
154
  ----
142
- book = Book.filter( title: "title 1" ).first
155
+ book = Book.where( title: "title 1" ).first
143
156
  book.title = "title 1 [update]"
144
157
  book.save
145
158
  ----
@@ -148,7 +161,7 @@ book.save
148
161
 
149
162
  [source,ruby]
150
163
  ----
151
- book = Book.filter( title: "title 1" ).first
164
+ book = Book.where( title: "title 1" ).first
152
165
  book.delete
153
166
  ----
154
167
 
@@ -158,7 +171,7 @@ book.delete
158
171
 
159
172
  [source,ruby]
160
173
  ----
161
- Mongous.connect!( hosts_or_uri = nil, **opts )
174
+ Mongous.connect!( hosts_or_uri = nil, **options )
162
175
  ----
163
176
 
164
177
  * Result:
@@ -166,23 +179,38 @@ Mongous.connect!( hosts_or_uri = nil, **opts )
166
179
 
167
180
  * Parameter:
168
181
  ** hosts_or_uri: ホスト配列または URI (default: ["localhost:21017"])
169
- ** opts: オプション
182
+ ** options: オプション
170
183
  *** file: データベース構成定義ファイルへのパス
171
184
  *** mode: 実行モード (default: "development")
172
185
  *** database: データベース名 (default: "test")
173
- *** * Mongo::Client.new のその他オプション引数
186
+ *** Mongo::Client.new のその他オプション引数
174
187
 
175
188
  === データベースに接続する
176
189
 
177
190
  [source,ruby]
178
191
  ----
179
- Mongous.connect( hosts_or_uri = nil, **opts )
192
+ Mongous.connect( hosts_or_uri = nil, **options )
193
+ ----
194
+
195
+ * Result:
196
+ ** Mongo::Client インスタンス.
197
+
198
+ === コレクション操作クラスをデフォルト設定で定義する.
199
+
200
+ [source,ruby]
201
+ ----
202
+ Mongous.document!( *names, **options )
180
203
  ----
181
204
 
182
205
  * Result:
183
- ** Mongo::Client.
206
+ ** nil.
184
207
 
185
- === ドキュメントの機能を取り入れる.
208
+ * Parameter:
209
+ ** names: コレクション名. (String または Symbol)
210
+ ** options: オプション
211
+ *** timestamp: 真のとき, フィールド :created_at, :updated_at を追加する.
212
+
213
+ === コレクション操作クラスにドキュメントの機能を取り入れる.
186
214
 
187
215
  [source,ruby]
188
216
  ----
@@ -193,24 +221,76 @@ include Mongous::Document
193
221
 
194
222
  [source,ruby]
195
223
  ----
196
- set_client( client )
224
+ self.client=( client )
197
225
  ----
198
226
 
199
227
  * Result:
200
- ** nil.
228
+ ** Mongo::Client インスタンス.
229
+
230
+ * Parameter:
231
+ ** client: Mongo::Client インスタンス.
232
+
233
+ === Get binded database.
234
+
235
+ [source,ruby]
236
+ ----
237
+ self.client
238
+ ----
239
+
240
+ * Result:
241
+ ** Mongo::Client インスタンス.
242
+
243
+ * Parameter:
244
+ ** None.
245
+
246
+ === 別のコレクションを割り当てる.
247
+
248
+ [source,ruby]
249
+ ----
250
+ self.collection_name=( collection_name )
251
+ ----
252
+
253
+ * Result:
254
+ ** Collection name 文字列.
255
+
256
+ * Parameter:
257
+ ** collection_name: コレクション名.
258
+
259
+ === Get binded collection name.
260
+
261
+ [source,ruby]
262
+ ----
263
+ self.collection_name
264
+ ----
265
+
266
+ * Result:
267
+ ** Collection name 文字列.
201
268
 
202
269
  * Parameter:
203
- ** client: Mongo::Client instance.
270
+ ** None.
271
+
272
+ === Get collection.
273
+
274
+ [source,ruby]
275
+ ----
276
+ self.collection( collection_name = nil )
277
+ ----
278
+
279
+ * Result:
280
+ ** Mongo::Collection インスタンス.
281
+
282
+ * Parameter:
283
+ ** collection_name: 一時指定するコレクション名.
204
284
 
205
285
  === ドキュメントの要素を定義する.
206
286
 
207
287
  [source,ruby]
208
288
  ----
209
- field( label, *attrs, &block )
289
+ self.field( symbol, *attrs, **items )
210
290
  ----
211
291
 
212
292
  * Parameter:
213
- ** label: 項目名シンボル
293
+ ** symbol: 項目名
214
294
  ** attrs: 項目属性
215
295
  *** Class: 項目検証用 Class
216
296
  *** Proc: 項目検証用 Proc
@@ -218,17 +298,20 @@ field( label, *attrs, &block )
218
298
  *** Array: 項目検証用配列
219
299
  *** Symbol: 特別な指示子
220
300
  **** must: ナル値でも空文字列でもない
221
- ** block: デフォルト値を返す
301
+ ** items: 保存時の操作.
302
+ *** default: 未定義のときの値または Proc.
303
+ *** create: ドキュメントを新規保存するときの値または Proc.
304
+ *** update: ドキュメントを更新するときの値または Proc.
222
305
 
223
306
  === 保存や代入の前にドキュメントの要素を検証する.
224
307
 
225
308
  [source,ruby]
226
309
  ----
227
- verify( *syms, &block )
310
+ self.verify( *directives, &block )
228
311
  ----
229
312
 
230
313
  * Parameter:
231
- ** syms: 条件シンボル
314
+ ** directives: 条件シンボル
232
315
  *** strict: 定義済み項目名であることを検証する.
233
316
  ** block: 各項目値を検証して真偽を返す内容を記述する.
234
317
 
@@ -236,18 +319,18 @@ verify( *syms, &block )
236
319
 
237
320
  [source,ruby]
238
321
  ----
239
- index( *syms, **opts )
322
+ self.index( *symbols, **options )
240
323
  ----
241
324
 
242
325
  * Parameter:
243
- ** syms: 項目名シンボル
244
- ** opts: Mongo::Collection#indexes() のオプション.
326
+ ** symbols: 項目名
327
+ ** options: Mongo::Collection#indexes() のオプション.
245
328
 
246
329
  === 項目値がナル値でも空文字列でもないことを検証する.
247
330
 
248
331
  [source,ruby]
249
332
  ----
250
- having?( label )
333
+ self.having?( label )
251
334
  ----
252
335
 
253
336
  * Result:
@@ -256,6 +339,161 @@ having?( label )
256
339
  * Parameter:
257
340
  ** label: メソッド呼び出しする項目名.
258
341
 
342
+ === 検索条件に名前をつける.
343
+
344
+ [source,ruby]
345
+ ----
346
+ self.filter( symbol, filter_or_cond )
347
+ ----
348
+
349
+ * Parameter:
350
+ ** symbol: 項目名
351
+ ** filter_or_cond: フィルタまたは検索条件
352
+
353
+ === 出力項目を選択する.
354
+
355
+ [source,ruby]
356
+ ----
357
+ Mongous::Document.select( *keys, **kwargs )
358
+ Mongous::Filter#select( *keys, **kwargs )
359
+ ----
360
+
361
+ * Result:
362
+ ** Mongous::Filter instance.
363
+
364
+ * Parameter:
365
+ ** keys: 項目名
366
+ ** kwargs: 項目名と項目値.
367
+
368
+ === 検索条件.
369
+
370
+ [source,ruby]
371
+ ----
372
+ Mongous::Document.where( filter = nil, **conditions )
373
+ Mongous::Filter#where( filter = nil, **conditions )
374
+ ----
375
+
376
+ * Result:
377
+ ** Mongous::Filter instance.
378
+
379
+ * Parameter:
380
+ ** filter: 項目名またはフィルタインスタンス
381
+ ** conditions: 検索条件
382
+
383
+ === 否定検索条件.
384
+
385
+ [source,ruby]
386
+ ----
387
+ Mongous::Document.not( filter = nil, **conditions )
388
+ Mongous::Filter#not( filter = nil, **conditions )
389
+ ----
390
+
391
+ * Result:
392
+ ** Mongous::Filter instance.
393
+
394
+ * Parameter:
395
+ ** filter: 項目名またはフィルタインスタンス
396
+ ** conditions: 検索条件
397
+
398
+ === 論理積検索条件.
399
+
400
+ [source,ruby]
401
+ ----
402
+ Mongous::Document.and( *filters )
403
+ Mongous::Filter#and( *filters )
404
+ ----
405
+
406
+ * Result:
407
+ ** Mongous::Filter instance.
408
+
409
+ * Parameter:
410
+ ** filters: 項目名またはフィルタインスタンス
411
+
412
+ === 論理和検索条件.
413
+
414
+ [source,ruby]
415
+ ----
416
+ Mongous::Document.or( *filters )
417
+ Mongous::Filter#or( *filters )
418
+ ----
419
+
420
+ * Result:
421
+ ** Mongous::Filter instance.
422
+
423
+ * Parameter:
424
+ ** filters: 項目名またはフィルタインスタンス
425
+
426
+ === ドキュメントを作成.
427
+
428
+ [source,ruby]
429
+ ----
430
+ Mongous::Document.create( **doc )
431
+ ----
432
+
433
+ * Result:
434
+ ** nil.
435
+
436
+ * Parameter:
437
+ ** doc: キーワード引数.
438
+
439
+ === ドキュメントを保存.
440
+
441
+ [source,ruby]
442
+ ----
443
+ Mongous::Document#save
444
+ ----
445
+
446
+ * Result:
447
+ ** nil.
448
+
449
+ === ドキュメントをHashに変換.
450
+
451
+ [source,ruby]
452
+ ----
453
+ Mongous::Document#to_hash
454
+ ----
455
+
456
+ * Result:
457
+ ** Hash object.
458
+
459
+ === ドキュメントをJSONに変換.
460
+
461
+ [source,ruby]
462
+ ----
463
+ Mongous::Document#to_json
464
+ ----
465
+
466
+ * Result:
467
+ ** JSON String.
468
+
469
+ === ドキュメントの項目値を読む.
470
+
471
+ [source,ruby]
472
+ ----
473
+ Mongous::Document#[]( field_name )
474
+ Mongous::Document#field_name
475
+ ----
476
+
477
+ * Result:
478
+ ** 項目値.
479
+
480
+ * Parameter:
481
+ ** field_name: 項目名.
482
+
483
+ === ドキュメントの項目値を書く.
484
+
485
+ [source,ruby]
486
+ ----
487
+ Mongous::Document#[]=( field_name, field_value )
488
+ Mongous::Document#field_name = field_value
489
+ ----
490
+
491
+ * Result:
492
+ ** 項目値.
493
+
494
+ * Parameter:
495
+ ** field_name: 項目名.
496
+ ** field_value: 項目値.
259
497
 
260
498
  == 貢献
261
499