Handlers
Register functions for tag keys, order them, filter them and choose whether they run before or after a field's children.
A handler is a function that runs on a field.
type HandlerFunc func(ctx structwalker.FieldContext) error
Tag handlers
Handle registers a handler for one tag key. It runs on every field that has that key.
w := structwalker.New()
w.Handle("mask", func(ctx structwalker.FieldContext) error {
return ctx.SetValue("***")
})
type Login struct {
User string
Password string `mask:"true"`
}
Only Password reaches the handler. User has no mask tag.
A field tagged mask:"-" is skipped as well. - is Go's usual way to opt a field out and tag handlers respect it.
Handlers for every field
HandleAll registers a handler that runs on every field, tagged or not.
w.HandleAll(func(ctx structwalker.FieldContext) error {
fmt.Println(ctx.Path)
return nil
})
In a HandleAll handler ctx.Tag is empty, because the handler wasn't matched to a tag. Read tags with ctx.Lookup.
What a handler receives
ctx.Tag |
The parsed tag the handler was registered for |
ctx.AllTags |
Every tag on the field |
ctx.Lookup(key) |
Another tag on the same field |
ctx.Field |
The reflect.StructField |
ctx.Value |
The field's reflect.Value |
ctx.Path |
Where the field is, such as Address.Street |
ctx.Depth |
How many structs deep. Root fields are 0 |
ctx.Parent |
The struct holding the field |
ctx.Index |
The field's position in its parent |
ctx.Context() |
The walk's context.Context |
ctx.SetValue(v) |
Sets the field |
ctx.IsZero() |
The field holds its zero value |
ctx.IsNil() |
The field is a nil pointer, interface, slice, map, channel or func |
ctx.IsExported() |
The field is exported |
Order
Several handlers can run on one field. They run in priority order, lowest first. The default priority is 100.
w.Handle("default", setDefault, structwalker.WithPriority(10))
w.Handle("validate", validate) // 100, so after defaults
w.HandleAll(audit, structwalker.WithPriority(1000))
Priority orders everything on the field: handlers for different tag keys and HandleAll handlers alike.
When priorities tie:
- Tag handlers run in the order their tags are written on the field.
HandleAllhandlers come after tag handlers.- Anything still tied runs in the order it was registered.
So with no priorities set, json:"a" validate:"b" runs the json handler before the validate handler.
Filters
WithFilter narrows a handler to the fields where a function returns true.
w.Handle("validate", validateString, structwalker.WithFilter(
func(ctx structwalker.FieldContext) bool {
return ctx.Value.Kind() == reflect.String
},
))
A filtered-out handler is skipped. The other handlers on the field still run.
Before or after children
By default a handler runs on a struct field before the walker goes into it. WithPhase(AfterChildren) runs it afterwards.
w.Handle("section", open)
w.Handle("section", closeSection, structwalker.WithPhase(structwalker.AfterChildren))
open: Database
... Database.Host
... Database.Port
close: Database
After-children handlers are useful when a field's meaning depends on what's inside it: totals, "at least one of these is set" checks or closing something you opened.
Returning errors
Returning an error stops the walk and you get it back from Walk, wrapped with the field's path. Two errors are special and steer the walk instead: ErrSkipField and ErrSkipChildren. Collecting every error instead of stopping is covered in errors.
Registering late
You can call Handle, HandleAll and Use at any time, even while other goroutines are walking. A walk uses the handlers that were registered when it started.