The complete reference for the script-facing surface a base-built module
exposes: the generated configuration accessor builtins and any host-supplied
functions. For an overview, installation, the resolution-priority model, and a
quickstart, see the README.
base defines no fixed-name builtins of its own. Instead,
LoadModule(moduleName, additionalFuncs) derives the script-facing surface from
the configuration options a host registered, so the exact function names depend
on the module's config keys. For every registered option named <name> the
loader generates a set_<name> setter — unless the option is host-only, in
which case no setter is generated so a script cannot change it — and for every
non-secret option a get_<name> getter; any callables passed in
additionalFuncs are merged in alongside under their own names.
When a ConfigurableModule is loaded with LoadModule(moduleName, …), each
registered option contributes one or two builtins to the module namespace, named
by string concatenation from the option's key:
| Generated builtin | Generated for | Signature |
|---|---|---|
set_<name> |
non-host-only options only | set_<name>(value) |
get_<name> |
non-secret options only | get_<name>() |
So a module with options api_key (secret) and endpoint (non-secret) exposes
exactly set_api_key, set_endpoint, and get_endpoint — a setter for every
non-host-only option and a getter for every non-secret option. A host-only
option (e.g. a limit the module enforces) gets a get_<name> but no
set_<name>, so a script can read it but never change it.
Sets the configuration option <name> from a single positional value. This
is the highest-priority source in the resolution order (it overrides getter,
environment variable, and default), so a value set from a script takes effect
immediately for subsequent reads.
Parameters:
value: the new value for the option. It is converted from Starlark to Go viadataconv.Unmarshal, then coerced to match the option's declared Go type:- numeric scalars are converted between numeric kinds (e.g. a Starlark int into
a Go
int64/float64option). The conversion is checked: a value that would overflow the target (e.g.300into anint8), a negative value into an unsigned option,NaN/Inf, or a non-integral float into an integer option is rejected with an error, never silently truncated or wrapped; - lists are converted element-by-element into the target slice type;
- dicts are converted into the target map type (numeric map keys, which
dataconvrenders as decimal strings, are parsed back to the numeric key type); - other types are accepted only by a direct type assertion to the option's type.
- numeric scalars are converted between numeric kinds (e.g. a Starlark int into
a Go
Returns: None.
Errors: raises a script error (rather than crashing the host) when:
- the value is
None/nil(aNonecannot populate a typed option); - the value's type cannot be converted to the option's type (type mismatch);
- a numeric value is out of range for the target (overflow), negative into an
unsigned option,
NaN/Inf, or a non-integral float into an integer option (checked conversion — no silent truncation/wrapping); - a slice element or map key/value cannot be converted to the target element type;
- the option has a validator and the converted value fails it.
A reflection/conversion panic is recovered internally and surfaced as an
invalid config value error, never as a host panic.
Example:
load("mymodule", "set_api_key", "set_endpoint", "set_timeout")
set_api_key("sk-secret-12345") # secret option: settable, but no getter exists
set_endpoint("https://api.prod") # string option
set_timeout(60) # int optionReturns the resolved value of the non-secret option <name>, marshalled back to
a Starlark value via dataconv.Marshal. The value is resolved in priority order:
an explicit set_<name> value, then the getter, then the environment variable,
then the default.
This builtin is only generated for non-secret options. A SetSecret(true)
option exposes its set_<name> but no get_<name> — secret values are never
readable from a script (Go code can still read them via GetConfigValue).
Parameters: none.
Returns: the option's current value as a Starlark value (string, int, float, bool, list, dict, …, matching the option's Go type).
Errors: raises a script error if the option's value cannot be resolved (for example, a configured getter function panics).
Example:
load("mymodule", "get_endpoint", "get_timeout")
print(get_endpoint()) # resolved value: explicit > getter > env > default
print(get_timeout())Any callables passed to LoadModule(moduleName, additionalFuncs) (a
starlark.StringDict of starlark.Callable values supplied by the host module)
are merged into the same module namespace under their own names, alongside the
generated set_<name> / get_<name> accessors. Their signatures, parameters,
returns, and errors are defined by the host module that registers them, not by
base; consult that module's own reference.
load("mymodule", "set_api_key", "get_endpoint", "make_request")
set_api_key("sk-...") # generated accessor
print(get_endpoint()) # generated accessor
make_request() # a host-supplied additional functionThe accessors marshal values between Starlark and the option's Go type:
- Starlark → Go (
set_<name>) —dataconv.Unmarshalfollowed by reflect coercion: numeric kinds convert across; lists become slices element-wise; dicts become maps (numeric keys are parsed from their decimal-string form);None/nilis rejected. - Go → Starlark (
get_<name>) —dataconv.Marshal: the resolved value (explicit > getter > env > default) is marshalled back.
Environment-variable string values (resolution priority 3) are parsed into the option's Go type before marshalling, by target type:
- string — the raw string, as-is.
- bool —
true/false,yes/no,1/0,on/off(case-insensitive). - integer (
int,int8…int64,uint,uint8…uint64) — a base-10 integer literal. - float (
float32,float64) — a decimal/float literal. - slice / map (complex types) — a JSON document (a value starting with
[or{).
A value that fails to parse for its target type is ignored, and resolution falls through to the default.
base is itself the configuration framework, so it registers no fixed config
keys of its own — there are no built-in option names to enumerate here. The
accessors a script sees are generated from whatever options the host module
registers, following one uniform contract:
get_<key>()— returns the option's current value. Generated for non-secret options only.set_<key>(value)— sets the option (returnsNone). Generated for every non-host-only option (secret or not); a host-only option has none.
A <key>'s value resolves in priority order — an explicit set_<key> value, the
option's getter, the environment variable, then the default. The environment
variable is whatever name the host passes to WithEnvVar; the conventional name
a starpkg domain module uses is <MODULE>_<KEY> (uppercased), e.g. a
timeout option on the sqlite module reads SQLITE_TIMEOUT.
The generated-accessor contract that every base-built option follows is below.
<MODULE> is the loaded module name, <KEY> the uppercased option key; the env
var is host-chosen via WithEnvVar (conventionally <MODULE>_<KEY>), and the
default/description are whatever the host declared (WithDefault /
NewConfigOption, WithDescription).
<key>(plain) — getterget_<key>, setterset_<key>; both value reads and writes are reachable from a script.<key>(secret) — setterset_<key>only; no getter is generated, since secrets are never readable from a script.<key>(host-only) — getterget_<key>only; no setter is generated, so a script can read the value but never change it (a limit the module enforces). A host-only and secret option gets neither accessor.
Secret options expose only set_<key> — never a getter. A host marks an
option secret with SetSecret(true) (or the equivalent genSecretConfigOption
helper a domain module wraps it in); the loader then emits the set_<key> setter
but no get_<key>, and ListConfigs() / GetInfo() omit the value. Go code can
still read a secret via GetConfigValue, but it is never reachable from a script.
Example:
A host that registers api_key (secret) and endpoint (non-secret) on a module
loaded as mymodule exposes exactly these accessors:
load("mymodule", "set_api_key", "set_endpoint", "get_endpoint")
set_api_key("sk-secret-12345") # secret: settable, no get_api_key exists
set_endpoint("https://api.prod") # non-secret: settable
print(get_endpoint()) # non-secret: readableFor the resolution-priority model, the Go-side builder/accessor API
(NewConfigOption, WithEnvVar, WithDefault, SetSecret, GetConfigValue,
…), and how a host registers options, see the README and the
GoDoc.