.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "BSON 3pm" .TH BSON 3pm "2018-12-09" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" BSON \- BSON serialization and deserialization .SH "VERSION" .IX Header "VERSION" version v1.10.2 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& use BSON; \& use BSON::Types \*(Aq:all\*(Aq; \& use boolean; \& \& my $codec = BSON\->new; \& \& my $document = { \& _id => bson_oid(), \& creation_time => bson_time(), # now \& zip_code => bson_string("08544"), \& hidden => false, \& }; \& \& my $bson = $codec\->encode_one( $document ); \& my $doc = $codec\->decode_one( $bson ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This class implements a \s-1BSON\s0 encoder/decoder (\*(L"codec\*(R"). It consumes \&\*(L"documents\*(R" (typically hash references) and emits \s-1BSON\s0 strings and vice versa in accordance with the \s-1BSON\s0 Specification . .PP \&\s-1BSON\s0 is the primary data representation for MongoDB. While this module has several features that support MongoDB-specific needs and conventions, it can be used as a standalone serialization format. .PP The codec may be customized through attributes on the codec option as well as encode/decode specific options on methods: .PP .Vb 1 \& my $codec = BSON\->new( \e%global_attributes ); \& \& my $bson = $codec\->encode_one( $document, \e%encode_options ); \& my $doc = $codec\->decode_one( $bson , \e%decode_options ); .Ve .PP Because \s-1BSON\s0 is strongly-typed and Perl is not, this module supports a number of \*(L"type wrappers\*(R" – classes that wrap Perl data to indicate how they should serialize. The BSON::Types module describes these and provides associated helper functions. See \*(L"PERL-BSON \s-1TYPE MAPPING\*(R"\s0 for more details. .PP When decoding, type wrappers are used for any data that has no native Perl representation. Optionally, all data may be wrapped for precise control of round-trip encoding. .PP Please read the configuration attributes carefully to understand more about how to control encoding and decoding. .PP At compile time, this module will select an implementation backend. It will prefer \f(CW\*(C`BSON::XS\*(C'\fR (released separately) if available, or will fall back to \s-1BSON::PP\s0 (bundled with this module). See \*(L"\s-1ENVIRONMENT\*(R"\s0 for a way to control the selection of the backend. .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" .SS "error_callback" .IX Subsection "error_callback" This attribute specifies a function reference that will be called with three positional arguments: .IP "\(bu" 4 an error string argument describing the error condition .IP "\(bu" 4 a reference to the problematic document or byte-string .IP "\(bu" 4 the method in which the error occurred (e.g. \f(CW\*(C`encode_one\*(C'\fR or \f(CW\*(C`decode_one\*(C'\fR) .PP Note: for decoding errors, the byte-string is passed as a reference to avoid copying possibly large strings. .PP If not provided, errors messages will be thrown with \f(CW\*(C`Carp::croak\*(C'\fR. .SS "invalid_chars" .IX Subsection "invalid_chars" A string containing \s-1ASCII\s0 characters that must not appear in keys. The default is the empty string, meaning there are no invalid characters. .SS "max_length" .IX Subsection "max_length" This attribute defines the maximum document size. The default is 0, which disables any maximum. .PP If set to a positive number, it applies to both encoding \fBand\fR decoding (the latter is necessary for prevention of resource consumption attacks). .SS "op_char" .IX Subsection "op_char" This is a single character to use for special MongoDB-specific query operators. If a key starts with \f(CW\*(C`op_char\*(C'\fR, the \f(CW\*(C`op_char\*(C'\fR character will be replaced with \*(L"$\*(R". .PP The default is \*(L"$\*(R", meaning that no replacement is necessary. .SS "ordered" .IX Subsection "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. .PP \&\fB\s-1IMPORTANT CAVEATS\s0\fR: .IP "\(bu" 4 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. .IP "\(bu" 4 Turning this option on entails a significant speed penalty as tied hashes are slower than regular Perl hashes. .PP The default is false. .SS "prefer_numeric" .IX Subsection "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. \*(L"42\*(R") will be encoded as a string. .PP If \f(CW\*(C`prefer_numeric\*(C'\fR 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. .PP \&\fB\s-1IMPORTANT CAVEAT\s0\fR: 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. .PP The default is false. .SS "wrap_dbrefs" .IX Subsection "wrap_dbrefs" If set to true, during decoding, documents with the fields \f(CW\*(Aq$id\*(Aq\fR and \&\f(CW\*(Aq$ref\*(Aq\fR (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 \f(CW\*(C`ordered\*(C'\fR is true). .PP The default is true. .SS "wrap_numbers" .IX Subsection "wrap_numbers" If set to true, during decoding, numeric values will be wrapped into \&\s-1BSON\s0 type-wrappers: BSON::Double, BSON::Int64 or BSON::Int32. While very slow, this can help ensure fields can round-trip if unmodified. .PP The default is false. .SS "wrap_strings" .IX Subsection "wrap_strings" If set to true, during decoding, string values will be wrapped into a \s-1BSON\s0 type-wrappers, BSON::String. While very slow, this can help ensure fields can round-trip if unmodified. .PP The default is false. .SS "dt_type (Discouraged)" .IX Subsection "dt_type (Discouraged)" Sets the type of object which is returned for \s-1BSON\s0 DateTime fields. The default is \f(CW\*(C`undef\*(C'\fR, 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 \f(CW\*(C`dt_type\*(C'\fR in the MongoDB driver. .PP Other acceptable values are BSON::Time (explicitly), DateTime, Time::Moment, DateTime::Tiny, Mango::BSON::Time. .PP 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. .SH "METHODS" .IX Header "METHODS" .SS "encode_one" .IX Subsection "encode_one" .Vb 2 \& $byte_string = $codec\->encode_one( $doc ); \& $byte_string = $codec\->encode_one( $doc, \e%options ); .Ve .PP Takes a \*(L"document\*(R", typically a hash reference, an array reference, or a Tie::IxHash object and returns a byte string with the \s-1BSON\s0 representation of the document. .PP An optional hash reference of options may be provided. Valid options include: .IP "\(bu" 4 first_key – if \f(CW\*(C`first_key\*(C'\fR is defined, it and \f(CW\*(C`first_value\*(C'\fR will be encoded first in the output \s-1BSON\s0; any matching key found in the document will be ignored. .IP "\(bu" 4 first_value \- value to assign to \f(CW\*(C`first_key\*(C'\fR; will encode as Null if omitted .IP "\(bu" 4 error_callback – overrides codec default .IP "\(bu" 4 invalid_chars – overrides codec default .IP "\(bu" 4 max_length – overrides codec default .IP "\(bu" 4 op_char – overrides codec default .IP "\(bu" 4 prefer_numeric – overrides codec default .SS "decode_one" .IX Subsection "decode_one" .Vb 2 \& $doc = $codec\->decode_one( $byte_string ); \& $doc = $codec\->decode_one( $byte_string, \e%options ); .Ve .PP Takes a byte string with a BSON-encoded document and returns a hash reference representing the decoded document. .PP An optional hash reference of options may be provided. Valid options include: .IP "\(bu" 4 dt_type – overrides codec default .IP "\(bu" 4 error_callback – overrides codec default .IP "\(bu" 4 max_length – overrides codec default .IP "\(bu" 4 ordered \- overrides codec default .IP "\(bu" 4 wrap_dbrefs \- overrides codec default .IP "\(bu" 4 wrap_numbers \- overrides codec default .IP "\(bu" 4 wrap_strings \- overrides codec default .SS "clone" .IX Subsection "clone" .Vb 1 \& $copy = $codec\->clone( ordered => 1 ); .Ve .PP Constructs a copy of the original codec, but allows changing attributes in the copy. .SS "create_oid" .IX Subsection "create_oid" .Vb 1 \& $oid = BSON\->create_oid; .Ve .PP This class method returns a new \s-1BSON::OID\s0. This abstracts \s-1OID\s0 generation away from any specific Object \s-1ID\s0 class and makes it an interface on a \s-1BSON\s0 codec. Alternative \s-1BSON\s0 codecs should define a similar class method that returns an Object \s-1ID\s0 of whatever type is appropriate. .SS "inflate_extjson (\s-1DEPRECATED\s0)" .IX Subsection "inflate_extjson (DEPRECATED)" This legacy method does not follow the MongoDB Extended \s-1JSON\s0 specification. .PP Use \*(L"extjson_to_perl\*(R" instead. .SS "perl_to_extjson" .IX Subsection "perl_to_extjson" .Vb 3 \& use JSON::MaybeXS; \& my $ext = BSON\->perl_to_extjson($data, \e%options); \& my $json = encode_json($ext); .Ve .PP Takes a perl data structure (i.e. hashref) and turns it into an MongoDB Extended \s-1JSON\s0 structure. Note that the structure will still have to be serialized. .PP Possible options are: .IP "\(bu" 4 \&\f(CW\*(C`relaxed\*(C'\fR A boolean indicating if \*(L"relaxed extended \s-1JSON\*(R"\s0 should .Sp be generated. If not set, the default value is taken from the \&\f(CW\*(C`BSON_EXTJSON_RELAXED\*(C'\fR environment variable. .SS "extjson_to_perl" .IX Subsection "extjson_to_perl" .Vb 3 \& use JSON::MaybeXS; \& my $ext = decode_json($json); \& my $data = $bson\->extjson_to_perl($ext); .Ve .PP Takes an MongoDB Extended \s-1JSON\s0 data structure and inflates it into a Perl data structure. Note that you have to decode the \s-1JSON\s0 string manually beforehand. .PP Canonically specified numerical values like \f(CW\*(C`{"$numberInt":"23"}\*(C'\fR will be inflated into their respective \f(CW\*(C`BSON::*\*(C'\fR wrapper types. Plain numeric values will be left as-is. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "encode" .IX Subsection "encode" .Vb 1 \& my $bson = encode({ bar => \*(Aqfoo\*(Aq }, \e%options); .Ve .PP This is the legacy, functional interface and is only exported on demand. It takes a hashref and returns a \s-1BSON\s0 string. It uses an internal codec singleton with default attributes. .SS "decode" .IX Subsection "decode" .Vb 1 \& my $hash = decode( $bson, \e%options ); .Ve .PP This is the legacy, functional interface and is only exported on demand. It takes a \s-1BSON\s0 string and returns a hashref. It uses an internal codec singleton with default attributes. .SH "PERL-BSON TYPE MAPPING" .IX Header "PERL-BSON TYPE MAPPING" \&\s-1BSON\s0 has numerous data types and Perl does not. .PP When \fBdecoding\fR, each \s-1BSON\s0 type should result in a single, predictable Perl type. Where no native Perl type is appropriate, \s-1BSON\s0 decodes to an object of a particular class (a \*(L"type wrapper\*(R"). .PP When \fBencoding\fR, for historical reasons, there may be many Perl representations that should encode to a particular \s-1BSON\s0 type. For example, all the popular \*(L"boolean\*(R" type modules on \s-1CPAN\s0 should encode to the \s-1BSON\s0 boolean type. Likewise, as this module is intended to supersede the type wrappers that have shipped with the MongoDB module, those type wrapper are supported by this codec. .PP The table below describes the BSON/Perl mapping for both encoding and decoding. .PP On the left are all the Perl types or classes this \s-1BSON\s0 codec knows how to serialize to \s-1BSON.\s0 The middle column is the \s-1BSON\s0 type for each class. The right-most column is the Perl type or class that the \s-1BSON\s0 type deserializes to. Footnotes indicate variations or special behaviors. .PP .Vb 10 \& Perl type/class \-> BSON type \-> Perl type/class \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& float[1] 0x01 DOUBLE float[2] \& BSON::Double \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& string[3] 0x02 UTF8 string[2] \& BSON::String \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& hashref 0x03 DOCUMENT hashref[4][5] \& BSON::Doc \& BSON::Raw \& MongoDB::BSON::Raw[d] \& Tie::IxHash \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& arrayref 0x04 ARRAY arrayref \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& 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 \*(Aqprefer_numeric\*(Aq option is true. \& [2] If the \*(Aqwrap_numbers\*(Aq option is true, numeric types will be wrapped \& as BSON::Double, BSON::Int32 or BSON::Int64 as appropriate to ensure \& round\-tripping. If the \*(Aqwrap_strings\*(Aq 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 \*(Aqordered\*(Aq option is set, will return a tied hash that preserves \& order (deprecated \*(Aqixhash\*(Aq option still works). \& [5] If the document appears to contain a DBRef and a \*(Aqdbref_callback\*(Aq \& 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 \*(Aqprefer_numeric\*(Aq 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 \*(Aqwrap_scalars\*(Aq is true). .Ve .SH "THREADS" .IX Header "THREADS" Threads are never recommended in Perl, but this module is thread safe. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" .IP "\(bu" 4 \&\s-1PERL_BSON_BACKEND\s0 – if set at compile time, this will be treated as a module name. The module will be loaded and used as the \s-1BSON\s0 backend implementation. It must implement the same \s-1API\s0 as \f(CW\*(C`BSON::PP\*(C'\fR. .IP "\(bu" 4 \&\s-1BSON_EXTJSON\s0 \- if set, serializing \s-1BSON\s0 type wrappers via \f(CW\*(C`TO_JSON\*(C'\fR will produce Extended \s-1JSON\s0 v2 output. .IP "\(bu" 4 \&\s-1BSON_EXTJSON_RELAXED\s0 \- if producing Extended \s-1JSON\s0 output, if this is true, values will use the \*(L"Relaxed\*(R" form of Extended \s-1JSON,\s0 which sacrifices type round-tripping for improved human readability. .SH "SEMANTIC VERSIONING SCHEME" .IX Header "SEMANTIC VERSIONING SCHEME" Starting with \s-1BSON\s0 \f(CW\*(C`v0.999.0\*(C'\fR, this module is using a \*(L"tick-tock\*(R" three-part version-tuple numbering scheme: \f(CW\*(C`vX.Y.Z\*(C'\fR .IP "\(bu" 4 In stable releases, \f(CW\*(C`X\*(C'\fR will be incremented for incompatible \s-1API\s0 changes. .IP "\(bu" 4 Even-value increments of \f(CW\*(C`Y\*(C'\fR indicate stable releases with new functionality. \f(CW\*(C`Z\*(C'\fR will be incremented for bug fixes. .IP "\(bu" 4 Odd-value increments of \f(CW\*(C`Y\*(C'\fR indicate unstable (\*(L"development\*(R") releases that should not be used in production. \f(CW\*(C`Z\*(C'\fR increments have no semantic meaning; they indicate only successive development releases. Development releases may have API-breaking changes, usually indicated by \f(CW\*(C`Y\*(C'\fR equal to \*(L"999\*(R". .SH "HISTORY AND ROADMAP" .IX Header "HISTORY AND ROADMAP" This module was originally written by Stefan G. In 2014, he graciously transferred ongoing maintenance to MongoDB, Inc. .PP The \f(CW\*(C`bson_xxxx\*(C'\fR helper functions in BSON::Types were inspired by similar work in Mango::BSON by Sebastian Riedel. .SH "SUPPORT" .IX Header "SUPPORT" .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests through the issue tracker at . You will be notified automatically of any progress on your issue. .SS "Source Code" .IX Subsection "Source Code" This is open source software. The code repository is available for public review and contribution under the terms of the license. .PP .PP .Vb 1 \& git clone https://github.com/mongodb/mongo\-perl\-bson.git .Ve .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 David Golden .IP "\(bu" 4 Stefan G. .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Eric Daniels .IP "\(bu" 4 Finn .IP "\(bu" 4 Olivier Duclos .IP "\(bu" 4 Pat Gunn .IP "\(bu" 4 Petr Písař .IP "\(bu" 4 Robert Sedlacek .IP "\(bu" 4 Thomas Bloor .IP "\(bu" 4 Tobias Leich .IP "\(bu" 4 Wallace Reis .IP "\(bu" 4 Yury Zavarin .IP "\(bu" 4 Oleg Kostyuk .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2018 by Stefan G. and MongoDB, Inc. .PP This is free software, licensed under: .PP .Vb 1 \& The Apache License, Version 2.0, January 2004 .Ve