scriggo

type BatchRun struct {
	Out     io.Writer
	Vars    map[string]any
	Options *RunOptions
	Before  func() error
	After   func()
}

type BatchRunError struct {
	Index int
	Err   error
}

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

type BuildOptions struct {

	// AllowGoStmt, when true, allows the use of the go statement.
	AllowGoStmt bool

	// Packages is a package importer that makes native packages available
	// in programs and templates through the import statement.
	Packages native.Importer

	// UnexpandedTransformer transforms an unexpanded AST.
	// If non-nil, it is invoked on each parsed file before expansion.
	//
	// Used for templates only.
	UnexpandedTransformer func(tree *ast.Tree) error

	// ExpandedTransformer transforms the expanded AST.
	// If non-nil, it is invoked on the expanded tree before type checking.
	//
	// Used for templates only.
	ExpandedTransformer func(tree *ast.Tree) error

	// NoParseShortShowStmt, when true, don't parse the short show statements.
	//
	// Used for templates only.
	NoParseShortShowStmt bool

	// MarkdownConverter converts a Markdown source code to HTML.
	//
	// Used for templates only.
	MarkdownConverter Converter

	// Globals declares constants, types, variables, functions and packages
	// that are accessible from the code in the template.
	//
	// Used for templates only.
	Globals native.Declarations

	// EnableProfiling enables profiling instrumentation in the compiled template.
	// When true, the runtime will collect timing data for function calls,
	// macros, and includes during execution.
	//
	// Used for templates only.
	EnableProfiling bool

	// IsolateRootRenderState makes each render expression in the root template
	// reinitialize package variables reachable through the rendered file.
	// Nested renders share the state of their enclosing root render.
	//
	// Used for templates only.
	IsolateRootRenderState bool
}

type CallKind int

type CallNode struct {
	// Call is the call record for this node (nil for the root node).
	Call *CallRecord
	// Children are the child calls.
	Children []*CallNode
}

type CallRecord struct {
	// ID is a unique identifier for this call.
	ID uint64
	// ParentID links to the parent call (0 for root calls).
	ParentID uint64

	// Name is the function or macro name.
	Name string
	// Package is the package path (empty for macros).
	Package string
	// File is the source file path.
	File string
	// Line is the source line number.
	Line int

	// Kind indicates the type of call.
	Kind CallKind

	// StartTime is when the call began.
	StartTime time.Time
	// Duration is how long the call took.
	Duration time.Duration
	// SelfDuration excludes time spent in child calls.
	SelfDuration time.Duration

	// TemplatePath is the template path for include calls.
	TemplatePath string
}

type Converter func(src []byte, out io.Writer) error

type ExitError struct {
	Code int
	Err  error
}

type Files map[string][]byte

type Format int

type FormatFS interface {
	fs.FS
	Format(name string) (Format, error)
}

type FunctionStats struct {
	// Name is the function or macro name.
	Name string
	// Package is the package path (empty for macros).
	Package string
	// CallCount is the number of times this function was called.
	CallCount int
	// TotalTime is the sum of all call durations.
	TotalTime time.Duration
	// SelfTime is the sum of all self durations.
	SelfTime time.Duration
	// MinTime is the minimum call duration.
	MinTime time.Duration
	// MaxTime is the maximum call duration.
	MaxTime time.Duration
}

type Mutation = runtime.Mutation

type MutationOperation = runtime.MutationOperation

type NativeCall = runtime.NativeCall

type NativeCallableKind uint8

type NativeDeclarationKind uint8

type NativeFrameCallStatistics = runtime.NativeFrameCallStatistics

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

type Position struct {
	Line   int // line starting from 1
	Column int // column in characters starting from 1
	Start  int // index of the first byte
	End    int // index of the last byte
}

type PrintFunc func(any)

type Profile struct {
	// StartTime is when execution began.
	StartTime time.Time
	// EndTime is when execution completed.
	EndTime time.Time
	// TotalDuration is the wall-clock execution time.
	TotalDuration time.Duration

	// Calls contains all recorded function/macro calls in order.
	Calls []*CallRecord
	// contains filtered or unexported fields
}

type ProfileStats struct {
	// TotalCalls is the total number of function/macro calls.
	TotalCalls int
	// NativeCalls is the count of native Go function calls.
	NativeCalls int
	// ScriggoCalls is the count of Scriggo function calls.
	ScriggoCalls int
	// MacroCalls is the count of macro invocations.
	MacroCalls int
	// ByFunction maps function key (pkg.name or name for macros) to stats.
	ByFunction map[string]*FunctionStats
}

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

