Class: BSON::Document

Inherits:
Hash
  • Object
show all
Defined in:
lib/bson/document.rb

Overview

Note:

The specification is: document ::= int32 e_list “x00”

This module provides behaviour for serializing and deserializing entire BSON documents, according to the BSON specification.

See Also:

Since:

  • 2.0.0

Constant Summary collapse

ARG_ERROR =

Message for argument error when providing bad arguments to [].

Since:

  • 2.0.0

"An even number of arguments must be passed to BSON::Document[]."

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args, &block) ⇒ Document

Instantiate a new Document.

Examples:

Instantiate an empty new document.

BSON::Document.new

Since:

  • 2.0.0



248
249
250
251
 
# File 'lib/bson/document.rb', line 248

def initialize(*args, &block)
  super
  @order = []
end

Class Method Details

.[](*args) ⇒ BSON::Document

Create a new document given the provided arguments. The args can either be empty in order to instantiate an empty document, or an array of key/value pairs in the order that they should remain in.

Examples:

Create a new empty document.

BSON::Document[]

Create a new document with the provided elements.

BSON::Document[1, 2, 3, 4]

Create a new document with key/value array pairs.

BSON::Document[[ 1, 2 ], [ 3, 4 ]]

Parameters:

  • args (Array<Object>) —

    The key/value pairs.

Returns:

Raises:

  • (ArgumentError)

Since:

  • 2.0.0



456
457
458
459
460
461
462
 
# File 'lib/bson/document.rb', line 456

def [](*args)
  if (args.length == 1 && args.first.is_a?(Array))
    return document_from_pairs(args)
  end
  raise ArgumentError.new(ARG_ERROR) unless (args.size % 2 == 0)
  document_from_args(args)
end

Instance Method Details

#[](key) ⇒ Object

Get a value from the document for the provided key. Can use string or symbol access, but the fastest will be to always provide a key that is of the same type as the stored keys.

Examples:

Get an element for the key.

document["field"]

Get an element for the key by symbol.

document[:field]

Parameters:

Returns:

  • (Object) —

    The found value, or nil if none found.

Since:

  • 2.0.0



52
53
54
 
# File 'lib/bson/document.rb', line 52

def [](key)
  super(key) || super(key.to_s)
end

#[]=(key, value) ⇒ Object

Sets a value for the provided key.

Examples:

Set the value in the document.

document[:name] = "Sid"

Parameters:

  • key (Object) —

    The name of the key.

  • value (Object) —

    The value for the key.

Returns:

  • (Object) —

    The passed in value.

Since:

  • 2.0.0



78
79
80
81
 
# File 'lib/bson/document.rb', line 78

def []=(key, value)
  order.push(key) unless has_key?(key)
  super
end

#clear ⇒ BSON::Document

Clear out all elements in the document.

Examples:

Clear out all elements.

document.clear

Returns:

Since:

  • 2.0.0



91
92
93
94
95
 
# File 'lib/bson/document.rb', line 91

def clear
  super
  order.clear
  self
end

#delete(key) ⇒ Object

Delete a value from the document for the provided key.

Examples:

Delete a value from the document.

document.delete(:name)

Parameters:

  • key (Object) —

    The key to delete for.

Returns:

  • (Object) —

    The deleted value.

Since:

  • 2.0.0



107
108
109
110
111
112
 
# File 'lib/bson/document.rb', line 107

def delete(key)
  if has_key?(key)
    order.delete_at(order.index(key))
  end
  super
end

#delete_if ⇒ BSON::Document Also known as: reject!

Delete each key/value pair in the document for which the provided block returns true.

Examples:

Delete each for when the block is true.

document.delete_if do |key, value|
  value == 1
end

Returns:

Since:

  • 2.0.0



125
126
127
128
129
 
# File 'lib/bson/document.rb', line 125

def delete_if
  super
  synchronize!
  self
end

#each ⇒ BSON::Document

