api

package module
v1.0.0-alpha.14 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 6, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

README

Universal Ferret API

Portable contracts for compiled execution and retained source-level debugging. Implementations own engine configuration; consumers share Runtime, reusable Plan, per-run Session, and the types in source, result, debugger, and diagnostics.

Execution and ownership

Runtime.Compile and CompileDebug finish compilation before returning a plan. Syntax and compiler errors are immediate. Plans support repeated and concurrent sessions with independent parameters and filesystem configuration; Params returns a caller-owned snapshot.

Callers close directly created sessions before plans, then close the runtime. Parents reject new children after closure begins and coordinate admitted construction with closure; they do not promise to close descendants. Close is idempotent and retains the completed cleanup result. Ordinary execution owners cancel and settle running work before closing the session. Debugger session closure terminates and settles active commands. Runtime.Run owns its temporary session and plan and returns execution and cleanup errors together, preserving available output. Output and inspection snapshots belong to their callers.

Contexts must be non-nil. Already-canceled contexts are rejected before options, hooks, or acquisition. Implementations recheck cancellation before publishing resources and preserve context.Canceled and context.DeadlineExceeded through errors.Is. Synchronous native compilation checks cancellation between phases; it does not preempt the parser or detach compilation into a goroutine.

Options

Session options target the implementation's actual SessionOptions owner. Non-nil options run exactly once in order; their validation failures are joined before acquiring resources. Later options can override earlier values. Native extensions validate their target explicitly. No intermediate option replay is required.

WithOptimizationLevel configures one compilation. Native Ferret inherits the engine's level when omitted, supports explicit OptimizationNone, OptimizationBasic, and OptimizationFull without mutating shared compiler configuration, and rejects OptimizationAggressive. Debug compilation accepts omission or OptimizationNone only. Other implementations document their supported levels.

Portable data

Native Ferret produces one-based lines and byte columns, with zero-based, half-open byte spans. Source names are identities and need not be filesystem paths; anonymous sources have an empty name. Adapters translate native indexed source text into the portable Source representation. Portable coordinates, encoded output, debugger values, variables, frames, breakpoints, reasons, and events preserve their existing fields and JSON representations.

debugger.ValueReference.Valid accepts positive references. References are scoped to a paused state and become stale when execution resumes. debugger.NoFunction identifies the top-level program body. Compiler table identifiers and validation remain implementation details.

Debugger commands are StepIn, StepOver, and StepOut. Breakpoint requests use canonical source locations and binding options. A completed event and its output can accompany a later cleanup error. Error projections should preserve each diagnostic's source, annotation order, joined branches, and native causes through standard Go error traversal.

Documentation

Overview

Package api defines implementation-independent contracts for compiling, executing, and debugging Ferret queries.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Location 

type Location = source.Location

Location represents the location of a specific point in a source file, including the file name and position.

type OptimizationLevel 

type OptimizationLevel int
const (
	OptimizationNone OptimizationLevel = iota
	OptimizationBasic
	OptimizationFull
	OptimizationAggressive
)

type Output 

type Output = result.Output

Output is the encoded result returned from session or engine execution.

type Plan 

type Plan interface {
	io.Closer
	Params() []string
	NewSession(ctx context.Context, opts ...SessionOption) (Session, error)
	NewDebugSession(ctx context.Context, opts ...SessionOption) (debugger.Session, error)
}

Plan represents an already compiled program. Compilation errors are returned before a plan is published. Plans support independent sessions and are not consumed by execution. Callers close sessions before their plan. Close is idempotent, retains its cleanup result, and prevents new sessions. Admitted creation settles before parent cleanup; descendant cleanup is not guaranteed. Params returns a caller-owned snapshot. Contexts must be non-nil.

type PlanOption 

type PlanOption = func(PlanOptions) error

func WithOptimizationLevel 

func WithOptimizationLevel(level OptimizationLevel) PlanOption

WithOptimizationLevel sets the optimization level for the execution plan.

type PlanOptions 

type PlanOptions interface {
	SetOptimizationLevel(OptimizationLevel) error
}

type Position 

type Position = source.Position

Position represents a specific point in a source file, defined by line and column numbers.

type Range 

type Range = source.Range

Range represents a range of characters in a source file, including the location and span.

type Runtime 

type Runtime interface {
	io.Closer
	Run(ctx context.Context, src Source, opts ...SessionOption) (Output, error)
	Compile(ctx context.Context, src Source, opts ...PlanOption) (Plan, error)
	CompileDebug(ctx context.Context, src Source, opts ...PlanOption) (Plan, error)
}

Runtime compiles source into reusable plans. Callers own directly created plans and sessions and close them from children to parents before the runtime. Close is idempotent, retains its cleanup result, and rejects new work. Admitted creation settles before parent cleanup. Descendant cleanup is not guaranteed. Contexts must be non-nil. Run closes its temporary session and plan, preserving execution and cleanup errors together with any available encoded output.

type Session 

type Session interface {
	io.Closer
	Run(c context.Context) (Output, error)
}

Session executes a compiled plan with per-session configuration. Run observes its non-nil context and returns caller-owned encoded output. Unless documented otherwise, callers serialize Run and settle it before Close. Close is idempotent and retains its cleanup result.

type SessionOption 

type SessionOption = func(SessionOptions) error

func WithFSRoot 

func WithFSRoot(root string) SessionOption

WithFSRoot selects the rooted filesystem used by one execution session. The runtime defines path validation and owns any filesystem resources created for the session.

func WithOutputContentType 

func WithOutputContentType(contentType string) SessionOption

WithOutputContentType selects the output codec content type for session results.

func WithParam 

func WithParam(key string, value any) SessionOption

WithParam sets a session parameter for the execution.

func WithParams 

func WithParams(params map[string]any) SessionOption

WithParams merges the provided parameter map into the session environment, overriding existing keys while preserving any other previously defined parameters.

type SessionOptions 

type SessionOptions interface {
	SetParam(string, any) error
	SetParams(map[string]any) error
	SetOutputContentType(string) error
	SetFSRoot(string) error
}

SessionOptions is implemented by the runtime's actual session option owner. Implementations apply non-nil options once in order, joining validation errors before acquiring resources. Later setters override earlier values; SetParams merges keys. Runtime-specific options reject incompatible targets.

type Source 

type Source = source.Source

Source represents the input data for a Ferret query.

func NewAnonymousSource 

func NewAnonymousSource(content string) Source

NewAnonymousSource creates a new anonymous Source instance with the given content.

func NewSource 

func NewSource(name, content string) Source

NewSource creates a new Source instance with the given name and content.

type Span 

type Span = source.Span

Span represents a range of characters in a source file, defined by start and end positions.

Source Files

View all Source files

Directories

Path Synopsis
Package debugger defines portable contracts and values for controlling and inspecting Ferret debug sessions, including events, breakpoints, frames, and values.
 Package debugger defines portable contracts and values for controlling and inspecting Ferret debug sessions, including events, breakpoints, frames, and values.
Package diagnostics defines the portable structured reporting model shared by Ferret runtimes and tooling.
 Package diagnostics defines the portable structured reporting model shared by Ferret runtimes and tooling.
Package result defines portable encoded outputs returned by Ferret query execution.
 Package result defines portable encoded outputs returned by Ferret query execution.
Package source defines portable Ferret source inputs and coordinates.
 Package source defines portable Ferret source inputs and coordinates.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.