1 // Copyright (C) MongoDB, Inc. 2022-present.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License"); you may
4 // not use this file except in compliance with the License. You may obtain
5 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
6 7 // Package bsoncodec provides a system for encoding values to BSON representations and decoding
8 // values from BSON representations. This package considers both binary BSON and ExtendedJSON as
9 // BSON representations. The types in this package enable a flexible system for handling this
10 // encoding and decoding.
11 //
12 // The codec system is composed of two parts:
13 //
14 // 1) ValueEncoders and ValueDecoders that handle encoding and decoding Go values to and from BSON
15 // representations.
16 //
17 // 2) A Registry that holds these ValueEncoders and ValueDecoders and provides methods for
18 // retrieving them.
19 //
20 // # ValueEncoders and ValueDecoders
21 //
22 // The ValueEncoder interface is implemented by types that can encode a provided Go type to BSON.
23 // The value to encode is provided as a reflect.Value and a bsonrw.ValueWriter is used within the
24 // EncodeValue method to actually create the BSON representation. For convenience, ValueEncoderFunc
25 // is provided to allow use of a function with the correct signature as a ValueEncoder. An
26 // EncodeContext instance is provided to allow implementations to lookup further ValueEncoders and
27 // to provide configuration information.
28 //
29 // The ValueDecoder interface is the inverse of the ValueEncoder. Implementations should ensure that
30 // the value they receive is settable. Similar to ValueEncoderFunc, ValueDecoderFunc is provided to
31 // allow the use of a function with the correct signature as a ValueDecoder. A DecodeContext
32 // instance is provided and serves similar functionality to the EncodeContext.
33 //
34 // # Registry
35 //
36 // A Registry is a store for ValueEncoders, ValueDecoders, and a type map. See the Registry type
37 // documentation for examples of registering various custom encoders and decoders. A Registry can
38 // have three main types of codecs:
39 //
40 // 1. Type encoders/decoders - These can be registered using the RegisterTypeEncoder and
41 // RegisterTypeDecoder methods. The registered codec will be invoked when encoding/decoding a value
42 // whose type matches the registered type exactly.
43 // If the registered type is an interface, the codec will be invoked when encoding or decoding
44 // values whose type is the interface, but not for values with concrete types that implement the
45 // interface.
46 //
47 // 2. Hook encoders/decoders - These can be registered using the RegisterHookEncoder and
48 // RegisterHookDecoder methods. These methods only accept interface types and the registered codecs
49 // will be invoked when encoding or decoding values whose types implement the interface. An example
50 // of a hook defined by the driver is bson.Marshaler. The driver will call the MarshalBSON method
51 // for any value whose type implements bson.Marshaler, regardless of the value's concrete type.
52 //
53 // 3. Type map entries - This can be used to associate a BSON type with a Go type. These type
54 // associations are used when decoding into a bson.D/bson.M or a struct field of type interface{}.
55 // For example, by default, BSON int32 and int64 values decode as Go int32 and int64 instances,
56 // respectively, when decoding into a bson.D. The following code would change the behavior so these
57 // values decode as Go int instances instead:
58 //
59 // intType := reflect.TypeOf(int(0))
60 // registry.RegisterTypeMapEntry(bsontype.Int32, intType).RegisterTypeMapEntry(bsontype.Int64, intType)
61 //
62 // 4. Kind encoder/decoders - These can be registered using the RegisterDefaultEncoder and
63 // RegisterDefaultDecoder methods. The registered codec will be invoked when encoding or decoding
64 // values whose reflect.Kind matches the registered reflect.Kind as long as the value's type doesn't
65 // match a registered type or hook encoder/decoder first. These methods should be used to change the
66 // behavior for all values for a specific kind.
67 //
68 // # Registry Lookup Procedure
69 //
70 // When looking up an encoder in a Registry, the precedence rules are as follows:
71 //
72 // 1. A type encoder registered for the exact type of the value.
73 //
74 // 2. A hook encoder registered for an interface that is implemented by the value or by a pointer to
75 // the value. If the value matches multiple hooks (e.g. the type implements bsoncodec.Marshaler and
76 // bsoncodec.ValueMarshaler), the first one registered will be selected. Note that registries
77 // constructed using bson.NewRegistry have driver-defined hooks registered for the
78 // bsoncodec.Marshaler, bsoncodec.ValueMarshaler, and bsoncodec.Proxy interfaces, so those will take
79 // precedence over any new hooks.
80 //
81 // 3. A kind encoder registered for the value's kind.
82 //
83 // If all of these lookups fail to find an encoder, an error of type ErrNoEncoder is returned. The
84 // same precedence rules apply for decoders, with the exception that an error of type ErrNoDecoder
85 // will be returned if no decoder is found.
86 //
87 // # DefaultValueEncoders and DefaultValueDecoders
88 //
89 // The DefaultValueEncoders and DefaultValueDecoders types provide a full set of ValueEncoders and
90 // ValueDecoders for handling a wide range of Go types, including all of the types within the
91 // primitive package. To make registering these codecs easier, a helper method on each type is
92 // provided. For the DefaultValueEncoders type the method is called RegisterDefaultEncoders and for
93 // the DefaultValueDecoders type the method is called RegisterDefaultDecoders, this method also
94 // handles registering type map entries for each BSON type.
95 package bsoncodec
96