NAME

VERSION

END OF LIFE NOTICE

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>.

SYNOPSIS

    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     );

DESCRIPTION

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

METHODS

    $byte_string = $codec->encode_one( $doc );
    $byte_string = $codec->encode_one( $doc, \%options );

    $doc = $codec->decode_one( $byte_string );
    $doc = $codec->decode_one( $byte_string, \%options );

    $copy = $codec->clone( ordered => 1 );

    $oid = BSON->create_oid;

    use JSON::MaybeXS;
    my $ext = BSON->perl_to_extjson($data, \%options);
    my $json = encode_json($ext);

    use JSON::MaybeXS;
    my $ext = decode_json($json);
    my $data = $bson->extjson_to_perl($ext);

FUNCTIONS

    my $bson = encode({ bar => 'foo' }, \%options);

    my $hash = decode( $bson, \%options );

PERL-BSON TYPE MAPPING

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

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".
• 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.

SEMANTIC VERSIONING SCHEME

• 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

The "bson_xxxx" helper functions in BSON::Types were inspired by similar work in Mango::BSON by Sebastian Riedel.

AUTHORS

• David Golden <david@mongodb.com>
• Stefan G. <minimalist@lavabit.com>

CONTRIBUTORS

• Eric Daniels <eric.daniels@mongodb.com>
• Finn <toyou1995@gmail.com>
• Olivier Duclos <odc@cpan.org>
• Pat Gunn <pgunn@mongodb.com>
• Petr Písař <ppisar@redhat.com>
• Robert Sedlacek <rs@474.at>
• Thomas Bloor <tbsliver@shadow.cat>
• Tobias Leich <email@froggs.de>
• Wallace Reis <wallace@reis.me>
• Yury Zavarin <yury.zavarin@gmail.com>
• Oleg Kostyuk <cub@cpan.org>

COPYRIGHT AND LICENSE

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004