Iterate over each element of the document in insertion order and yield the key and value.

Examples:

Iterate over the document.

document.each do |key, value|
  #...
end

Returns:

  • (BSON::Document) —

    The document if a block was given, otherwise an enumerator.

Since:

  • 2.0.0



144
145
146
147
148
149
150
151
 
# File 'lib/bson/document.rb', line 144

def each
  if block_given?
    order.each{ |key| yield([ key, self[key]]) }
    self
  else
    to_enum(:each)
  end
end

#each_key ⇒ BSON::Document

Iterate over each key in the document in insertion order and yield the key.

Examples:

Iterate over the keys.

document.each_key do |key|
  #...
end

Returns:

  • (BSON::Document) —

    The document if a block was given, otherwise an enumerator.

Since:

  • 2.0.0



165
166
167
168
169
170
171
172
 
# File 'lib/bson/document.rb', line 165

def each_key
  if block_given?
    order.each{ |key| yield(key) }
    self
  else
    to_enum(:each_key)
  end
end

#each_pair ⇒ BSON::Document

Iterate over each element of the document in insertion order and yield the key and value.

Examples:

Iterate over the document.

document.each_pair do |key, value|
  #...
end

Returns:

  • (BSON::Document) —

    The document if a block was given, otherwise an enumerator.

Since:

  • 2.0.0



207
208
209
210
211
212
213
214
 
# File 'lib/bson/document.rb', line 207

def each_pair
  if block_given?
    order.each{ |key| yield([ key, self[key]]) }
    self
  else
    to_enum(:each_pair)
  end
end

#each_value ⇒ BSON::Document

Iterate over each value in the document in insertion order and yield the value.

Examples:

Iterate over the values.

document.each_value do |value|
  #...
end

Returns:

  • (BSON::Document) —

    The document if a block was given, otherwise an enumerator.

Since:

  • 2.0.0



186
187
188
189
190
191
192
193
 
# File 'lib/bson/document.rb', line 186

def each_value
  if block_given?
    order.each{ |key| yield(self[key]) }
    self
  else
    to_enum(:each_value)
  end
end

#encode_with(coder) ⇒ String

Encode the document with the provided coder.

Examples:

Encode the document with the coder.

document.encode_with(coder)

Parameters:

  • coder (Object) —

    The coder.

Returns:

  • (String) —

    The encoded document.

Since:

  • 2.0.0



226
227
228
 
# File 'lib/bson/document.rb', line 226

def encode_with(coder)
  coder.represent_seq("!bsondoc", map{ |key, value| { key => value }})
end

#inspect ⇒ String

Inspect the contents of the document.

Examples:

Inspect the document.

document.inspect

Returns:

  • (String) —

    The inspection string.

Since:

  • 2.0.0



261
262
263
 
# File 'lib/bson/document.rb', line 261

def inspect
  "#<BSON::Document #{super}>"
end

#invert ⇒ BSON::Document

Invert the document - reverses the order of all key/value pairs and returns a new document.

Examples:

Invert the document.

document.invert

Returns:

Since:

  • 2.0.0



274
275
276
 
# File 'lib/bson/document.rb', line 274

def invert
  Document[to_a.map!{ |pair| pair.reverse }]
end

#keys ⇒ Array<Object>

Get all the keys in the document, in order.

Examples:

Get all the keys in the document.

document.keys

Returns:

  • (Array<Object>) —

    The ordered keys.

Since:

  • 2.0.0



238
239
240
 
# File 'lib/bson/document.rb', line 238

def keys
  order.dup
end

#merge(other, &block) ⇒ BSON::Document

Merge a document into this document. Will overwrite any existing keys and add potential new ones. This returns a new document instead of merging in place.

Examples:

Merge the document into this document.

document.merge(other_document)

Parameters:

Returns:

Since:

  • 2.0.0



290
291
292
 
# File 'lib/bson/document.rb', line 290

def merge(other, &block)
  dup.merge!(other, &block)
