Documentation
¶
Overview ¶
Package metadata parses and verifies PEP 723-style inline script metadata: a TOML block carried in comments before a script's first statement.
# /// script # requires-scriptling = ">=0.24" # # dependencies = [ # "requests", # "scriptling.sql via sql >= 0.23", # ] # # plugins = [ # "knot >= 1.2.3", # ] # ///
requires-scriptling carries a version constraint matched against the running host. dependencies name libraries the script imports; an entry may add "via <plugin>" to name the plugin that provides the library — with the same optional version constraint as the plugins list ("scriptling.sql via sql >= 0.23") — and when that library does not resolve the plugin (with its constraint) becomes required. A compiled-in or otherwise provided library satisfies the entry without the plugin. plugins name external plugin processes directly, with an optional version constraint matched against the version each plugin declared in its handshake.
Plugin names match the declared name from the plugin's handshake, and a bare name additionally matches the same name under scriptling's host-owned namespaces: "sql" matches a plugin declaring "scriptling.sql" (the first-party database plugins), "hello" matches one declaring the bare name "hello" (registered as "plugin.hello"), while "knot" matches only a plugin declaring "knot".
Tables under [tool.*] are reserved for tool and host configuration: scriptling ignores their contents, and Parse surfaces them as Tools so an embedding host can carry its own declarations in the same block. Any other unknown key is an error, so a typo fails loudly instead of silently doing nothing.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompareVersions ¶
CompareVersions compares dotted numeric versions, padding the shorter with zeros so 1.2 equals 1.2.0.
Types ¶
type CheckError ¶
type CheckError struct {
Failures []Failure
}
CheckError is the aggregated result of a failed Verify, carrying every failure so a script learns all of them at once instead of one per run.
func (*CheckError) Error ¶
func (e *CheckError) Error() string
func (*CheckError) Has ¶
func (e *CheckError) Has(kind FailureKind) bool
Has reports whether any failure has the given kind; hosts use it to attach their own remedy hints (the CLI adds how to load plugins).
type Dependency ¶
Dependency is one required library. Library is the name the script imports, checked by resolution. Plugin, when set, names the plugin that provides the library in the same "name [constraint]" syntax the plugins list accepts: if the library does not resolve, the plugin (with its constraint) becomes required and its absence is reported as a plugin failure with the plugin's own remedy, rather than an unresolved library.
type Env ¶
type Env struct {
// HostVersion is the running host's version. The CLI passes scriptling's
// build.Version; an embedding application passes its own version, since
// from a script's perspective the host is the interpreter it runs on.
HostVersion string
// Resolves reports whether a library or module name is available to
// scripts: a registered library, a built-in module, or module source a
// package loader can produce.
Resolves func(name string) bool
// PluginVersion returns the version a loaded plugin declared in its
// handshake, by plugin name. A nil function means no plugins are loaded.
PluginVersion func(name string) (string, bool)
}
Env supplies everything Verify needs to know about the running host.
type Failure ¶
type Failure struct {
Kind FailureKind
Message string
}
Failure is one unmet requirement with a rendered, neutral message.
type FailureKind ¶
type FailureKind string
FailureKind classifies a requirement failure.
const ( FailureVersion FailureKind = "version" FailureLibrary FailureKind = "library" FailurePluginMissing FailureKind = "plugin-missing" FailurePluginVersion FailureKind = "plugin-version" )
type Metadata ¶
type Metadata struct {
RequiresScriptling string
Dependencies []Dependency
Plugins []PluginRequirement
// Tools carries the [tool.<name>] tables, keyed by name. Scriptling
// ignores their contents; they exist for embedding hosts (knot declares
// plugin identity and registrations under [tool.knot]). Values are
// normalised: every table is map[string]any and every array is []any,
// whatever shapes the TOML decoder chose.
Tools map[string]any
}
Metadata is the parsed script metadata block.
func Parse ¶
Parse finds and parses the metadata block. It reports ok=false when the source has no block; every malformed block is an error, because a script that tried to declare its requirements should never run as if it had none. The block must appear before the first statement and at most once.
func (Metadata) Tool ¶ added in v0.24.1
Tool returns the named [tool.<name>] table, with nested values normalised the same way as Tools. It reports false when the name is absent or is not a table.
func (Metadata) Verify ¶
Verify checks the metadata against the host environment. Dependencies are checked first: a dependency that resolves is satisfied however the environment provides it, and only an unresolved dependency promotes its declared plugin into the required set. The plugin check then reports every missing or too-old plugin — declared directly or promoted — in one pass. When a plugin is named both directly and by a promoted dependency, the direct entry (with its constraint) is the intentional statement and wins.
type PluginRequirement ¶
PluginRequirement is one required external plugin process. Constraint, when set, is an operator and version (">=1.2.3", "==2.0") matched against the version the plugin declared in its handshake.
Source Files