File: README

package info (click to toggle)
libbson-perl 1.10.2-1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 1,152 kB
  • sloc: perl: 3,970; makefile: 2
file content (491 lines) | stat: -rw-r--r-- 19,407 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
NAME
    BSON - BSON serialization and deserialization

VERSION
    version v1.10.2

SYNOPSIS
        use BSON;
        use BSON::Types ':all';
        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     );

DESCRIPTION
    This class implements a BSON encoder/decoder ("codec"). It consumes
    "documents" (typically hash references) and emits BSON strings and vice
    versa in accordance with the BSON Specification <http://bsonspec.org>.

    BSON 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.

    The codec may be customized through attributes on the codec option as
    well as encode/decode specific options on methods:

        my $codec = BSON->new( \%global_attributes );

        my $bson = $codec->encode_one( $document, \%encode_options );
        my $doc  = $codec->decode_one( $bson    , \%decode_options );

    Because BSON is strongly-typed and Perl is not, this module supports a
    number of "type wrappers" – classes that wrap Perl data to indicate how
    they should serialize. The BSON::Types module describes these and
    provides associated helper functions. See "PERL-BSON TYPE MAPPING" for
    more details.

    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.

    Please read the configuration attributes carefully to understand more
    about how to control encoding and decoding.

    At compile time, this module will select an implementation backend. It
    will prefer "BSON::XS" (released separately) if available, or will fall
    back to BSON::PP (bundled with this module). See "ENVIRONMENT" for a way
    to control the selection of the backend.

ATTRIBUTES
  error_callback
    This attribute specifies a function reference that will be called with
    three positional arguments:

    *   an error string argument describing the error condition

    *   a reference to the problematic document or byte-string

    *   the method in which the error occurred (e.g. "encode_one" or
        "decode_one")

    Note: for decoding errors, the byte-string is passed as a reference to
    avoid copying possibly large strings.

    If not provided, errors messages will be thrown with "Carp::croak".

  invalid_chars
    A string containing ASCII characters that must not appear in keys. The
    default is the empty string, meaning there are no invalid characters.

  max_length
    This attribute defines the maximum document size. The default is 0,
    which disables any maximum.

    If set to a positive number, it applies to both encoding and decoding
    (the latter is necessary for prevention of resource consumption
    attacks).

  op_char
    This is a single character to use for special MongoDB-specific query
    operators. If a key starts with "op_char", the "op_char" character will
    be replaced with "$".

    The default is "$", meaning that no replacement is necessary.

  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.

    IMPORTANT CAVEATS:

    *   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.

    *   Turning this option on entails a significant speed penalty as tied
        hashes are slower than regular Perl hashes.

    The default is false.

  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. "42") will be encoded as a string.

    If "prefer_numeric" 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.

    IMPORTANT CAVEAT: 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.

    The default is false.

  wrap_dbrefs
    If set to true, during decoding, documents with the fields '$id' and
    '$ref' (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 "ordered" is true).

    The default is true.

  wrap_numbers
    If set to true, during decoding, numeric values will be wrapped into
    BSON type-wrappers: BSON::Double, BSON::Int64 or BSON::Int32. While very
    slow, this can help ensure fields can round-trip if unmodified.

    The default is false.

  wrap_strings
    If set to true, during decoding, string values will be wrapped into a
    BSON type-wrappers, BSON::String. While very slow, this can help ensure
    fields can round-trip if unmodified.

    The default is false.

  dt_type (Discouraged)
    Sets the type of object which is returned for BSON DateTime fields. The
    default is "undef", 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 "dt_type" in the
    MongoDB driver.

    Other acceptable values are BSON::Time (explicitly), DateTime,
    Time::Moment, DateTime::Tiny, Mango::BSON::Time.

    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.

METHODS
  encode_one
        $byte_string = $codec->encode_one( $doc );
        $byte_string = $codec->encode_one( $doc, \%options );

    Takes a "document", typically a hash reference, an array reference, or a
    Tie::IxHash object and returns a byte string with the BSON
    representation of the document.

    An optional hash reference of options may be provided. Valid options
    include:

    *   first_key – if "first_key" is defined, it and "first_value" will be
        encoded first in the output BSON; any matching key found in the
        document will be ignored.

    *   first_value - value to assign to "first_key"; will encode as Null if
        omitted

    *   error_callback – overrides codec default

    *   invalid_chars – overrides codec default

    *   max_length – overrides codec default

    *   op_char – overrides codec default

    *   prefer_numeric – overrides codec default

  decode_one
        $doc = $codec->decode_one( $byte_string );
        $doc = $codec->decode_one( $byte_string, \%options );

    Takes a byte string with a BSON-encoded document and returns a hash
    reference representing the decoded document.

    An optional hash reference of options may be provided. Valid options
    include:

    *   dt_type – overrides codec default

    *   error_callback – overrides codec default

    *   max_length – overrides codec default

    *   ordered - overrides codec default

    *   wrap_dbrefs - overrides codec default

    *   wrap_numbers - overrides codec default

    *   wrap_strings - overrides codec default

  clone
        $copy = $codec->clone( ordered => 1 );

    Constructs a copy of the original codec, but allows changing attributes
    in the copy.

  create_oid
        $oid = BSON->create_oid;

    This class method returns a new BSON::OID. This abstracts OID generation
    away from any specific Object ID class and makes it an interface on a
    BSON codec. Alternative BSON codecs should define a similar class method
    that returns an Object ID of whatever type is appropriate.

  inflate_extjson (DEPRECATED)
    This legacy method does not follow the MongoDB Extended JSON
    <https://github.com/mongodb/specifications/blob/master/source/extended-j
    son.rst> specification.

    Use "extjson_to_perl" instead.

  perl_to_extjson
        use JSON::MaybeXS;
        my $ext = BSON->perl_to_extjson($data, \%options);
        my $json = encode_json($ext);

    Takes a perl data structure (i.e. hashref) and turns it into an MongoDB
    Extended JSON
    <https://github.com/mongodb/specifications/blob/master/source/extended-j
    son.rst> structure. Note that the structure will still have to be
    serialized.

    Possible options are:

    *   "relaxed" A boolean indicating if "relaxed extended JSON" should

        be generated. If not set, the default value is taken from the
        "BSON_EXTJSON_RELAXED" environment variable.

  extjson_to_perl
        use JSON::MaybeXS;
        my $ext = decode_json($json);
        my $data = $bson->extjson_to_perl($ext);

    Takes an MongoDB Extended JSON
    <https://github.com/mongodb/specifications/blob/master/source/extended-j
    son.rst> data structure and inflates it into a Perl data structure. Note
    that you have to decode the JSON string manually beforehand.

    Canonically specified numerical values like "{"$numberInt":"23"}" will
    be inflated into their respective "BSON::*" wrapper types. Plain numeric
    values will be left as-is.

