Provided by: libbson-perl_1.4.0-1_all 
NAME
BSON - BSON serialization and deserialization
VERSION
version v1.4.0
SYNOPSIS
use BSON;
use BSON::Types ':all';
use boolean;
my $codec = BSON->new;
my $document = {
_id => bson_oid(),
creation_time => bson_time(),
zip_code => bson_string("08544"),
hidden => false,
};
my $bson = $codec->encode_one( $document );
my $doc = $codec->decode_one( $bson );
DESCRIPTION
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.
ATTRIBUTES
error_callback
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".
invalid_chars
A string containing ASCII characters that must not appear in keys. The default is the
empty string, meaning there are no invalid characters.
max_length
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).
op_char
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.
ordered
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.
prefer_numeric
If set to true, scalar values that look like a numeric value will be encoded as a BSON
numeric type. When false, if the scalar value was ever used as a string, it will be
encoded as a BSON UTF-8 string, otherwise it will be encoded as a numeric type.
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.
wrap_dbrefs
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.
wrap_numbers
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.
wrap_strings
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.
dt_type (Discouraged)
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.
METHODS
encode_one
$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
decode_one
$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
clone
$copy = $codec->clone( ordered => 1 );
Constructs a copy of the original codec, but allows changing attributes in the copy.
inflate_extjson
use JSON::MaybeXS;
$data = decode_json( $json_string );
$bson->inflate_extjson( $data );
Given a hash reference, this method walks the hash, replacing any MongoDB extended JSON
<https://docs.mongodb.org/manual/reference/mongodb-extended-json/> items with BSON type-
wrapper equivalents. Additionally, any JSON boolean objects (e.g. "JSON::PP::Boolean")
will be replaced with boolean.pm true or false values.
FUNCTIONS
encode
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.
decode
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.
PERL-BSON TYPE MAPPING
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 no "PV"
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 with "PV" 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 and no "PV"
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
Threads are never recommended in Perl, but this module is thread safe for Perl 5.8.5 or
later. Threads are not supported on older Perls.
ENVIRONMENT
• 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".
SEMANTIC VERSIONING SCHEME
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".
HISTORY AND ROADMAP
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.
SUPPORT
Bugs / Feature Requests
Please report any bugs or feature requests through the issue tracker at
<https://jira.mongodb.org/browse/PERL>. You will be notified automatically of any
progress on your issue.
Source Code
This is open source software. The code repository is available for public review and
contribution under the terms of the license.
<https://github.com/mongodb/mongo-perl-bson>
git clone https://github.com/mongodb/mongo-perl-bson.git
AUTHORS
• David Golden <david@mongodb.com>
• Stefan G. <minimalist@lavabit.com>
CONTRIBUTORS
• Eric Daniels <eric.daniels@mongodb.com>
• Olivier Duclos <odc@cpan.org>
• Pat Gunn <pgunn@mongodb.com>
• Petr Písař <ppisar@redhat.com>
• Yury Zavarin <yury.zavarin@gmail.com>
• Oleg Kostyuk <cub@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2017 by Stefan G. and MongoDB, Inc.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004