bson 1.12.5 → 2.0.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 09ee8db8844e09b37a0367f29804bca04f24fd42
-  data.tar.gz: e8c27a49f6d3ddc608958c8527597ec5f9b3b3c6
+  metadata.gz: e50654bfd852cf0daad41abc4d7249bf6dc293fc
+  data.tar.gz: 13709ff7d3d55d1990df6ac2f9c92acf193ae242
 SHA512:
-  metadata.gz: 79305ba921fc09f772b97e07d7e98da6f8c3af9f52e3589b4bfcae460c5cc01f2c7cc3022c995265e1b2ca03c051faf7fa85dd2c96d0ef51cb3d97e955a6497c
-  data.tar.gz: cb70dcb29e040f4ab2391c6ad0ce97322f23e39e72e32c949b60d3ae3086f6fc6e93983e59788d78f6f56898c84c271a9d9bfc77905ea8c17fb52faf6420c3c4
+  metadata.gz: 7caafece5f3d7fd32f470e928c9ef94297cefc953ba4a8b656b68258db73ecc397f1ff3f27d79d735e713e5cb586ec7882b17fba114172f1b67a739108984f06
+  data.tar.gz: aad6c2fea3db480b2e8b763e45c08cf9c663e28713f8322020921bce35a9aede9c32cbfcd4e324df9798b4fa6986ac146ebd0299d6be7eb29c6f650ed0e5a810

data/LICENSE.md

