Documentation

Overview

    Package bsonrw contains abstractions for reading and writing BSON and BSON like types from sources.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var ErrEOA = errors.New("end of array")

      ErrEOA is the error returned when the end of a BSON array has been reached.

      View Source
      var ErrEOD = errors.New("end of document")

        ErrEOD is the error returned when the end of a BSON document has been reached.

        View Source
        var ErrInvalidJSON = errors.New("invalid JSON input")

          ErrInvalidJSON indicates the JSON input is invalid

          Functions

          func CopyDocument

          func CopyDocument(dst ValueWriter, src ValueReader) error

            CopyDocument handles copying a document from src to dst.

            Types

            type ArrayReader

            type ArrayReader interface {
            	ReadValue() (ValueReader, error)
            }

              ArrayReader is implemented by types that allow reading values from a BSON array.

              type ArrayWriter

              type ArrayWriter interface {
              	WriteArrayElement() (ValueWriter, error)
              	WriteArrayEnd() error
              }

                ArrayWriter is the interface used to create a BSON or BSON adjacent array. Callers must ensure they call WriteArrayEnd when they have finished creating the array.

                type BSONValueReaderPool

                type BSONValueReaderPool struct {
                	// contains filtered or unexported fields
                }

                  BSONValueReaderPool is a pool for ValueReaders that read BSON.

                  func NewBSONValueReaderPool

                  func NewBSONValueReaderPool() *BSONValueReaderPool

                    NewBSONValueReaderPool instantiates a new BSONValueReaderPool.

                    func (*BSONValueReaderPool) Get

                    func (bvrp *BSONValueReaderPool) Get(src []byte) ValueReader

                      Get retrieves a ValueReader from the pool and uses src as the underlying BSON.

                      func (*BSONValueReaderPool) Put

                      func (bvrp *BSONValueReaderPool) Put(vr ValueReader) (ok bool)

                        Put inserts a ValueReader into the pool. If the ValueReader is not a BSON ValueReader nothing is inserted into the pool and ok will be false.

                        type BSONValueWriterPool

                        type BSONValueWriterPool struct {
                        	// contains filtered or unexported fields
                        }

                          BSONValueWriterPool is a pool for BSON ValueWriters.

                          func NewBSONValueWriterPool

                          func NewBSONValueWriterPool() *BSONValueWriterPool

                            NewBSONValueWriterPool creates a new pool for ValueWriter instances that write to BSON.

                            func (*BSONValueWriterPool) Get

                              Get retrieves a BSON ValueWriter from the pool and resets it to use w as the destination.

                              func (*BSONValueWriterPool) GetAtModeElement

                              func (bvwp *BSONValueWriterPool) GetAtModeElement(w io.Writer) ValueWriterFlusher

                                GetAtModeElement retrieves a ValueWriterFlusher from the pool and resets it to use w as the destination.

                                func (*BSONValueWriterPool) Put

                                func (bvwp *BSONValueWriterPool) Put(vw ValueWriter) (ok bool)

                                  Put inserts a ValueWriter into the pool. If the ValueWriter is not a BSON ValueWriter, nothing happens and ok will be false.

                                  type BytesReader

                                  type BytesReader interface {
                                  	ReadValueBytes(dst []byte) (bsontype.Type, []byte, error)
                                  }

                                    BytesReader is a generic interface used to read BSON bytes from a ValueReader. This imterface is meant to be a superset of ValueReader, so that types that implement ValueReader may also implement this interface.

                                    The bytes of the value will be appended to dst.

                                    type BytesWriter

                                    type BytesWriter interface {
                                    	WriteValueBytes(t bsontype.Type, b []byte) error
                                    }

                                      BytesWriter is the interface used to write BSON bytes to a ValueWriter. This interface is meant to be a superset of ValueWriter, so that types that implement ValueWriter may also implement this interface.

                                      type Copier

                                      type Copier struct{}

                                        Copier is a type that allows copying between ValueReaders, ValueWriters, and []byte values.

                                        func NewCopier

                                        func NewCopier() Copier

                                          NewCopier creates a new copier with the given registry. If a nil registry is provided a default registry is used.

                                          func (Copier) AppendArrayBytes

                                          func (c Copier) AppendArrayBytes(dst []byte, src ValueReader) ([]byte, error)

                                            AppendArrayBytes copies an array from the ValueReader to dst.

                                            func (Copier) AppendDocumentBytes

                                            func (c Copier) AppendDocumentBytes(dst []byte, src ValueReader) ([]byte, error)

                                              AppendDocumentBytes functions the same as CopyDocumentToBytes, but will append the result to dst.

                                              func (Copier) AppendValueBytes

                                              func (c Copier) AppendValueBytes(dst []byte, src ValueReader) (bsontype.Type, []byte, error)

                                                AppendValueBytes functions the same as CopyValueToBytes, but will append the result to dst.

                                                func (Copier) CopyArrayFromBytes

                                                func (c Copier) CopyArrayFromBytes(dst ValueWriter, src []byte) error

                                                  CopyArrayFromBytes copies the values from a BSON array represented as a []byte to a ValueWriter.

                                                  func (Copier) CopyBytesToArrayWriter

                                                  func (c Copier) CopyBytesToArrayWriter(dst ArrayWriter, src []byte) error

                                                    CopyBytesToArrayWriter copies the values from a BSON Array represented as a []byte to an ArrayWriter.

                                                    func (Copier) CopyBytesToDocumentWriter

                                                    func (c Copier) CopyBytesToDocumentWriter(dst DocumentWriter, src []byte) error

                                                      CopyBytesToDocumentWriter copies the values from a BSON document represented as a []byte to a DocumentWriter.

                                                      func (Copier) CopyDocument

                                                      func (c Copier) CopyDocument(dst ValueWriter, src ValueReader) error

                                                        CopyDocument handles copying one document from the src to the dst.

                                                        func (Copier) CopyDocumentFromBytes

                                                        func (c Copier) CopyDocumentFromBytes(dst ValueWriter, src []byte) error

                                                          CopyDocumentFromBytes copies the values from a BSON document represented as a []byte to a ValueWriter.

                                                          func (Copier) CopyDocumentToBytes

                                                          func (c Copier) CopyDocumentToBytes(src ValueReader) ([]byte, error)

                                                            CopyDocumentToBytes copies an entire document from the ValueReader and returns it as bytes.

                                                            func (Copier) CopyValue

                                                            func (c Copier) CopyValue(dst ValueWriter, src ValueReader) error

                                                              CopyValue will copy a single value from src to dst.

                                                              func (Copier) CopyValueFromBytes

                                                              func (c Copier) CopyValueFromBytes(dst ValueWriter, t bsontype.Type, src []byte) error

                                                                CopyValueFromBytes will write the value represtend by t and src to dst.

                                                                func (Copier) CopyValueToBytes

                                                                func (c Copier) CopyValueToBytes(src ValueReader) (bsontype.Type, []byte, error)

                                                                  CopyValueToBytes copies a value from src and returns it as a bsontype.Type and a []byte.

                                                                  type DocumentReader

                                                                  type DocumentReader interface {
                                                                  	ReadElement() (string, ValueReader, error)
                                                                  }

                                                                    DocumentReader is implemented by types that allow reading elements from a BSON document.

                                                                    type DocumentWriter

                                                                    type DocumentWriter interface {
                                                                    	WriteDocumentElement(string) (ValueWriter, error)
                                                                    	WriteDocumentEnd() error
                                                                    }

                                                                      DocumentWriter is the interface used to create a BSON or BSON adjacent document. Callers must ensure they call WriteDocumentEnd when they have finished creating the document.

                                                                      type ExtJSONValueReaderPool

                                                                      type ExtJSONValueReaderPool struct {
                                                                      	// contains filtered or unexported fields
                                                                      }

                                                                        ExtJSONValueReaderPool is a pool for ValueReaders that read ExtJSON.

                                                                        func NewExtJSONValueReaderPool

                                                                        func NewExtJSONValueReaderPool() *ExtJSONValueReaderPool

                                                                          NewExtJSONValueReaderPool instantiates a new ExtJSONValueReaderPool.

                                                                          func (*ExtJSONValueReaderPool) Get

                                                                          func (bvrp *ExtJSONValueReaderPool) Get(r io.Reader, canonical bool) (ValueReader, error)

                                                                            Get retrieves a ValueReader from the pool and uses src as the underlying ExtJSON.

                                                                            func (*ExtJSONValueReaderPool) Put

                                                                            func (bvrp *ExtJSONValueReaderPool) Put(vr ValueReader) (ok bool)

                                                                              Put inserts a ValueReader into the pool. If the ValueReader is not a ExtJSON ValueReader nothing is inserted into the pool and ok will be false.

                                                                              type ExtJSONValueWriterPool

                                                                              type ExtJSONValueWriterPool struct {
                                                                              	// contains filtered or unexported fields
                                                                              }

                                                                                ExtJSONValueWriterPool is a pool for ExtJSON ValueWriters.

                                                                                func NewExtJSONValueWriterPool

                                                                                func NewExtJSONValueWriterPool() *ExtJSONValueWriterPool

                                                                                  NewExtJSONValueWriterPool creates a new pool for ValueWriter instances that write to ExtJSON.

                                                                                  func (*ExtJSONValueWriterPool) Get

                                                                                  func (bvwp *ExtJSONValueWriterPool) Get(w io.Writer, canonical, escapeHTML bool) ValueWriter

                                                                                    Get retrieves a ExtJSON ValueWriter from the pool and resets it to use w as the destination.

                                                                                    func (*ExtJSONValueWriterPool) Put

                                                                                    func (bvwp *ExtJSONValueWriterPool) Put(vw ValueWriter) (ok bool)

                                                                                      Put inserts a ValueWriter into the pool. If the ValueWriter is not a ExtJSON ValueWriter, nothing happens and ok will be false.

                                                                                      type SliceWriter

                                                                                      type SliceWriter []byte

                                                                                        SliceWriter allows a pointer to a slice of bytes to be used as an io.Writer.

                                                                                        func (*SliceWriter) Write

                                                                                        func (sw *SliceWriter) Write(p []byte) (int, error)

                                                                                        type TransitionError

                                                                                        type TransitionError struct {
                                                                                        	// contains filtered or unexported fields
                                                                                        }

                                                                                          TransitionError is an error returned when an invalid progressing a ValueReader or ValueWriter state machine occurs. If read is false, the error is for writing

                                                                                          func (TransitionError) Error

                                                                                          func (te TransitionError) Error() string

                                                                                          type ValueReader

                                                                                          type ValueReader interface {
                                                                                          	Type() bsontype.Type
                                                                                          	Skip() error
                                                                                          
                                                                                          	ReadArray() (ArrayReader, error)
                                                                                          	ReadBinary() (b []byte, btype byte, err error)
                                                                                          	ReadBoolean() (bool, error)
                                                                                          	ReadDocument() (DocumentReader, error)
                                                                                          	ReadCodeWithScope() (code string, dr DocumentReader, err error)
                                                                                          	ReadDBPointer() (ns string, oid primitive.ObjectID, err error)
                                                                                          	ReadDateTime() (int64, error)
                                                                                          	ReadDecimal128() (primitive.Decimal128, error)
                                                                                          	ReadDouble() (float64, error)
                                                                                          	ReadInt32() (int32, error)
                                                                                          	ReadInt64() (int64, error)
                                                                                          	ReadJavascript() (code string, err error)
                                                                                          	ReadMaxKey() error
                                                                                          	ReadMinKey() error
                                                                                          	ReadNull() error
                                                                                          	ReadObjectID() (primitive.ObjectID, error)
                                                                                          	ReadRegex() (pattern, options string, err error)
                                                                                          	ReadString() (string, error)
                                                                                          	ReadSymbol() (symbol string, err error)
                                                                                          	ReadTimestamp() (t, i uint32, err error)
                                                                                          	ReadUndefined() error
                                                                                          }

                                                                                            ValueReader is a generic interface used to read values from BSON. This type is implemented by several types with different underlying representations of BSON, such as a bson.Document, raw BSON bytes, or extended JSON.

                                                                                            func NewBSONDocumentReader

                                                                                            func NewBSONDocumentReader(b []byte) ValueReader

                                                                                              NewBSONDocumentReader returns a ValueReader using b for the underlying BSON representation. Parameter b must be a BSON Document.

                                                                                              TODO(skriptble): There's a lack of symmetry between the reader and writer, since the reader takes a []byte while the writer takes an io.Writer. We should have two versions of each, one that takes a []byte and one that takes an io.Reader or io.Writer. The []byte version will need to return a thing that can return the finished []byte since it might be reallocated when appended to.

                                                                                              func NewBSONValueReader

                                                                                              func NewBSONValueReader(t bsontype.Type, val []byte) ValueReader

                                                                                                NewBSONValueReader returns a ValueReader that starts in the Value mode instead of in top level document mode. This enables the creation of a ValueReader for a single BSON value.

                                                                                                func NewExtJSONValueReader

                                                                                                func NewExtJSONValueReader(r io.Reader, canonical bool) (ValueReader, error)

                                                                                                  NewExtJSONValueReader creates a new ValueReader from a given io.Reader It will interpret the JSON of r as canonical or relaxed according to the given canonical flag

                                                                                                  type ValueWriter

                                                                                                  type ValueWriter interface {
                                                                                                  	WriteArray() (ArrayWriter, error)
                                                                                                  	WriteBinary(b []byte) error
                                                                                                  	WriteBinaryWithSubtype(b []byte, btype byte) error
                                                                                                  	WriteBoolean(bool) error
                                                                                                  	WriteCodeWithScope(code string) (DocumentWriter, error)
                                                                                                  	WriteDBPointer(ns string, oid primitive.ObjectID) error
                                                                                                  	WriteDateTime(dt int64) error
                                                                                                  	WriteDecimal128(primitive.Decimal128) error
                                                                                                  	WriteDouble(float64) error
                                                                                                  	WriteInt32(int32) error
                                                                                                  	WriteInt64(int64) error
                                                                                                  	WriteJavascript(code string) error
                                                                                                  	WriteMaxKey() error
                                                                                                  	WriteMinKey() error
                                                                                                  	WriteNull() error
                                                                                                  	WriteObjectID(primitive.ObjectID) error
                                                                                                  	WriteRegex(pattern, options string) error
                                                                                                  	WriteString(string) error
                                                                                                  	WriteDocument() (DocumentWriter, error)
                                                                                                  	WriteSymbol(symbol string) error
                                                                                                  	WriteTimestamp(t, i uint32) error
                                                                                                  	WriteUndefined() error
                                                                                                  }

                                                                                                    ValueWriter is the interface used to write BSON values. Implementations of this interface handle creating BSON or BSON adjacent representations of the values.

                                                                                                    func NewBSONValueWriter

                                                                                                    func NewBSONValueWriter(w io.Writer) (ValueWriter, error)

                                                                                                      NewBSONValueWriter creates a ValueWriter that writes BSON to w.

                                                                                                      This ValueWriter will only write entire documents to the io.Writer and it will buffer the document as it is built.

                                                                                                      func NewExtJSONValueWriter

                                                                                                      func NewExtJSONValueWriter(w io.Writer, canonical, escapeHTML bool) (ValueWriter, error)

                                                                                                        NewExtJSONValueWriter creates a ValueWriter that writes Extended JSON to w.

                                                                                                        type ValueWriterFlusher

                                                                                                        type ValueWriterFlusher interface {
                                                                                                        	ValueWriter
                                                                                                        	Flush() error
                                                                                                        }

                                                                                                          ValueWriterFlusher is a superset of ValueWriter that exposes functionality to flush to the underlying buffer.

                                                                                                          Directories

                                                                                                          Path Synopsis