Documentation
¶
Overview ¶
Package system provides domain types and autocompletion predictors for system users, groups, running processes, PIDs, POSIX signals, locales, and environment variables, plus optional standard library bindings for *user.User, *user.Group, and syscall.Signal fields.
Every exported domain type implements encoding.TextUnmarshaler and Predict: fields declared with these types coerce automatically and complete from package tables or live system state. Invalid values classify under conga.ErrCoerce with the flag and reason named in the message. Group.Lookup and User.Lookup report a blank receiver as an error naming the failed lookup.
Mount RegisterUser, RegisterGroup, or RegisterSignal to register the corresponding standard library types and enable completion on fields typed with them:
type CLI struct {
User conga.OptionalFlag[system.User] `help:"Run as user"`
Signal conga.OptionalFlag[syscall.Signal] `help:"Termination signal"`
}
app := conga.New[CLI]().Use(system.RegisterSignal)
Signals accept POSIX names (SIGHUP, SIGINT, TERM) or numeric values (15). Users and groups resolve via os/user lookups.
See https://docs.conga.sh/reference/domain-types/ for the domain type reference.
Index ¶
- func EnvVars() predict.Predictor
- func Groups() predict.Predictor
- func Locales() predict.Predictor
- func PIDs() predict.Predictor
- func ProcessIDs() predict.Predictor
- func ProcessNames() predict.Predictor
- func Processes() predict.Predictor
- func RegisterGroup[T any](app *conga.App[T])
- func RegisterSignal[T any](app *conga.App[T])
- func RegisterUser[T any](app *conga.App[T])
- func Signals() predict.Predictor
- func Users() predict.Predictor
- type EnvVar
- type Group
- type Locale
- type PID
- type Process
- type Signal
- type User
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnvVars ¶
EnvVars configures completion of environment variable names currently defined in the execution environment or in the prediction context.
func Locales ¶
Locales configures completion of system and standard internationalization locale identifiers.
func PIDs ¶
PIDs is an alias for ProcessIDs, configuring completion of active process IDs.
func ProcessIDs ¶
ProcessIDs configures completion of active process IDs with their executable names as descriptions. Full process scanning is supported on Linux via /proc; on other platforms, it returns the current process. It pairs with the PID type.
func ProcessNames ¶
ProcessNames configures completion of active running process executable names. Full process scanning is supported on Linux via /proc; on other platforms, it returns the current process. It pairs with the Process type, whose stored value is an executable name.
func Processes ¶
Processes is an alias for ProcessNames, configuring completion of active running process executable names.
func RegisterGroup ¶
RegisterGroup mounts *user.Group support onto the app builder: the parser resolves group names with os/user.LookupGroup and completion offers the host's groups. Apply with app.Use.
func RegisterSignal ¶
RegisterSignal mounts syscall.Signal support onto the app builder: the parser accepts POSIX signal names (SIGHUP, TERM) and numeric values (15), and completion offers the platform's signal table. Apply with app.Use.
Example ¶
RegisterSignal mounts syscall.Signal support: the flag accepts a POSIX signal name or number and completion offers the platform's signal table.
package main
import (
"context"
"fmt"
"syscall"
"github.com/conga-sh/conga"
"github.com/conga-sh/conga/system"
)
// CLI is an application whose flag accepts a POSIX signal.
type CLI struct {
Signal conga.OptionalFlag[syscall.Signal] `help:"Termination signal"`
}
func (c *CLI) Run(_ context.Context, session *conga.Session) error {
_, err := fmt.Fprintln(session.Stdout(), int(c.Signal.Get()))
return err
}
// RegisterSignal mounts syscall.Signal support: the flag accepts a POSIX signal
// name or number and completion offers the platform's signal table.
func main() {
app := conga.New[CLI]().
Use(system.RegisterSignal).
Args([]string{"--signal", "SIGTERM"})
if err := app.Run(); err != nil {
app.Exit(err)
}
}
Output: 15
func RegisterUser ¶
RegisterUser mounts *user.User support onto the app builder: the parser resolves usernames with os/user.Lookup and completion offers the host's users. Apply with app.Use.
Types ¶
type EnvVar ¶
type EnvVar string
EnvVar represents an environment variable name with automatic environment completion.
func (EnvVar) Help ¶
Help returns the default value syntax description for environment variable flags. The engine renders this text in the flag's help column when the field declares no help tag; a field with a help tag shows that text instead. Shells also show it as the description of the flag's completion candidates.
func (EnvVar) MarshalText ¶
MarshalText encodes the environment variable name as UTF-8 text.
func (*EnvVar) UnmarshalText ¶
UnmarshalText sets the environment variable name.
type Group ¶
type Group string
Group represents a system user group with automatic group completion.
func (Group) Help ¶
Help returns the default value syntax description for system group flags. The engine renders this text in the flag's help column when the field declares no help tag; a field with a help tag shows that text instead. Shells also show it as the description of the flag's completion candidates.
func (Group) MarshalText ¶
MarshalText encodes the group name as UTF-8 text.
func (*Group) UnmarshalText ¶
UnmarshalText sets the group name.
type Locale ¶
type Locale string
Locale represents an internationalization locale identifier with automatic locale completion.
func (Locale) Help ¶
Help returns the default value syntax description for locale flags. The engine renders this text in the flag's help column when the field declares no help tag; a field with a help tag shows that text instead. Shells also show it as the description of the flag's completion candidates.
func (Locale) MarshalText ¶
MarshalText encodes the locale identifier as UTF-8 text.
func (*Locale) UnmarshalText ¶
UnmarshalText sets the locale identifier.
type PID ¶
type PID int
PID represents a positive process identifier with active process autocompletion. Its Predict hook pairs with ProcessIDs().
func (PID) Help ¶
Help returns the default value syntax description for PID flags. The engine renders this text in the flag's help column when the field declares no help tag; a field with a help tag shows that text instead. Shells also show it as the description of the flag's completion candidates.
func (PID) MarshalText ¶
MarshalText encodes the PID as UTF-8 text.
func (*PID) UnmarshalText ¶
UnmarshalText validates and parses a positive PID.
type Process ¶
type Process string
Process represents a system process executable name with active process completion. The stored value is the executable name; its Predict hook pairs with ProcessNames().
func (Process) Help ¶
Help returns the default value syntax description for process name flags. The engine renders this text in the flag's help column when the field declares no help tag; a field with a help tag shows that text instead. Shells also show it as the description of the flag's completion candidates.
func (Process) MarshalText ¶
MarshalText encodes the process executable name as UTF-8 text.
func (*Process) UnmarshalText ¶
UnmarshalText sets the process executable name.
type Signal ¶
type Signal string
Signal represents a POSIX or system signal by name or numeric code.
func (Signal) Help ¶
Help returns the default value syntax description for signal flags. The engine renders this text in the flag's help column when the field declares no help tag; a field with a help tag shows that text instead. Shells also show it as the description of the flag's completion candidates.
func (Signal) MarshalText ¶
MarshalText encodes the signal representation as UTF-8 text.
func (Signal) Signal ¶
Signal converts the signal string into a syscall.Signal. It is a total conversion of a value already validated by UnmarshalText: an empty value and unrecognized text all yield 0. Callers that must reject unknown input validate it with UnmarshalText or the parser installed by RegisterSignal before converting; predictor callbacks have no error channel and ignore unknown text by construction.
func (*Signal) UnmarshalText ¶
UnmarshalText validates that the text represents a recognized signal.
type User ¶
type User string
User represents a system username with automatic user autocompletion.
func (User) Help ¶
Help returns the default value syntax description for username flags. The engine renders this text in the flag's help column when the field declares no help tag; a field with a help tag shows that text instead. Shells also show it as the description of the flag's completion candidates.
func (User) MarshalText ¶
MarshalText encodes the username as UTF-8 text.
func (*User) UnmarshalText ¶
UnmarshalText sets the username.