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.

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.connect!

class Book
  include  Mongous::Document
end

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,  ["A4","B5","A5","B6"]
  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.style = "A4"
book.save

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

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

Search document

pp books = Book.all

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

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), style: ["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( style: ["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

pp Book.where( title: /title/ )[0, 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.

Include document functions.

include Mongous::Document

Bind another database.

self.client=( _client )

• Result:

  • Mongo::Client instance.

• Parameter:

  • client: Mongo::Client instance.

Bind another collection.

self.collection_name=( _collection_name )

• Result:

  • Collection name string.

• Parameter:

  • collection_name: Collection name.

Declare document structure.

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.

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.

index( *symbols, **options )

• Parameter:

  • symbols: Field names.

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

Verify field value is not nil nor empty.

having?( label )

• Result:

  • Boolean

• Parameter:

  • label: Field label for method call.

Name the search condition.

filter( symbol, filter_or_cond )

• Parameter:

  • symbol: Filter name.

  • filter_or_cond: Filter or search criteria.

Search condition.

where( filter = nil, **conditions )

• Result:

  • Filter instance.

• Parameter:

  • filter: Filter name symbol, or filter instance.

  • conditions: Search criteria.

NOT search condition.

not( filter = nil, **conditions )

• Result:

  • Filter instance.

• Parameter:

  • filter: Filter name symbol, or filter instance.

  • conditions: Search criteria.

AND search condition.

and( *filters )

• Result:

  • Filter instance.

• Parameter:

  • filters: Filter name symbol, or filter instance.

OR search condition.

or( *filters )

• Result:

  • Filter instance.

• Parameter:

  • filters: Field name symbol, or filter instance.

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>