Tutorial do BSON

Escrevendo

Para criar um ByteBuffer para escrever (ou seja, serializando para BSON), instanciam BSON::ByteBuffer sem argumentos:

buffer = BSON::ByteBuffer.new

Para escrever bytes brutos no buffer de bytes sem transformações, use os métodos put_byte e put_bytes . Eles usam uma cadeia de bytes como argumento e copiam essa cadeia de caracteres no buffer. put_byte força que o argumento seja uma string de comprimento 1; put_bytes aceita strings de qualquer comprimento. As strings podem conter bytes nulos.

buffer.put_byte("\x00")
buffer.put_bytes("\xff\xfe\x00\xfd")

Métodos de escrita subsequentes escrevem objetos de tipos específicos na especificação BSON. Observe que o tipo indicado pelo nome do método tem precedência sobre o tipo do argumento - por exemplo, se um valor de ponto flutuante for fornecido a put_int32, ele será forçado em um número inteiro e o número inteiro resultante será gravado no buffer de bytes .

Para escrever uma cadeia UTF-8 (BSON tipo 0x02) no buffer de bytes, use put_string:

buffer.put_string("hello, world")

Observe que as strings BSON são sempre codificadas em UTF-8. Portanto, o argumento deve estar em UTF-8 ou em uma codificação convertível para UTF-8 (ou seja, não binário). Se o argumento estiver em uma codificação diferente de UTF-8, a string será primeiro convertida em UTF-8 e a versão codificada em UTF-8 será gravada no buffer. A string deve ser válida na codificação reivindicação, inclusive sendo UTF-8 válida se a codificação for UTF-8. A string pode conter bytes nulos.

A especificação BSON também define um tipo CString, que é usado, por exemplo, para chaves de documentos. Para escrever CStrings no buffer, use put_cstring:

buffer.put_cstring("hello, world")

Assim como nas strings regulares, as CStrings no BSON devem ser codificadas em UTF-8. Se o argumento não estiver em UTF-8, ele será convertido para UTF-8 e a string resultante será gravada no buffer. Ao contrário de put_string, a codificação UTF-8 do argumento fornecido a put_cstring não pode ter bytes nulos, uma vez que o formato de serialização CString em BSON tem encerramento nulo.

Ao contrário de put_string, put_cstring também aceita símbolos e inteiros. Em todos os casos, o argumento é definido como uma string antes de ser escrito:

buffer.put_cstring(:hello)
buffer.put_cstring(42)

Para escrever um número inteiro de 32 bits ou 64 bits no buffer de bytes, use os métodos put_int32 e put_int64 , respectivamente. Observe que os números inteiros Ruby podem ser arbitrariamente grandes; se o valor que está sendo gravado exceder o intervalo de um número inteiro de 32 ou 64 bits, put_int32 e put_int64 aumentem RangeError .

buffer.put_int32(12345)
buffer.put_int64(123456789012345)

Para escrever um valor de ponto flutuante de 64 bits no buffer de bytes, use put_double:

buffer.put_double(3.14159)

Para obter os dados serializados como uma cadeia de bytes (por exemplo, para enviar os dados por um soquete), chame to_s no buffer:

buffer = BSON::ByteBuffer.new
buffer.put_string('testing')
socket.write(buffer.to_s)

Leitura

Para criar um ByteBuffer para leitura (ou seja, desserializando do BSON), instancie BSON::ByteBuffer com uma cadeia de bytes como argumento:

buffer = BSON::ByteBuffer.new(string) # a read mode buffer.

A leitura do buffer é feita por meio da seguinte API:

buffer.get_byte # Pulls a single byte from the buffer.
buffer.get_bytes(value) # Pulls n number of bytes from the buffer.
buffer.get_cstring # Pulls a null-terminated string from the buffer.
buffer.get_double # Pulls a 64-bit floating point from the buffer.
buffer.get_int32 # Pulls a 32-bit integer (4 bytes) from the buffer.
buffer.get_int64 # Pulls a 64-bit integer (8 bytes) from the buffer.
buffer.get_string # Pulls a UTF-8 string from the buffer.

Para reiniciar a leitura a partir do início de um buffer, use rewind:

