BSON - BSON serialization and deserialization (EOL)
version v1.12.2
Version v1.12.0 was the final feature release of the MongoDB BSON library and
version v1.12.2 is the final patch release.
As of August 13, 2020, the MongoDB Perl driver and related libraries have
reached end of life and are no longer supported by MongoDB. See the
August 2019 deprecation notice
<
https://www.mongodb.com/blog/post/the-mongodb-perl-driver-is-being-deprecated>
for rationale.
If members of the community wish to continue development, they are welcome to
fork the code under the terms of the Apache 2 license and release it under a
new namespace. Specifications and test files for MongoDB drivers and libraries
are published in an open repository: mongodb/specifications
<
https://github.com/mongodb/specifications/tree/master/source>.
use BSON;
use BSON::Types ':all';
use boolean;
my $codec = BSON->new;
my $document = {
_id => bson_oid(),
creation_time => bson_time(), # now
zip_code => bson_string("08544"),
hidden => false,
};
my $bson = $codec->encode_one( $document );
my $doc = $codec->decode_one( $bson );
This class implements a BSON encoder/decoder ("codec"). It consumes
"documents" (typically hash references) and emits BSON strings and
vice versa in accordance with the BSON Specification
<
http://bsonspec.org>.
BSON is the primary data representation for MongoDB. While this module has
several features that support MongoDB-specific needs and conventions, it can
be used as a standalone serialization format.
The codec may be customized through attributes on the codec option as well as
encode/decode specific options on methods:
my $codec = BSON->new( \%global_attributes );
my $bson = $codec->encode_one( $document, \%encode_options );
my $doc = $codec->decode_one( $bson , \%decode_options );
Because BSON is strongly-typed and Perl is not, this module supports a number of
"type wrappers" – classes that wrap Perl data to indicate how
they should serialize. The BSON::Types module describes these and provides
associated helper functions. See "PERL-BSON TYPE MAPPING" for more
details.
When decoding, type wrappers are used for any data that has no native Perl
representation. Optionally, all data may be wrapped for precise control of
round-trip encoding.
Please read the configuration attributes carefully to understand more about how
to control encoding and decoding.
At compile time, this module will select an implementation backend. It will
prefer "BSON::XS" (released separately) if available, or will fall
back to BSON::PP (bundled with this module). See "ENVIRONMENT" for a
way to control the selection of the backend.
This attribute specifies a function reference that will be called with three
positional arguments:
- •
- an error string argument describing the error
condition
- •
- a reference to the problematic document or byte-string
- •
- the method in which the error occurred (e.g.
"encode_one" or "decode_one")
Note: for decoding errors, the byte-string is passed as a reference to avoid
copying possibly large strings.
If not provided, errors messages will be thrown with "Carp::croak".
A string containing ASCII characters that must not appear in keys. The default
is the empty string, meaning there are no invalid characters.
This attribute defines the maximum document size. The default is 0, which
disables any maximum.
If set to a positive number, it applies to both encoding
and decoding
(the latter is necessary for prevention of resource consumption attacks).
This is a single character to use for special MongoDB-specific query operators.
If a key starts with "op_char", the "op_char" character
will be replaced with "$".
The default is "$", meaning that no replacement is necessary.
If set to a true value, then decoding will return a reference to a tied hash
that preserves key order. Otherwise, a regular (unordered) hash reference will
be returned.
IMPORTANT CAVEATS:
- •
- When 'ordered' is true, users must not rely on the return
value being any particular tied hash implementation. It may change in the
future for efficiency.
- •
- Turning this option on entails a significant speed penalty
as tied hashes are slower than regular Perl hashes.
The default is false.
When false, scalar values will be encoded as a number if they were originally a
number or were ever used in a numeric context. However, a string that looks
like a number but was never used in a numeric context (e.g. "42")
will be encoded as a string.
If "prefer_numeric" is set to true, the encoder will attempt to coerce
strings that look like a number into a numeric value. If the string doesn't
look like a double or integer, it will be encoded as a string.
IMPORTANT CAVEAT: the heuristics for determining whether something is a
string or number are less accurate on older Perls. See BSON::Types for wrapper
classes that specify exact serialization types.
The default is false.
If set to true, during decoding, documents with the fields '$id' and '$ref'
(literal dollar signs, not variables) will be wrapped as BSON::DBRef objects.
If false, they are decoded into ordinary hash references (or ordered hashes,
if "ordered" is true).
The default is true.
If set to true, during decoding, numeric values will be wrapped into BSON
type-wrappers: BSON::Double, BSON::Int64 or BSON::Int32. While very slow, this
can help ensure fields can round-trip if unmodified.
The default is false.
If set to true, during decoding, string values will be wrapped into a BSON
type-wrappers, BSON::String. While very slow, this can help ensure fields can
round-trip if unmodified.
The default is false.
Sets the type of object which is returned for BSON DateTime fields. The default
is "undef", which returns objects of type BSON::Time. This is
overloaded to be the integer epoch value when used as a number or string, so
is somewhat backwards compatible with "dt_type" in the MongoDB
driver.
Other acceptable values are BSON::Time (explicitly), DateTime, Time::Moment,
DateTime::Tiny, Mango::BSON::Time.
Because BSON::Time objects have methods to convert to DateTime, Time::Moment or
DateTime::Tiny, use of this field is discouraged. Users should use these
methods on demand. This option is provided for backwards compatibility only.
$byte_string = $codec->encode_one( $doc );
$byte_string = $codec->encode_one( $doc, \%options );
Takes a "document", typically a hash reference, an array reference, or
a Tie::IxHash object and returns a byte string with the BSON representation of
the document.
An optional hash reference of options may be provided. Valid options include:
- •
- first_key – if "first_key" is
defined, it and "first_value" will be encoded first in the
output BSON; any matching key found in the document will be ignored.
- •
- first_value - value to assign to "first_key";
will encode as Null if omitted
- •
- error_callback – overrides codec default
- •
- invalid_chars – overrides codec default
- •
- max_length – overrides codec default
- •
- op_char – overrides codec default
- •
- prefer_numeric – overrides codec default
$doc = $codec->decode_one( $byte_string );
$doc = $codec->decode_one( $byte_string, \%options );
Takes a byte string with a BSON-encoded document and returns a hash reference
representing the decoded document.
An optional hash reference of options may be provided. Valid options include:
- •
- dt_type – overrides codec default
- •
- error_callback – overrides codec default
- •
- max_length – overrides codec default
- •
- ordered - overrides codec default
- •
- wrap_dbrefs - overrides codec default
- •
- wrap_numbers - overrides codec default
- •
- wrap_strings - overrides codec default
$copy = $codec->clone( ordered => 1 );
Constructs a copy of the original codec, but allows changing attributes in the
copy.
$oid = BSON->create_oid;
This class method returns a new BSON::OID. This abstracts OID generation away
from any specific Object ID class and makes it an interface on a BSON codec.
Alternative BSON codecs should define a similar class method that returns an
Object ID of whatever type is appropriate.
This legacy method does not follow the MongoDB Extended JSON
<
https://github.com/mongodb/specifications/blob/master/source/extended-json.rst>
specification.
Use "extjson_to_perl" instead.
use JSON::MaybeXS;
my $ext = BSON->perl_to_extjson($data, \%options);
my $json = encode_json($ext);
Takes a perl data structure (i.e. hashref) and turns it into an MongoDB Extended
JSON
<
https://github.com/mongodb/specifications/blob/master/source/extended-json.rst>
structure. Note that the structure will still have to be serialized.
Possible options are:
- •
- "relaxed" A boolean indicating if "relaxed
extended JSON" should
be generated. If not set, the default value is taken from the
"BSON_EXTJSON_RELAXED" environment variable.
use JSON::MaybeXS;
my $ext = decode_json($json);
my $data = $bson->extjson_to_perl($ext);
Takes an MongoDB Extended JSON
<
https://github.com/mongodb/specifications/blob/master/source/extended-json.rst>
data structure and inflates it into a Perl data structure. Note that you have
to decode the JSON string manually beforehand.
Canonically specified numerical values like
"{"$numberInt":"23"}" will be inflated into
their respective "BSON::*" wrapper types. Plain numeric values will
be left as-is.
my $bson = encode({ bar => 'foo' }, \%options);
This is the legacy, functional interface and is only exported on demand. It
takes a hashref and returns a BSON string. It uses an internal codec singleton
with default attributes.
my $hash = decode( $bson, \%options );
This is the legacy, functional interface and is only exported on demand. It
takes a BSON string and returns a hashref. It uses an internal codec singleton
with default attributes.
BSON has numerous data types and Perl does not.
When
decoding, each BSON type should result in a single, predictable Perl
type. Where no native Perl type is appropriate, BSON decodes to an object of a
particular class (a "type wrapper").
When
encoding, for historical reasons, there may be many Perl
representations that should encode to a particular BSON type. For example, all
the popular "boolean" type modules on CPAN should encode to the BSON
boolean type. Likewise, as this module is intended to supersede the type
wrappers that have shipped with the MongoDB module, those type wrapper are
supported by this codec.
The table below describes the BSON/Perl mapping for both encoding and decoding.
On the left are all the Perl types or classes this BSON codec knows how to
serialize to BSON. The middle column is the BSON type for each class. The
right-most column is the Perl type or class that the BSON type deserializes
to. Footnotes indicate variations or special behaviors.
Perl type/class -> BSON type -> Perl type/class
-------------------------------------------------------------------
float[1] 0x01 DOUBLE float[2]
BSON::Double
-------------------------------------------------------------------
string[3] 0x02 UTF8 string[2]
BSON::String
-------------------------------------------------------------------
hashref 0x03 DOCUMENT hashref[4][5]
BSON::Doc
BSON::Raw
MongoDB::BSON::Raw[d]
Tie::IxHash
-------------------------------------------------------------------
arrayref 0x04 ARRAY arrayref
-------------------------------------------------------------------
BSON::Bytes 0x05 BINARY BSON::Bytes
scalarref
BSON::Binary[d]
MongoDB::BSON::Binary[d]
-------------------------------------------------------------------
n/a 0x06 UNDEFINED[d] undef
-------------------------------------------------------------------
BSON::OID 0x07 OID BSON::OID
BSON::ObjectId[d]
MongoDB::OID[d]
-------------------------------------------------------------------
boolean 0x08 BOOL boolean
BSON::Bool[d]
JSON::XS::Boolean
JSON::PP::Boolean
JSON::Tiny::_Bool
Mojo::JSON::_Bool
Cpanel::JSON::XS::Boolean
Types::Serialiser::Boolean
-------------------------------------------------------------------
BSON::Time 0x09 DATE_TIME BSON::Time
DateTime
DateTime::Tiny
Time::Moment
Mango::BSON::Time
-------------------------------------------------------------------
undef 0x0a NULL undef
-------------------------------------------------------------------
BSON::Regex 0x0b REGEX BSON::Regex
qr// reference
MongoDB::BSON::Regexp[d]
-------------------------------------------------------------------
n/a 0x0c DBPOINTER[d] BSON::DBRef
-------------------------------------------------------------------
BSON::Code[6] 0x0d CODE BSON::Code
MongoDB::Code[6]
-------------------------------------------------------------------
n/a 0x0e SYMBOL[d] string
-------------------------------------------------------------------
BSON::Code[6] 0x0f CODEWSCOPE BSON::Code
MongoDB::Code[6]
-------------------------------------------------------------------
integer[7][8] 0x10 INT32 integer[2]
BSON::Int32
-------------------------------------------------------------------
BSON::Timestamp 0x11 TIMESTAMP BSON::Timestamp
MongoDB::Timestamp[d]
-------------------------------------------------------------------
integer[7] 0x12 INT64 integer[2][9]
BSON::Int64
Math::BigInt
Math::Int64
-------------------------------------------------------------------
BSON::MaxKey 0x7F MAXKEY BSON::MaxKey
MongoDB::MaxKey[d]
-------------------------------------------------------------------
BSON::MinKey 0xFF MINKEY BSON::MinKey
MongoDB::MinKey[d]
[d] Deprecated or soon to be deprecated.
[1] Scalar with "NV" internal representation or a string that looks
like a float if the 'prefer_numeric' option is true.
[2] If the 'wrap_numbers' option is true, numeric types will be wrapped
as BSON::Double, BSON::Int32 or BSON::Int64 as appropriate to ensure
round-tripping. If the 'wrap_strings' option is true, strings will
be wrapped as BSON::String, likewise.
[3] Scalar without "NV" or "IV" representation and not identified as a
number by notes [1] or [7].
[4] If 'ordered' option is set, will return a tied hash that preserves
order (deprecated 'ixhash' option still works).
[5] If the document appears to contain a DBRef and a 'dbref_callback'
exists, that callback is executed with the deserialized document.
[6] Code is serialized as CODE or CODEWSCOPE depending on whether a
scope hashref exists in BSON::Code/MongoDB::Code.
[7] Scalar with "IV" internal representation or a string that looks like
an integer if the 'prefer_numeric' option is true.
[8] Only if the integer fits in 32 bits.
[9] On 32-bit platforms, 64-bit integers are deserialized to
Math::BigInt objects (even if subsequently wrapped into
BSON::Int64 if 'wrap_scalars' is true).
Threads are never recommended in Perl, but this module is thread safe.
- •
- PERL_BSON_BACKEND – if set at compile time, this
will be treated as a module name. The module will be loaded and used as
the BSON backend implementation. It must implement the same API as
"BSON::PP".
- •
- BSON_EXTJSON - if set, serializing BSON type wrappers via
"TO_JSON" will produce Extended JSON v2 output.
- •
- BSON_EXTJSON_RELAXED - if producing Extended JSON output,
if this is true, values will use the "Relaxed" form of Extended
JSON, which sacrifices type round-tripping for improved human
readability.
Starting with BSON "v0.999.0", this module is using a
"tick-tock" three-part version-tuple numbering scheme:
"vX.Y.Z"
- •
- In stable releases, "X" will be incremented for
incompatible API changes.
- •
- Even-value increments of "Y" indicate stable
releases with new functionality. "Z" will be incremented for bug
fixes.
- •
- Odd-value increments of "Y" indicate unstable
("development") releases that should not be used in production.
"Z" increments have no semantic meaning; they indicate only
successive development releases. Development releases may have
API-breaking changes, usually indicated by "Y" equal to
"999".
This module was originally written by Stefan G. In 2014, he graciously
transferred ongoing maintenance to MongoDB, Inc.
The "bson_xxxx" helper functions in BSON::Types were inspired by
similar work in Mango::BSON by Sebastian Riedel.
- •
- David Golden <[email protected]>
- •
- Stefan G. <[email protected]>
- •
- Eric Daniels <[email protected]>
- •
- Finn <[email protected]>
- •
- Olivier Duclos <[email protected]>
- •
- Pat Gunn <[email protected]>
- •
- Petr Písař <[email protected]>
- •
- Robert Sedlacek <[email protected]>
- •
- Thomas Bloor <[email protected]>
- •
- Tobias Leich <[email protected]>
- •
- Wallace Reis <[email protected]>
- •
- Yury Zavarin <[email protected]>
- •
- Oleg Kostyuk <[email protected]>
This software is Copyright (c) 2020 by Stefan G. and MongoDB, Inc.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004