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.

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.

inflate_extjson

Given a hash reference, this method walks the hash, replacing any 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.

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.