mongous 0.1.8 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ac08d4dc3cd1b50de8ae75c4db5f63b9604abefa5890f046564d44619d75cf4
-  data.tar.gz: 446aae2fcd699ad4a27cc5f15790a00d84eaceff3e38ef4ded3b5aec425dcba4
+  metadata.gz: 8b0a73aa23287619bdae717f683f04e266d582dca4a6d055b798cf32243c6566
+  data.tar.gz: 14e22dcbf25b3a0fa200023c9f770c549607060ddb03057b32c8c1ccee3b58c2
 SHA512:
-  metadata.gz: ce0e4ff3b90f13ac1bdb328ecac4c8986120e780575dbb97a242638d2cfd2c11581963cc2141c2f09f3a184cdcef85420354f4a12d02eca890c66b1458c9ea8e
-  data.tar.gz: 6e78c1a620e8cdc974e9e60bca01f54b0127b225a7e1e0f567c7354ec7d43adf1cd2e3ffa72859f6805ffcacd8b3a198258763a4f14ab0f216b6f4d585d56e0d
+  metadata.gz: b37766d78679cc2a6bee8bfe256da0a363344b6e349552f0491d5a0892fa1dfeb7cca90d4b2e326ac7687cdd2c3a0561fdfe9fca4ce71382029077d8c289e6de
+  data.tar.gz: b5e9fee3f8f9d4f34d5203b9b260559d8ee1ca86e659d85629ef9c1b700bcfcb450b7ffc0447b7f3fa8c4245634f2e968619f9ba451c9591016e13c07d23060f

data/README.adoc

@@ -5,9 +5,11 @@ Yet another mongo wrapper library.
 == Features
 
 * A light library that depends only on the mongo driver and bson, except for built-in and standard attachments.
-* Item default value can be described in the block.
-* Item constraints can be described by Array, Range, and Proc.
-* Checks that constraints are met when saving and setting values.
+* Document item constraints can be described in Array, Range, Regexp, Proc instances, or base classes.
+* Check if the constraint conditions are met when saving the document.
+* Check if the constraint condition is satisfied when setting the item value of the document.
+* The contents of undefined items in the document can be described by value or Proc.
+* Item contents at the time of document creation and update can be described by value or Proc.
 
 == Installation
 
@@ -36,11 +38,7 @@ Or install it yourself as:
 ----
 require  "mongous"
 
-Mongous.connect!
-
-class Book
-  include  Mongous::Document
-end
+Mongous.document!  :Book
 ----
 
 === Detail declaration
@@ -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,31 +102,34 @@ Book.create( **doc )
 ----
 pp books = Book.all
 
-p book = Book.filter( title: "title 1" ).first
+p book = Book.where( title: /title/ ).first
+p book = Book.where( title: /title/ ).last
 
-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( filter1, filter3 ).each do |book|
+Book.or( filter2, filter4 ).each do |book|
   p book
 end
 
@@ -132,14 +137,22 @@ Book.find( { title: /title/ }, { projection: {_id: 0} } ).each do |book|
   p book
 end
 
-pp Book.filter( title: /title/ )[0, 5].all
+Book.where( title: /title/ ).select( _id: 0 ).each do |book|
+  p book
+end
+
+Book.select( _id: 0 )[0, 5].each do |book|
+  p book
+end
+
+pp Book.select( :title, :price, :size )[5, 5].all
 ----
 
 === Update document
 
 [source,ruby]
 ----
-book = Book.filter( title: "title 1" ).first
+book = Book.where( title: "title 1" ).first
 book.title = "title 1 [update]"
 book.save
 ----
@@ -148,7 +161,7 @@ book.save
 
 [source,ruby]
 ----
-book = Book.filter( title: "title 1" ).first
+book = Book.where( title: "title 1" ).first
 book.delete
 ----
 
@@ -158,7 +171,7 @@ book.delete
 
 [source,ruby]
 ----
-Mongous.connect!( hosts_or_uri = nil, **opts )
+Mongous.connect!( hosts_or_uri = nil, **options )
 ----
 
 * Result:
@@ -166,23 +179,38 @@ Mongous.connect!( hosts_or_uri = nil, **opts )
 
 * Parameter:
   ** hosts_or_uri:    Array of hosts, or URI (default: ["localhost:21017"])
-  ** opts:            Options.
+  ** options:         Options.
     *** file:         Path to database configuration file.
     *** mode:         Execution mode. (default: "development")
     *** database:     Database name. (default: "test")
-    *** *             Other optional arguments for Mongo::Client.new.
+    ***               Other optional arguments for Mongo::Client.new.
 
 === Connect database.
 
 [source,ruby]
 ----
-Mongous.connect( hosts_or_uri = nil, **opts )
+Mongous.connect( hosts_or_uri = nil, **options )
+----
+
+* Result:
+  ** Mongo::Client instance.
+
+=== Define collection operate class with default settings.
+
+[source,ruby]
+----
+Mongous.document!( *names, **options )
 ----
 
 * Result:
-  ** Mongo::Client.
+  ** nil.
 
-=== Include document functions.
+* Parameter:
+  ** names:           Collection names. (String or Symbol)
+  ** options:         Options.
+    *** timestamp:    If true then add fields :created_at, :updated_at.
+
+=== Include document functions into collection operate class.
 
 [source,ruby]
 ----
@@ -193,42 +221,97 @@ include Mongous::Document
 
 [source,ruby]
 ----
-set_client( client )
+self.client=( client )
 ----
 
 * Result:
-  ** nil.
+  ** Mongo::Client instance.
 
 * Parameter:
   ** client:          Mongo::Client instance.
 