buffer.rewind

BSON::Binary

Utilize objetos BSON::Binary para armazenar dados binários arbitrários. Os objetos Binary podem ser construídos a partir de strings binárias da seguinte forma:

BSON::Binary.new("binary_string")
# => <BSON::Binary:0x47113101192900 type=generic data=0x62696e6172795f73...>

Por padrão, objetos Binary são criados com BSON subtipo binário 0 (:generic). O subtipo pode ser explicitamente especificado para indicar que os bytes codificam um tipo específico de dados:

BSON::Binary.new("binary_string", :user)
# => <BSON::Binary:0x47113101225420 type=user data=0x62696e6172795f73...>

Os subtipos válidos são :generic, :function, :old, :uuid_old, :uuid, :md5 e :user.

Os dados e o subtipo podem ser recuperados de instâncias do Binary utilizando atributos do data e type , como segue:

binary = BSON::Binary.new("binary_string", :user)
binary.data
=> "binary_string"
binary.type
=> :user

str = "binary_string"
str.encoding
# => #<Encoding:US-ASCII>
binary = BSON::Binary.new(str)
binary.data
# => "binary_string"
binary.data.encoding
# => #<Encoding:ASCII-8BIT>

uuid_str = "00112233-4455-6677-8899-aabbccddeeff"
BSON::Binary.from_uuid(uuid_str)
# => <BSON::Binary:0x46986653612880 type=uuid data=0x0011223344556677...>

binary = BSON::Binary.new("\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF".force_encoding('BINARY'), :uuid)
=> <BSON::Binary:0x46942046606480 type=uuid data=0x0011223344556677...>
binary.to_uuid
=> "00112233-4455-6677-8899aabbccddeeff"

binary = BSON::Binary.from_uuid(uuid_str, :standard)
binary.to_uuid(:standard)

binary = BSON::Binary.new("\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF".force_encoding('BINARY'), :uuid_old)
=> <BSON::Binary:0x46942046606480 type=uuid data=0x0011223344556677...>
binary.to_uuid
# => ArgumentError (Representation must be specified for BSON::Binary objects of type :uuid_old)
binary.to_uuid(:csharp_legacy)
# => "33221100-5544-7766-8899aabbccddeeff"
binary.to_uuid(:java_legacy)
# => "77665544-3322-1100-ffeeddccbbaa9988"
binary.to_uuid(:python_legacy)
# => "00112233-4455-6677-8899aabbccddeeff"

uuid_str = "00112233-4455-6677-8899-aabbccddeeff"
BSON::Binary.from_uuid(uuid_str, :csharp_legacy)
# => <BSON::Binary:0x46986653650480 type=uuid_old data=0x3322110055447766...>
BSON::Binary.from_uuid(uuid_str, :java_legacy)
# => <BSON::Binary:0x46986653663960 type=uuid_old data=0x7766554433221100...>
BSON::Binary.from_uuid(uuid_str, :python_legacy)
# => <BSON::Binary:0x46986653686300 type=uuid_old data=0x0011223344556677...>

BSON::Binary.from_uuid('77665544-3322-1100-ffeeddccbbaa9988',:java_legacy).to_uuid(:csharp_legacy)
# => "33221100-5544-7766-8899aabbccddeeff"

BSON::Code

Representa uma string de código JavaScript.

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

BSON::CodeWithScope

Representa uma string de código JavaScript com um hash de valores.

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

BSON::DBRef

Esta é uma subclasse de BSON::Document que fornece acessadores para a coleção, id e banco de dados do DBRef.

BSON::DBRef.new({"$ref" => "collection", "$id" => "id"})
BSON::DBRef.new({"$ref" => "collection", "$id" => "id", "database" => "db"})

bson = {"$ref" => "collection", "$id" => "id"}.to_bson.to_s
loaded = Hash.from_bson(BSON::ByteBuffer.new(bson))
=> {"$ref"=>"collection", "$id"=>"id"}
loaded.class
=> BSON::DBRef

Para compatibilidade com versões 2.17 e anteriores do driver Ruby do MongoDB, BSON::DBRef também pode ser construído usando a API de driver legada. Esta API está obsoleta e será removida em uma versão futura do bson-ruby:

