Documentation
¶
Index ¶
- func RelFilename(filename string) string
- func TrustedName(name string) bool
- type Func
- type FuncInfo
- func (f *FuncInfo) Clone() FuncInfo
- func (f *FuncInfo) CopyFrom(other FuncInfo)
- func (f *FuncInfo) CopyTo(other *FuncInfo)
- func (f *FuncInfo) Equal(other FuncInfo) bool
- func (f *FuncInfo) SetFilenameLine(filename string, line int)
- func (f *FuncInfo) SetNameFileAndLineByMethod(typ reflect.Type, methodName string)
- func (f *FuncInfo) String() string
- func (f *FuncInfo) TrustedFuncName() bool
- type List
- func (l *List[T]) Append(fn T, opts ...Option[T]) *List[T]
- func (l *List[T]) AppendAfter(newFunction T, afterName string, opts ...Option[T]) bool
- func (l *List[T]) AppendList(list *List[T]) *List[T]
- func (l *List[T]) AppendSlice(fns []T, opts ...Option[T]) *List[T]
- func (l *List[T]) Clone() *List[T]
- func (l *List[T]) Count() int
- func (l *List[T]) Delete(name string) *List[T]
- func (l *List[T]) Exists(name string) bool
- func (l *List[T]) First() *Func[T]
- func (l *List[T]) FuncDelete(fn T) *List[T]
- func (l *List[T]) FuncExists(fn T) bool
- func (l *List[T]) FuncName(fn T) string
- func (l *List[T]) Last() *Func[T]
- func (l *List[T]) List() []*Func[T]
- func (l *List[T]) Lookup(name string) (*Func[T], bool)
- func (l *List[T]) Prepend(fn T, opts ...Option[T]) *List[T]
- func (l *List[T]) PrependBefore(newFunction T, beforeName string, opts ...Option[T]) bool
- func (l *List[T]) PrependList(list *List[T]) *List[T]
- func (l *List[T]) Replace(fn T) *List[T]
- func (l *List[T]) Reset()
- func (l *List[T]) Set(fns ...T) *List[T]
- func (l *List[T]) SetIfEmpty(fns ...T) *List[T]
- func (l *List[T]) SubscribeAppendAfter(fn T, afterName string, opts ...Option[T])
- func (l *List[T]) SubscribePrependBefore(fn T, beforeName string, opts ...Option[T])
- func (l *List[T]) UniqueValues() []T
- func (l *List[T]) Upsert(fn T, opts ...Option[T]) *List[T]
- func (l *List[T]) UpsertSlice(fns []T, opts ...Option[T]) *List[T]
- func (l *List[T]) Values() []T
- func (l *List[T]) Walk(fn func(*Func[T]) bool) bool
- type ListActionFunc
- type NameExpr
- type NameResolver
- func (ns *NameResolver) GetCustomName(funcName, filename string) string
- func (ns *NameResolver) GetCustomNameMatched(funcName, filename string) (string, bool)
- func (ns *NameResolver) GetName(fn any) string
- func (ns *NameResolver) GetNameAndFileAndLine(fn any) (name, file string, line int)
- func (ns *NameResolver) SetName(original string, replacement string)
- type NameSource
- type Option
- type ProgramCounter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RelFilename ¶
RelFilename returns the relative filename of a file.
func TrustedName ¶
TrustedName reports whether "name" is safe to use as a function identity: anything except a compiler-generated anonymous symbol. Names produced by the compiler for function literals (a trailing ".funcN" chain, "glob..funcN" package-level literals and "-fm" method-value wrappers) are NOT trusted, because since Go 1.27 two distinct literals may share the code pointer the name was derived from.
Types ¶
type Func ¶
type Func[T any] struct { Value T `json:"-"` // the function itself. Meta any `json:"meta"` // any custom meta data. FuncInfo // the function's information. }
Func is a structure that holds the function and its name.
func (*Func[T]) CopyFrom ¶
CopyFrom copies the information of the other Func to the current Func. It does not copy the function itself.
type FuncInfo ¶
type FuncInfo struct {
Name string `json:"name"` // function name.
File string `json:"file"` // file name.
FileRel string `json:"file_rel"` // relative file name.
Line int `json:"line"` // line number.
// ID is a process-wide unique registration id, assigned when the function
// enters a List. It is the primary identity of anonymous functions:
// their derived names cannot be trusted since Go 1.27, where distinct
// code-identical literals may share a code pointer (and therefore a
// runtime symbol, file and line).
ID uint64 `json:"-"`
// NameSource records how Name was produced; see the NameSource constants.
NameSource NameSource `json:"-"`
}
FuncInfo is a structure that holds the function's name, file and line number.
func NewFuncInfo ¶
func NewFuncInfo(ns *NameResolver, ptr uintptr) *FuncInfo
NewFuncInfo returns a new FuncInfo based on the function pointer.
func (*FuncInfo) CopyFrom ¶
CopyFrom copies the values of the other Func to the current FuncInfo. The copied Name becomes this FuncInfo's explicit (trusted) identity. The registration ID is inherited only when the source carries one, so copying display information from a cache-resolved FuncInfo does not erase the destination's own registration.
func (*FuncInfo) CopyTo ¶
CopyTo copies the values of the current FuncInfo to the other FuncInfo. See CopyFrom for the identity semantics.
func (*FuncInfo) Equal ¶
Equal compares two FuncInfo values for identity.
Two FuncInfos are equal when they carry the same registration ID, or when they share the same trusted Name. Compiler-derived anonymous names are never used as identity: since Go 1.27 two distinct code-identical literals may share a code pointer, so name/file/line equality no longer proves the functions are the same registration. A consequence: re-registering the same unnamed anonymous closure through Upsert appends instead of replacing; name it (WithFuncName or SetHandlerName) to get replace semantics back.
func (*FuncInfo) SetFilenameLine ¶
SetFilenameLine sets the filename and line number of the function.
func (*FuncInfo) SetNameFileAndLineByMethod ¶
SetNameFileAndLineByMethod sets the function name, filename and line number of the function by type and method name by using reflection.
func (*FuncInfo) TrustedFuncName ¶
TrustedFuncName reports whether this FuncInfo's Name is safe to use as the function's identity: it was set explicitly, matched a SetName mapping, or is a derived name of a named (non-anonymous) function.
type List ¶
type List[T any] struct { // contains filtered or unexported fields }
List can be used to manage a list of functions of any type.
func ConcatLists ¶
ConcatLists concatenates multiple lists into a single list.
func NewList ¶
func NewList[T any](pc *ProgramCounter[T], skipper func(T) bool, funcs ...T) *List[T]
NewList returns a new List of T type.
func (*List[T]) Append ¶
Append adds a new function at the end of the list. Insert event is fired. Returns itself.
func (*List[T]) AppendAfter ¶
AppendAfter adds a new function after another function identified by name.
func (*List[T]) AppendList ¶
AppendList appends the functions of the given list to the end of the list.
func (*List[T]) AppendSlice ¶
AppendSlice appends the given functions to the end of the list. Insert event is fired. Returns itself.
func (*List[T]) Delete ¶
Delete deletes a function from the list by name. Remove event is fired. Returns itself.
func (*List[T]) FuncDelete ¶
FuncDelete deletes a function from the list by the function itself.
func (*List[T]) FuncExists ¶
FuncExists checks if a function exists in the list by the function itself.
func (*List[T]) List ¶
List returns all the functions in the list. Any modifications to the returned slice will affect the list.
func (*List[T]) Lookup ¶
Lookup returns a function by name. If the function does not exist, the second return value is false.
func (*List[T]) Prepend ¶
Prepend adds a new function at the beginning of the list. Insert event is fired. Returns itself.
func (*List[T]) PrependBefore ¶
PrependBefore adds a new function before another function identified by name.
func (*List[T]) PrependList ¶
PrependList prepends the functions of the given list to the beginning of the list.
func (*List[T]) Replace ¶
Replace finds a function by name and replaces it. It does nothing if the function does not exist. No event is fired. Returns itself.
func (*List[T]) Reset ¶
func (l *List[T]) Reset()
Reset removes all functions and listeners from the list.
func (*List[T]) Set ¶
Set replaces the list of functions with the given functions. No event is fired.
func (*List[T]) SetIfEmpty ¶
SetIfEmpty replaces the list of functions with the given functions if the list is empty.
func (*List[T]) SubscribeAppendAfter ¶
SubscribeAppendAfter adds a new function after the "afterName" function. If the function with the same name is already registered, it will be added after it. If the function with the same name is not registered yet, it will be added after that when it will be registered.
func (*List[T]) SubscribePrependBefore ¶
SubscribePrependBefore adds a new function before the "beforeName" function. If the function with the same name is already registered, it will be added before it. If the function with the same name is not registered yet, it will be added before that when it will be registered.
func (*List[T]) UniqueValues ¶
func (l *List[T]) UniqueValues() []T
UniqueValues returns all the unique function values in the list.
Uniqueness follows the identity rules of FuncInfo.Equal: trusted names deduplicate by name, anonymous functions deduplicate by registration id only — two separate registrations of code-identical anonymous closures are both kept, they are not the same function.
func (*List[T]) Upsert ¶
Upsert inserts a new function if it doesn't exist, or replaces the existing one if it does. If not exist, insert event is fired. Returns itself.
func (*List[T]) UpsertSlice ¶
UpsertSlice inserts a new function if it doesn't exist, or replaces the existing one if it does. If not exist, insert event is fired. Returns itself.
type ListActionFunc ¶
ListActionFunc is a function type that can be used to use a function from a list.
type NameExpr ¶
type NameExpr struct {
// contains filtered or unexported fields
}
NameExpr regex or literal comparison through `MatchString`.
func (*NameExpr) MatchFilename ¶
MatchFilename reports whether "filename" contains the normalized form of the expression, that is the "literal" lower-cased and without the kataras or iris-contrib module prefix, the "/vN" version suffix and the ".*" part. The given filename is expected to be already lower-cased, see GetCustomName.
func (*NameExpr) MatchString ¶
MatchString reports whether "s" is equal to the "literal" or it matches the regex expression at "regex".
type NameResolver ¶
type NameResolver struct {
// contains filtered or unexported fields
}
NameResolver is a type that can be used to register custom names for functions.
func NewNameResolver ¶
func NewNameResolver() *NameResolver
NewNameResolver returns a new NameResolver.
func (*NameResolver) GetCustomName ¶
func (ns *NameResolver) GetCustomName(funcName, filename string) string
GetCustomName returns the custom name of a function or/and filename.
func (*NameResolver) GetCustomNameMatched ¶
func (ns *NameResolver) GetCustomNameMatched(funcName, filename string) (string, bool)
GetCustomNameMatched returns the custom name of a function or/and filename and reports whether a registered SetName mapping matched. A matched name is trusted as the function's identity (see FuncInfo.TrustedFuncName).
func (*NameResolver) GetName ¶
func (ns *NameResolver) GetName(fn any) string
GetName returns the custom name of a function.
func (*NameResolver) GetNameAndFileAndLine ¶
func (ns *NameResolver) GetNameAndFileAndLine(fn any) (name, file string, line int)
GetNameAndFileAndLine returns the custom name of a function and the file and line of that function.
func (*NameResolver) SetName ¶
func (ns *NameResolver) SetName(original string, replacement string)
SetName registers a custom name for a function. The "replacement" should be the custom, human-text of that function name.
If the name starts with "iris" then it replaces that string with the full Iris module package name.
The "original" pattern must be a valid regular expression (a plain function name is a valid regexp as long as it carries no metacharacters like "(*Type)"; escape those). An invalid pattern panics: every SetName call is an init-time constant, and a swallowed compile error used to silently degrade the pattern to an exact-literal match.
type NameSource ¶
type NameSource uint8
NameSource records how a FuncInfo's Name was produced. It exists because, since Go 1.27, two distinct function literals with identical code may share a single code pointer — so a name derived from the program counter is not a safe identity for anonymous functions anymore. Explicitly assigned and resolver-matched names remain safe: they are chosen by a human, not by the compiler's symbol generator.
const ( // NameDerived means the Name came straight from the runtime symbol of the // function's program counter, e.g. "mypackage.MyHandler" or // "mypackage.New.func1". NameDerived NameSource = iota // NameResolved means a SetName (iris.SetHandlerName) mapping matched and // replaced the derived name with a friendly one, e.g. "iris.recover". NameResolved // NameExplicit means the Name was assigned directly through WithFuncName, // FuncInfo.CopyFrom/CopyTo or SetNameFileAndLineByMethod. NameExplicit )
type Option ¶
func WithFuncName ¶
WithFuncName sets the name of the function. A name set this way is trusted as the function's identity (see FuncInfo.Equal), unlike compiler-derived anonymous names.
type ProgramCounter ¶
type ProgramCounter[T any] struct { // contains filtered or unexported fields }
ProgramCounter is a type that can be used to resolve the name and location of a function.
The cache below is keyed by the function's code pointer and is DISPLAY-ONLY: since Go 1.27 two distinct code-identical function literals may share a code pointer, so entries may be shared between genuinely different functions. Identity never flows from this cache — it comes from the registration id assigned when a function enters a List (see FuncInfo.Equal).
func NewProgramCounter ¶
func NewProgramCounter[T any](resolver *NameResolver) *ProgramCounter[T]
NewProgramCounter returns a new ProgramCounter.
func (*ProgramCounter[T]) GetName ¶
func (pc *ProgramCounter[T]) GetName(h any) string
GetName returns the custom name of a function. It caches the result for future calls.
func (*ProgramCounter[T]) Resolve ¶
func (pc *ProgramCounter[T]) Resolve(h T) *Func[T]
Resolve returns the custom name and the location of a function.