+=== Get binded database.
+
+[source,ruby]
+----
+self.client
+----
+
+* Result:
+  ** Mongo::Client instance.
+
+* Parameter:
+  ** None.
+
+=== Bind another collection.
+
+[source,ruby]
+----
+self.collection_name=( _collection_name )
+----
+
+* Result:
+  ** Collection name string.
+
+* Parameter:
+  ** collection_name: Collection name.
+
+=== Get binded collection name.
+
+[source,ruby]
+----
+self.collection_name
+----
+
+* Result:
+  ** Collection name string.
+
+* Parameter:
+  ** None.
+
+=== Get collection.
+
+[source,ruby]
+----
+self.collection( collection_name = nil )
+----
+
+* Result:
+  ** Mongo::Collection instance.
+
+* Parameter:
+  ** collection_name: Tempolary collection name.
+
 === Declare document structure.
 
 [source,ruby]
 ----
-field( label, *attrs, &block )
+self.field( symbol, *attrs, **items )
 ----
 
 * Parameter:
-  ** label:           Field label symbol.
+  ** symbol:          Field name.
   ** attrs:           Field attributes.
     *** Class:        Class for field verification.
     *** Proc:         Proc for field verification.
     *** Range:        Range for field verification.
     *** Array:        Array for field verification.
-    *** Symbol:       Special delectives.
+    *** Symbol:       Special directive symbol.
       **** must:      Not nil nor empty.
-  ** block:           Returning default value.
+  ** items:           Operation when saving.
+    *** default:      Value or proc when undefined.
+    *** create:       Value or proc when saving a new document.
+    *** update:       Value or proc when saving update document.
 
 === Verify before save or assignment action.
 
 [source,ruby]
 ----
-verify( *syms, &block )
+self.verify( *directives, &block )
 ----
 
 * Parameter:
-  ** syms:            Conditional symbols.
+  ** directives:      Special directive symbol.
     *** strict:       Verify that it is a defined item name.
   ** block:           Describe the content that verifies each item value and returns the truth.
 
@@ -236,18 +319,18 @@ verify( *syms, &block )
 
 [source,ruby]
 ----
-index( *syms, **opts )
+self.index( *symbols, **options )
 ----
 
 * Parameter:
-  ** syms:            Field label symbols.
-  ** opts:            Options for Mongo::Collection#indexes().
+  ** symbols:         Field names.
+  ** options:         Options for Mongo::Collection#indexes().
 
 === Verify field value is not nil nor empty.
 
 [source,ruby]
 ----
-having?( label )
+self.having?( label )
 ----
 
 * Result:
@@ -256,6 +339,161 @@ having?( label )
 * Parameter:
   ** label:           Field label for method call.
 
+=== Name the search condition.
+
+[source,ruby]
+----
+self.filter( symbol, filter_or_cond )
+----
+
+* Parameter:
+  ** symbol:          Filter name.
+  ** filter_or_cond:  Filter or search criteria.
+
+=== Select output fields.
+
+[source,ruby]
+----
+Mongous::Document.select( *keys, **kwargs )
+Mongous::Filter#select( *keys, **kwargs )
+----
+
+* Result:
+  ** Mongous::Filter instance.
+
+* Parameter:
+  ** keys:            Field symbols.
+  ** kwargs:          Field symbols and values.
+
+=== Search condition.
+
+[source,ruby]
+----
+Mongous::Document.where( filter = nil, **conditions )
+Mongous::Filter#where( filter = nil, **conditions )
+----
+
+* Result:
+  ** Mongous::Filter instance.
+
+* Parameter:
+  ** filter:          Filter name symbol, or filter instance.
+  ** conditions:      Search criteria.
+
+=== NOT search condition.
+
+[source,ruby]
+----
+Mongous::Document.not( filter = nil, **conditions )
+Mongous::Filter#not( filter = nil, **conditions )
+----
+
+* Result:
+  ** Mongous::Filter instance.
+
+* Parameter:
+  ** filter:          Filter name symbol, or filter instance.
+  ** conditions:      Search criteria.
+
+=== AND search condition.
+
+[source,ruby]
+----
+Mongous::Document.and( *filters )
+Mongous::Filter#and( *filters )
+----
+
+* Result:
+  ** Mongous::Filter instance.
+
+* Parameter:
+  ** filters:         Filter name symbol, or filter instance.
+
+=== OR search condition.
+
+[source,ruby]
+----
+Mongous::Document.or( *filters )
+Mongous::Filter#or( *filters )
+----
+
+* Result:
+  ** Mongous::Filter instance.
+
+* Parameter:
+  ** filters:         Field name symbol, or filter instance.
+
+=== Create document.
+
+[source,ruby]
+----
+Mongous::Document.create( **doc )
+----
+
+* Result:
+  ** nil.
+
+* Parameter:
+  ** doc:             Keyword arguments.
+
+=== Save document.
+
+[source,ruby]
+----
+Mongous::Document#save
+----
+
+* Result:
+  ** nil.
+
+=== Convert document to Hash.
+
+[source,ruby]
+----
+Mongous::Document#to_hash
+----
+
+* Result:
+  ** Hash object.
+
+=== Convert document to JSON.
+
+[source,ruby]
+----
+Mongous::Document#to_json
+----
+
+* Result:
+  ** JSON String.
+
+=== Read document field.
+
+[source,ruby]
+----
+Mongous::Document#[]( field_name )
+Mongous::Document#field_name
+----
+
+* Result:
+  ** field_value.
+
+* Parameter:
+  ** field_name:      Field name.
+
+=== Write document field.
+
+[source,ruby]
+----
+Mongous::Document#[]=( field_name, field_value )
+Mongous::Document#field_name = field_value
+----
+
+* Result:
+  ** field_value.
+
+* Parameter:
+  ** field_name:      Field name.
+  ** field_value:     Field value.
 
 == Contributing