@@ -0,0 +1,13 @@
+Copyright (C) 2013 10gen 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](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.

data/README.md

@@ -0,0 +1,185 @@
+BSON [![Build Status](https://secure.travis-ci.org/mongodb/bson-ruby.png?branch=master&.png)](http://travis-ci.org/mongodb/bson-ruby) [![Code Climate](https://codeclimate.com/github/mongodb/bson-ruby.png)](https://codeclimate.com/github/mongodb/bson-ruby)
+====
+
+An implementation of the BSON specification in Ruby.
+
+Compatibility
+-------------
+
+BSON is tested against MRI (1.8.7+), JRuby (1.5.0+), Rubinius (2.0.0+), and REE.
+
+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.
+
+```ruby
+gem "bson", "~> 2.0"
+```
+
+Require the `bson` gem in your application.
+
+```ruby
+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:
+
+```ruby
+"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.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+BSON::Code.new("this.value = 5;")
+```
+
+#### `BSON::CodeWithScope`
+
+Represents a string of Javascript code with a hash of values.
+
+```ruby
+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.
+
+```ruby
+BSON::Document[:key, "value"]
+BSON::Document.new
+```
+
+#### `BSON::MaxKey`
+
+Represents a value in BSON that will always compare higher to another value.
+
+```ruby
+BSON::MaxKey.new
+```
+
+#### `BSON::MinKey`
+
+Represents a value in BSON that will always compare lower to another value.
+
+```ruby
+BSON::MinKey.new
+```
+
+#### `BSON::ObjectId`
+
+Represents a 12 byte unique identifier for an object on a given machine.
+
+```ruby
+BSON::ObjectId.new
+```
+
+#### `BSON::Timestamp`
+
+Represents a special time with a start and increment value.
+
+```ruby
+BSON::Timestamp.new(5, 30)
+```
+
+#### `BSON::Undefined`
+
+Represents a placeholder for a value that was not provided.
+
+```ruby
+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" }`
+
+API Documentation
+-----------------
+
+The [API Documentation](http://rdoc.info/github/mongodb/bson-ruby/master/frames) is
+located at rdoc.info.
+
+BSON Specification
+------------------
+
+The [BSON specification](http://bsonspec.org) is at bsonspec.org.
+
+License
+-------
+
+Copyright (C) 2013 10gen 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.

data/Rakefile

@@ -0,0 +1,83 @@
+require "bundler"
+Bundler.setup
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __FILE__))
+
+require "rake"
+require "rake/extensiontask"
+require "rspec/core/rake_task"
+
+def jruby?
+  defined?(JRUBY_VERSION)
+end
+
+if jruby?
+  require "rake/javaextensiontask"
+  Rake::JavaExtensionTask.new do |ext|
+    ext.name = "NativeService"
+    ext.ext_dir = "src"
+    ext.lib_dir = "lib/bson"
+  end
+else
+  require "rake/extensiontask"
+  Rake::ExtensionTask.new do |ext|
+    ext.name = "native"
+    ext.ext_dir = "ext/bson"
+    ext.lib_dir = "lib/bson"
+  end
+end
+
+require "bson/version"
+
+def extension
+  RUBY_PLATFORM =~ /darwin/ ? "bundle" : "so"
+end
+
+if RUBY_VERSION < "1.9"
+  require "perf/bench"
+else
+  require_relative "perf/bench"
+end
+
+RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:rspec)
+
+task :build do
+  system "gem build bson.gemspec"
+end
+
+task :clean_all => :clean do
+  begin
+    Dir.chdir(Pathname(__FILE__).dirname + "lib/bson") do
+      `rm native.#{extension}`
+      `rm native.o`
+      `rm NativeService.jar`
+    end
+  rescue Exception => e
+    puts e.message
+  end
+end
+
+task :release => :build do
+  system "git tag -a v#{BSON::VERSION} -m 'Tagging release: #{BSON::VERSION}'"
+  system "git push --tags"
+  system "gem push bson-#{BSON::VERSION}.gem"
+  system "rm bson-#{BSON::VERSION}.gem"
+end
+
+namespace :benchmark do
+
+  task :ruby => :clean_all do
+    puts "Benchmarking pure Ruby..."
+    require "bson"
+    benchmark!
+  end
+
+  task :native => :compile do
+    puts "Benchmarking with native extensions..."
+    require "bson"
+    benchmark!
+  end
+end
+
+task :default => [ :clean_all, :spec, :compile, :rspec ]

data/ext/bson/extconf.rb

@@ -0,0 +1,3 @@
+require "mkmf"
+$CFLAGS << " -Wall -g -std=c99"
+create_makefile("native")

data/lib/bson.rb

@@ -1,113 +1,124 @@
-# Copyright (C) 2009-2013 MongoDB, Inc.
+# encoding: utf-8
+
+# Determine if we are using JRuby or not.
 #
-# 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
+# @example Are we running with JRuby?
+#   jruby?
 #
-#   http://www.apache.org/licenses/LICENSE-2.0
+# @return [ true, false ] If JRuby is our vm.
 #
-# 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.
+# @since 2.0.0
+def jruby?
+  defined?(JRUBY_VERSION)
+end
 
-module BSON
-  DEFAULT_MAX_BSON_SIZE = 4 * 1024 * 1024
+# Does the Ruby runtime we are using support ordered hashes?
+#
+# @example Does the runtime support ordered hashes?
+#   ordered_hash_support?
+#
+# @return [ true, false ] If the runtime has ordered hashes.
+#
+# @since 2.0.0
+def ordered_hash_support?
+  jruby? || RUBY_VERSION > "1.9.1"
+end
 
-  def self.serialize(obj, check_keys=false, move_id=false)
-    BSON_CODER.serialize(obj, check_keys, move_id)
-  end
+# Are we running in a ruby runtime that is version 1.8.x?
+#
+# @since 2.0.0
+def ruby_18?
+  RUBY_VERSION < "1.9"
+end
 
-  def self.deserialize(buf=nil, opts={})
-    BSON_CODER.deserialize(buf, opts)
-  end
+# In the case where we don't have encoding, we need to monkey
+# patch string to ignore the encoding directives.
+#
+# @since 2.0.0
+if ruby_18?
 
-  # Reads a single BSON document from an IO object.
-  # This method is used in the executable b2json, bundled with
-  # the bson gem, for reading a file of bson documents.
-  #
-  # @param [IO] io an io object containing a bson object.
-  #
-  # @return [ByteBuffer]
-  def self.read_bson_document(io)
-    bytebuf = BSON::ByteBuffer.new
-    sz = io.read(4).unpack("V")[0]
-    bytebuf.put_int(sz)
-    bytebuf.put_array(io.read(sz-4).unpack("C*"))
-    bytebuf.rewind
-    return BSON.deserialize(bytebuf)
-  end
+  class String
 
-  def self.extension?
-    !((ENV.key?('BSON_EXT_DISABLED') && RUBY_PLATFORM =~ /java/) ||
-      (ENV.key?('BSON_EXT_DISABLED') || "\x01\x00\x00\x00".unpack("i")[0] != 1))
+    # In versions prior to 1.9 we need to ignore the encoding requests.
+    #
+    # @since 2.0.0
+    def chr; self; end
+    def force_encoding(*); self; end
+    def encode(*); self; end
+    def encode!(*); self; end
   end
-end
 
-begin
-  # Skips loading extensions if one of the following is true:
-  # 1) JRuby and BSON_EXT_DISABLED is set.
-  #     -OR-
-  # 2) Ruby MRI and big endian or BSON_EXT_DISABLED is set.
-  raise LoadError unless BSON.extension?
+  class EncodingError < RuntimeError; end
+end
 
-  if RUBY_PLATFORM =~ /java/
-    require 'bson/bson_java'
-    module BSON
-      BSON_CODER = BSON_JAVA
-    end
-  else
-    require 'bson_ext/cbson'
-    raise LoadError unless defined?(CBson::VERSION)
-    require 'bson/bson_c'
-    module BSON
-      BSON_CODER = BSON_C
-    end
-  end
-rescue LoadError
-  require 'bson/bson_ruby'
-  module BSON
-    BSON_CODER = BSON_RUBY
-  end
+#
+# The core namespace for all BSON related behaviour.
+#
+# @since 0.0.0
+module BSON
 
-  if RUBY_PLATFORM =~ /java/
-    unless ENV['TEST_MODE']
-      warn <<-NOTICE
-      ** Notice: The BSON extension was not loaded. **
+  # Constant for binary string encoding.
+  #
+  # @since 2.0.0
+  BINARY = "BINARY".freeze
 
-      For optimal performance, use of the BSON extension is recommended. To
-      enable the extension make sure ENV['BSON_EXT_DISABLED'] is not set.
-      NOTICE
-    end
-  else
-    unless ENV['TEST_MODE']
-      warn <<-NOTICE
-      ** Notice: The native BSON extension was not loaded. **
+  # Constant for bson types that don't actually serialize a value.
+  #
+  # @since 2.0.0
+  NO_VALUE = "".force_encoding(BINARY).freeze
 
-      For optimal performance, use of the BSON extension is recommended.
+  # Constant for a null byte (0x00).
+  #
+  # @since 2.0.0
+  NULL_BYTE = 0.chr.force_encoding(BINARY).freeze
 
-      To enable the extension make sure ENV['BSON_EXT_DISABLED'] is not set
-      and run the following command:
+  # Constant for UTF-8 string encoding.
+  #
+  # @since 2.0.0
+  UTF8 = "UTF-8".freeze
+end
 
-        gem install bson_ext
+require "bson/registry"
+require "bson/specialized"
+require "bson/json"
+require "bson/int32"
+require "bson/int64"
+require "bson/integer"
+require "bson/encodable"
+require "bson/array"
+require "bson/binary"
+require "bson/boolean"
+require "bson/code"
+require "bson/code_with_scope"
+require "bson/document"
+require "bson/false_class"
+require "bson/float"
+require "bson/hash"
+require "bson/max_key"
+require "bson/min_key"
+require "bson/nil_class"
+require "bson/object_id"
+require "bson/regexp"
+require "bson/string"
+require "bson/symbol"
+require "bson/time"
+require "bson/timestamp"
+require "bson/true_class"
+require "bson/undefined"
+require "bson/version"
 
-      If you continue to receive this message after installing, make sure that
-      the bson_ext gem is in your load path.
-      NOTICE
-    end
+# If we are using JRuby, attempt to load the Java extensions, if we are using
+# MRI or Rubinius, attempt to load the C extenstions. If either of these fail,
+# we revert back to a pure Ruby implementation of the Buffer class.
+#
+# @since 2.0.0
+begin
+  if jruby?
+    require "bson/NativeService.jar"
+    org.bson.NativeService.new.basicLoad(JRuby.runtime)
+  else
+    require "bson/native"
   end
+rescue LoadError
+  $stderr.puts("BSON is using the pure Ruby implementation.")
 end
-
-require 'base64'
-require 'bson/bson_ruby'
-require 'bson/byte_buffer'
-require 'bson/exceptions'
-require 'bson/ordered_hash'
-require 'bson/types/binary'
-require 'bson/types/code'
-require 'bson/types/dbref'
-require 'bson/types/min_max_keys'
-require 'bson/types/regex'
-require 'bson/types/object_id'
-require 'bson/types/timestamp'