FUNCTIONS
  encode
        my $bson = encode({ bar => 'foo' }, \%options);

    This is the legacy, functional interface and is only exported on demand.
    It takes a hashref and returns a BSON string. It uses an internal codec
    singleton with default attributes.

  decode
        my $hash = decode( $bson, \%options );

    This is the legacy, functional interface and is only exported on demand.
    It takes a BSON string and returns a hashref. It uses an internal codec
    singleton with default attributes.

PERL-BSON TYPE MAPPING
    BSON has numerous data types and Perl does not.

    When decoding, each BSON type should result in a single, predictable
    Perl type. Where no native Perl type is appropriate, BSON decodes to an
    object of a particular class (a "type wrapper").

    When encoding, for historical reasons, there may be many Perl
    representations that should encode to a particular BSON type. For
    example, all the popular "boolean" type modules on CPAN should encode to
    the BSON 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.

    The table below describes the BSON/Perl mapping for both encoding and
    decoding.

    On the left are all the Perl types or classes this BSON codec knows how
    to serialize to BSON. The middle column is the BSON type for each class.
    The right-most column is the Perl type or class that the BSON type
    deserializes to. Footnotes indicate variations or special behaviors.

        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 'prefer_numeric' option is true.
        [2] If the 'wrap_numbers' option is true, numeric types will be wrapped
            as BSON::Double, BSON::Int32 or BSON::Int64 as appropriate to ensure
            round-tripping. If the 'wrap_strings' 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 'ordered' option is set, will return a tied hash that preserves
            order (deprecated 'ixhash' option still works).
        [5] If the document appears to contain a DBRef and a 'dbref_callback'
            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 'prefer_numeric' 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 'wrap_scalars' is true).

THREADS
    Threads are never recommended in Perl, but this module is thread safe.

ENVIRONMENT
    *   PERL_BSON_BACKEND – if set at compile time, this will be treated as
        a module name. The module will be loaded and used as the BSON
        backend implementation. It must implement the same API as
        "BSON::PP".

    *   BSON_EXTJSON - if set, serializing BSON type wrappers via "TO_JSON"
        will produce Extended JSON v2 output.

    *   BSON_EXTJSON_RELAXED - if producing Extended JSON output, if this is
        true, values will use the "Relaxed" form of Extended JSON, which
        sacrifices type round-tripping for improved human readability.

SEMANTIC VERSIONING SCHEME
    Starting with BSON "v0.999.0", this module is using a "tick-tock"
    three-part version-tuple numbering scheme: "vX.Y.Z"

    *   In stable releases, "X" will be incremented for incompatible API
        changes.

    *   Even-value increments of "Y" indicate stable releases with new
        functionality. "Z" will be incremented for bug fixes.

    *   Odd-value increments of "Y" indicate unstable ("development")
        releases that should not be used in production. "Z" increments have
        no semantic meaning; they indicate only successive development
        releases. Development releases may have API-breaking changes,
        usually indicated by "Y" equal to "999".

HISTORY AND ROADMAP
    This module was originally written by Stefan G. In 2014, he graciously
    transferred ongoing maintenance to MongoDB, Inc.

    The "bson_xxxx" helper functions in BSON::Types were inspired by similar
    work in Mango::BSON by Sebastian Riedel.

SUPPORT
  Bugs / Feature Requests
    Please report any bugs or feature requests through the issue tracker at
    <https://jira.mongodb.org/browse/PERL>. You will be notified
    automatically of any progress on your issue.

  Source Code
    This is open source software. The code repository is available for
    public review and contribution under the terms of the license.

    <https://github.com/mongodb/mongo-perl-bson>

      git clone https://github.com/mongodb/mongo-perl-bson.git

AUTHORS
    *   David Golden <david@mongodb.com>

    *   Stefan G. <minimalist@lavabit.com>

CONTRIBUTORS
    *   Eric Daniels <eric.daniels@mongodb.com>

    *   Finn <toyou1995@gmail.com>

    *   Olivier Duclos <odc@cpan.org>

    *   Pat Gunn <pgunn@mongodb.com>

    *   Petr Písař <ppisar@redhat.com>

    *   Robert Sedlacek <rs@474.at>

    *   Thomas Bloor <tbsliver@shadow.cat>

    *   Tobias Leich <email@froggs.de>

    *   Wallace Reis <wallace@reis.me>

    *   Yury Zavarin <yury.zavarin@gmail.com>

    *   Oleg Kostyuk <cub@cpan.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2018 by Stefan G. and MongoDB, Inc.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004