rrrene/bson-ruby

Ruby Implementation of the BSON Specification (2.0.0+)

BSON

An implementation of the BSON specification in Ruby.

Compatibility

BSON is tested against MRI (1.9.2+), JRuby (1.7.0+) and Rubinius (2.0.0+).

Installation

With bundler, add the bson gem to your Gemfile. As of 2.0.0 native extensions are bundled with the bson gem and bson_ext is no longer needed.

gem "bson", "~> 2.3"

Require the bson gem in your application.

require "bson"

Usage

BSON Serialization

Getting a Ruby object's raw BSON representation is done by calling to_bson on the Ruby object. For example:

"Shall I compare thee to a summer's day".to_bson
1024.to_bson

Generating an object from BSON is done via calling from_bson on the class you wish to instantiate and passing it the StringIO bytes.

String.from_bson(string_io)
Int32.from_bson(string_io)

Core Ruby object's that have representations in the BSON specification and will have a to_bson method defined for them are:

• Array
• FalseClass
• Float
• Hash
• Integer
• NilClass
• Regexp
• String
• Symbol (deprecated)
• Time
• TrueClass

In addition to the core Ruby objects, BSON also provides some special types specific to the specification:

BSON::Binary

This is a representation of binary data, and must provide the raw data and a subtype when constructing.

BSON::Binary.new(binary_data, :md5)

Valid subtypes are: :generic, :function, :old, :uuid_old, :uuid, :md5, :user.

BSON::Code

Represents a string of Javascript code.

BSON::Code.new("this.value = 5;")

BSON::CodeWithScope

Represents a string of Javascript code with a hash of values.

BSON::CodeWithScope.new("this.value = age;", age: 5)

BSON::Document

This is a special ordered hash for use with Ruby below 1.9, and is simply a subclass of a Ruby hash in 1.9 and higher.

BSON::Document[:key, "value"]
BSON::Document.new

BSON::MaxKey

Represents a value in BSON that will always compare higher to another value.

BSON::MaxKey.new

BSON::MinKey

Represents a value in BSON that will always compare lower to another value.

BSON::MinKey.new

BSON::ObjectId

Represents a 12 byte unique identifier for an object on a given machine.

BSON::ObjectId.new

BSON::Timestamp

Represents a special time with a start and increment value.

BSON::Timestamp.new(5, 30)

BSON::Undefined

Represents a placeholder for a value that was not provided.

BSON::Undefined.new

JSON Serialization

Some BSON types have special representations in JSON. These are as follows and will be automatically serialized in the form when calling to_json on them.

• BSON::Binary: { "$binary" : "\x01", "$type" : "md5" }
• BSON::Code: { "$code" : "this.v = 5 }
• BSON::CodeWithScope: { "$code" : "this.v = value", "$scope" : { v => 5 }}
• BSON::MaxKey: { "$maxKey" : 1 }
• BSON::MinKey: { "$minKey" : 1 }
• BSON::ObjectId: { "$oid" : "4e4d66343b39b68407000001" }
• BSON::Timestamp: { "t" : 5, "i" : 30 }
• Regexp: { "$regex" : "[abc]", "$options" : "i" }

Notes on Special Ruby Date Classes

As of 2.1.0, Ruby's Date and DateTime are able to be serialized, but when they are deserialized they will always be returned as a Time since the BSON specification only has a Time type and knows nothing about Ruby.

API Documentation

The API Documentation is located at rdoc.info.

BSON Specification

The BSON specification is at bsonspec.org.

Versioning

As of 2.0.0, this project adheres to the Semantic Versioning Specification.

License

Copyright (C) 2009-2014 MongoDB Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.