/ 
MongoDB-v1.3.0-TRIAL
River stage two • 48 direct dependents • 56 total dependents
/ MongoDB::BSON

NAME

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

VERSION

version v1.3.0

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.

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>

  • Mike Friedman <friedo@friedo.com>

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

  • Florian Ragwitz <rafl@debian.org>

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

The Apache License, Version 2.0, January 2004