Documentation
¶
Overview ¶
Package ir is unison's language-neutral intermediate representation.
It is the seam §5 asks for. The hard half of this tool — roster handling, convergent shape computation, divergence policy, prefix markers — has nothing to do with Go, so it produces one of these and an emitter renders it. v1 ships exactly one emitter and a second language is out of scope, but keeping the core honest about what it knows is what makes the emitter replaceable rather than entangled.
Nothing here imports the plugin protocol, and nothing here names a Go type. The one exception is Type.Override, which is deliberately opaque: it carries a string the consumer wrote in their config for an emitter to interpret.
Index ¶
Constants ¶
const PrefixMarker = "{{prefix}}"
PrefixMarker is the token §9's rewriting places before a table name, and the one the generated constructor replaces once per statement at construction.
It is deliberately not valid SQL. A marker that happened to parse would let a statement that was never given a prefix reach the database and fail there, rather than failing where it was written.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Command ¶
type Command uint8
Command is a query's sqlc annotation.
const ( // CommandInvalid is the zero value and never appears in a valid Package. CommandInvalid Command = iota // CommandExec is `:exec` — run it, report only failure. CommandExec // CommandOne is `:one` — exactly one row. CommandOne // CommandMany is `:many` — zero or more rows. CommandMany // CommandExecRows is `:execrows` — the number of rows affected. CommandExecRows // CommandExecResult is `:execresult` — the driver's own result. CommandExecResult )
func (Command) ReturnsRows ¶
ReturnsRows reports whether the command produces a row shape.
type Field ¶
type Field struct {
// Name is the canonical name, spelled as the SQL spells it — snake_case,
// as it arrives from the analyzer. Turning it into an identifier is the
// emitter's job, because the rules differ by language.
Name string
// Type is what it holds.
Type Type
}
Field is one named, typed member of a params or row shape.
type Kind ¶
type Kind uint8
Kind is a type as unison understands it, independent of both the engine that reported it and the language that will render it.
The set is small on purpose. It is the intersection worth converging: the types the three engines agree about often enough that a shared struct is honest. Anything outside it is a type_override or an error, never a guess.
type Package ¶
type Package struct {
Name string
Dialect string
SQLCVersion string
UnisonVersion string
NullAs string
Roster []string
Queries []Query
Statements []Statement
TablePrefix bool
}
Package is everything an emitter needs for one invocation.
type Query ¶
type Query struct {
// Name is the query's name from its `-- name:` annotation, and the join key
// across dialects.
Name string
// Params are the distinct parameters, in the order the placeholders for
// them first appear. Distinct is the important word: MySQL repeats a
// placeholder for every occurrence of a named argument, so its statement
// can bind sixteen positions from these eight fields.
Params []Field
// Columns is the projection, empty unless Command.ReturnsRows.
Columns []Field
// Command is the annotation.
Command Command
}
Query is one query's shared shape: what every dialect must agree on.
It is computed from a single dialect's analysis, because a single dialect's analysis is all any invocation has. Convergence is not checked here — it is the consequence of every invocation computing this the same way from the same query set and writing the result to the same path.
type Statement ¶
type Statement struct {
// Name matches the Query it realizes.
Name string
// SQL is the analyzed statement text, carrying {{prefix}} markers when the
// consumer asked for them.
SQL string
// Args names the parameter each placeholder binds, in placeholder order.
// Names repeat when the engine repeats a placeholder.
Args []string
}
Statement is one dialect's realization of a Query.
It is the half that is allowed to differ. The SQL is that engine's text, and Args names which parameter each placeholder binds — the list that is written by hand today, in the order of a column list a few lines up, and is wrong on two engines out of three when it is wrong at all.
type Type ¶
type Type struct {
// Override, when set, replaces Kind entirely. It is whatever the consumer
// wrote in a type_override — for the Go emitter, a type name or a full
// import path and type name.
Override string
// Kind is the converged type, meaningful only when Override is empty.
Kind Kind
// Nullable reports that the analyzer could not rule out NULL.
Nullable bool
}
Type is a field's type.
Source Files