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.

• 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.

• The database collection name corresponding to the class name is not converted to the plural form.

Installation

Add this line to your application’s Gemfile:

gem 'mongous'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install mongous
or
$ gem install -l mongous-x.x.x.gem

Usage

Simple declaration

require  "mongous"

Mongous.document!  :Book

Detail declaration

require  "mongous"

Mongous.connect!  ["localhost:27017"], database: "test"

class Book
  include  Mongous::Document

  field  :title,      String,   :must
  field  :author,     String
  field  :publisher,  String
  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
    having?(author) | having?(publisher)
  end

  def isbn?
    isbn.gsub(/[\D]*/, '').size == 13
  end

  index  :title
end

Create document

book = Book.new
book.title = "title 1"
book.price = 1000
book.size = "A4"
book.save

book = Book.new( title: "title 2", price: 2000, size: "A5" )
book.save

doc = { title: "title 3", price: 3000, size: "A6" }
Book.create( **doc )

Search document

pp books = Book.all

p book = Book.where( title: /title/ ).first
p book = Book.where( title: /title/ ).last

books = Book.where( title: /title/ ).all
books.each do |book|
  p book
end

Book.where( title: /title/ ).projection( _id: 0 ).each do |book|
  p book
end

Book.where( price: (1..2000), size: ["A4","A5"] ).each do |book|
  p book
end

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, 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.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

book = Book.where( title: "title 1" ).first
book.title = "title 1 [update]"
book.save

Delete document

book = Book.where( title: "title 1" ).first
book.delete

Reference

Connect default database.

Mongous.connect!( hosts_or_uri = nil, **options )

• Result:

  • nil.

• Parameter:

  • hosts_or_uri: Array of hosts, or URI (default: ["localhost:21017"])

  • 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.

Connect database.

Mongous.connect( hosts_or_uri = nil, **options )

• Result:

  • Mongo::Client instance.

Define collection operate class with default settings.

Mongous.document!( *names, **options )

• Result:

  • nil.

• 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.

include Mongous::Document

Bind another database.

self.client=( client )

• Result:

  • Mongo::Client instance.

• Parameter:

  • client: Mongo::Client instance.

Get binded database.

self.client

• Result:

  • Mongo::Client instance.

• Parameter:

  • None.

Bind another collection.

self.collection_name=( _collection_name )

• Result:

  • Collection name string.

• Parameter:

  • collection_name: Collection name.

Get binded collection name.

self.collection_name

• Result:

  • Collection name string.

• Parameter:

  • None.

Get collection.

self.collection( collection_name = nil )

• Result:

  • Mongo::Collection instance.

• Parameter:

  • collection_name: Tempolary collection name.

Declare document structure.

self.field( symbol, *attrs, **items )

• Parameter:

  • 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 directive symbol.

      • must: Not nil nor empty.

  • 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.

self.verify( *directives, &block )

• Parameter:

  • 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.

Make index.

self.index( *symbols, **options )

• Parameter:

  • symbols: Field names.

  • options: Options for Mongo::Collection#indexes().

Verify field value is not nil nor empty.

self.having?( label )

• Result:

  • Boolean

• Parameter:

  • label: Field label for method call.

Name the search condition.

self.filter( symbol, filter_or_cond )

• Parameter:

  • symbol: Filter name.

  • filter_or_cond: Filter or search criteria.

Select output fields.

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.

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.

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.

Mongous::Document.and( *filters )
Mongous::Filter#and( *filters )

• Result:

  • Mongous::Filter instance.

• Parameter:

  • filters: Filter name symbol, or filter instance.

OR search condition.

Mongous::Document.or( *filters )
Mongous::Filter#or( *filters )

• Result:

  • Mongous::Filter instance.

• Parameter:

  • filters: Field name symbol, or filter instance.

Create document.

Mongous::Document.create( **doc )

• Result:

  • nil.

• Parameter:

  • doc: Keyword arguments.

Save document.

Mongous::Document#save

• Result:

  • nil.

Convert document to Hash.

Mongous::Document#to_hash

• Result:

  • Hash object.

Convert document to JSON.

Mongous::Document#to_json

• Result:

  • JSON String.

Read document field.

Mongous::Document#[]( field_name )
Mongous::Document#field_name

• Result:

  • field_value.

• Parameter:

  • field_name: Field name.

Write document field.

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

Bug reports and pull requests are welcome on GitHub at https://github.com/arimay/mongous.

License

The gem is available as open source under the terms of the MIT License.

Copyright (c) ARIMA Yasuhiro <arima.yasuhiro@gmail.com>