obj

Documentation

Overview

The `obj` package defines Marshaller and Unmarshaller types, which can be used to convert in-memory values to token streams, and token streams to unpack in-memory values.

Index

• type ErrInvalidUnmarshalTarget
  • func (e ErrInvalidUnmarshalTarget) Error() string
• type ErrMalformedTokenStream
  • func (e ErrMalformedTokenStream) Error() string
• type ErrNoSuchField
  • func (e ErrNoSuchField) Error() string
• type ErrNoSuchUnionMember
  • func (e ErrNoSuchUnionMember) Error() string
• type ErrUnmarshalTypeCantFit
  • func (e ErrUnmarshalTypeCantFit) Error() string
• type MarshalMachine
• type Marshaller
  • func NewMarshaller(atl atlas.Atlas) *Marshaller
  • func (d *Marshaller) Bind(v interface{}) error
  • func (d *Marshaller) Recurse(tok *Token, rv reflect.Value, rt reflect.Type, nextMach MarshalMachine) (err error)
  • func (d *Marshaller) Step(tok *Token) (bool, error)
• type UnmarshalMachine
• type Unmarshaller
  • func NewUnmarshaller(atl atlas.Atlas) *Unmarshaller
  • func (d *Unmarshaller) Bind(v interface{}) error
  • func (d *Unmarshaller) Recurse(tok *Token, rv reflect.Value, rt reflect.Type, nextMach UnmarshalMachine) (err error)
  • func (d *Unmarshaller) Step(tok *Token) (bool, error)

Types

type ErrInvalidUnmarshalTarget

type ErrInvalidUnmarshalTarget struct {
	Type reflect.Type
}

ErrInvalidUnmarshalTarget describes an invalid argument passed to Unmarshaller.Bind. (Unmarshalling must target a non-nil pointer so that it can address the value.)

func (ErrInvalidUnmarshalTarget) Error

func (e ErrInvalidUnmarshalTarget) Error() string

type ErrMalformedTokenStream

type ErrMalformedTokenStream struct {
	Got      TokenType // Token in the stream that triggered the error.
	Expected string    // Freeform string describing valid token types.  Often a summary like "array close or start of value", or "map close or key".
}

ErrMalformedTokenStream is the error returned when unmarshalling recieves ae completely invalid transition, such as when a map value is expected, but the map suddenly closes, or an array close is recieved with no matching array open.

func (ErrMalformedTokenStream) Error

func (e ErrMalformedTokenStream) Error() string

type ErrNoSuchField

type ErrNoSuchField struct {
	Name string // Field name from the token.
	Type string // Type name of the struct we're operating on.
}

ErrNoSuchField is the error returned when unmarshalling into a struct and the token stream for the map contains a key which is not defined for the struct.

func (ErrNoSuchField) Error

func (e ErrNoSuchField) Error() string

type ErrNoSuchUnionMember

type ErrNoSuchUnionMember struct {
	Name         string       // Key name from the token.
	Type         reflect.Type // The interface type we're trying to fill.
	KnownMembers []string     // Members we expected isntead.
}

ErrNoSuchUnionMember is the error returned when unmarshalling into a union interface and the token stream contains a key which does not name any of the known members of the union.

func (ErrNoSuchUnionMember) Error

func (e ErrNoSuchUnionMember) Error() string

type ErrUnmarshalTypeCantFit

type ErrUnmarshalTypeCantFit struct {
	Token  Token
	Value  reflect.Value
	LenLim int // Set only if Value.Kind == Array and Token is bytes of a mismatch length.
}

ErrUnmarshalTypeCantFit is the error returned when unmarshalling cannot coerce the tokens in the stream into the kind of variables the unmarshal is targetting, for example if a map open token comes when an int is expected, or an int token comes when a string is expected.

func (ErrUnmarshalTypeCantFit) Error

func (e ErrUnmarshalTypeCantFit) Error() string

type MarshalMachine

type MarshalMachine interface {
	Reset(*marshalSlab, reflect.Value, reflect.Type) error
	Step(*Marshaller, *marshalSlab, *Token) (done bool, err error)
}

type Marshaller

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

func NewMarshaller

func NewMarshaller(atl atlas.Atlas) *Marshaller

Allocates the machinery for treating an object like a `TokenSource`. This machinery will walk over structures in memory, emitting tokens representing values and fields as it visits them.

Initialization must be finished by calling `Bind` to set the value to visit; after this, the `Step` function is ready to be pumped. Subsequent calls to `Bind` do a full reset, leaving `Step` ready to call again and making all of the machinery reusable without re-allocating.

func (*Marshaller) Bind

func (d *Marshaller) Bind(v interface{}) error

func (*Marshaller) Recurse

func (d *Marshaller) Recurse(tok *Token, rv reflect.Value, rt reflect.Type, nextMach MarshalMachine) (err error)

Starts the process of recursing marshalling over value `rv`.

Caller provides the machine to use (this is an optimization for maps and slices, which already know the machine and keep reusing it for all their entries). This method pushes the first step with `tok` (the upstream tends to have peeked at it in order to decide what to do, but if recursing, it belongs to the next obj), then saves this new machine onto the driver's stack: future calls to step the driver will then continuing stepping the new machine it returns a done status, at which point we'll finally "return" by popping back to the last machine on the stack (which is presumably the same one that just called this Recurse method).

In other words, your MarshalMachine calls this when it wants to deal with an object, and by the time we call back to your machine again, that object will be traversed and the stream ready for you to continue.

func (*Marshaller) Step

func (d *Marshaller) Step(tok *Token) (bool, error)

type UnmarshalMachine

type UnmarshalMachine interface {
	Reset(*unmarshalSlab, reflect.Value, reflect.Type) error
	Step(*Unmarshaller, *unmarshalSlab, *Token) (done bool, err error)
}

type Unmarshaller

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

func NewUnmarshaller

func NewUnmarshaller(atl atlas.Atlas) *Unmarshaller

Allocates the machinery for treating an in-memory object like a `TokenSink`. This machinery will walk over values, using received tokens to fill in fields as it visits them.

Initialization must be finished by calling `Bind` to set the value to visit; after this, the `Step` function is ready to be pumped. Subsequent calls to `Bind` do a full reset, leaving `Step` ready to call again and making all of the machinery reusable without re-allocating.

func (*Unmarshaller) Bind

func (d *Unmarshaller) Bind(v interface{}) error

func (*Unmarshaller) Recurse

func (d *Unmarshaller) Recurse(tok *Token, rv reflect.Value, rt reflect.Type, nextMach UnmarshalMachine) (err error)

Starts the process of recursing unmarshalling over value `rv`.

Caller provides the machine to use (this is an optimization for maps and slices, which already know the machine and keep reusing it for all their entries). This method pushes the first step with `tok` (the upstream tends to have peeked at it in order to decide what to do, but if recursing, it belongs to the next obj), then saves this new machine onto the driver's stack: future calls to step the driver will then continuing stepping the new machine it returns a done status, at which point we'll finally "return" by popping back to the last machine on the stack (which is presumably the same one that just called this Recurse method).

In other words, your UnmarshalMachine calls this when it wants to deal with an object, and by the time we call back to your machine again, that object will be traversed and the stream ready for you to continue.

func (*Unmarshaller) Step

func (d *Unmarshaller) Step(tok *Token) (bool, error)