Documentation
¶
Overview ¶
Package sdbapi describes the sdb package — what a script can call on s *sdb.S, and the fields and methods of the types it hands back — as data, for the script editor's completion and hover in dbc web.
The description is generated from the sdb source with go/doc and embedded (api.json), not written by hand, so it cannot drift from the code: TestAPIUpToDate rebuilds it from the source and fails when the embedded copy differs. After changing sdb (or a type it aliases):
go generate ./sdb/sdbapi
Why build time and not run time: the binary has no source to read, and reflection would give method names and types but none of the doc comments, which are most of what hover is for.
sdb/sdb.go, sdb/etl.go ── go/doc ──► S's methods, package funcs, types
│ type CopyOpts = etl.CopyOptions
└──── follow the alias ──► etl/*.go ── go/doc ──► its fields, methods
(named CopyOpts)
▼
api.json (embedded) ──► GET /api/v1/scripts/api
Only one level is followed: CopyOpts' fields are described, but not a type one of those fields names (explain.Plan's Node). A script reaching that far has go doc.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Encode ¶
Encode is api as api.json holds it: indented, so a regeneration's diff reads as the API change it is.
func JSON ¶
func JSON() []byte
JSON is the embedded description, as GET /api/v1/scripts/api serves it.
func Summary ¶
func Summary() string
Summary is the sdb API as plain text for the assistant: what a script can call and the fields of what it gets back, each with the first sentence of its doc. It goes with the first question a conversation asks from a script tab, so the model writes s.Query(conn, …) against the real signatures instead of guessing at a database/sql-shaped API.
Why a summary and not api.json: the JSON is ~35 KB, most of it full doc comments written for hover, and the model is sent this once per conversation on the user's tokens. Signatures plus one sentence each are what writing a call needs; the rest is a `go doc` away.
package sdb — … func IsCanceled(err error) bool — reports whether … type S — … func (s *S) Query(conn, query string, args ...any) (*Result, error) — … type CopyOpts = etl.CopyOptions — … To string — names the destination table; … func (r *Reader) Next() … (methods of the other types: signature only)
It is built once from the embedded JSON, which is generated from the source (see the package comment), so it cannot drift either.
Types ¶
type API ¶
type API struct {
Package string `json:"package"` // "sdb": what a script's import is called
Doc string `json:"doc"`
Funcs []Func `json:"funcs"` // package-level: sdb.IsCanceled
Types []Type `json:"types"`
}
API is the sdb package as an editor sees it.
type Field ¶
type Field struct {
Name string `json:"name"`
Type string `json:"type"`
Doc string `json:"doc"` // its doc comment, or else its line comment
}
Field is an exported struct field.
type Func ¶
type Func struct {
Name string `json:"name"`
Sig string `json:"sig"` // as declared: "func (s *S) Query(conn, query string, args ...any) (*Result, error)"
Doc string `json:"doc"`
Params []Param `json:"params"` // one per name, so a completion can make a snippet
// ConnArgs are the positions of the parameters that name a connection
// (string parameters called conn, src or dst): inside those string
// literals the editor offers connection names. Derived from the names
// so a new method gets it without a list to update.
ConnArgs []int `json:"connArgs,omitempty"`
}
Func is a function or a method.
type Type ¶
type Type struct {
Name string `json:"name"`
Of string `json:"of,omitempty"` // "etl.CopyOptions"
Kind string `json:"kind"` // "struct", "interface" or "other"
Doc string `json:"doc"`
Fields []Field `json:"fields,omitempty"`
Methods []Func `json:"methods,omitempty"`
}
Type is a type the sdb package declares. For an alias of another package's type (CopyOpts = etl.CopyOptions), Of names the target and the fields and methods are the target's.
Source Files