.\" Automatically generated by Pod::Man 4.09 (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 .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "MongoDB::BSON 3pm" .TH MongoDB::BSON 3pm "2018-01-18" "perl v5.26.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" MongoDB::BSON \- Tools for serializing and deserializing data in BSON form .SH "VERSION" .IX Header "VERSION" version v1.8.1 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& my $codec = MongoDB::BSON\->new; \& \& 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 documents and emits \s-1BSON\s0 strings and vice versa. .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" .SS "dbref_callback" .IX Subsection "dbref_callback" A document with keys \f(CW$ref\fR and \f(CW$id\fR is a special MongoDB convention representing a DBRef . .PP This attribute specifies a function reference that will be called with a hash reference argument representing a DBRef. .PP The hash reference will have keys \f(CW$ref\fR and \f(CW$id\fR and may have \f(CW$db\fR and other keys. The callback must return a scalar value representing the dbref (e.g. a document, an object, etc.) .PP The default \f(CW\*(C`dbref_callback\*(C'\fR returns the DBRef hash reference without modification. .PP Note: in MongoDB::MongoClient, when no MongoDB::BSON object is provided as the \f(CW\*(C`bson_codec\*(C'\fR attribute, creates a \&\fBcustom\fR MongoDB::BSON object that inflates DBRefs into MongoDB::DBRef objects using a custom \f(CW\*(C`dbref_callback\*(C'\fR: .PP .Vb 1 \& dbref_callback => sub { return MongoDB::DBRef\->new(shift) }, .Ve .PP Object-database mappers may wish to implement alternative \f(CW\*(C`dbref_callback\*(C'\fR attributes to provide whatever semantics they require. .SS "dt_type" .IX Subsection "dt_type" Sets the type of object which is returned for \s-1BSON\s0 DateTime fields. The default is DateTime. Other acceptable values are Time::Moment, DateTime::Tiny and \f(CW\*(C`undef\*(C'\fR. The latter will give you the raw epoch value (possibly as a floating point value) rather than an object. .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 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". .SS "prefer_numeric" .IX Subsection "prefer_numeric" If set to true, scalar values that look like a numeric value will be encoded as a \s-1BSON\s0 numeric type. When false, if the scalar value was ever used as a string, it will be encoded as a \s-1BSON UTF\-8\s0 string. .PP The default is false. .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 representin the decoded document. .PP An optional hash reference of options may be provided. Valid options include: .IP "\(bu" 4 dbref_callback – overrides codec default .IP "\(bu" 4 dt_type – overrides codec default .IP "\(bu" 4 error_callback – overrides codec default .IP "\(bu" 4 max_length – overrides codec default .SS "clone" .IX Subsection "clone" .Vb 1 \& $codec\->clone( dt_type => \*(AqTime::Moment\*(Aq ); .Ve .PP Constructs a copy of the original codec, but allows changing attributes in the copy. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 David Golden .IP "\(bu" 4 Rassi .IP "\(bu" 4 Mike Friedman .IP "\(bu" 4 Kristina Chodorow .IP "\(bu" 4 Florian Ragwitz .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2018 by MongoDB, Inc. .PP This is free software, licensed under: .PP .Vb 1 \& The Apache License, Version 2.0, January 2004 .Ve