.\" 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 "Mango::BSON 3pm"
.TH Mango::BSON 3pm "2018-04-14" "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"
Mango::BSON \- BSON
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Mango::BSON \*(Aq:bson\*(Aq;
\&
\&  my $bson = bson_encode {
\&    foo       => \*(Aqbar\*(Aq,
\&    baz       => 0.42,
\&    unordered => {one => [1, 2, 3], two => bson_time},
\&    ordered   => bson_doc(one => qr/test/i, two => bson_true)
\&  };
\&  my $doc = bson_decode $bson;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mango::BSON is a minimalistic implementation of <http://bsonspec.org>.
.PP
In addition to a bunch of custom \s-1BSON\s0 data types it supports normal Perl data
types like scalar, regular expression, \f(CW\*(C`undef\*(C'\fR, array reference, hash
reference and will try to call the \f(CW\*(C`TO_BSON\*(C'\fR and \f(CW\*(C`TO_JSON\*(C'\fR methods on
blessed references, or stringify them if it doesn't exist. Scalar references
will be used to generate booleans, based on if their values are true or false.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
Mango::BSON implements the following functions, which can be imported
individually or at once with the \f(CW\*(C`:bson\*(C'\fR flag.
.SS "bson_bin"
.IX Subsection "bson_bin"
.Vb 1
\&  my $bin = bson_bin $bytes;
.Ve
.PP
Create new \s-1BSON\s0 element of the binary type with Mango::BSON::Binary,
defaults to the \f(CW\*(C`generic\*(C'\fR binary subtype.
.PP
.Vb 2
\&  # Function
\&  bson_bin($bytes)\->type(\*(Aqfunction\*(Aq);
\&
\&  # MD5
\&  bson_bin($bytes)\->type(\*(Aqmd5\*(Aq);
\&
\&  # UUID
\&  bson_bin($bytes)\->type(\*(Aquuid\*(Aq);
\&
\&  # User defined
\&  bson_bin($bytes)\->type(\*(Aquser_defined\*(Aq);
.Ve
.SS "bson_code"
.IX Subsection "bson_code"
.Vb 1
\&  my $code = bson_code \*(Aqfunction () {}\*(Aq;
.Ve
.PP
Create new \s-1BSON\s0 element of the code type with Mango::BSON::Code.
.PP
.Vb 2
\&  # With scope
\&  bson_code(\*(Aqfunction () {}\*(Aq)\->scope({foo => \*(Aqbar\*(Aq});
.Ve
.SS "bson_dbref"
.IX Subsection "bson_dbref"
.Vb 1
\&  my $dbref = bson_dbref \*(Aqtest\*(Aq, $oid;
.Ve
.PP
Create a new database reference.
.PP
.Vb 2
\&  # Longer version
\&  my $dbref = {\*(Aq$ref\*(Aq => \*(Aqtest\*(Aq, \*(Aq$id\*(Aq => $oid};
.Ve
.SS "bson_decode"
.IX Subsection "bson_decode"
.Vb 1
\&  my $doc = bson_decode $bson;
.Ve
.PP
Decode \s-1BSON\s0 into Perl data structures.
.SS "bson_doc"
.IX Subsection "bson_doc"
.Vb 2
\&  my $doc = bson_doc;
\&  my $doc = bson_doc foo => \*(Aqbar\*(Aq, baz => 0.42, yada => {yada => [1, 2, 3]};
.Ve
.PP
Create new \s-1BSON\s0 document with Mango::BSON::Document, which can also be used
as a generic ordered hash.
.PP
.Vb 5
\&  # Order is preserved
\&  my $hash = bson_doc one => 1, two => 2, three => 3;
\&  $hash\->{four} = 4;
\&  delete $hash\->{two};
\&  say for keys %$hash;
.Ve
.SS "bson_double"
.IX Subsection "bson_double"
.Vb 1
\&  my $doc = { foo => bson_double(13.0) };
.Ve
.PP
Force a scalar value to be encoded as a double in MongoDB. Croaks if the
value is incompatible with the double type.
.SS "bson_encode"
.IX Subsection "bson_encode"
.Vb 2
\&  my $bson = bson_encode $doc;
\&  my $bson = bson_encode {};
.Ve
.PP
Encode Perl data structures into \s-1BSON.\s0
.SS "bson_false"
.IX Subsection "bson_false"
.Vb 1
\&  my $false = bson_false;
.Ve
.PP
Create new \s-1BSON\s0 element of the boolean type false.
.SS "bson_int32"
.IX Subsection "bson_int32"
.Vb 1
\&  my $doc = { foo => bson_int32(13) };
\&
\&  # This will die (integer is too big)
\&  my $doc = { foo => bson_int32(2147483648) };
.Ve
.PP
Force a scalar value to be encoded as a 32 bit integer in MongoDB. Croaks if
the value is incompatible with the int32 type.
.SS "bson_int64"
.IX Subsection "bson_int64"
.Vb 1
\&  my $doc = { foo => bson_int64(666) };
.Ve
.PP
Force a scalar value to be encoded as a 64 bit integer in MongoDB. Croaks if
the value is incompatible with the int64 type.
.SS "bson_length"
.IX Subsection "bson_length"
.Vb 1
\&  my $len = bson_length $bson;
.Ve
.PP
Check \s-1BSON\s0 length prefix.
.SS "bson_max"
.IX Subsection "bson_max"
.Vb 1
\&  my $max_key = bson_max;
.Ve
.PP
Create new \s-1BSON\s0 element of the max key type.
.SS "bson_min"
.IX Subsection "bson_min"
.Vb 1
\&  my $min_key = bson_min;
.Ve
.PP
Create new \s-1BSON\s0 element of the min key type.
.SS "bson_oid"
.IX Subsection "bson_oid"
.Vb 2
\&  my $oid = bson_oid;
\&  my $oid = bson_oid \*(Aq1a2b3c4e5f60718293a4b5c6\*(Aq;
.Ve
.PP
Create new \s-1BSON\s0 element of the object id type with Mango::BSON::ObjectID,
defaults to generating a new unique object id.
.PP
.Vb 2
\&  # Generate object id with specific epoch time
\&  my $oid = bson_oid\->from_epoch(1359840145);
.Ve
.SS "bson_raw"
.IX Subsection "bson_raw"
.Vb 1
\&  my $raw = bson_raw $bson;
.Ve
.PP
Pre-encoded \s-1BSON\s0 document.
.PP
.Vb 2
\&  # Longer version
\&  my $raw = {\*(Aq$bson\*(Aq => $bson};
\&
\&  # Embed pre\-encoded BSON document
\&  my $first  = bson_encode {foo => \*(Aqbar\*(Aq};
\&  my $second = bson_encode {test => bson_raw $first};
.Ve
.SS "bson_time"
.IX Subsection "bson_time"
.Vb 2
\&  my $now  = bson_time;
\&  my $time = bson_time time * 1000;
.Ve
.PP
Create new \s-1BSON\s0 element of the \s-1UTC\s0 datetime type with Mango::BSON::Time,
defaults to milliseconds since the \s-1UNIX\s0 epoch.
.PP
.Vb 2
\&  # "1360626536.748"
\&  bson_time(1360626536748)\->to_epoch;
\&
\&  # "2013\-02\-11T23:48:56.748Z"
\&  bson_time(1360626536748)\->to_datetime;
.Ve
.SS "bson_true"
.IX Subsection "bson_true"
.Vb 1
\&  my $true = bson_true;
.Ve
.PP
Create new \s-1BSON\s0 element of the boolean type true.
.SS "bson_ts"
.IX Subsection "bson_ts"
.Vb 1
\&  my $timestamp = bson_ts 23, 24;
.Ve
.PP
Create new \s-1BSON\s0 element of the timestamp type with Mango::BSON::Timestamp.
.SS "encode_cstring"
.IX Subsection "encode_cstring"
.Vb 1
\&  my $bytes = encode_cstring $cstring;
.Ve
.PP
Encode cstring.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mango, Mojolicious::Guides, <http://mojolicio.us>.