Documentation
¶
Overview ¶
Package language defines Orchard's HCL function registry — the single source of truth for every function available in scenario expressions. Each entry carries the implementation (a cty function.Function) alongside structured metadata: description, parameter signatures, return type, examples, and purity.
Multiple consumers read this registry:
- parser.Functions() builds the map[string]function.Function the engine evaluates expressions against.
- The docs generator (orchard docs functions, just docs-generate) renders the function reference page from the metadata.
- A future LSP server will serve completions and hover docs directly from the same metadata.
- orchard functions --json exports the registry as a JSON manifest for editor grammars and external tooling.
To add a function: append a FunctionDef to the registry slice in registry_*.go. The implementation and documentation live together so neither drifts.
Index ¶
- func Categories() []string
- func CustomFunc(name string) function.Function
- func Map() map[string]function.Function
- func RandomFuncs(r *Rand) map[string]function.Function
- func RandomSeed() uint64
- func Scoped(parent *hcl.EvalContext, seed uint64, scope string) *hcl.EvalContext
- type ExampleDef
- type FakeKind
- type FunctionDef
- type ParamDef
- type Rand
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Categories ¶
func Categories() []string
Categories returns the distinct category names in sorted order.
func CustomFunc ¶
CustomFunc returns a custom function implementation by name. Used by internal/language to reference individual implementations without importing the entire function map.
func Map ¶
Map builds the function.Function map the parser/engine use as an EvalContext.Functions value. This is the bridge between the metadata-rich registry and the engine's bare function dispatch.
func RandomFuncs ¶
RandomFuncs returns the random functions bound to r.
func RandomSeed ¶
func RandomSeed() uint64
RandomSeed returns a fresh seed for runs that don't set one.
func Scoped ¶
func Scoped(parent *hcl.EvalContext, seed uint64, scope string) *hcl.EvalContext
Scoped returns a child of parent whose random functions draw from the stream for scope. Every expression evaluation in a run goes through here so its random values follow the run's seed.
Types ¶
type ExampleDef ¶
ExampleDef is a worked usage snippet.
type FunctionDef ¶
type FunctionDef struct {
// Name is the function name as scenario authors write it:
// "jsonencode", "timesub", "uuid", etc. Lowercase compound
// words, no separators.
Name string `json:"name"`
// Category groups functions in docs and completion menus.
// Conventional values: "strings", "collections", "encoding",
// "math", "regex", "time", "identity", "environment", "sets".
Category string `json:"category"`
// Description is a one-liner shown in completion menus and
// at the top of a docs entry.
Description string `json:"description"`
// Detail is the full documentation for hover popups and the
// reference page. Markdown.
Detail string `json:"detail,omitempty"`
// Params lists the positional parameters in order.
Params []ParamDef `json:"params"`
// VarParam describes the variadic trailing parameter, if any.
// nil when the function takes a fixed number of args.
VarParam *ParamDef `json:"var_param,omitempty"`
// ReturnType is a human-readable type string for display:
// "string", "number", "list(string)", etc.
ReturnType string `json:"return_type"`
// Pure is true when the function is deterministic — same
// inputs always produce the same output. False for uuid, env,
// now, timerandom, timesequence (randomised intervals).
Pure bool `json:"pure"`
// Examples are short usage snippets. Each has a Code string
// (the expression) and an optional Result (what it produces).
Examples []ExampleDef `json:"examples,omitempty"`
// Func is the cty function implementation. Omitted from JSON
// serialisation — tooling that imports this package calls it
// directly; external consumers (grammars, docs) only need the
// metadata.
Func function.Function `json:"-"`
// Random builds the implementation of a function that draws
// random values, bound to one stream. Set it instead of Func;
// register fills Func from an unseeded stream, and Scoped binds
// a run's seeded one.
Random func(r *Rand) function.Function `json:"-"`
}
FunctionDef is one function in the registry. It bundles the cty implementation with the metadata tooling needs.
func ByCategory ¶
func ByCategory(category string) []FunctionDef
ByCategory returns all functions in the given category, sorted by name.
func ByName ¶
func ByName(name string) (FunctionDef, bool)
ByName returns the function with the given name, or false.
type ParamDef ¶
type ParamDef struct {
Name string `json:"name"`
Type string `json:"type"`
Description string `json:"description,omitempty"`
}
ParamDef describes one parameter.
type Rand ¶
Rand is the random source behind the random functions (uuid, rand*, fake, the id generators, timerandom, timesequence).
A run has one seed. Each evaluation scope — one attribute of one action, one variable default, one provider config attribute — draws from its own stream, derived from the seed and the scope's name. So a scope's values don't depend on which other scopes ran first (parallel runs, map iteration order) or whether other nodes were added or removed, and plan and run see the same values for the same seed.
Source Files