Documentation
¶
Overview ¶
Package tag expands JaWS tag values into comparable keys that identify elements during dirtying, broadcasts and event routing.
TagExpand rejects values that are not usable as hashable tag keys, including values whose static type is comparable but whose runtime contents are not.
Index ¶
- Variables
- func FindTagGetter(x any) (path string, tgType reflect.Type, found bool)
- func MustTagExpand(ctx Context, tag any) []any
- func NewErrNotComparable(x any) error
- func NewErrNotUsableAsTag(x any) error
- func TagExpand(ctx Context, tag any) (result []any, err error)
- func TagString(tag any) string
- type Context
- type Tag
- type TagGetter
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrIllegalTagType errIllegalTagType
ErrIllegalTagType is returned when a UI tag type is disallowed.
var ErrNotComparable errNotComparable
ErrNotComparable is returned when a UI object or tag is not comparable.
var ErrNotUsableAsTag errNotUsableAsTag
ErrNotUsableAsTag is returned when a value cannot be used as a tag.
It also matches ErrNotComparable via errors.Is, because a non-comparable value is one reason a value cannot be used as a tag.
var ErrTooManyTags errTooManyTags
ErrTooManyTags is returned when tag expansion exceeds the recursion depth (maxTagDepth) or result count (maxTagCount) limits.
Functions ¶
func FindTagGetter ¶
FindTagGetter searches x recursively for a nested TagGetter.
The search is bounded: it follows at most maxTagDepth levels of nesting and scans only the first maxHintScan elements of any array or slice. It is used only to enrich the ErrNotUsableAsTag diagnostic, so these bounds trade completeness for a cheap, terminating search.
It is a best-effort diagnostic aid: the maxHintScan and maxTagDepth bounds may change, and a negative result is not authoritative, so callers should not rely on it for non-diagnostic purposes.
func MustTagExpand ¶
MustTagExpand calls TagExpand and either logs or panics if expansion fails.
On a non-nil ctx, expansion errors are passed to Context.MustLog (which logs them, or panics if no Logger is set); MustTagExpand then returns the partial result from TagExpand. A nil ctx always panics on error.
func NewErrNotComparable ¶
NewErrNotComparable returns ErrNotComparable if x is not comparable.
func NewErrNotUsableAsTag ¶
NewErrNotUsableAsTag returns ErrNotUsableAsTag if x cannot be used as a tag.
func TagExpand ¶
TagExpand expands tag into a flat list of unique comparable tag values.
tag may be nil, a Tag, a slice of tags, a TagGetter or another comparable value. Primitive HTML/value types are rejected with ErrIllegalTagType to catch common accidental tags, and a value that is not comparable at runtime is rejected with ErrNotUsableAsTag (which also matches ErrNotComparable via errors.Is). Expansion that exceeds the nesting-depth or total-count limits is rejected with ErrTooManyTags.
On error, result holds the tags expanded before the failure; the exception is a value that is not comparable at runtime, for which ErrNotUsableAsTag is returned with a nil result.
Expansion reads tag and any values returned by TagGetter.JawsGetTag by reference, so tag and those values must not be mutated concurrently with the call.
Example (ErrorsIs) ¶
package main
import (
"errors"
"fmt"
"github.com/linkdata/jaws/lib/tag"
)
func main() {
_, err := tag.TagExpand(nil, []int{1})
fmt.Println(errors.Is(err, tag.ErrNotUsableAsTag))
fmt.Println(errors.Is(err, tag.ErrNotComparable))
}
Output: true true
Example (TagGetter) ¶
package main
import (
"fmt"
"github.com/linkdata/jaws/lib/tag"
)
type exampleItem struct {
Name string
}
func (item *exampleItem) JawsGetTag(tag.Context) any {
return item
}
func main() {
item := &exampleItem{Name: "row"}
tags, err := tag.TagExpand(nil, []any{item, tag.Tag("list")})
if err != nil {
panic(err)
}
fmt.Println(len(tags), tags[0] == item, tags[1] == tag.Tag("list"))
}
Output: 2 true true
Types ¶
type Context ¶
type Context interface {
// Initial returns the Request's initial HTTP request, or nil.
Initial() (r *http.Request)
// Get returns the JaWS session value for the key, or nil.
Get(key string) any
// Set sets the JaWS session value for the key.
Set(key string, value any)
// Context returns the Request's context.
Context() (ctx context.Context)
// Log sends an error to the Logger set in the Jaws.
// Has no effect if the err is nil or the Logger is nil.
// Returns err.
Log(err error) error
// MustLog sends an error to the Logger set in the Jaws or
// panics with the given error if no Logger is set.
// Has no effect if the err is nil.
MustLog(err error)
}
Context is the request state made available while expanding tags.
type TagGetter ¶
type TagGetter interface {
// JawsGetTag returns the dynamic tag or tags for the implementing object.
//
// ctx may be nil — [TagExpand] is routinely called with a nil [Context] — so
// implementations must not dereference it unconditionally.
JawsGetTag(ctx Context) any
}
TagGetter exposes dynamic tags during TagExpand.
Source Files