BSON::DBRef.new("collection", BSON::ObjectId('61eeb760a15d5d0f9f1e401d'))
BSON::DBRef.new("collection", BSON::ObjectId('61eeb760a15d5d0f9f1e401d'), "db")

BSON::Document

Esta é uma subclasse de Hash que armazena todas as chaves como strings, mas permite acesso a elas com chaves de símbolo.

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

bson = {test: 1}.to_bson.to_s
loaded = Hash.from_bson(BSON::ByteBuffer.new(bson))
=> {"test"=>1}
loaded.class
=> BSON::Document

BSON::MaxKey

Representa um valor em BSON que sempre será comparado com outro valor.

BSON::MaxKey.new

BSON::MinKey

Representa um valor em BSON que sempre será comparado como inferior a outro valor.

BSON::MinKey.new

BSON::ObjectId

Representa um identificador exclusivo de 12 bytes para um objeto em uma determinada máquina.

BSON::ObjectId.new

BSON::Timestamp

Representa um horário especial com um valor inicial e incremental.

BSON::Timestamp.new(5, 30)

BSON::Undefined

Representa um espaço reservado para um valor que não foi fornecido.

BSON::Undefined.new

BSON::Decimal128

Representa um valor de ponto flutuante baseado em decimal de 128 bits capaz de emular arredondamentos decimais com precisão exata.

# Instantiate with a String
BSON::Decimal128.new("1.28")
# Instantiate with a BigDecimal
d = BigDecimal(1.28, 3)
BSON::Decimal128.new(d)

Symbol

A especificação BSON define um tipo de símbolo que permite percorrer valores Ruby Symbol (ou seja, um Ruby Symbol``is encoded into a BSON symbol and a BSON symbol is decoded into a Ruby ``Symbol). No entanto, como a maioria das linguagens de programação não tem um tipo de símbolo nativo, para promover a interoperabilidade, o MongoDB depreciou o tipo de símbolo BSON e incentiva o uso de strings.

Hash.from_bson({foo: 'bar'}.to_bson)
# => {"foo"=>"bar"}
Hash.from_bson({1 => 2}.to_bson)
# => {"1"=>2}

Por padrão, a biblioteca BSON codifica valores de hash Symbol como strings e decodifica símbolos BSON em valores Ruby Symbol :

{foo: :bar}.to_bson.to_s
# => "\x12\x00\x00\x00\x02foo\x00\x04\x00\x00\x00bar\x00\x00"
# 0x02 is the string type
Hash.from_bson(BSON::ByteBuffer.new("\x12\x00\x00\x00\x02foo\x00\x04\x00\x00\x00bar\x00\x00".force_encoding('BINARY')))
# => {"foo"=>"bar"}
# 0x0E is the symbol type
Hash.from_bson(BSON::ByteBuffer.new("\x12\x00\x00\x00\x0Efoo\x00\x04\x00\x00\x00bar\x00\x00".force_encoding('BINARY')))
# => {"foo"=>:bar}

Para forçar a codificação de símbolos Ruby para símbolos BSON, envolva os símbolos Ruby em BSON::Symbol::Raw:

{foo: BSON::Symbol::Raw.new(:bar)}.to_bson.to_s
# => "\x12\x00\x00\x00\x0Efoo\x00\x04\x00\x00\x00bar\x00\x00"

Expressões regulares Ruby versus MongoDB

O servidor MongoDB usa expressões regulares compatíveis com Perl implementadas usando a biblioteca PCRE e expressões regulares Ruby são implementadas usando o mecanismo de expressão regular Onigmo, que é uma bifurcação do Oniguruma. As duas implementações de expressão regular geralmente fornecem funcionalidade equivalente, mas têm várias diferenças de sintaxe importantes, conforme descrito abaixo.

Infelizmente, não há uma maneira simples de converter programaticamente uma expressão regular PCRE na expressão regular Ruby equivalente, e atualmente não há vinculações Ruby para PCRE.

BSON::Regexp::Raw classe

