functy

type Assign struct {
	Name     string
	Expr     hcl.Expression
	SrcRange hcl.Range
}

type Block struct {
	Body     []Statement
	SrcRange hcl.Range
}

type Break struct {
	Label    string // "" for the innermost loop
	SrcRange hcl.Range
}

type CaptureAssign struct {
	ValName  string // "_" to discard the value
	ErrName  string // "_" to discard the error
	Declare  bool   // true for the `:=` declare-and-capture form
	Expr     hcl.Expression
	ValRange hcl.Range // the value target, for diagnostics
	ErrRange hcl.Range // the error target, for diagnostics
	SrcRange hcl.Range
}

type CatchClause struct {
	Name      string         // "" when omitted
	Type      TypeConstraint // nil = no type filter
	TypeSrc   string         // source text of the type filter, for rendering (fmt)
	Guard     hcl.Expression // nil = no guard
	Body      []Statement
	BodyRange hcl.Range // the `{ ... }` body span, for fmt
	SrcRange  hcl.Range
}

type Clause struct {
	Values    []hcl.Expression
	IsDefault bool
	Body      []Statement
	SrcRange  hcl.Range
}

type Comment struct {
	// Text is the comment's source text with any trailing CR/LF trimmed. It keeps
	// the leading marker (`//`, `#`, or `/*` … `*/`).
	Text string
	// Line is true for a `//` or `#` single-line comment, false for a `/* */`
	// block comment.
	Line bool
	// Range is the comment's full source span. For a line comment it includes the
	// terminating newline (as HCL's lexer reports it).
	Range hcl.Range
}

type Compiled struct {
	// Funcs is the map for the host's eval context. It holds only the *exported*
	// functions — private (`_`-prefixed) ones are absent — keyed by their
	// *qualified* name (`foo::bar::baz`, or the bare name in the global
	// namespace).
	Funcs map[string]function.Function

	// Units maps a namespace ("" = global) to that namespace's own functions by
	// their *bare* names, private ones included. This mirrors the layer a
	// namespace's functions resolve their siblings through, and it is what makes a
	// private function callable from inside its namespace while remaining invisible
	// to the host. Exposed because tooling needs it: to reach a private function by
	// name (`functy run --func _helper`), and to detect a bare name that shadows a
	// host function (see the note on unitCtxFn).
	//
	// It is a *snapshot*, not the live table the compiled functions read: those are
	// consulted on every call, from whatever goroutine is calling, so handing the
	// same maps out would let a host's write race a running function.
	Units map[string]map[string]function.Function

	// Vars maps a namespace ("" = global) to that namespace's variable scope: the
	// map a namespace's function bodies resolve a bare variable name against,
	// symmetric to Units for functions (a body in namespace ns calls Units[ns] and
	// reads Vars[ns]). A bare name a body does not resolve locally falls through
	// here, and if still absent, on to the host's own Variables.
	//
	// functy hands this back EMPTY and puts nothing in it: it takes no position on
	// what a const or var means, so it neither evaluates declarations nor buckets
	// them by namespace. The host FILLS it — writing a scope under Vars[ns] for any
	// namespace it likes, by any policy (e.g. evaluate the namespace's Decls with
	// EvalDecls, or use EvalNamespacedDecls for the own+global convention) — before
	// any function is invoked. Each namespace's bodies look their scope up in this
	// same map by name at call time, so there is no per-namespace pre-registration
	// and no distinction between a namespace that has functions and one that has only
	// consts: whatever the host writes under Vars[ns] is what ns's bodies read.
	// Leaving it empty preserves the pre-namespaced behavior (bare names resolve only
	// against host globals).
	Vars map[string]map[string]cty.Value
}

type CondBranch struct {
	Condition hcl.Expression
	Body      []Statement
	BodyRange hcl.Range // the `{ ... }` body span, for fmt
	SrcRange  hcl.Range
}

type Continue struct {
	Label    string // "" for the innermost loop
	SrcRange hcl.Range
}

type Decl struct {
	Name string
	// Namespace is the enclosing namespace of the file the declaration appeared
	// in ("" = global). functy attaches it and takes no further position: a global
	// is whatever the host decides it is, so the host may ignore namespaced
	// globals, reject them, or implement them by a mechanism of its own.
	//
	// Note there is no qualified *spelling* for a global: HCL's `::` is a
	// function-call selector, so `foo::bar::x` as a variable reference is a parse
	// error. Namespacing therefore applies to functions; this field is metadata.
	Namespace string
	// Doc is the rendered leading doc-comment block (`//` or `#` lines directly
	// above the declaration, directive lines excluded); "" when there is none.
	Doc      string
	Type     TypeConstraint // from an optional `: T`; nil if unannotated
	TypeSrc  string         // source text of the type annotation, for rendering (fmt)
	Expr     hcl.Expression // initializer, lazily evaluated (nil if none)
	DefRange hcl.Range
}

