mongous 0.1.6 → 0.4.0

data/README.ja.adoc

@@ -4,10 +4,12 @@
 
 == 特徴
 
-* 組込みと標準添付を除いて、mongo driver と bson のみに依存する軽いライブラリである。
-* 項目デフォルト値をブロックで記述できる.
-* 項目制約条件を Array, Range, Proc で記述できる.
-* 保存時および値設定時に制約条件を満たすか検査する.
+* 組込みと標準添付を除いて、mongo driver と bson のみに依存する軽いライブラリである.
+* ドキュメント項目の制約条件を Array, Range, Regexp, Proc インスタンスまたは基本クラスで記述できる.
+* ドキュメント保存時に制約条件を満たすか検査する.
+* ドキュメントの項目値設定時に制約条件を満たすか検査する.
+* ドキュメントの未定義項目の内容を値または Proc で記述できる.
+* ドキュメント作成時および更新時の項目内容を値または Proc で記述できる.
 
 == 導入
 
@@ -30,17 +32,13 @@ gem 'mongous'
 
 == 使い方
 
-=== 簡素な定義
+=== 簡潔な定義
 
 [source,ruby]
 ----
 require  "mongous"
 
-Mongous.connect!
-
-class Book
-  include  Mongous::Document
-end
+Mongous.attach!  :Book
 ----
 
 === 詳細な定義
@@ -54,15 +52,19 @@ Mongous.connect!  ["localhost:27017"], database: "test"
 class Book
   include  Mongous::Document
 
-  field  :title,      String,  :must
+  field  :title,      String,   :must
   field  :author,     String
   field  :publisher,  String
-  field  :style,      String,  ["A4","B5","A5","B6"]
-  field  :price,      Integer, (0..1_000_000)
-  field  :page,       Integer, proc{ page % 4 == 0 }
-  field  :publish_at, Date,    &proc{ Date.today }
-  field  :isbn,       String,  proc{ isbn? }
-  field  :lang,       String,  &proc{ "ja" }
+  field  :style,      String,   %w[hardcover, softcover, paperback]
+  field  :size,       String,   /[AB]\d/
+  field  :price,      Integer,  (0..1_000_000)
+  field  :page,       Integer,  proc{ page % 4 == 0 }
+  field  :isbn,       String,   proc{ isbn? }
+  field  :lang,       String,   default: "en"
+  field  :created_at, Time,     create: proc{ Time.now }
+  field  :updated_at, Time,     update: proc{ Time.now }
+
+  filter :foobar,     {title: /foobar/}
 
   verify :strict
   verify do
@@ -84,13 +86,13 @@ end
 book = Book.new
 book.title = "title 1"
 book.price = 1000
-book.style = "A4"
+book.size = "A4"
 book.save
 
-book = Book.new( title: "title 2", price: 2000, style: "A5" )
+book = Book.new( title: "title 2", price: 2000, size: "A5" )
 book.save
 
-doc = { title: "title 3", price: 3000, style: "A6" }
+doc = { title: "title 3", price: 3000, size: "A6" }
 Book.create( **doc )
 ----
 
@@ -100,44 +102,56 @@ Book.create( **doc )
 ----
 pp books = Book.all
 
-p book = Book.filter( title: "title 1" ).first
+p book = Book.where( title: "title 1" ).first
 
-books = Book.filter( title: /title/ ).all
+books = Book.where( title: /title/ ).all
 books.each do |book|
   p book
 end
 
-Book.filter( title: /title/ ).projection( _id: 0 ).each do |book|
+Book.where( title: /title/ ).projection( _id: 0 ).each do |book|
   p book
 end
 
-Book.filter( price: (1..2000), style: ["A4","A5"] ).each do |book|
+Book.where( price: (1..2000), size: ["A4","A5"] ).each do |book|
   p book
 end
 
-filter1 = Book.filter( title: /title/ )
-filter2 = Book.filter( price: (1..2000) )
-filter3 = Book.filter( style: ["A4","A5"] )
+filter1 = Book.where( title: /title/ )
+filter2 = Book.where( :foobar )
+filter3 = Book.where( price: (1..2000) )
+filter4 = Book.where( size: ["A4","A5"] )
+
 Book.not( filter1 ).each do |book|
   p book
 end
-Book.and( filter1, filter2 ).each do |book|
+Book.and( filter1, filter3 ).each do |book|
+  p book
+end
+Book.or( filter2, filter4 ).each do |book|
+  p book
+end
+
+Book.find( { title: /title/ }, { projection: {_id: 0} } ).each do |book|
   p book
 end
