Documentation
¶
Overview ¶
Package path provides a simple utility to navigate go objects using string paths.
A path is a series of components seperated by a '.' character. As an example:
value, err := New("A.B").Get(obj)
will access field B of field A of object obj.
Path supports just about all go constructs with with the following caveats: Pointers will automatically be dereferenced when accessed. Slices and Arrays can only be traversed using unsigned integers as path components. Only maps that use strings as keys can be traversed. The returned value will be used to dereference the rest of the path.
A wildcard component, denoted by the '*' character, is also available when using the GetAll to return all the values that match the path pattern.
For channels a wildcard component can be provided to read all values until the channel is closed or a count which to indicate the number of values to read.
Functions contains special handling whereby to path through a function the '()' component needs to be provided and the function must take no input arguments and output a single value with an optional error. To set, the function must take a single input argument and return at most a single error argument. The errors returned by function calls will be reported as errors from the pathing function.
A translation mechanism is available to convert JSON paths into paths usable by gopath. This is accomplished by creating an alias table using the JSONAliases function which is then used to translate paths using the Path.Translate function.
Index ¶
- Variables
- func JSONAliases(typ reflect.Type) map[string]string
- func JsonSchema(typ reflect.Type) string
- type Context
- type P
- func (path P) Apply(obj interface{}, ctx *Context) (err error)
- func (path P) Get(obj interface{}) (result interface{}, err error)
- func (path P) GetAll(obj interface{}) (result []interface{}, err error)
- func (path P) Last() string
- func (path P) Read(obj, dest interface{}) (err error)
- func (path P) ReadAll(obj, dest interface{}) error
- func (path P) Set(obj, value interface{}) error
- func (path P) SetAll(obj, value interface{}) (err error)
- func (path P) String() string
- func (path P) Translate(aliases map[string]string) (result P)
- func (path P) Type(obj interface{}) (result reflect.Type, err error)
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidType = errors.New("type mismatch")
ErrInvalidType indicates that the type of the value to be written did not match the destination's type.
var ErrMissing = errors.New("unable to path through the object")
ErrMissing is an error that indicates that the path could not be found in the object due to a nil pointer, missing array index or missing map key.
var ErrNil = errors.New("value is nil")
ErrNil indicates that value is nil
Functions ¶
func JSONAliases ¶
JSONAliases crawls the given type and returns an alias map from JSON names to struct field names.
func JsonSchema ¶
Types ¶
type Context ¶
type Context struct {
// Fn is the function to be called when the path is fully matched. The P
// argument is the fully qualified path where wildcard are replaced by their
// actual component name. The Context argument contains the current state of
// the path crawler and can be used to retrieve various information. The
// bool return value indicates whether we should continue to explore the
// path for additional matchin values.
Fn func(P, *Context) (bool, error)
// CreateIfMissing will prevent Missing errors from being returned by
// filling in any missing components with their zero values. Arrays will be
// expanded until they are large enough for the desired index. Channels will
// be created with a default configuration. Note that interfaces, and
// unsafe.Pointers will cause an error to be returned.
CreateIfMissing bool
// contains filtered or unexported fields
}
Context contains the state of the path crawl.
type P ¶
type P []string
P represents a path through an object seperated by '.' characters. A path can also contain wildcard components indicated by a '*' character. Arrays and slice indexes should be specified using non-negative numbers. Only map keyed with string are currently supported. Channels can be read by providing either a number of values to read or a wildcard character to read all values until the channel is closed. To call through a function, specify the '()'.
func Newf ¶
Newf returns a new P object from the given format strings applied to args. Formatting is done using fmt.Sprintf.
func (P) Get ¶
Get fetches the first value in the given object that matches the path. Returns ErrMissing if the path could not be completed due to a nil field, a missing array index or a missing map value.
func (P) GetAll ¶
GetAll fetches all the values in the given object that matches the path. Returns ErrMissing if the path could not be completed due to a nil field, a missing array index or a missing map value. Note that missing components are ignored if they are encountered after a wildcard path component.
func (P) Read ¶
Read sets the given dest object to the content of the path applied to the given obj object. Returns ErrInvalidType if the type of the value can't be converted or assigned to dest. Panics if dest is can't be set.
func (P) ReadAll ¶
ReadAll appends to the given dest slice to content of the path applied to the given obj object. Returns ErrInvalidType if the type of the value can't be converted or assigned to the member of dest. Panics if dest is not a slice.
func (P) Set ¶
Set modifies the first value in the given object that matches the path to contain the given value. Returns ErrInvalidType if the type of the given value doesn't match the type of value at the path location in the given object. Returns an error if the object is not addresable and therefore not modifiable.
func (P) SetAll ¶
SetAll modifies all the values in the given object that matches the path to contain the given value. Returns ErrInvalidType if the type of the given value doesn't match the type of value at the path location in the given object. Returns an error if the object is not addresable and therefore not modifiable.
Source Files