Como não há uma maneira simples de converter programaticamente uma expressão PCRE na expressão Ruby equivalente, o BSON fornece a classe BSON::Regexp::Raw para manter as expressão do MongoDB/PCRE. As instâncias dessa classe são chamadas de "expressões regulares BSON" nesta documentação.

As instâncias desta classe podem ser criadas utilizando o texto de expressão regular como uma string e modificadores PCRE opcionais:

BSON::Regexp::Raw.new("^b403158")
# => #<BSON::Regexp::Raw:0x000055df63186d78 @pattern="^b403158", @options="">
BSON::Regexp::Raw.new("^Hello.world$", "s")
# => #<BSON::Regexp::Raw:0x000055df6317f028 @pattern="^Hello.world$", @options="s">

O módulo BSON::Regexp está incluído na classe Ruby Regexp , de modo que o prefixo BSON:: pode ser omitido:

Regexp::Raw.new("^b403158")
# => #<BSON::Regexp::Raw:0x000055df63186d78 @pattern="^b403158", @options="">
Regexp::Raw.new("^Hello.world$", "s")
# => #<BSON::Regexp::Raw:0x000055df6317f028 @pattern="^Hello.world$", @options="s">

Conversão de expressões regulares

Para converter uma expressão regular Ruby em uma expressão regular BSON, instancie um objeto BSON::Regexp::Raw da seguinte forma:

regexp = /^Hello.world/
bson_regexp = BSON::Regexp::Raw.new(regexp.source, regexp.options)
# => #<BSON::Regexp::Raw:0x000055df62e42d60 @pattern="^Hello.world", @options=0>

Observe que o construtor BSON::Regexp::Raw aceita as opções numéricas Ruby e as strings de modificadores PCRE.

Para converter uma expressão regular BSON em uma expressão regular Ruby, chame o método compile na expressão regular BSON:

bson_regexp = BSON::Regexp::Raw.new("^hello.world", "s")
bson_regexp.compile
# => /^hello.world/m
bson_regexp = BSON::Regexp::Raw.new("^hello", "")
bson_regexp.compile
# => /^hello.world/
bson_regexp = BSON::Regexp::Raw.new("^hello.world", "m")
bson_regexp.compile
# => /^hello.world/

Observe que o modificador PCRE s foi convertido no modificador Ruby m no primeiro exemplo e os dois últimos exemplos foram convertidos na mesma expressão regular, embora as expressões regulares BSON originais tenham significados diferentes.

Quando uma expressão regular BSON utiliza as âncoras não portáteis ^ e $ , sua conversão para uma expressão regular Ruby pode alterar seu significado:

BSON::Regexp::Raw.new("^hello.world", "").compile =~ "42\nhello world"
# => 3

Quando uma expressão regular Ruby é convertida em uma expressão regular BSON (por exemplo, para enviar ao servidor como parte de uma query), a expressão regular BSON sempre tem o modificador m definido refletindo o comportamento de ^ e $ âncoras em expressões regulares Ruby.

Leitura e escrita

As expressões regulares Ruby e BSON implementam o método to_bson para serialização para BSON:

regexp_ruby = /^b403158/
# => /^b403158/
regexp_ruby.to_bson
# => #<BSON::ByteBuffer:0x007fcf20ab8028>
_.to_s
# => "^b403158\x00m\x00"
regexp_raw = Regexp::Raw.new("^b403158")
# => #<BSON::Regexp::Raw:0x007fcf21808f98 @pattern="^b403158", @options="">
regexp_raw.to_bson
# => #<BSON::ByteBuffer:0x007fcf213622f0>
_.to_s
# => "^b403158\x00\x00"

As classes Regexp e BSON::Regexp::Raw implementam o método de classe from_bson que desserializa uma expressão regular de um buffer de bytes BSON. Os métodos de ambas as classes retornam uma instância BSON::Regexp::Raw que deve ser convertida em uma expressão regular Ruby usando o método compile conforme descrito acima.

byte_buffer = BSON::ByteBuffer.new("^b403158\x00\x00")
regex = Regexp.from_bson(byte_buffer)
# => #<BSON::Regexp::Raw:0x000055df63100d40 @pattern="^b403158", @options="">
regex.pattern
# => "^b403158"
regex.options
# => ""
regex.compile
# => /^b403158/