|
4 | 4 | // not use this file except in compliance with the License. You may obtain |
5 | 5 | // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 |
6 | 6 |
|
7 | | -// Package bson is a library for reading, writing, and manipulating BSON. BSON is a binary serialization format used to |
8 | | -// store documents and make remote procedure calls in MongoDB. The BSON specification is located at https://bsonspec.org. |
9 | | -// The BSON library handles marshaling and unmarshaling of values through a configurable codec system. For a description |
10 | | -// of the codec system and examples of registering custom codecs, see the bsoncodec package. For additional information |
11 | | -// and usage examples, check out the [Work with BSON] page in the Go Driver docs site. |
12 | | -// |
13 | | -// # Raw BSON |
14 | | -// |
15 | | -// The Raw family of types is used to validate and retrieve elements from a slice of bytes. This |
16 | | -// type is most useful when you want do lookups on BSON bytes without unmarshaling it into another |
17 | | -// type. |
18 | | -// |
19 | | -// Example: |
20 | | -// |
21 | | -// var raw bson.Raw = ... // bytes from somewhere |
22 | | -// err := raw.Validate() |
23 | | -// if err != nil { return err } |
24 | | -// val := raw.Lookup("foo") |
25 | | -// i32, ok := val.Int32OK() |
26 | | -// // do something with i32... |
| 7 | +// Package bson is a library for reading, writing, and manipulating BSON. BSON is a binary serialization |
| 8 | +// format used to store documents and make remote procedure calls in MongoDB. For more information about |
| 9 | +// the Go BSON library, including usage examples, check out the [Work with BSON] page in the Go Driver |
| 10 | +// docs site. For more information about BSON, see https://bsonspec.org. |
27 | 11 | // |
28 | 12 | // # Native Go Types |
29 | 13 | // |
30 | | -// The D and M types defined in this package can be used to build representations of BSON using native Go types. D is a |
| 14 | +// The [D] and [M] types defined in this package can be used to build representations of BSON using native Go types. D is a |
31 | 15 | // slice and M is a map. For more information about the use cases for these types, see the documentation on the type |
32 | 16 | // definitions. |
33 | 17 | // |
|
93 | 77 | // 5. When unmarshaling, a field of type interface{} will follow the D/M type mappings listed above. BSON documents |
94 | 78 | // unmarshaled into an interface{} field will be unmarshaled as a D. |
95 | 79 | // |
96 | | -// The encoding of each struct field can be customized by the "bson" struct tag. |
97 | | -// |
98 | | -// This tag behavior is configurable, and different struct tag behavior can be configured by initializing a new |
99 | | -// bsoncodec.StructCodec with the desired tag parser and registering that StructCodec onto the Registry. By default, JSON |
100 | | -// tags are not honored, but that can be enabled by creating a StructCodec with JSONFallbackStructTagParser, like below: |
101 | | -// |
102 | | -// Example: |
103 | | -// |
104 | | -// structcodec, _ := bsoncodec.NewStructCodec(bsoncodec.JSONFallbackStructTagParser) |
105 | | -// |
106 | | -// The bson tag gives the name of the field, possibly followed by a comma-separated list of options. |
107 | | -// The name may be empty in order to specify options without overriding the default field name. The following options can |
108 | | -// be used to configure behavior: |
| 80 | +// The encoding of each struct field can be customized by the "bson" struct tag. The "bson" tag gives the name of the |
| 81 | +// field, followed by a comma-separated list of options. The name may be omitted in order to specify options without |
| 82 | +// overriding the default field name. The following options can be used to configure behavior: |
109 | 83 | // |
110 | 84 | // 1. omitempty: If the "omitempty" struct tag is specified on a field, the field will not be marshaled if it is set to |
111 | 85 | // an "empty" value. Numbers, booleans, and strings are considered empty if their value is equal to the zero value for |
112 | 86 | // the type (i.e. 0 for numbers, false for booleans, and "" for strings). Slices, maps, and arrays are considered |
113 | 87 | // empty if they are of length zero. Interfaces and pointers are considered empty if their value is nil. By default, |
114 | | -// structs are only considered empty if the struct type implements [bsoncodec.Zeroer] and the IsZero |
115 | | -// method returns true. Struct types that do not implement [bsoncodec.Zeroer] are never considered empty and will be |
| 88 | +// structs are only considered empty if the struct type implements [Zeroer] and the "IsZero" |
| 89 | +// method returns true. Struct types that do not implement [Zeroer] are never considered empty and will be |
116 | 90 | // marshaled as embedded documents. NOTE: It is recommended that this tag be used for all slice and map fields. |
117 | 91 | // |
118 | 92 | // 2. minsize: If the minsize struct tag is specified on a field of type int64, uint, uint32, or uint64 and the value of |
|
134 | 108 | // error will be returned. This tag can be used with fields that are pointers to structs. If an inlined pointer field |
135 | 109 | // is nil, it will not be marshaled. For fields that are not maps or structs, this tag is ignored. |
136 | 110 | // |
137 | | -// # Marshaling and Unmarshaling |
| 111 | +// # Raw BSON |
138 | 112 | // |
139 | | -// Manually marshaling and unmarshaling can be done with the Marshal and Unmarshal family of functions. |
| 113 | +// The Raw family of types is used to validate and retrieve elements from a slice of bytes. This |
| 114 | +// type is most useful when you want do lookups on BSON bytes without unmarshaling it into another |
| 115 | +// type. |
140 | 116 | // |
141 | | -// bsoncodec code provides a system for encoding values to BSON representations and decoding |
142 | | -// values from BSON representations. This package considers both binary BSON and ExtendedJSON as |
143 | | -// BSON representations. The types in this package enable a flexible system for handling this |
144 | | -// encoding and decoding. |
| 117 | +// Example: |
145 | 118 | // |
146 | | -// The codec system is composed of two parts: |
| 119 | +// var raw bson.Raw = ... // bytes from somewhere |
| 120 | +// err := raw.Validate() |
| 121 | +// if err != nil { return err } |
| 122 | +// val := raw.Lookup("foo") |
| 123 | +// i32, ok := val.Int32OK() |
| 124 | +// // do something with i32... |
| 125 | +// |
| 126 | +// # Custom Registry |
| 127 | +// |
| 128 | +// The Go BSON library uses a [Registry] to define encoding and decoding behavior for different data types. |
| 129 | +// The default encoding and decoding behavior can be customized or extended by using a modified Registry. |
| 130 | +// The custom registry system is composed of two parts: |
147 | 131 | // |
148 | 132 | // 1) [ValueEncoder] and [ValueDecoder] that handle encoding and decoding Go values to and from BSON |
149 | 133 | // representations. |
150 | 134 | // |
151 | 135 | // 2) A [Registry] that holds these ValueEncoders and ValueDecoders and provides methods for |
152 | 136 | // retrieving them. |
153 | 137 | // |
| 138 | +// To use a custom Registry, use [Encoder.SetRegistry] or [Decoder.SetRegistry]. |
| 139 | +// |
154 | 140 | // [Work with BSON]: https://www.mongodb.com/docs/drivers/go/current/fundamentals/bson/ |
155 | 141 | package bson |
0 commit comments