BSON
view release on metacpan or search on metacpan
At compile time, this module will select an implementation backend. It
will prefer "BSON::XS" (released separately) if available, or will fall
back to BSON::PP (bundled with this module). See "ENVIRONMENT" for a way
to control the selection of the backend.
ATTRIBUTES
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 MongoDB-specific query
operators. If a key starts with "op_char", the "op_char" character will
be replaced with "$".
The default is "$", meaning that no replacement is necessary.
ordered
If set to a true value, then decoding will return a reference to a tied
hash that preserves key order. Otherwise, a regular (unordered) hash
reference will be returned.
IMPORTANT CAVEATS:
* When 'ordered' is true, users must not rely on the return value
being any particular tied hash implementation. It may change in the
future for efficiency.
* Turning this option on entails a significant speed penalty as tied
hashes are slower than regular Perl hashes.
The default is false.
prefer_numeric
When false, scalar values will be encoded as a number if they were
originally a number or were ever used in a numeric context. However, a
string that looks like a number but was never used in a numeric context
(e.g. "42") will be encoded as a string.
If "prefer_numeric" is set to true, the encoder will attempt to coerce
strings that look like a number into a numeric value. If the string
doesn't look like a double or integer, it will be encoded as a string.
IMPORTANT CAVEAT: the heuristics for determining whether something is a
string or number are less accurate on older Perls. See BSON::Types for
wrapper classes that specify exact serialization types.
The default is false.
wrap_dbrefs
If set to true, during decoding, documents with the fields '$id' and
'$ref' (literal dollar signs, not variables) will be wrapped as
BSON::DBRef objects. If false, they are decoded into ordinary hash
references (or ordered hashes, if "ordered" is true).
The default is true.
wrap_numbers
If set to true, during decoding, numeric values will be wrapped into
BSON type-wrappers: BSON::Double, BSON::Int64 or BSON::Int32. While very
slow, this can help ensure fields can round-trip if unmodified.
The default is false.
wrap_strings
If set to true, during decoding, string values will be wrapped into a
BSON type-wrappers, BSON::String. While very slow, this can help ensure
fields can round-trip if unmodified.
The default is false.
dt_type (Discouraged)
Sets the type of object which is returned for BSON DateTime fields. The
default is "undef", which returns objects of type BSON::Time. This is
overloaded to be the integer epoch value when used as a number or
string, so is somewhat backwards compatible with "dt_type" in the
MongoDB driver.
Other acceptable values are BSON::Time (explicitly), DateTime,
Time::Moment, DateTime::Tiny, Mango::BSON::Time.
Because BSON::Time objects have methods to convert to DateTime,
Time::Moment or DateTime::Tiny, use of this field is discouraged. Users
should use these methods on demand. This option is provided for
backwards compatibility only.
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:
BSON::Bytes 0x05 BINARY BSON::Bytes
scalarref
BSON::Binary[d]
MongoDB::BSON::Binary[d]
-------------------------------------------------------------------
n/a 0x06 UNDEFINED[d] undef
-------------------------------------------------------------------
BSON::OID 0x07 OID BSON::OID
BSON::ObjectId[d]
MongoDB::OID[d]
-------------------------------------------------------------------
boolean 0x08 BOOL boolean
BSON::Bool[d]
JSON::XS::Boolean
JSON::PP::Boolean
JSON::Tiny::_Bool
Mojo::JSON::_Bool
Cpanel::JSON::XS::Boolean
Types::Serialiser::Boolean
-------------------------------------------------------------------
BSON::Time 0x09 DATE_TIME BSON::Time
DateTime
DateTime::Tiny
Time::Moment
Mango::BSON::Time
-------------------------------------------------------------------
undef 0x0a NULL undef
-------------------------------------------------------------------
BSON::Regex 0x0b REGEX BSON::Regex
qr// reference
MongoDB::BSON::Regexp[d]
-------------------------------------------------------------------
n/a 0x0c DBPOINTER[d] BSON::DBRef
-------------------------------------------------------------------
BSON::Code[6] 0x0d CODE BSON::Code
MongoDB::Code[6]
-------------------------------------------------------------------
n/a 0x0e SYMBOL[d] string
-------------------------------------------------------------------
BSON::Code[6] 0x0f CODEWSCOPE BSON::Code
MongoDB::Code[6]
-------------------------------------------------------------------
integer[7][8] 0x10 INT32 integer[2]
BSON::Int32
-------------------------------------------------------------------
BSON::Timestamp 0x11 TIMESTAMP BSON::Timestamp
MongoDB::Timestamp[d]
-------------------------------------------------------------------
integer[7] 0x12 INT64 integer[2][9]
BSON::Int64
Math::BigInt
Math::Int64
-------------------------------------------------------------------
BSON::MaxKey 0x7F MAXKEY BSON::MaxKey
MongoDB::MaxKey[d]
-------------------------------------------------------------------
BSON::MinKey 0xFF MINKEY BSON::MinKey
MongoDB::MinKey[d]
[d] Deprecated or soon to be deprecated.
[1] Scalar with "NV" internal representation or a string that looks
like a float if the 'prefer_numeric' option is true.
[2] If the 'wrap_numbers' option is true, numeric types will be wrapped
as BSON::Double, BSON::Int32 or BSON::Int64 as appropriate to ensure
round-tripping. If the 'wrap_strings' option is true, strings will
be wrapped as BSON::String, likewise.
[3] Scalar without "NV" or "IV" representation and not identified as a
number by notes [1] or [7].
[4] If 'ordered' option is set, will return a tied hash that preserves
order (deprecated 'ixhash' option still works).
[5] If the document appears to contain a DBRef and a 'dbref_callback'
exists, that callback is executed with the deserialized document.
[6] Code is serialized as CODE or CODEWSCOPE depending on whether a
scope hashref exists in BSON::Code/MongoDB::Code.
[7] Scalar with "IV" internal representation or a string that looks like
an integer if the 'prefer_numeric' option is true.
[8] Only if the integer fits in 32 bits.
[9] On 32-bit platforms, 64-bit integers are deserialized to
Math::BigInt objects (even if subsequently wrapped into
BSON::Int64 if 'wrap_scalars' is true).
THREADS
Threads are never recommended in Perl, but this module is thread safe.
ENVIRONMENT
* PERL_BSON_BACKEND – if set at compile time, this will be treated as
a module name. The module will be loaded and used as the BSON
backend implementation. It must implement the same API as
"BSON::PP".
* BSON_EXTJSON - if set, serializing BSON type wrappers via "TO_JSON"
will produce Extended JSON v2 output.
* BSON_EXTJSON_RELAXED - if producing Extended JSON output, if this is
true, values will use the "Relaxed" form of Extended JSON, which
sacrifices type round-tripping for improved human readability.
SEMANTIC VERSIONING SCHEME
Starting with BSON "v0.999.0", this module is using a "tick-tock"
three-part version-tuple numbering scheme: "vX.Y.Z"
* In stable releases, "X" will be incremented for incompatible API
changes.
* Even-value increments of "Y" indicate stable releases with new
functionality. "Z" will be incremented for bug fixes.
* Odd-value increments of "Y" indicate unstable ("development")
releases that should not be used in production. "Z" increments have
no semantic meaning; they indicate only successive development
releases. Development releases may have API-breaking changes,
usually indicated by "Y" equal to "999".
HISTORY AND ROADMAP
This module was originally written by Stefan G. In 2014, he graciously
transferred ongoing maintenance to MongoDB, Inc.
The "bson_xxxx" helper functions in BSON::Types were inspired by similar
work in Mango::BSON by Sebastian Riedel.
AUTHORS
* David Golden <david@mongodb.com>
* Stefan G. <minimalist@lavabit.com>
CONTRIBUTORS
* Eric Daniels <eric.daniels@mongodb.com>
* Finn <toyou1995@gmail.com>
* Olivier Duclos <odc@cpan.org>
* Pat Gunn <pgunn@mongodb.com>
* Petr PÃsaÅ™ <ppisar@redhat.com>
( run in 0.471 second using v1.01-cache-2.11-cpan-cdf2f3d4e48 )