How montferret/ferret works
Ferret is an embeddable Go runtime for the FQL declarative language. Its documented primary workflow is to configure an engine, compile a query into a reusable plan, create an isolated session, run it, and collect or consume the encoded output. The map also preserves querying, host extension, portable bytecode, debugging, compatibility, and source-formatting capabilities. Relationships are limited to the README workflow and source-index or excerpt evidence; several subsystem internals were not sampled.
Main entry points: engine_options.go Engine options · engine.go Engine · compiler Compiler · plan_session.go Plans and sessions
Components 24
Language and compilation
- Compiler
pkg/compiler - Query expressions
pkg/compiler/internal/expr_query_compiler.go - FQL parser
pkg/parser/parser.go - Parse diagnostics
pkg/parser/diagnostics/match_error_query.go - Optimization passes
pkg/compiler/internal/optimization/pipeline.go - Bytecode program
pkg/bytecode/program.go - Program artifacts
pkg/bytecode/artifact
Runtime and execution
- Plans and sessions
pkg/engine/plan_session.go - Bytecode VM
pkg/vm - Value runtime
pkg/runtime - Queryable values
pkg/runtime/queryable.go - Standard library
pkg/stdlib/lib.go - Resource lifecycle
pkg/engine/internal/resource/manager.go - Encoding and output
pkg/encoding/output.go
Embedding and extensions
- Native API
engine.go - Engine
pkg/engine/engine.go - Engine options
engine_options.go - Modules and hooks
pkg/module - Host-value SDK
pkg/sdk/decode.go
Developer interfaces
- Debugger sessions
pkg/debugger/session.go - FQL formatter
pkg/formatter/internal/engine.go - Compatibility API
compat/compat.go - Universal adapter
uapi/debug_session.go
Other components
- Host application
Connections 26
- Host application → Native API: embeds
- Native API → Engine: constructs
engine.go - Host application → Engine options: configures
engine_options.go - Engine options → Engine: sets options
engine_options.go - Engine → Compiler: compiles with
pkg/engine/engine.go - Compiler → Bytecode program: emits
pkg/compiler/internal/expr_query_compiler.go - Compiler → FQL parser: uses grammar
pkg/compiler/internal/expr_query_compiler.go - Compiler → Optimization passes: optimizes
- Optimization passes → Bytecode program: rewrites
pkg/compiler/internal/optimization/pipeline.go - Engine → Plans and sessions: creates plan
- Plans and sessions → Bytecode VM: executes
- Bytecode VM → Value runtime: evaluates values
pkg/vm/query.go - Bytecode VM → Queryable values: dispatches queries
pkg/vm/query.go - Queryable values → Value runtime: uses values
- Engine options → Modules and hooks: registers modules
- Engine options → Standard library: selects libraries
engine_options.go - Engine → Resource lifecycle: owns resources
pkg/engine/engine.go - Plans and sessions → Encoding and output: produces output
- Host application → Encoding and output: collects output
- Engine options → Program artifacts: configures loading
engine_options.go - Host application → Host-value SDK: converts host values
- Host application → Debugger sessions: inspects sessions
pkg/debugger/session.go - Host application → FQL formatter: formats source
- Host application → Compatibility API: migrates integrations
- Host application → Universal adapter: uses adapter
- FQL parser → Parse diagnostics: reports errors
pkg/parser/diagnostics/match_error_query.go