bionic (3) MongoDB::BSON.3pm.gz

NAME

       MongoDB::BSON - Tools for serializing and deserializing data in BSON form

VERSION

       version v1.8.1

SYNOPSIS

           my $codec = MongoDB::BSON->new;

           my $bson = $codec->encode_one( $document );
           my $doc  = $codec->decode_one( $bson     );

DESCRIPTION

       This class implements a BSON encoder/decoder ("codec").  It consumes documents and emits BSON strings and
       vice versa.

ATTRIBUTES

   dbref_callback
       A document with keys $ref and $id is a special MongoDB convention representing a DBRef
       <http://docs.mongodb.org/manual/applications/database-references/#dbref>.

       This attribute specifies a function reference that will be called with a hash reference argument
       representing a DBRef.

       The hash reference will have keys $ref and $id and may have $db and other keys.  The callback must return
       a scalar value representing the dbref (e.g. a document, an object, etc.)

       The default "dbref_callback" returns the DBRef hash reference without modification.

       Note: in MongoDB::MongoClient, when no MongoDB::BSON object is provided as the "bson_codec" attribute,
       <MongoDB:MongoClient> creates a custom MongoDB::BSON object that inflates DBRefs into MongoDB::DBRef
       objects using a custom "dbref_callback":

           dbref_callback => sub { return MongoDB::DBRef->new(shift) },

       Object-database mappers may wish to implement alternative "dbref_callback" attributes to provide whatever
       semantics they require.

   dt_type
       Sets the type of object which is returned for BSON DateTime fields. The default is DateTime. Other
       acceptable values are Time::Moment, DateTime::Tiny and "undef". The latter will give you the raw epoch
       value (possibly as a floating point value) rather than an object.

   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 operators.  If a key starts with "op_char", the "op_char"
       character will be replaced with "$".

       The default is "$".

   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.

       The default is false.

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 representin the decoded
       document.

       An optional hash reference of options may be provided.  Valid options include:

       •   dbref_callback – overrides codec default

       •   dt_type – overrides codec default

       •   error_callback – overrides codec default

       •   max_length – overrides codec default

   clone
           $codec->clone( dt_type => 'Time::Moment' );

       Constructs a copy of the original codec, but allows changing attributes in the copy.

AUTHORS

       •   David Golden <david@mongodb.com>

       •   Rassi <rassi@mongodb.com>

       •   Mike Friedman <friedo@friedo.com>

       •   Kristina Chodorow <k.chodorow@gmail.com>

       •   Florian Ragwitz <rafl@debian.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2018 by MongoDB, Inc.

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004