dsl package reference

Package path: github.com/cpcf/gess/dsl

Types

CallFunc

CallFunc is the signature host code implements to back a .gess (call name arg…) action. It receives the action context and the evaluated argument values, and returns an error to fail the action.

type CallFunc func(rules.ActionContext, []rules.Value) error

Deffacts

Deffacts is one named deffacts declaration after Load has lowered it.

type Deffacts struct {
  Name  string
  Facts []session.InitialFact
}

Document

Document is a parsed .gess source file. Parse produces a Document; Load lowers it into a Workspace and populates the facts returned by InitialFacts.

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

Parse

Parse parses .gess source bytes into a Document without loading it into a workspace. name is stored as the document’s identity and used in error spans. The result’s InitialFacts are empty until Load runs.

func Parse(name string, source []byte) (*Document, error)

*Document.Deffacts

Deffacts returns named seed-fact declarations in source order after Load. Returned facts are defensive copies.

func (d *Document) Deffacts() []Deffacts

*Document.InitialFacts

InitialFacts returns facts declared by deffacts after Load has lowered the document.

func (d *Document) InitialFacts() []session.InitialFact

*Document.MissingRegistrations

MissingRegistrations returns host action and call registrations referenced by the parsed source but absent from registry.

func (d *Document) MissingRegistrations(registry Registry) MissingRegistrations

*Document.Name

Name returns the source name supplied to Parse.

func (d *Document) Name() string

*Document.Symbols

Symbols returns named top-level declarations in source order. Loading and compilation remain authoritative for semantic validity.

func (d *Document) Symbols() []Symbol

FileError

FileError reports a .gess parser or lowering error with the source span where it occurred. It wraps an underlying error where one exists, so errors.Is and errors.As work through it.

type FileError struct {
  Span   SourceSpan
  Reason string
  Err    error
}

*FileError.Error

func (e *FileError) Error() string

*FileError.Unwrap

func (e *FileError) Unwrap() error

GoGeneratorOptions

GoGeneratorOptions controls the package and function name of Go source emitted by GenerateGo. Empty fields default to “main” and “BuildRuleset”.

type GoGeneratorOptions struct {
  PackageName  string
  FunctionName string
}

MissingRegistrations

MissingRegistrations lists the host action and call names a parsed Document references that a Registry does not provide, as returned by Document.MissingRegistrations.

type MissingRegistrations struct {
  Calls   []string
  Actions []string
}

Registry

Registry supplies the host-provided actions, call targets, and pure functions that a .gess file’s (call …) forms and expressions reference. Load and Compile fail if a .gess file names an action, call, or function that Registry doesn’t provide.

type Registry struct {
  Actions   map[string]rules.ActionFunc
  Calls     map[string]CallFunc
  Functions []rules.PureFunctionSpec
}

SourceFile

SourceFile is one .gess file passed to GenerateGo, identified by name (for error spans) and its raw source bytes.

type SourceFile struct {
  Name   string
  Source []byte
}

SourceSpan

SourceSpan is a source location range within a .gess file, used to locate parse and lowering errors.

type SourceSpan struct {
  Name        string
  StartLine   int
  StartColumn int
  EndLine     int
  EndColumn   int
}

SourceSpan.String

String returns the source name and starting line/column.

func (s SourceSpan) String() string

Symbol

Symbol is one syntactic top-level declaration from a parsed Document.

type Symbol struct {
  Kind   SymbolKind
  Name   string
  Module string
  Source SourceSpan
}

SymbolKind

SymbolKind identifies a named top-level .gess declaration.

type SymbolKind string

SymbolModule, SymbolTemplate, SymbolRule, SymbolQuery, SymbolFunction, SymbolGlobal, SymbolDeffacts

const (
  SymbolModule   SymbolKind = "module"
  SymbolTemplate SymbolKind = "template"
  SymbolRule     SymbolKind = "rule"
  SymbolQuery    SymbolKind = "query"
  SymbolFunction SymbolKind = "function"
  SymbolGlobal   SymbolKind = "global"
  SymbolDeffacts SymbolKind = "deffacts"
)

Functions

Compile

Compile parses and loads .gess source into a new workspace and compiles it in one step, equivalent to Parse followed by Load and Workspace.Compile. Use Parse and Load directly to load multiple .gess files into one shared workspace before compiling, or to keep the intermediate Document for InitialFacts.

func Compile(ctx context.Context, name string, source []byte, registry Registry) (*rules.Ruleset, error)

Format

Format parses source and returns the canonical byte layout used by gessfmt, preserving comments and reporting syntax failures as FileError values.

func Format(name string, source []byte) ([]byte, error)

GenerateGo

GenerateGo emits Go source that builds the same workspace as the given .gess sources, without parsing those files at application startup. The generated build function takes a Registry and validates every (call …) name against it. If formatting the generated source fails, GenerateGo returns the unformatted bytes alongside the error.

func GenerateGo(ctx context.Context, sources []SourceFile, opts GoGeneratorOptions) ([]byte, error)

InitialFacts

InitialFacts returns the deffacts-declared seed facts from doc for use with session.WithInitialFacts. It is safe to call with a nil doc, and returns nil if doc has not been through Load yet.

func InitialFacts(doc *Document) []session.InitialFact

Load

Load lowers a parsed Document into workspace, registering its modules, templates, rules, queries, and deffacts seed facts, and resolving its (call …) forms and pure functions against registry. On success it populates doc’s InitialFacts. Loading fails if the document references an action, call, or function name registry doesn’t provide.

func Load(ctx context.Context, workspace *rules.Workspace, doc *Document, registry Registry) error

RenderFunction

RenderFunction renders one deffunction definition back to canonical .gess source.

func RenderFunction(revision *rules.Ruleset, name string) ([]byte, error)

RenderModule

RenderModule renders one module of a compiled ruleset, and everything defined in it, back to canonical .gess source.

func RenderModule(revision *rules.Ruleset, name rules.ModuleName) ([]byte, error)

RenderQuery

RenderQuery renders one query definition back to canonical .gess source.

func RenderQuery(revision *rules.Ruleset, name string) ([]byte, error)

RenderRule

RenderRule renders one rule definition back to canonical .gess source.

func RenderRule(revision *rules.Ruleset, name string) ([]byte, error)

RenderRuleset

RenderRuleset renders every module, template, function, rule, and query in a compiled ruleset back to canonical .gess source.

func RenderRuleset(revision *rules.Ruleset) ([]byte, error)

RenderTemplate

RenderTemplate renders one template definition back to canonical .gess source.

func RenderTemplate(revision *rules.Ruleset, name string) ([]byte, error)