1Mango::BSON(3)        User Contributed Perl Documentation       Mango::BSON(3)
2
3
4

NAME

6       Mango::BSON - BSON
7

SYNOPSIS

9         use Mango::BSON ':bson';
10
11         my $bson = bson_encode {
12           foo       => 'bar',
13           baz       => 0.42,
14           unordered => {one => [1, 2, 3], two => bson_time},
15           ordered   => bson_doc(one => qr/test/i, two => bson_true)
16         };
17         my $doc = bson_decode $bson;
18

DESCRIPTION

20       Mango::BSON is a minimalistic implementation of <http://bsonspec.org>.
21
22       In addition to a bunch of custom BSON data types it supports normal
23       Perl data types like scalar, regular expression, "undef", array
24       reference, hash reference and will try to call the "TO_BSON" and
25       "TO_JSON" methods on blessed references, or stringify them if it
26       doesn't exist. Scalar references will be used to generate booleans,
27       based on if their values are true or false.
28

FUNCTIONS

30       Mango::BSON implements the following functions, which can be imported
31       individually or at once with the ":bson" flag.
32
33   bson_bin
34         my $bin = bson_bin $bytes;
35
36       Create new BSON element of the binary type with Mango::BSON::Binary,
37       defaults to the "generic" binary subtype.
38
39         # Function
40         bson_bin($bytes)->type('function');
41
42         # MD5
43         bson_bin($bytes)->type('md5');
44
45         # UUID
46         bson_bin($bytes)->type('uuid');
47
48         # User defined
49         bson_bin($bytes)->type('user_defined');
50
51   bson_code
52         my $code = bson_code 'function () {}';
53
54       Create new BSON element of the code type with Mango::BSON::Code.
55
56         # With scope
57         bson_code('function () {}')->scope({foo => 'bar'});
58
59   bson_dbref
60         my $dbref = bson_dbref 'test', $oid;
61
62       Create a new database reference.
63
64         # Longer version
65         my $dbref = {'$ref' => 'test', '$id' => $oid};
66
67   bson_decode
68         my $doc = bson_decode $bson;
69
70       Decode BSON into Perl data structures.
71
72   bson_doc
73         my $doc = bson_doc;
74         my $doc = bson_doc foo => 'bar', baz => 0.42, yada => {yada => [1, 2, 3]};
75
76       Create new BSON document with Mango::BSON::Document, which can also be
77       used as a generic ordered hash.
78
79         # Order is preserved
80         my $hash = bson_doc one => 1, two => 2, three => 3;
81         $hash->{four} = 4;
82         delete $hash->{two};
83         say for keys %$hash;
84
85   bson_double
86         my $doc = { foo => bson_double(13.0) };
87
88       Force a scalar value to be encoded as a double in MongoDB. Croaks if
89       the value is incompatible with the double type.
90
91   bson_encode
92         my $bson = bson_encode $doc;
93         my $bson = bson_encode {};
94
95       Encode Perl data structures into BSON.
96
97   bson_false
98         my $false = bson_false;
99
100       Create new BSON element of the boolean type false.
101
102   bson_int32
103         my $doc = { foo => bson_int32(13) };
104
105         # This will die (integer is too big)
106         my $doc = { foo => bson_int32(2147483648) };
107
108       Force a scalar value to be encoded as a 32 bit integer in MongoDB.
109       Croaks if the value is incompatible with the int32 type.
110
111   bson_int64
112         my $doc = { foo => bson_int64(666) };
113
114       Force a scalar value to be encoded as a 64 bit integer in MongoDB.
115       Croaks if the value is incompatible with the int64 type.
116
117   bson_length
118         my $len = bson_length $bson;
119
120       Check BSON length prefix.
121
122   bson_max
123         my $max_key = bson_max;
124
125       Create new BSON element of the max key type.
126
127   bson_min
128         my $min_key = bson_min;
129
130       Create new BSON element of the min key type.
131
132   bson_oid
133         my $oid = bson_oid;
134         my $oid = bson_oid '1a2b3c4e5f60718293a4b5c6';
135
136       Create new BSON element of the object id type with
137       Mango::BSON::ObjectID, defaults to generating a new unique object id.
138
139         # Generate object id with specific epoch time
140         my $oid = bson_oid->from_epoch(1359840145);
141
142   bson_raw
143         my $raw = bson_raw $bson;
144
145       Pre-encoded BSON document.
146
147         # Longer version
148         my $raw = {'$bson' => $bson};
149
150         # Embed pre-encoded BSON document
151         my $first  = bson_encode {foo => 'bar'};
152         my $second = bson_encode {test => bson_raw $first};
153
154   bson_time
155         my $now  = bson_time;
156         my $time = bson_time time * 1000;
157
158       Create new BSON element of the UTC datetime type with
159       Mango::BSON::Time, defaults to milliseconds since the UNIX epoch.
160
161         # "1360626536.748"
162         bson_time(1360626536748)->to_epoch;
163
164         # "2013-02-11T23:48:56.748Z"
165         bson_time(1360626536748)->to_datetime;
166
167   bson_true
168         my $true = bson_true;
169
170       Create new BSON element of the boolean type true.
171
172   bson_ts
173         my $timestamp = bson_ts 23, 24;
174
175       Create new BSON element of the timestamp type with
176       Mango::BSON::Timestamp.
177
178   encode_cstring
179         my $bytes = encode_cstring $cstring;
180
181       Encode cstring.
182

SEE ALSO

184       Mango, Mojolicious::Guides, <http://mojolicio.us>.
185
186
187
188perl v5.36.0                      2023-01-20                    Mango::BSON(3)
Impressum