NAME
    BSON - Pure Perl implementation of MongoDB's BSON serialization

VERSION
    version 0.16

SYNOPSIS
        use BSON qw/encode decode/;

        my $document = {
            _id      => BSON::ObjectId->new,
            date     => BSON::Time->new,
            name     => 'James Bond',
            age      => 45,
            amount   => 24587.45,
            badass   => BSON::Bool->true,
            password => BSON::String->new('12345')
        };

        my $bson = encode( $document );
        my $doc2 = decode( $bson, %options );

DESCRIPTION
    This module implements BSON serialization and deserialization as
    described at <http://bsonspec.org>. BSON is the primary data
    representation for MongoDB.

EXPORT
    The module does not export anything. You have to request "encode" and/or
    "decode" manually.

        use BSON qw/encode decode/;

SUBROUTINES
  encode
    Takes a hashref and returns a BSON string.

        my $bson = encode({ bar => 'foo' });

  decode
    Takes a BSON string and returns a hashref.

        my $hash = decode( $bson, ixhash => 1 );

    The options after $bson are optional and they can be any of the
    following:

   options
    1   ixhash => 1|0

        If set to 1 "decode" will return a Tie::IxHash ordered hash.
        Otherwise, a regular unordered hash will be returned. Turning this
        option on entails a significant speed penalty as Tie::IxHash is
        slower than a regular Perl hash. The default value for this option
        is 0.

THREADS
    This module is thread safe.

LIMITATION
    MongoDB sets a limit for any BSON record to 16MB. This module does not
    enforce this limit and you can use it to "encode" and "decode"
    structures as large as you please.

CAVEATS
    BSON uses zero terminated strings and Perl allows the \0 character to be
    anywhere in a string. If you expect your strings to contain \0
    characters, use BSON::Binary instead.

HISTORY AND ROADMAP
    This module was originally written by minimalist. In 2014, he graciously
    transferred ongoing maintenance to MongoDB, Inc.

    Going forward, work will focus on restoration of a pure-Perl dependency
    chain, harmonization with MongoDB driver BSON classes and some API
    enhancements so this can provide a pure-Perl alternative serializer for
    the MongoDB driver.

SEE ALSO
    BSON::String, BSON::Time, BSON::ObjectId, BSON::Code, BSON::Binary,
    BSON::Bool, BSON::MinKey, BSON::MaxKey, BSON::Timestamp, Tie::IxHash,
    MongoDB

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
    *   minimalist <minimalist@lavabit.com>

    *   David Golden <david@mongodb.com>

CONTRIBUTORS
    *   Eric Daniels <eric.daniels@mongodb.com>

    *   Pat Gunn <pgunn@mongodb.com>

    *   Yury Zavarin <yury.zavarin@gmail.com>

    *   Oleg Kostyuk <cub@cpan.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2015 by minimalist and MongoDB, Inc..

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004