type Defer struct {
	Expr     hcl.Expression
	SrcRange hcl.Range
}

type Directive struct {
	Namespace string
	Name      string
	Args      string
	Range     hcl.Range
}

type ExprStmt struct {
	Expr     hcl.Expression
	SrcRange hcl.Range
}

type Fallthrough struct{ SrcRange hcl.Range }

type For struct {
	Kind ForKind

	// Label is the loop's label ("" if unlabeled); a labeled break/continue whose
	// target equals this label is consumed by this loop rather than an inner one.
	Label string

	// While is true when a ForCond loop was written with the `while` keyword rather
	// than `for` (the two are synonyms); recorded so fmt can preserve the keyword.
	While bool

	// ForCond / ForClause:
	Init Statement      // ForClause init clause (nil otherwise)
	Cond hcl.Expression // condition (nil = always true)
	Post Statement      // ForClause post clause (nil otherwise)

	// ForRange:
	KeyName    string         // first range variable ("" if absent)
	ValName    string         // second range variable ("" if only one is given)
	Collection hcl.Expression // collection being ranged over

	Body      []Statement
	BodyRange hcl.Range // the `{ ... }` body span, for fmt
	SrcRange  hcl.Range
}

type ForKind int

type FuncDecl struct {
	Name string
	// Namespace is the enclosing namespace, from the file's `namespace a::b`
	// declaration; "" is the global namespace. See NamespaceDecl.
	Namespace string
	// Doc is the rendered leading doc-comment block (`//` or `#` lines directly
	// above the declaration, directive lines excluded); "" when there is none.
	Doc        string
	Params     []Param
	ParenRange hcl.Range      // the (…) parameter-list span, for fmt
	RetType    TypeConstraint // nil when no return type is annotated (dynamic)
	RetTypeSrc string         // source text of the return-type annotation, for rendering (fmt)
	SigRange   hcl.Range      // spans `func` … the last signature token (`)` or the return type)
	// Extern marks a declaration from a //functy:extern file: a signature only,
	// never compiled and never callable. See Result.Externs.
	Extern    bool
	Body      []Statement
	BodyRange hcl.Range // the `{ ... }` body span, for rendering (fmt); zero for an extern
	DefRange  hcl.Range
}

type IfChain struct {
	Branches  []CondBranch
	Else      []Statement
	ElseRange hcl.Range // the `else { ... }` body span (zero when there is no else), for fmt
	SrcRange  hcl.Range
}

type LimitError struct {
	// Steps is the step count at the moment the limit tripped; Limit is the ceiling.
	Steps, Limit int
	// Range is the source location of the checkpoint that tripped (a loop or the
	// statement being executed), used to underline the breach in diagnostics.
	Range hcl.Range
}

type NamespaceDecl struct {
	Name     string    // "foo" or "foo::bar"
	DefRange hcl.Range // spans `namespace` … the last segment
}

type Param struct {
	Name string
	// Doc is the parameter's documentation: a trailing comment on its line
	// (`a: T, // desc`) or a leading `//` / `#` block directly above it (which
	// wins if both are present); "" when there is none. See attachDocComments.
	Doc        string
	Type       TypeConstraint // nil when unannotated (dynamic)
	TypeSrc    string         // source text of the type annotation, for rendering (fmt)
	Default    hcl.Expression // non-nil for a defaulted parameter
	DefaultSrc string         // source text of the default expression, for rendering (help()/fmt)
	// Optional marks `name?`: optional with *no* default, and mutually exclusive
	// with Default. It exists because it is the only way to spell an optional
	// *leading* parameter — the `get([ctx,] thing)` convention that host libraries
	// implement by sniffing args[0], and that cty's parameter list cannot express
	// (an optional cty param may only sit at the tail).
	//
	// Legal only in an extern file, where it is never compiled: BuildFunction
	// classifies a param with no Default as *required*, so an Optional param
	// reaching it would be silently mis-compiled. The compile path guards on
	// FuncDecl.Extern to keep that unreachable.
	Optional  bool
	Variadic  bool // true for the trailing *rest parameter
	DefRange  hcl.Range
	FullRange hcl.Range // spans the whole parameter (name … type/default), for fmt
}

type Parser struct {
	// contains filtered or unexported fields
}

