README
¶
Owl
Owl is a Go package that provides algorithmic guidance through structured directives using Go struct tags.
Documentation
¶
Overview ¶
Package "owl" a go struct tag framework and algorithm driver. It provides algorithmic guidance through structured directives using Go struct tags. Users can design their own directives and register them to owl. Owl will run the directives on the struct fields in a depth-first manner. Which means it is suitable for data-binding algorithms, data validations, etc.
Index ¶
- Constants
- Variables
- func RegisterDirectiveExecutor(name string, exe DirectiveExecutor, replace ...bool)
- func Tag() string
- func UseTag(tag string)
- type Directive
- type DirectiveExecutionError
- type DirectiveExecutor
- type DirectiveExecutorFunc
- type DirectiveRuntime
- type Namespace
- type Option
- type OptionFunc
- type ResolveError
- type Resolver
- func (r *Resolver) Copy() *Resolver
- func (r *Resolver) DebugLayoutText(depth int) string
- func (r *Resolver) GetDirective(name string) *Directive
- func (r *Resolver) IsLeaf() bool
- func (r *Resolver) IsRoot() bool
- func (r *Resolver) Iterate(fn func(*Resolver) error) error
- func (r *Resolver) Lookup(path string) *Resolver
- func (r *Resolver) Namespace() *Namespace
- func (r *Resolver) PathString() string
- func (r *Resolver) RemoveDirective(name string) *Directive
- func (r *Resolver) Resolve(opts ...Option) (reflect.Value, error)
- func (r *Resolver) ResolveTo(value any, opts ...Option) (err error)
- func (r *Resolver) Scan(value any, opts ...Option) error
- func (r *Resolver) String() string
- type ScanError
Constants ¶
const DefaultTagName = "owl"
Variables ¶
var ( ErrUnsupportedType = errors.New("unsupported type") ErrInvalidDirectiveName = errors.New("invalid directive name") ErrDuplicateDirective = errors.New("duplicate directive") ErrMissingExecutor = errors.New("missing executor") ErrTypeMismatch = errors.New("type mismatch") ErrScanNilField = errors.New("scan nil field") ErrInvalidResolveTarget = errors.New("invalid resolve target") )
Functions ¶
func RegisterDirectiveExecutor ¶
func RegisterDirectiveExecutor(name string, exe DirectiveExecutor, replace ...bool)
RegisterDirectiveExecutor registers a named executor globally, i.e. to the default namespace.
Types ¶
type Directive ¶
Directive defines the profile to locate a `DirectiveExecutor` instance and drives it with essential arguments.
func NewDirective ¶
NewDirective creates a Directive instance.
func ParseDirective ¶
ParseDirective creates a Directive instance by parsing a directive string extracted from the struct tag.
Example directives are:
"form=page,page_index" -> { Name: "form", Args: ["page", "page_index"] }
"header=x-api-token" -> { Name: "header", Args: ["x-api-token"] }
type DirectiveExecutionError ¶
func (*DirectiveExecutionError) Error ¶
func (e *DirectiveExecutionError) Error() string
func (*DirectiveExecutionError) Unwrap ¶
func (e *DirectiveExecutionError) Unwrap() error
type DirectiveExecutor ¶
type DirectiveExecutor interface {
Execute(*DirectiveRuntime) error
}
DirectiveExecutor is the interface that wraps the Execute method. Execute executes the directive by passing the runtime context.
func LookupExecutor ¶
func LookupExecutor(name string) DirectiveExecutor
LookupExecutor returns the executor by name globally (from the default namespace).
type DirectiveExecutorFunc ¶
type DirectiveExecutorFunc func(*DirectiveRuntime) error
DirecrtiveExecutorFunc is an adapter to allow the use of ordinary functions as DirectiveExecutors.
func (DirectiveExecutorFunc) Execute ¶
func (f DirectiveExecutorFunc) Execute(de *DirectiveRuntime) error
type DirectiveRuntime ¶
type DirectiveRuntime struct {
Directive *Directive
Resolver *Resolver
// Value is the reflect.Value of the field that the directive is applied to.
// Worth noting that the value is a pointer to the field value. Which means
// if the field is of type int. Then Value is of type *int. And the actual
// value is stored in Value.Elem().Int(). The same for other types. So if you
// want to modify the field value, you should call Value.Elem().Set(value),
// e.g. Value.Elem().SetString(value), Value.Elem().SetInt(value), etc.
Value reflect.Value
// Context is the runtime context of the directive execution. The initial
// context can be tweaked by applying options to Resolver.Resolve method.
// Use WithValue option to set a value to the initial context. Each field
// resolver will creates a new context by copying this initial context. And
// for the directives of the same field resolver, they will use the same
// context. Latter directives can use the values set by the former
// directives. Ex:
//
// type User struct {
// Name string `owl:"dirA;dirB"` // Context_1
// Gender string `owl:"dirC"` // Context_2
// }
//
// New(User{}).Resolve(WithValue("color", "red")) // Context_0
//
// In the above example, the initial context is Context_0. It has a value of "color" set to "red".
// The context of the first field resolver is Context_1. It is created by copying Context_0.
// The context of the second field resolver is Context_2. It is also created by copying Context_0.
// Thus, all the directives during execution can access the value of "color" in Context_0.
// For the Name field resolver, it has two directives, dirA and dirB. They will use the same context Context_1.
// and if in dirA we set a value of "foo" to "bar", then in dirB we can get the value of "foo" as "bar".
Context context.Context
}
DirectiveRuntime is the execution runtime/context of a directive. NOTE: the Directive and Resolver are both exported for the convenience but in an unsafe way. The user should not modify them. If you want to modify them, please call Resolver.Iterate to iterate the resolvers and modify them in the callback. And make sure this be done before any callings to Resolver.Resolve.
type Namespace ¶
type Namespace struct {
// contains filtered or unexported fields
}
Namespace isolates the executors as a collection.
func NewNamespace ¶
func NewNamespace() *Namespace
NewNamespace creates a new namespace. Which is a collection of executors.
func (*Namespace) LookupExecutor ¶
func (ns *Namespace) LookupExecutor(name string) DirectiveExecutor
LookupExecutor returns the executor by name.
func (*Namespace) RegisterDirectiveExecutor ¶
func (ns *Namespace) RegisterDirectiveExecutor(name string, exe DirectiveExecutor, replace ...bool)
RegisterDirectiveExecutor registers a named executor to the namespace. The executor should implement the DirectiveExecutor interface. Will panic if the name were taken or the executor is nil. Pass replace (true) to ignore the name conflict.
type Option ¶
Option is an option for New.
func WithNamespace ¶
WithNamespace binds a namespace to the resolver. The namespace is used to lookup directive executors. There's a default namespace, which is used when the namespace is not specified. The namespace set in New() will be overridden by the namespace set in Resolve() or Scan().
func WithNestedDirectivesEnabled ¶ added in v0.5.0
WithNestedDirectivesEnabled controls whether to resolve nested directives. The default value is true. When set to false, the nested directives will not be executed. The value set in New() will be overridden by the value set in Resolve() or Scan().
type OptionFunc ¶
OptionFunc is a function that implements Option.
type ResolveError ¶
type ResolveError struct {
// contains filtered or unexported fields
}
func (*ResolveError) AsDirectiveExecutionError ¶ added in v0.1.6
func (e *ResolveError) AsDirectiveExecutionError() *DirectiveExecutionError
func (*ResolveError) Error ¶
func (e *ResolveError) Error() string
type Resolver ¶
type Resolver struct {
Type reflect.Type
Field reflect.StructField
Index []int
Path []string
Directives []*Directive
Parent *Resolver
Children []*Resolver
Context context.Context // save custom resolver settings here
}
Resolver is a field resolver. Which is a node in the resolver tree. The resolver tree is built from a struct value. Each node represents a field in the struct. The root node represents the struct itself. It is used to resolve a field value from a data source.
func New ¶
New builds a resolver tree from a struct value. The given options will be applied to all the resolvers. In the resolver tree, each node is also a Resolver. Available options are WithNamespace, WithNestedDirectivesEnabled and WithValue.
func (*Resolver) Copy ¶ added in v0.7.0
Copy returns a copy of the resolver tree. The copy is a deep copy, which means the children are also copied.
func (*Resolver) DebugLayoutText ¶
func (*Resolver) GetDirective ¶
func (*Resolver) Iterate ¶
Iterate visits the resolver tree by depth-first. The callback function will be called on each field resolver. The iteration will stop if the callback returns an error.
func (*Resolver) Lookup ¶
Find finds a field resolver by path. e.g. "Pagination.Page", "User.Name", etc.
func (*Resolver) PathString ¶
func (*Resolver) RemoveDirective ¶ added in v0.1.4
func (*Resolver) Resolve ¶
Resolve resolves the struct type by traversing the tree in depth-first order. Typically it is used to create a new struct instance by reading from some data source. This method always creates a new value of the type the resolver holds. And runs the directives on each field.
Use WithValue to create an Option that can add custom values to the context, the context can be used by the directive executors during the resolution. Example:
type Settings struct {
DarkMode bool `owl:"env=MY_APP_DARK_MODE;cfg=appearance.dark_mode;default=false"`
}
resolver := owl.New(Settings{})
settings, err := resolver.Resolve(WithValue("app_config", appConfig))
NOTE: while iterating the tree, if resolving a field failed, the iteration will be stopped immediately and the error will be returned.
func (*Resolver) ResolveTo ¶ added in v0.8.0
ResolveTo works like Resolve, but it resolves the struct value to the given pointer value instead of creating a new value. The pointer value must be non-nil and a pointer to the type the resolver holds.
func (*Resolver) Scan ¶ added in v0.2.0
Scan scans the struct value by traversing the fields in depth-first order. The value is required to have the same type as the resolver holds. While scanning, it will run the directives on each field. The DirectiveRuntime that can be accessed during the directive exeuction will have its Value property populated with reflect.Value of the field. Typically, Scan is used to do some readonly operations against the struct value, e.g. validate the struct value, build something based on the struct value, etc.
Use WithValue to create an Option that can add custom values to the context, the context can be used by the directive executors during the scanning.
NOTE: Unlike Resolve, it will iterate the whole resolver tree against the given value, try to access each corresponding field. Even scan fails on one of the fields, it will continue to scan the rest of the fields. The returned error can be a multi-error combined by errors.Join, which contains all the errors that occurred during the scan.
type ScanError ¶ added in v0.2.0
type ScanError struct {
// contains filtered or unexported fields
}
func (*ScanError) AsDirectiveExecutionError ¶ added in v0.2.0
func (e *ScanError) AsDirectiveExecutionError() *DirectiveExecutionError
Source Files