type RunOptions struct {
	// Deterministic orders map ranges by key and disables print, println,
	// goroutines, and parallel rendering. Functions containing those operations
	// and statically unsupported map key types are rejected before execution.
	// Dynamic pointer, channel, unsafe-pointer, and NaN map keys are rejected when
	// their range begins. Native functions and methods remain outside this policy.
	Deterministic bool

	// Vector installs concrete slice columns into every mutable global slot
	// with the corresponding name. A native.VectorEnv controller selects the
	// active element. Used for templates only.
	Vector *VectorRunOptions

	// NativeFunctionTrampolines provide direct paths for function values created
	// by native.MakeFunctionTrampoline. Other native functions use normal dispatch.
	NativeFunctionTrampolines []*native.FunctionTrampoline

	// Context is a context that can be read by native functions and methods
	// via the Context method of native.Env. Canceling the context, the
	// execution is terminated and the Run method returns Context.Err().
	Context context.Context

	// ChildContext derives the context exposed through native.Env in a child
	// execution from the context of its parent execution. It is called for
	// Scriggo functions invoked by native code and for executions started by a
	// go statement, including parallel template renders. The returned context
	// must derive from parent. Calls may occur concurrently.
	ChildContext func(parent context.Context) context.Context

	// ObserveMutation is called synchronously immediately before template code
	// mutates reachable storage. Returning an error prevents the mutation and
	// makes Run return that error. The Env carries the current child execution
	// context. Calls may occur concurrently.
	//
	// Native functions and methods are outside this observer. Clone or guard
	// mutable values before passing them to native code, or use
	// ObserveNativeCall for method receivers. Detached Scriggo go
	// statements return [ErrMutationObserverDetachedGo] before they start.
	// Channel operations return this function's error, or
	// [ErrMutationObserverChannelOperation] when it returns nil. A select reports
	// every channel candidate; an empty select has an invalid Target.
	ObserveMutation func(env native.Env, mutation Mutation) error

	// ObserveMutationContext is the non-escaping context-only form of ObserveMutation.
	ObserveMutationContext func(ctx context.Context, mutation Mutation) error

	// ObserveNativeCall is called synchronously before Scriggo calls a native
	// method or exposes it as a method value. Returning an error prevents the
	// access and makes Run return that error. It is not called for native
	// functions. Calls may occur concurrently.
	ObserveNativeCall func(env native.Env, call NativeCall) error

	// ObserveNativeCallContext is the non-escaping context-only form of ObserveNativeCall.
	ObserveNativeCallContext func(ctx context.Context, call NativeCall) error

	// BeforeNativeCall is called synchronously immediately before every native
	// function or method invocation. Returning an error prevents the call and
	// makes Run return that error. Calls may occur concurrently.
	BeforeNativeCall func(env native.Env) error

	// BeforeNativeCallContext is the non-escaping context-only form of BeforeNativeCall.
	BeforeNativeCallContext func(ctx context.Context) error

	// Print is called by the print and println builtins to print values.
	// If it is nil, the print and println builtins format their arguments as
	// expected and write the result to standard error.
	Print PrintFunc

	// Profile receives profiling data after execution completes.
	// Only populated if the template was built with EnableProfiling=true.
	// Caller must allocate: &scriggo.Profile{}
	//
	// Note: Native function calls executed as goroutines (via go statement)
	// are not included in the profile since their execution is asynchronous.
	//
	// Used for templates only. Ignored for programs.
	Profile *Profile

	// MaxParallelRenders limits the number of concurrent "go render" operations.
	// If zero or negative, defaults to 2*GOMAXPROCS.
	//
	// Used for templates only. Ignored for programs.
	MaxParallelRenders int

	// CollectSourceMap requests an output-to-source line map: after Run,
	// SourceSpans holds one span per contiguous run of rendered output,
	// attributing it to the template source position that produced it. This
	// is pure observation and does not change the rendered bytes, but adds
	// per-write bookkeeping, so leave it false for production rendering.
	//
	// Used for templates only. Ignored for programs.
	CollectSourceMap bool

	// SourceSpans is populated after Run when CollectSourceMap is true. The
	// spans are in output order and their Length fields sum to the output
	// size, so a caller can walk the rendered bytes and attribute each output
	// line to (Path, Line). Output produced by a parallel "{{ go … }}" render
	// is attributed as one span to the go-render call site.
	SourceSpans []SourceSpan
}

type SourceFrame struct {
	Path string
	Line int
}

type SourceSpan struct {
	// Frames is the include stack, innermost first: Frames[0] is where the text
	// literally is, followed by the render/include callers up to the entry
	// template. Piped renders ("{{ render \"x\" | indent }}") resolve into x's
	// own source when the filter is line-preserving.
	Frames []SourceFrame
	// Length is the number of output bytes this span covers.
	Length int
	// IsText reports whether the span is literal template text (so Frames[0].Line
	// advances with each '\n' in the output) rather than a show-expression value.
	IsText bool
}

type StackFrame struct {
	Function string // Function name
	Path     string // File path
	Line     int    // Line number
}

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

type UsedNativeCallable struct {
	Kind            NativeCallableKind
	Receiver        reflect.Type
	Name            string
	Path            string
	Package         string
	DeclarationName string
	Declaration     native.Declaration
	MemberPath      string
	Synchronous     bool
	Constructed     bool
}

type UsedNativeDeclaration struct {
	Package            string
	Name               string
	Kind               NativeDeclarationKind
	Declaration        native.Declaration
	Synchronous        bool
	SynchronousMembers []string
}

type UsedNativeValueAccess struct {
	Package         string
	DeclarationName string
	Declaration     native.Declaration
	MemberPath      string
}

type UsedVariable struct {
	Package          string
	Path             string
	Name             string
	Native           bool
	FunctionPath     string
	FunctionName     string
	FunctionPosition ast.Position
}

type VectorRunOptions struct {
	Authority        *native.VectorAuthority
	Count            int
	Bindings         map[string]any
	Contexts         []context.Context
	DeferredBindings []string
	VMNative         bool
	Boundary         *native.VectorBoundary
	Lifecycle        native.VectorLifecycle
	FiberBoundary    *native.VectorFiberBoundary
	FiberLifecycle   native.VectorFiberLifecycle
}