Documentation
¶
Overview ¶
Package dialect describes the files a dialect seed is made of — the JSONL records under internal/engine/<engine>/dialect that give an engine its type system and standard library — and provides what a generator needs to write them and a check needs to compare them with what is committed.
The record types mirror the ones in internal/core/seed, which reads the files. They are repeated here rather than imported so that this module never shares code with the analysis it checks: the files are the contract, and a change to their shape has to be made on both sides.
Index ¶
- Constants
- func Check(dir string, files Files) (string, error)
- func Diff(want, got string) string
- func Dir(engine string) (string, error)
- func JSONL[T any](records []T) ([]byte, error)
- func Write(dir string, files Files) error
- type Arg
- type Cast
- type Column
- type Files
- type Function
- type Operator
- type Relation
- type Type
Constants ¶
const ( SettingsFile = "dialect.json" TypesFile = "types.jsonl" OperatorsFile = "operators.jsonl" CastsFile = "casts.jsonl" FunctionsFile = "functions.jsonl" RelationsFile = "relations.jsonl" )
The files a dialect directory is made of.
const ExtensionsDir = "extensions"
ExtensionsDir is the directory under a dialect holding one directory per extension the dialect knows, each a smaller bundle of the same files.
Variables ¶
This section is empty.
Functions ¶
func Check ¶
Check compares the files with the ones committed in dir and returns a report of every file that differs, or "" when each matches byte for byte.
func Diff ¶
Diff is a line diff of two texts, marking lines only in want with "-" and lines only in got with "+", showing two lines of context around each change and eliding the rest. The committed files run to thousands of lines and usually differ in a handful, so the common head and tail are stripped before the longest common subsequence of the middle is found.
func Dir ¶
Dir returns the dialect directory of an engine, internal/engine/<engine>/dialect, found relative to this source file so the working directory does not matter.
Types ¶
type Arg ¶
type Arg struct {
Name string `json:"name,omitempty"`
Type string `json:"type"`
Mode string `json:"mode,omitempty"`
HasDefault bool `json:"has_default,omitempty"`
}
Arg is one of a function's parameters. Mode is 'i'n, 'o'ut, 'b'oth, 't'able or 'v'ariadic, and defaults to in.
type Cast ¶
type Cast struct {
Source string `json:"source"`
Target string `json:"target"`
Context string `json:"context,omitempty"`
}
Cast is a single cast between two types. Context is 'i'mplicit, 'a'ssignment or 'e'xplicit.
type Column ¶
type Column struct {
Name string `json:"name"`
Type string `json:"type"`
NotNull bool `json:"not_null,omitempty"`
Array bool `json:"array,omitempty"`
Length int `json:"length,omitempty"`
}
Column is one of a relation's columns.
type Files ¶
Files is what a generator produces: the content of each file it writes, keyed by slash-separated path relative to the dialect directory, such as "functions.jsonl" or "extensions/hstore/types.jsonl". A generator owns only the files it produces; the rest of a dialect, dialect.json above all, is written by hand and is neither generated nor checked.
type Function ¶
type Function struct {
Name string `json:"name"`
Kind string `json:"kind,omitempty"`
Args []Arg `json:"args,omitempty"`
Returns string `json:"returns"`
Nullable bool `json:"nullable,omitempty"`
}
Function is a function the dialect ships with. Kind is 'f'unction, 'a'ggregate, 'w'indow or 'p'rocedure.
type Operator ¶
type Operator struct {
Name string `json:"name"`
Left string `json:"left"`
Right string `json:"right"`
Result string `json:"result"`
}
Operator is a single operator overload.
type Relation ¶
type Relation struct {
Catalog string `json:"catalog,omitempty"`
Schema string `json:"schema"`
Name string `json:"name"`
Kind string `json:"kind,omitempty"`
Columns []Column `json:"columns"`
}
Relation is a table or view the dialect ships with, such as one of PostgreSQL's system catalogs. Kind is 'r' for a table or 'v' for a view, and defaults to a table.
Source Files