Documentation
¶
Overview ¶
Package examples provides access to embedded scafctl example files.
Examples are embedded at build time via go:embed, making them available in distributed binaries without filesystem access to the source repo.
For development, examples are also looked up from the filesystem as a fallback when the embedded filesystem is empty or when the examples weren't copied at build time.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var EmbeddedExamples embed.FS
var ErrAmbiguousExample = errors.New("ambiguous example query")
ErrAmbiguousExample is returned when a lookup query matches more than one example. It is a sentinel error: ResolveExample wraps it with the candidate paths in the error string (e.g. `...: "hello-world" matches a.yaml, b.yaml`), so callers detect it with errors.Is and can surface the message to the user.
var ErrExampleNotFound = errors.New("example not found")
ErrExampleNotFound is returned when a lookup query matches no example.
var ErrPathTraversal = errors.New("example path must be relative and must not contain '..'")
ErrPathTraversal is returned when an example lookup path is unsafe: it either contains a ".." traversal component or is an absolute/UNC/drive-letter path. Example paths are always relative (e.g. "resolvers/hello-world.yaml").
Functions ¶
func Categories ¶
func Categories() []string
Categories returns the list of available example categories.
func ResolveExample ¶ added in v0.40.0
ResolveExample resolves a query to a single example path. It is a thin wrapper over MatchExamples for callers requiring exactly one result: when the query matches more than one example, ErrAmbiguousExample is returned wrapped with the candidate paths.
Types ¶
type Example ¶
type Example struct {
// DisplayName is the human-friendly name from metadata.displayName.
// Falls back to metadata.name when unset.
DisplayName string `json:"displayName,omitempty" yaml:"displayName,omitempty"`
// Name is the solution's metadata.name (its stable identifier).
Name string `json:"name" yaml:"name"`
// Category is metadata.category (falls back to the top-level directory).
Category string `json:"category,omitempty" yaml:"category,omitempty"`
// Tags are metadata.tags.
Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`
// Description is metadata.description (first line, trimmed).
Description string `json:"description,omitempty" yaml:"description,omitempty"`
// Path is the embedded-FS path used as the unambiguous fetch handle for
// `get examples <path>` (metadata.name is not unique across examples).
Path string `json:"path" yaml:"path"`
// Content is the full example file content. It powers the interactive (-i)
// detail view so a user can read the solution without leaving the browser.
// Omitted from the default table (see the command's column hints).
Content string `json:"content,omitempty" yaml:"content,omitempty"`
}
Example represents a runnable example solution in the listing. Fields are sourced from the solution's own metadata block (not the filename), so the listing reflects what the author declared.
func MatchExamples ¶ added in v0.40.0
MatchExamples resolves a user-supplied query to the example(s) it identifies. The query may be an exact embedded path, a metadata.name, or a file basename. It returns:
- exactly one Example when the query names a single example (by exact path, or a unique name/basename),
- more than one Example when a name/basename matches several (the caller should present them as a list to choose from),
- ErrExampleNotFound when nothing matches,
- ErrPathTraversal when the query is an unsafe path.
Exact-path matches also resolve non-solution embedded files (e.g. kind: Config) that the solution-only listing excludes; those are returned as a single Example carrying just the Path.
func Scan ¶
Scan walks the examples filesystem and returns matching example solutions. Only kind: Solution files are returned; non-solution YAML (configs, partials, templates) is skipped. If category is non-empty, only examples in that category are returned. Metadata is read from each solution's own metadata block.
Source Files