GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  MONGODB::BSON (3)

.ds Aq ’

NAME

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

CONTENTS

VERSION

version v1.2.3

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 <B>customB> 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:
o an error string argument describing the error condition
o a reference to the problematic document or byte-string
o 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 <B>andB> 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:
o first_key X 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.
o first_value - value to assign to first_key; will encode as Null if omitted
o error_callback X overrides codec default
o invalid_chars X overrides codec default
o max_length X overrides codec default
o op_char X overrides codec default
o prefer_numeric X 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:
o dbref_callback X overrides codec default
o dt_type X overrides codec default
o error_callback X overrides codec default
o max_length X 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

o David Golden <david@mongodb.com>
o Mike Friedman <friedo@friedo.com>
o Kristina Chodorow <k.chodorow@gmail.com>
o Florian Ragwitz <rafl@debian.org>

COPYRIGHT AND LICENSE

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

This is free software, licensed under:



  The Apache License, Version 2.0, January 2004



Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 MONGODB::BSON (3) 2016-03-08

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.