Mango::BSON(3pm)

💖 Mango::BSON — the manual, but make it cute 💖

okay bestie, so this is Mango::BSON(3pm) — like, the whole entire page — and I'm gonna walk you through it like we're texting at 2am. stay with me, it's giving ✨essential✨.

---

🌸 SYNOPSIS 🌸

use Mango::BSON ':bson';

my $bson = bson_encode {
  foo       => 'bar',
  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;

literally that's it. that's the whole vibe check. 💅

---

🦋 DESCRIPTION 🦋

Mango::BSON is a minimalistic implementation of <http://bsonspec.org>. tiny. iconic. does exactly what it says.

and the way that it handles normal Perl data types?? obsessed. it supports scalar, regular expression, undef, array reference, hash reference — all the classics — AND it will try to call the TO_BSON and TO_JSON methods on blessed references, or stringify them if those don't exist. (no method? no problem, we're just gonna stringify you, bestie 💀)

oh and also: scalar references get used to generate booleans, based on whether their values are true or false. true ref = true bool, false ref = false bool. periodt. 🎀

---

✨ FUNCTIONS ✨

Mango::BSON implements the following functions, which can be imported individually or at once with the :bson flag. pick your faves or take the whole squad. 🫶

🍓 bson_bin

my $bin = bson_bin $bytes;

creates a new BSON element of the binary type with Mango::BSON::Binary, and it defaults to the "generic" binary subtype.

# Function
bson_bin($bytes)->type('function');

# MD5
bson_bin($bytes)->type('md5');

# UUID
bson_bin($bytes)->type('uuid');

# User defined
bson_bin($bytes)->type('user_defined');

look at all those subtypes slaying. 🌈

💜 bson_code

my $code = bson_code 'function () {}';

creates a new BSON element of the code type with Mango::BSON::Code.

# With scope
bson_code('function () {}')->scope({foo => 'bar'});

yes you can give it a scope. main character energy fr. 👑

🧚 bson_dbref

my $dbref = bson_dbref 'test', $oid;

creates a new database reference.

# Longer version
my $dbref = {'$ref' => 'test', '$id' => $oid};

same thing, just, y'know, longer. 🙈

🌸 bson_decode

my $doc = bson_decode $bson;

decodes BSON into Perl data structures. that's the whole job description and she does it flawlessly. ✨

🎀 bson_doc

my $doc = bson_doc;
my $doc = bson_doc foo => 'bar', baz => 0.42, yada => {yada => [1, 2, 3]};

creates a new BSON document with Mango::BSON::Document, which can also be used as a generic ordered hash. yes bestie, it remembers the order.

# Order is preserved
my $hash = bson_doc one => 1, two => 2, three => 3;
$hash->{four} = 4;
delete $hash->{two};
say for keys %$hash;

order is preserved. no cap. 💅

🔥 bson_double

my $doc = { foo => bson_double(13.0) };

forces a scalar value to be encoded as a double in MongoDB. and it croaks if the value is incompatible with the double type. (like, it WILL yell at you. fair.) 😭

⭐ bson_encode

my $bson = bson_encode $doc;
my $bson = bson_encode {};

encodes Perl data structures into BSON. also accepts an empty hashref, because sometimes you just have nothing to say and that's valid. 🫶

🦋 bson_false

my $false = bson_false;

creates a new BSON element of the boolean type false. the villain of the boolean world. 💀

🌈 bson_int32

my $doc = { foo => bson_int32(13) };

# This will die (integer is too big)
my $doc = { foo => bson_int32(2147483648) };

forces a scalar value to be encoded as a 32 bit integer in MongoDB. and yes — it croaks if the value is incompatible with the int32 type. see that 2147483648? too big. too powerful. she will not make it. ⚠️

💖 bson_int64

my $doc = { foo => bson_int64(666) };

forces a scalar value to be encoded as a 64 bit integer in MongoDB. and yup, it croaks if the value is incompatible with the int64 type. same energy, bigger number. 🔥

🎀 bson_length

my $len = bson_length $bson;

checks the BSON length prefix. short king of a function. 📏

💜 bson_max

my $max_key = bson_max;

creates a new BSON element of the max key type.

🧚 bson_min

my $min_key = bson_min;

creates a new BSON element of the min key type. she and bson_max are literally a matched set. 🫶

🌸 bson_oid

my $oid = bson_oid;
my $oid = bson_oid '1a2b3c4e5f60718293a4b5c6';

creates a new BSON element of the object id type with Mango::BSON::ObjectID, and it defaults to generating a new unique object id for you. so thoughtful.

# Generate object id with specific epoch time
my $oid = bson_oid->from_epoch(1359840145);

time travel but make it an object id. ⏰✨

🍓 bson_raw

my $raw = bson_raw $bson;

pre-encoded BSON document. it's already done, bestie, no further processing needed.

# Longer version
my $raw = {'$bson' => $bson};

# Embed pre-encoded BSON document
my $first  = bson_encode {foo => 'bar'};
my $second = bson_encode {test => bson_raw $first};

embedding pre-encoded docs inside other docs? nesting dolls but BSON. iconic. 🪆

⭐ bson_time

my $now  = bson_time;
my $time = bson_time time * 1000;

creates a new BSON element of the UTC datetime type with Mango::BSON::Time, and it defaults to milliseconds since the UNIX epoch. yes, milliseconds. don't forget the * 1000. 😭

# "1360626536.748"
bson_time(1360626536748)->to_epoch;

# "2013-02-11T23:48:56.748Z"
bson_time(1360626536748)->to_datetime;

two formats, both gorgeous. 💅

🌈 bson_true

my $true = bson_true;

creates a new BSON element of the boolean type true. the hero of the boolean world. 🫶

💜 bson_ts

my $timestamp = bson_ts 23, 24;

creates a new BSON element of the timestamp type with Mango::BSON::Timestamp. two little numbers, one big vibe. 🕐

🧚 encode_cstring

my $bytes = encode_cstring $cstring;

encodes cstring. short. sweet. does the thing. ✨

---

👑 SEE ALSO 👑

• Mango
• Mojolicious::Guides
• <http://mojolicio.us>

---

that's the whole page bestie, every flag, every default, every croak, nothing skipped. go forth and BSON. 🦋

okay and the lil sign-off at the very bottom: this was perl v5.30.3, dated 2020-06-05, and it's the Mango::BSON(3pm) page. love her, respect her, she's vintage and she's thriving. 💖✨🎀