system

package
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 19 Imported by: 0

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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func EnvVars

func EnvVars() predict.Predictor

EnvVars configures completion of environment variable names currently defined in the execution environment or in the prediction context.

func Groups

func Groups() predict.Predictor

Groups configures completion of system user groups.

func Locales

func Locales() predict.Predictor

Locales configures completion of system and standard internationalization locale identifiers.

func PIDs

func PIDs() predict.Predictor

PIDs is an alias for ProcessIDs, configuring completion of active process IDs.

func ProcessIDs

func ProcessIDs() predict.Predictor

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

func ProcessNames() predict.Predictor

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

func Processes() predict.Predictor

Processes is an alias for ProcessNames, configuring completion of active running process executable names.

func RegisterGroup

func RegisterGroup[T any](app *conga.App[T])

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

func RegisterSignal[T any](app *conga.App[T])

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

func RegisterUser[T any](app *conga.App[T])

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.

func Signals

func Signals() predict.Predictor

Signals configures completion of standard POSIX / system signals.

func Users

func Users() predict.Predictor

Users configures completion of system user accounts.

Types

type EnvVar

type EnvVar string

EnvVar represents an environment variable name with automatic environment completion.

func (EnvVar) Help

func (e EnvVar) Help() string

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) Lookup

func (e EnvVar) Lookup() (string, bool)

Lookup queries the environment variable via os.LookupEnv.

func (EnvVar) MarshalText

func (e EnvVar) MarshalText() ([]byte, error)

MarshalText encodes the environment variable name as UTF-8 text.

func (EnvVar) Predict

func (e EnvVar) Predict() predict.Predictor

Predict returns environment variable autocompletion candidates.

func (EnvVar) String

func (e EnvVar) String() string

String returns the environment variable name.

func (*EnvVar) UnmarshalText

func (e *EnvVar) UnmarshalText(text []byte) error

UnmarshalText sets the environment variable name.

func (EnvVar) Value

func (e EnvVar) Value() string

Value returns the value of the environment variable via os.Getenv.

type Group

type Group string

Group represents a system user group with automatic group completion.

func (Group) Help

func (g Group) Help() string

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) Lookup

func (g Group) Lookup() (*user.Group, error)

Lookup queries system group details using os/user.LookupGroup.

func (Group) MarshalText

func (g Group) MarshalText() ([]byte, error)

MarshalText encodes the group name as UTF-8 text.

func (Group) Predict

func (g Group) Predict() predict.Predictor

Predict returns system group autocompletion candidates.

func (Group) String

func (g Group) String() string

String returns the group name.

func (*Group) UnmarshalText

func (g *Group) UnmarshalText(text []byte) error

UnmarshalText sets the group name.

type Locale

type Locale string

Locale represents an internationalization locale identifier with automatic locale completion.

func (Locale) Help

func (l Locale) Help() string

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

func (l Locale) MarshalText() ([]byte, error)

MarshalText encodes the locale identifier as UTF-8 text.

func (Locale) Predict

func (l Locale) Predict() predict.Predictor

Predict returns locale autocompletion candidates.

func (Locale) String

func (l Locale) String() string

String returns the locale identifier.

func (*Locale) UnmarshalText

func (l *Locale) UnmarshalText(text []byte) error

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

func (p PID) Help() string

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) Int

func (p PID) Int() int

Int returns the PID as an integer.

func (PID) MarshalText

func (p PID) MarshalText() ([]byte, error)

MarshalText encodes the PID as UTF-8 text.

func (PID) Predict

func (p PID) Predict() predict.Predictor

Predict returns active process ID autocompletion candidates.

func (PID) String

func (p PID) String() string

String returns the PID formatted as a string.

func (*PID) UnmarshalText

func (p *PID) UnmarshalText(text []byte) error

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

func (p Process) Help() string

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

func (p Process) MarshalText() ([]byte, error)

MarshalText encodes the process executable name as UTF-8 text.

func (Process) Predict

func (p Process) Predict() predict.Predictor

Predict returns active process autocompletion candidates.

func (Process) String

func (p Process) String() string

String returns the process executable name.

func (*Process) UnmarshalText

func (p *Process) UnmarshalText(text []byte) error

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

func (s Signal) Help() string

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

func (s Signal) MarshalText() ([]byte, error)

MarshalText encodes the signal representation as UTF-8 text.

func (Signal) Predict

func (s Signal) Predict() predict.Predictor

Predict returns kill signal autocompletion candidates.

func (Signal) Signal

func (s Signal) Signal() syscall.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) String

func (s Signal) String() string

String returns the signal representation.

func (*Signal) UnmarshalText

func (s *Signal) UnmarshalText(text []byte) error

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

func (u User) Help() string

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) Lookup

func (u User) Lookup() (*user.User, error)

Lookup queries system user details using os/user.Lookup.

func (User) MarshalText

func (u User) MarshalText() ([]byte, error)

MarshalText encodes the username as UTF-8 text.

func (User) Predict

func (u User) Predict() predict.Predictor

Predict returns system username autocompletion candidates.

func (User) String

func (u User) String() string

String returns the username.

func (*User) UnmarshalText

func (u *User) UnmarshalText(text []byte) error

UnmarshalText sets the username.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL