Class: BSON::Document
- Inherits:
-
Hash
- Object
- Hash
- BSON::Document
- Defined in:
- lib/bson/document.rb
Overview
The specification is: document ::= int32 e_list “x00”
This module provides behaviour for serializing and deserializing entire BSON documents, according to the BSON specification.
Constant Summary collapse
- ARG_ERROR =
Message for argument error when providing bad arguments to [].
"An even number of arguments must be passed to BSON::Document[]."
Class Method Summary collapse
-
.[](*args) ⇒ BSON::Document
Create a new document given the provided arguments.
Instance Method Summary collapse
-
#[](key) ⇒ Object
Get a value from the document for the provided key.
-
#[]=(key, value) ⇒ Object
Sets a value for the provided key.
-
#clear ⇒ BSON::Document
Clear out all elements in the document.
-
#delete(key) ⇒ Object
Delete a value from the document for the provided key.
-
#delete_if ⇒ BSON::Document
(also: #reject!)
Delete each key/value pair in the document for which the provided block returns true.
-
#each ⇒ BSON::Document
Iterate over each element of the document in insertion order and yield the key and value.
-
#each_key ⇒ BSON::Document
Iterate over each key in the document in insertion order and yield the key.
-
#each_pair ⇒ BSON::Document
Iterate over each element of the document in insertion order and yield the key and value.
-
#each_value ⇒ BSON::Document
Iterate over each value in the document in insertion order and yield the value.
-
#encode_with(coder) ⇒ String
Encode the document with the provided coder.
-
#initialize(*args, &block) ⇒ Document
constructor
Instantiate a new Document.
-
#inspect ⇒ String
Inspect the contents of the document.
-
#invert ⇒ BSON::Document
Invert the document - reverses the order of all key/value pairs and returns a new document.
-
#keys ⇒ Array<Object>
Get all the keys in the document, in order.
-
#merge(other, &block) ⇒ BSON::Document
Merge a document into this document.
-
#merge!(other) ⇒ BSON::Document
(also: #update)
Merge a document into this document.
-
#reject(&block) ⇒ BSON::Document
Delete each key/value pair in the document for which the provided block returns true.
-
#replace(other) ⇒ BSON::Document
Replace this document with the other document.
-
#shift ⇒ Array<Object, Object>
Shift the document by popping off the first key/value pair in the document.
-
#to_a ⇒ Array<Array<Object, Object>>
Get the document as an array.
-
#to_hash ⇒ BSON::Document
Convert this document to a hash.
-
#to_yaml(options = {}) ⇒ String
Convert the document to yaml.
-
#to_yaml_type ⇒ String
Get the custom yaml type for the document.
-
#values ⇒ Array<Object>
Get all the values in the document, by order of insertion.
Constructor Details
#initialize(*args, &block) ⇒ Document
Instantiate a new Document.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
387 388 389 |
# File 'lib/bson/document.rb', line 387 def to_hash self end |
#to_yaml(options = {}) ⇒ String
Convert the document to yaml.
401 402 403 404 405 406 407 408 409 410 |
# File 'lib/bson/document.rb', line 401 def to_yaml( = {}) if YAML.const_defined?(:ENGINE) && !YAML::ENGINE.syck? return super end YAML.quick_emit(self, ) 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.
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.
432 433 434 |
# File 'lib/bson/document.rb', line 432 def values order.map{ |key| self[key] } end |