Documentation
¶
Overview ¶
The fluent package offers helper utilities for using NodeAssembler more tersely by providing an interface that handles all errors for you, and allows use of closures for any recursive assembly so that creating trees of data results in indentation for legibility.
Note that the fluent package creates wrapper objects in order to provide the API conveniences that it does, and this comes at some cost to performance. If you're optimizing for performance, using some of the features of the fluent package may be inadvisable (and some moreso than others). However, as with any performance questions, benchmark before making decisions; its entirely possible that your performance bottlenecks will be elsewhere and there's no reason to deny yourself syntactic sugar if the costs don't detectably affect the bottom line. Various feature of the package will also attempt to document how costly they are in relative terms (e.g. the fluent.Reflect helper methods are very costly;
Index ¶
- func Build(np ld.NodePrototype, fn func(NodeAssembler)) (ld.Node, error)
- func BuildList(np ld.NodePrototype, sizeHint int64, fn func(ListAssembler)) (ld.Node, error)
- func BuildMap(np ld.NodePrototype, sizeHint int64, fn func(MapAssembler)) (ld.Node, error)
- func MustBuild(np ld.NodePrototype, fn func(NodeAssembler)) ld.Node
- func MustBuildList(np ld.NodePrototype, sizeHint int64, fn func(ListAssembler)) ld.Node
- func MustBuildMap(np ld.NodePrototype, sizeHint int64, fn func(MapAssembler)) ld.Node
- func MustReflect(np ld.NodePrototype, i interface{}) ld.Node
- func Recover(fn func()) (err error)
- func Reflect(np ld.NodePrototype, i interface{}) (ld.Node, error)
- func ReflectIntoAssembler(na ld.NodeAssembler, i interface{}) error
- type Error
- type ListAssembler
- type MapAssembler
- type NodeAssembler
- type Reflector
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Build ¶
func Build(np ld.NodePrototype, fn func(NodeAssembler)) (ld.Node, error)
func BuildList ¶
func BuildList(np ld.NodePrototype, sizeHint int64, fn func(ListAssembler)) (ld.Node, error)
func BuildMap ¶
func BuildMap(np ld.NodePrototype, sizeHint int64, fn func(MapAssembler)) (ld.Node, error)
func MustBuild ¶
func MustBuild(np ld.NodePrototype, fn func(NodeAssembler)) ld.Node
func MustBuildList ¶
func MustBuildList(np ld.NodePrototype, sizeHint int64, fn func(ListAssembler)) ld.Node
func MustBuildMap ¶
func MustBuildMap(np ld.NodePrototype, sizeHint int64, fn func(MapAssembler)) ld.Node
func MustReflect ¶
func MustReflect(np ld.NodePrototype, i interface{}) ld.Node
MustReflect is a shortcut for Reflect but panics on any error. It is useful if you need a single return value for function composition purposes.
func Recover ¶
func Recover(fn func()) (err error)
Recover invokes a function within a panic-recovering context, and returns any raised fluent.Error values; any other values are re-panicked.
This can be useful for writing large blocks of code using fluent nodes, and handling any errors at once at the end.
func Reflect ¶
func Reflect(np ld.NodePrototype, i interface{}) (ld.Node, error)
Reflect creates a new Node by looking at a golang value with reflection and converting it into LD Data Model. This is a quick-and-dirty way to get data into the LD Data Model; it's useful for rapid prototyping and demos, but note that this feature is not intended to be suitable for "production" use due to low performance and lack of configurability.
The concrete type of the returned Node is determined by the NodePrototype argument provided by the caller.
No type information from the golang value will be observable in the result.
The reflection will walk over any golang value, but is not configurable. Golang maps become LD maps; golang slices and arrays become LD lists; and golang structs become LD maps too. When converting golang structs to LD maps, the field names will become the map keys. Pointers and interfaces will be traversed transparently and are not visible in the output.
An error will be returned if the process of assembling the Node returns any errors (for example, if the NodePrototype is for a schema-constrained Node, any validation errors from the schema will cause errors to be returned).
A panic will be raised if there is any difficulty examining the golang value via reflection (for example, if the value is a struct with unexported fields, or if a non-data type like a channel or function is encountered).
Some configuration (in particular, what to do about map ordering) is available via the Reflector struct. That structure has a method of the same name and signiture as this one on it. (This function is a shortcut for calling that method on a Reflector struct with default configuration.)
Performance remarks: performance of this function will generally be poor. In general, creating data in golang types and then *flipping* it to LD form involves handling the data at least twice, and so will always be slower than just creating the same data in LD form programmatically directly. In particular, reflection is generally not fast, and this feature has not been optimized for either speed nor allocation avoidance. Other features in the fluent package will typically out-perform this, and using NodeAssemblers directly (without any fluent tools) will be much faster. Only use this function if performance is not of consequence.
func ReflectIntoAssembler ¶
func ReflectIntoAssembler(na ld.NodeAssembler, i interface{}) error
ReflectIntoAssembler is similar to Reflect, but takes a NodeAssembler parameter instead of a Node Prototype. This may be useful if you need more direct control over allocations, or want to fill in only part of a larger node assembly process using the reflect tool. Data is accumulated by the NodeAssembler parameter, so no Node is returned.
Types ¶
type ListAssembler ¶
type ListAssembler interface {
AssembleValue() NodeAssembler
ValuePrototype(idx int64) ld.NodePrototype
}
ListAssembler is the same as the interface in the core package, except: instead of returning errors, any error will cause panic (and you can collect these with `fluent.Recover`); and all recursive operations take a function as a parameter, within which you will receive another {Map,List,}NodeAssembler.
type MapAssembler ¶
type MapAssembler interface {
AssembleKey() NodeAssembler
AssembleValue() NodeAssembler
AssembleEntry(k string) NodeAssembler
KeyPrototype() ld.NodePrototype
ValuePrototype(k string) ld.NodePrototype
}
MapAssembler is the same as the interface in the core package, except: instead of returning errors, any error will cause panic (and you can collect these with `fluent.Recover`); and all recursive operations take a function as a parameter, within which you will receive another {Map,List,}NodeAssembler.
type NodeAssembler ¶
type NodeAssembler interface {
CreateMap(sizeHint int64, fn func(MapAssembler))
CreateList(sizeHint int64, fn func(ListAssembler))
AssignNull()
AssignBool(bool)
AssignInt(int64)
AssignFloat(float64)
AssignString(string)
AssignBytes([]byte)
AssignLink(ld.Link)
AssignNode(ld.Node)
Prototype() ld.NodePrototype
}
NodeAssembler is the same as the interface in the core package, except: instead of returning errors, any error will cause panic (and you can collect these with `fluent.Recover`); and all recursive operations take a function as a parameter, within which you will receive another {Map,List,}NodeAssembler.
func WrapAssembler ¶
func WrapAssembler(na ld.NodeAssembler) NodeAssembler
type Reflector ¶
type Reflector struct {
// MapOrder is used to decide a deterministic order for inserting entries to maps.
// (This is used when converting golang maps, since their iteration order is randomized;
// it is not used when converting other types such as structs, since those have a stable order.)
// MapOrder should return x < y in the same way as sort.Interface.Less.
//
// If using a default Reflector (e.g. via the package-scope functions),
// this function is a simple natural golang string sort: it performs `x < y` on the strings.
MapOrder func(x, y string) bool
}
Reflector allows configuration of the Reflect family of functions (`Reflect`, `ReflectIntoAssembler`, etc).
func (Reflector) Reflect ¶
Reflect is as per the package-scope function of the same name and signature, but using the configuration in the Reflector struct. See the package-scope function for documentation.
func (Reflector) ReflectIntoAssembler ¶
ReflectIntoAssembler is as per the package-scope function of the same name and signature, but using the configuration in the Reflector struct. See the package-scope function for documentation.
Source Files
Directories