-Book.or( filter1, filter3 ).each do |book|
+
+Book.where( title: /title/ ).select( _id: 0 ).each do |book|
   p book
 end
 
-Book.find( {}, { projection: {_id: 0} } ).each do |book|
+Book.select( _id: 0 )[0, 5].each do |book|
   p book
 end
+
+pp Book.select( :title, :price, :size )[5, 5].all
 ----
 
 === ドキュメント更新
 
 [source,ruby]
 ----
-book = Book.filter( title: "title 1" ).first
+book = Book.where( title: "title 1" ).first
 book.title = "title 1 [update]"
 book.save
 ----
@@ -146,7 +160,7 @@ book.save
 
 [source,ruby]
 ----
-book = Book.filter( title: "title 1" ).first
+book = Book.where( title: "title 1" ).first
 book.delete
 ----
 
@@ -156,7 +170,7 @@ book.delete
 
 [source,ruby]
 ----
-Mongous.connect!( hosts_or_uri = nil, **opts )
+Mongous.connect!( hosts_or_uri = nil, **options )
 ----
 
 * Result:
@@ -164,38 +178,116 @@ Mongous.connect!( hosts_or_uri = nil, **opts )
 
 * Parameter:
   ** hosts_or_uri:    ホスト配列または URI (default: ["localhost:21017"])
-  ** opts:            オプション
+  ** options:         オプション
     *** file:         データベース構成定義ファイルへのパス
     *** mode:         実行モード (default: "development")
     *** database:     データベース名 (default: "test")
-    *** *             Mongo::Client.new のその他オプション引数
+    ***               Mongo::Client.new のその他オプション引数
 
 === データベースに接続する
 
 [source,ruby]
 ----
-Mongous.connect( hosts_or_uri = nil, **opts )
+Mongous.connect( hosts_or_uri = nil, **options )
 ----
 
 * Result:
-  ** Mongo::Client.
+  ** Mongo::Client インスタンス.
 
-=== ドキュメントの機能を取り入れる.
+=== コレクション操作クラスをデフォルト設定で定義する.
+
+[source,ruby]
+----
+Mongous.attach!( *names )
+----
+
+* Result:
+  ** nil.
+
+* Parameter:
+  ** names:           コレクション名. (String または Symbol)
+
+=== コレクション操作クラスにドキュメントの機能を取り入れる.
 
 [source,ruby]
 ----
 include Mongous::Document
 ----
 
+=== 別のデータベースを割り当てる.
+
+[source,ruby]
+----
+self.client=( client )
+----
+
+* Result:
+  ** Mongo::Client インスタンス.
+
+* Parameter:
+  ** client:          Mongo::Client インスタンス.
+
+=== Get binded database.
+
+[source,ruby]
+----
+self.client
+----
+
+* Result:
+  ** Mongo::Client インスタンス.
+
+* Parameter:
+  ** None.
+
+=== 別のコレクションを割り当てる.
+
+[source,ruby]
+----
+self.collection_name=( collection_name )
+----
+
+* Result:
+  ** Collection name 文字列.
+
+* Parameter:
+  ** collection_name: コレクション名.
+
+=== Get binded collection name.
+
+[source,ruby]
+----
+self.collection_name
+----
+
+* Result:
+  ** Collection name 文字列.
+
+* Parameter:
+  ** None.
+
+=== Get collection.
+
+[source,ruby]
+----
+self.collection( collection_name = nil )
+----
+
+* Result:
+  ** Mongo::Collection インスタンス.
+
+* Parameter:
+  ** collection_name: 一時指定するコレクション名.
+
 === ドキュメントの要素を定義する.
 
 [source,ruby]
 ----
-field( label, *attrs, &block )
+self.field( symbol, *attrs, **items )
 ----
 
 * Parameter:
-  ** label:           項目名シンボル
+  ** symbol:          項目名
   ** attrs:           項目属性
     *** Class:        項目検証用 Class
     *** Proc:         項目検証用 Proc
@@ -203,17 +295,20 @@ field( label, *attrs, &block )
     *** Array:        項目検証用配列
     *** Symbol:       特別な指示子
       **** must:      ナル値でも空文字列でもない
-  ** block:           デフォルト値を返す
+  ** items:           保存時の操作.
+    *** default:      未定義のときの値または Proc.
+    *** create:       ドキュメントを新規保存するときの値または Proc.
+    *** update:       ドキュメントを更新するときの値または Proc.
 
 === 保存や代入の前にドキュメントの要素を検証する.
 
 [source,ruby]
 ----
