view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    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);