funcer

package
v14.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: BSD-3-Clause Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RelFilename

func RelFilename(filename string) string

RelFilename returns the relative filename of a file.

func TrustedName

func TrustedName(name string) bool

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]) Clone

func (f *Func[T]) Clone() *Func[T]

Clone returns a new copy of the Func.

func (*Func[T]) CopyFrom

func (f *Func[T]) CopyFrom(other *Func[T])

CopyFrom copies the information of the other Func to the current Func. It does not copy the function itself.

func (*Func[T]) CopyTo

func (f *Func[T]) CopyTo(other *Func[T])

CopyTo copies the information of the current Func to the other Func. It does not copy the function itself.

func (*Func[T]) Equal

func (f *Func[T]) Equal(other *Func[T]) bool

Equal compares two FuncInfo values for equality.

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) Clone

func (f *FuncInfo) Clone() FuncInfo

Clone returns a new copy of the FuncInfo.

func (*FuncInfo) CopyFrom

func (f *FuncInfo) CopyFrom(other FuncInfo)

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

func (f *FuncInfo) CopyTo(other *FuncInfo)

CopyTo copies the values of the current FuncInfo to the other FuncInfo. See CopyFrom for the identity semantics.

func (*FuncInfo) Equal

func (f *FuncInfo) Equal(other FuncInfo) bool

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

func (f *FuncInfo) SetFilenameLine(filename string, line int)

SetFilenameLine sets the filename and line number of the function.

func (*FuncInfo) SetNameFileAndLineByMethod

func (f *FuncInfo) SetNameFileAndLineByMethod(typ reflect.Type, methodName string)

SetNameFileAndLineByMethod sets the function name, filename and line number of the function by type and method name by using reflection.

func (*FuncInfo) String

func (f *FuncInfo) String() string

String returns a string representation of the FuncInfo.

func (*FuncInfo) TrustedFuncName

func (f *FuncInfo) TrustedFuncName() bool

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

func ConcatLists[T any](lists ...*List[T]) *List[T]

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

func (l *List[T]) Append(fn T, opts ...Option[T]) *List[T]

Append adds a new function at the end of the list. Insert event is fired. Returns itself.

func (*List[T]) AppendAfter

func (l *List[T]) AppendAfter(newFunction T, afterName string, opts ...Option[T]) bool

AppendAfter adds a new function after another function identified by name.

func (*List[T]) AppendList

func (l *List[T]) AppendList(list *List[T]) *List[T]

AppendList appends the functions of the given list to the end of the list.

func (*List[T]) AppendSlice

func (l *List[T]) AppendSlice(fns []T, opts ...Option[T]) *List[T]

AppendSlice appends the given functions to the end of the list. Insert event is fired. Returns itself.

func (*List[T]) Clone

func (l *List[T]) Clone() *List[T]

Clone returns a deep copy of the list.

func (*List[T]) Count

func (l *List[T]) Count() int

Count returns the number of functions in the list.

func (*List[T]) Delete

func (l *List[T]) Delete(name string) *List[T]

Delete deletes a function from the list by name. Remove event is fired. Returns itself.

func (*List[T]) Exists

func (l *List[T]) Exists(name string) bool

Exists checks if a function exists in the list by name.

func (*List[T]) First

func (l *List[T]) First() *Func[T]

First returns the first function in the list.

func (*List[T]) FuncDelete

func (l *List[T]) FuncDelete(fn T) *List[T]

FuncDelete deletes a function from the list by the function itself.

func (*List[T]) FuncExists

func (l *List[T]) FuncExists(fn T) bool

FuncExists checks if a function exists in the list by the function itself.

func (*List[T]) FuncName

func (l *List[T]) FuncName(fn T) string

FuncName returns the name of the function in the list.

func (*List[T]) Last

func (l *List[T]) Last() *Func[T]

Last returns the last function in the list.

func (*List[T]) List

func (l *List[T]) List() []*Func[T]

List returns all the functions in the list. Any modifications to the returned slice will affect the list.

func (*List[T]) Lookup

func (l *List[T]) Lookup(name string) (*Func[T], bool)

Lookup returns a function by name. If the function does not exist, the second return value is false.

func (*List[T]) Prepend

func (l *List[T]) Prepend(fn T, opts ...Option[T]) *List[T]

Prepend adds a new function at the beginning of the list. Insert event is fired. Returns itself.

func (*List[T]) PrependBefore

func (l *List[T]) PrependBefore(newFunction T, beforeName string, opts ...Option[T]) bool

PrependBefore adds a new function before another function identified by name.

func (*List[T]) PrependList

func (l *List[T]) PrependList(list *List[T]) *List[T]

PrependList prepends the functions of the given list to the beginning of the list.

func (*List[T]) Replace

func (l *List[T]) Replace(fn T) *List[T]

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

func (l *List[T]) Set(fns ...T) *List[T]

Set replaces the list of functions with the given functions. No event is fired.

func (*List[T]) SetIfEmpty

func (l *List[T]) SetIfEmpty(fns ...T) *List[T]

SetIfEmpty replaces the list of functions with the given functions if the list is empty.

func (*List[T]) SubscribeAppendAfter

func (l *List[T]) SubscribeAppendAfter(fn T, afterName string, opts ...Option[T])

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

func (l *List[T]) SubscribePrependBefore(fn T, beforeName string, opts ...Option[T])

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

func (l *List[T]) Upsert(fn T, opts ...Option[T]) *List[T]

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

func (l *List[T]) UpsertSlice(fns []T, opts ...Option[T]) *List[T]

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.

func (*List[T]) Values

func (l *List[T]) Values() []T

Values returns all the function values in the list.

func (*List[T]) Walk

func (l *List[T]) Walk(fn func(*Func[T]) bool) bool

Walk calls the given function for each function in the list. If the function returns false, the iteration stops.

type ListActionFunc

type ListActionFunc[T any] func(T, ...Option[T]) *List[T]

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

func (expr *NameExpr) MatchFilename(filename string) bool

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

func (expr *NameExpr) MatchString(s string) bool

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

type Option[T any] func(*Func[T])

func WithFuncName

func WithFuncName[T any](name string) Option[T]

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL