funcfind

Documentation

Overview

Package funcfind provides static analysis tools for discovering Go functions by their return types.

Overview

FuncFind uses Go's type system and the golang.org/x/tools/go/packages library to analyze Go packages and find functions that return specific types. This is particularly useful for static analysis tools, code generators, and developer utilities that need to understand the structure of Go codebases.

Key Features

• Type-based function discovery using string matching
• Lazy evaluation through Go 1.23+ iterators
• Support for any accessible Go package
• Memory-efficient processing of large codebases
• Early termination support for performance

Usage Patterns

The primary function is Returning, which takes a package path and a return type string:

functions, err := funcfind.Returning("fmt", "error")
if err != nil {
	return err
}

for fn := range functions {
	fmt.Printf("Function %s returns error\n", fn.Name())
}

Type Matching

Function signatures are matched by comparing the string representation of their return types. Only functions with exactly one return value are considered. For example:

• func() error ✓ matches "error"
• func() (error, bool) ✗ multiple returns
• func() ✗ no returns
• func() string ✗ different type

Performance Considerations

The iterator pattern allows for efficient memory usage and early termination:

// Stop after finding the first match
for fn := range functions {
	if fn.Name() == "target" {
		break // Iterator stops here
	}
}

Limitations

• Only exported functions are found in external packages
• Package must be accessible and compilable
• Type matching is exact string comparison
• No support for interface satisfaction matching

Error Handling

Errors are returned when:

• Package cannot be loaded (e.g., doesn't exist, compilation errors)
• Package path is malformed
• Module resolution fails

All errors are wrapped with context to aid debugging.

Package funcfind provides utilities for discovering Go functions by their return types. It uses static analysis to find functions that return specific types without requiring code compilation or execution.

The primary use case is for static analysis tools that need to discover functions with particular return type signatures across Go packages.

Example usage:

functions, err := funcfind.Returning("fmt", "error")
if err != nil {
	panic(err)
}

for fn := range functions {
	fmt.Printf("Function %s returns error\n", fn.Name())
}

Index

• func Returning(pkgPath string, returnType string) (iter.Seq[*types.Func], error)

Functions

func Returning

func Returning(pkgPath string, returnType string) (iter.Seq[*types.Func], error)

Returning finds all functions in the specified Go package that return exactly one value of the provided returnType.

The pkgPath parameter should be a valid Go package path (e.g., "fmt", "encoding/json", "github.com/user/repo/pkg"). The returnType parameter should be the string representation of the desired return type (e.g., "error", "string", "github.com/user/repo.CustomType").

Returns an iterator over all matching functions, allowing for lazy evaluation and early termination. If package loading fails, returns a non-nil error.

Only functions with exactly one return value are considered. Functions with zero return values or multiple return values are excluded from results.

Example:

// Find all functions in fmt package that return error
functions, err := Returning("fmt", "error")
if err != nil {
	return err
}

for fn := range functions {
	fmt.Printf("Found: %s\n", fn.Name())
}