MongoDB::BSON - Tools for serializing and deserializing data in BSON form
version v1.0.3
my $codec = MongoDB::BSON->new; my $bson = $codec->encode_one( $document ); my $doc = $codec->decode_one( $bson );
This class implements a BSON encoder/decoder ("codec"). It consumes documents and emits BSON strings and vice versa.
A document with keys $ref and $id is a special MongoDB convention representing a DBRef.
$ref
$id
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.)
$db
The default dbref_callback returns the DBRef hash reference without modification.
dbref_callback
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:
bson_codec
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.
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.
undef
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)
encode_one
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.
Carp::croak
A string containing ASCII characters that must not appear in keys. The default is the empty string, meaning there are no invalid characters.
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).
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 "$".
op_char
The default is "$".
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.
$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_key
first_value
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
$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.
dbref_callback – overrides codec default
dt_type – overrides codec default
$codec->clone( dt_type => 'Time::Moment' );
Constructs a copy of the original codec, but allows changing attributes in the copy.
David Golden <david@mongodb.com>
Mike Friedman <friedo@friedo.com>
Kristina Chodorow <k.chodorow@gmail.com>
Florian Ragwitz <rafl@debian.org>
This software is Copyright (c) 2015 by MongoDB, Inc..
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
To install MongoDB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MongoDB
CPAN shell
perl -MCPAN -e shell install MongoDB
For more information on module installation, please visit the detailed CPAN module installation guide.