type Result struct {
	Funcs  []*FuncDecl // parsed function declarations
	Tests  []*TestDecl // parsed test blocks (not registered as callable functions)
	Consts []Decl      // top-level const declarations (only when enabled)
	Vars   []Decl      // top-level var declarations (only when enabled)
	Types  []TypeAlias // top-level type aliases (namespace-scoped; see TypeAlias)

	// Externs are the bodiless declarations from //functy:extern sources, in source
	// order. They declare the signatures of functions the *host* provides, so they
	// are never compiled and never callable — Compile and CompileUnits ignore them
	// entirely. They exist so help(), `functy symbols`, and editor tooling can show
	// a host function's real signature, which its cty metadata cannot express: a cty
	// function fakes optional and defaulted arguments with a trailing VarParam, which
	// erases their names, their defaults, and (for the `f([ctx,] x)` convention) the
	// leading parameter itself.
	//
	// A slice, not a map, and deliberately: two declarations of one name is exactly
	// an overload set, so supporting overloads later is a relaxation of
	// checkExternNames rather than a change to this type.
	Externs []*FuncDecl

	// HostExterns are the externs the *host* registered with Parser.RegisterExterns,
	// as opposed to those declared by the parsed sources (Externs). They describe the
	// host's own functions, so they belong to no source file here.
	//
	// The split is what makes fmt safe, and is why this is a separate field rather
	// than a flag: a tool that renders *a source* — fmt, symbols, an outline — must
	// iterate Externs and ignore HostExterns, and gets that by default, because it
	// cannot reach this field without naming it. Merging the two would let `fmt` on a
	// user's file emit another package's declarations into it.
	//
	// Reflection (help()) reads both.
	HostExterns []*FuncDecl

	// Namespaces holds the `namespace a::b` declaration of each namespaced source
	// parsed together, in parse order (a source without one is in the global
	// namespace and contributes nothing here). The namespace a given declaration
	// belongs to is on the declaration itself (FuncDecl.Namespace and friends);
	// this slice exists so tooling that renders or lists the source — notably fmt,
	// which emits from the AST — can see the declaration itself.
	Namespaces []NamespaceDecl

	// Comments is every comment from every source parsed together, in source
	// order, retained with position. Declaration doc comments are also surfaced on
	// FuncDecl.Doc / Decl.Doc; this is the complete table for tooling that needs
	// all comments (e.g. a formatter).
	Comments []Comment

	// Directives are the directive comments from each source's leading comment
	// block (file-scope), across all sources. functy acts on its own `functy:`
	// namespace; others are passed through for the host.
	Directives []Directive
	// contains filtered or unexported fields
}

type Return struct {
	Expr     hcl.Expression
	SrcRange hcl.Range
}

type Scope struct {
	// contains filtered or unexported fields
}

type Signal struct {
	Kind  SignalKind
	Value cty.Value // meaningful only for SignalReturn
	Label string    // target loop label for SignalBreak / SignalContinue ("" = innermost)
}

type SignalKind int

type SkipError struct{ Reason string }

type Source struct {
	Filename string
	Bytes    []byte
}

type Statement interface {
	// contains filtered or unexported methods
}

type Switch struct {
	Subject   hcl.Expression
	Clauses   []Clause
	BodyRange hcl.Range // the `{ ... }` body span (open brace to close brace), for fmt
	SrcRange  hcl.Range
}

type TestDecl struct {
	Name      string      // the test description (a string literal)
	Namespace string      // the namespace of the file the test was declared in ("" = global)
	Body      []Statement // body statements, like a function body
	BodyRange hcl.Range   // the `{ ... }` body span, for rendering (fmt)
	DefRange  hcl.Range   // spans `test` … closing `}`
}

type TestOutcome struct {
	Name       string        // the test's description
	DefRange   hcl.Range     // the test block's source location
	Duration   time.Duration // wall-clock time to run the body
	Err        error         // nil if the test passed; the skip or failure otherwise
	Skipped    bool          // true if Err is a skip (not a failure)
	SkipReason string        // the reason passed to skip(), if any
}

type Throw struct {
	Expr     hcl.Expression
	SrcRange hcl.Range
}

type ThrownError struct{ Value cty.Value }

type Try struct {
	Body         []Statement
	BodyRange    hcl.Range // the `try { ... }` body span, for fmt
	Catches      []CatchClause
	Finally      []Statement
	FinallyRange hcl.Range // the `finally { ... }` body span (zero when absent), for fmt
	SrcRange     hcl.Range
}

type TypeAlias struct {
	Name string
	// Namespace is the enclosing namespace of the file the alias appeared in
	// ("" = global). It scopes name resolution (own-then-global) and lets a
	// consumer project an alias under the right namespace surface.
	Namespace string
	Type      TypeConstraint
	TypeSrc   string // source text of the aliased type (right-hand side), for rendering (fmt)
	DefRange  hcl.Range
}

type TypeConstraint interface {
	// Coerce applies the constraint to a value, returning the value to store or
	// an error if it does not satisfy the constraint.
	Coerce(cty.Value) (cty.Value, error)
	// Cty returns the underlying cty.Type (dynamic for `any`, void, and open
	// predicate types).
	Cty() cty.Type
	String() string
}

type TypeResolver struct {
	// contains filtered or unexported fields
}

type VarDecl struct {
	Name     string
	Type     TypeConstraint // nil when unannotated (dynamic)
	TypeSrc  string         // source text of the type annotation, for rendering (fmt)
	Init     hcl.Expression
	Short    bool // declared with the `:=` shorthand (always untyped); preserved for fmt
	SrcRange hcl.Range
}