end

#merge!(other) ⇒ BSON::Document Also known as: update

Merge a document into this document. Will overwrite any existing keys and add potential new ones.

Examples:

Merge the document into this document.

document.merge!(other_document)

Parameters:

Returns:

Since:

  • 2.0.0



305
306
307
308
309
310
311
312
313
314
 
# File 'lib/bson/document.rb', line 305

def merge!(other)
  if block_given?
    other.each do |key, value|
      self[key] = key?(key) ? yield(key, self[key], value) : value
    end
  else
    other.each{ |key, value| self[key] = value }
  end
  self
end

#reject(&block) ⇒ BSON::Document

Delete each key/value pair in the document for which the provided block returns true. This returns a new document instead of modifying in place.

Examples:

Delete each for when the block is true.

document.reject do |key, value|
  value == 1
end

Returns:

Since:

  • 2.0.0



328
329
330
 
# File 'lib/bson/document.rb', line 328

def reject(&block)
  dup.reject!(&block)
end

#replace(other) ⇒ BSON::Document

Replace this document with the other document.

Examples:

Replace the contents of this document with the other.

document.replace(other_document)

Parameters:

Returns:

Since:

  • 2.0.0



342
343
344
345
346
 
# File 'lib/bson/document.rb', line 342

def replace(other)
  super
  @order = other.keys
  self
end

#shift ⇒ Array<Object, Object>

Shift the document by popping off the first key/value pair in the document.

Examples:

Shift the document.

document.shift

Returns:

  • (Array<Object, Object>) —

    The first key/value pair.

Since:

  • 2.0.0



357
358
359
360
361
 
# File 'lib/bson/document.rb', line 357

def shift
  key = order.first
  value = delete(key)
  [ key, value ]
end

#to_a ⇒ Array<Array<Object, Object>>

Get the document as an array. This returns a multi-dimensional array where each element is a [ key, value ] pair in the insertion order.

Examples:

Get the document as an array.

document.to_a

Returns:

  • (Array<Array<Object, Object>>) —

    The pairs in insertion order.

Since:

  • 2.0.0



374
375
376
 
# File 'lib/bson/document.rb', line 374

def to_a
  order.map{ |key| [ key, self[key] ]}
end

#to_hash ⇒ BSON::Document

Convert this document to a hash. Since a document is simply an ordered hash we return self.

Examples:

Get the document as a hash.

document.to_hash

Returns:

Since:

  • 2.0.0



387
388
389
 
# File 'lib/bson/document.rb', line 387

def to_hash
  self
end

#to_yaml(options = {}) ⇒ String

Convert the document to yaml.

Examples:

Convert the document to yaml.

document.to_yaml

Parameters:

  • options (Hash) (defaults to: {}) —

    The yaml options.

Returns:

  • (String) —

    The document as yaml.

Since:

  • 2.0.0



401
402
403
404
405
406
407
408
409
410
 
# File 'lib/bson/document.rb', line 401

def to_yaml(options = {})
  if YAML.const_defined?(:ENGINE) && !YAML::ENGINE.syck?
    return super
  end
  YAML.quick_emit(self, options) do |out|
    out.seq(taguri) do |seq|
      each{ |key, value| seq.add(key => value) }
    end
  end
end

#to_yaml_type ⇒ String

Get the custom yaml type for the document.

Examples:

Get the yaml type.

document.to_yaml_type

Returns:

  • (String) —

    “!bsondoc”.

Since:

  • 2.0.0



420
421
422
 
# File 'lib/bson/document.rb', line 420

def to_yaml_type
  "!bsondoc"
end

#values ⇒ Array<Object>

Get all the values in the document, by order of insertion.

Examples:

Get all the values in the document.

document.values

Returns:

  • (Array<Object>) —

    The ordered values.

Since:

  • 2.0.0



432
433
434
 
# File 'lib/bson/document.rb', line 432

def values
  order.map{ |key| self[key] }
end