-verify( *syms, &block )
+self.verify( *directives, &block )
 ----
 
 * Parameter:
-  ** syms:            条件シンボル
+  ** directives:      条件シンボル
     *** strict:       定義済み項目名であることを検証する.
   ** block:           各項目値を検証して真偽を返す内容を記述する.
 
@@ -221,18 +316,18 @@ verify( *syms, &block )
 
 [source,ruby]
 ----
-index( *syms, **opts )
+self.index( *symbols, **options )
 ----
 
 * Parameter:
-  ** syms:            項目名シンボル
-  ** opts:            Mongo::Collection#indexes() のオプション.
+  ** symbols:         項目名
+  ** options:         Mongo::Collection#indexes() のオプション.
 
 === 項目値がナル値でも空文字列でもないことを検証する.
 
 [source,ruby]
 ----
-having?( label )
+self.having?( label )
 ----
 
 * Result:
@@ -241,6 +336,161 @@ having?( label )
 * Parameter:
   ** label:           メソッド呼び出しする項目名.
 
+=== 検索条件に名前をつける.
+
+[source,ruby]
+----
+self.filter( symbol, filter_or_cond )
+----
+
+* Parameter:
+  ** symbol:          項目名
+  ** filter_or_cond:  フィルタまたは検索条件
+
+=== 出力項目を選択する.
+
+[source,ruby]
+----
+Mongous::Document.select( *keys, **kwargs )
+Mongous::Filter#select( *keys, **kwargs )
+----
+
+* Result:
+  ** Mongous::Filter instance.
+
+* Parameter:
+  ** keys:            項目名
+  ** kwargs:          項目名と項目値.
+
+=== 検索条件.
+
+[source,ruby]
+----
+Mongous::Document.where( filter = nil, **conditions )
+Mongous::Filter#where( filter = nil, **conditions )
+----
+
+* Result:
+  ** Mongous::Filter instance.
+
+* Parameter:
+  ** filter:          項目名またはフィルタインスタンス
+  ** conditions:      検索条件
+
+=== 否定検索条件.
+
+[source,ruby]
+----
+Mongous::Document.not( filter = nil, **conditions )
+Mongous::Filter#not( filter = nil, **conditions )
+----
+
+* Result:
+  ** Mongous::Filter instance.
+
+* Parameter:
+  ** filter:          項目名またはフィルタインスタンス
+  ** conditions:      検索条件
+
+=== 論理積検索条件.
+
+[source,ruby]
+----
+Mongous::Document.and( *filters )
+Mongous::Filter#and( *filters )
+----
+
+* Result:
+  ** Mongous::Filter instance.
+
+* Parameter:
+  ** filters:         項目名またはフィルタインスタンス
+
+=== 論理和検索条件.
+
+[source,ruby]
+----
+Mongous::Document.or( *filters )
+Mongous::Filter#or( *filters )
+----
+
+* Result:
+  ** Mongous::Filter instance.
+
+* Parameter:
+  ** filters:         項目名またはフィルタインスタンス
+
+=== ドキュメントを作成.
+
+[source,ruby]
+----
+Mongous::Document.create( **doc )
+----
+
+* Result:
+  ** nil.
+
+* Parameter:
+  ** doc:             キーワード引数.
+
+=== ドキュメントを保存.
+
+[source,ruby]
+----
+Mongous::Document#save
+----
+
+* Result:
+  ** nil.
+
+=== ドキュメントをHashに変換.
+
+[source,ruby]
+----
+Mongous::Document#to_hash
+----
+
+* Result:
+  ** Hash object.
+
+=== ドキュメントをJSONに変換.
+
+[source,ruby]
+----
+Mongous::Document#to_json
+----
+
+* Result:
+  ** JSON String.
+
+=== ドキュメントの項目値を読む.
+
+[source,ruby]
+----
+Mongous::Document#[]( field_name )
+Mongous::Document#field_name
+----
+
+* Result:
+  ** 項目値.
+
+* Parameter:
+  ** field_name:      項目名.
+
+=== ドキュメントの項目値を書く.
+
+[source,ruby]
+----
+Mongous::Document#[]=( field_name, field_value )
+Mongous::Document#field_name = field_value
+----
+
+* Result:
+  ** 項目値.
+
+* Parameter:
+  ** field_name:      項目名.
+  ** field_value:     項目値.
 
 == 貢献