prompter

README

prompter

prompter is a small package for interactive CLI input.

What It Provides

• String prompts with optional defaults.
• Choice prompts with validation.
• Int64, float64, and time.Duration prompts.
• Secret input with no echo on TTY.
• Generic helpers for custom parsing.

Constructors

• NewStdio(): uses os.Stdin and os.Stdout (recommended for interactive CLI use).
• NewWithIO(stdin, stdout): uses custom streams (useful for tests and I/O wiring).

Usage

p, err := prompter.NewStdio()
if err != nil {
    return err
}

name, err := p.String("Name: ", "guest")
if err != nil {
    return err
}

timeout, err := p.Duration("Timeout: ", 2*time.Second)
if err != nil {
    return err
}

_ = name
_ = timeout

mode, err := p.Choices("Mode [fast|safe]: ", []string{"fast", "safe"}, "safe")
if err != nil {
    return err
}

_ = mode

port, err := prompter.PromptValue[int](p, "Port: ", func(s string) (int, error) {
    return strconv.Atoi(strings.TrimSpace(s))
}, 8080)
if err != nil {
    return err
}

_ = port

token, err := prompter.PromptSecretBytes[string](p, "Token: ", func(b []byte) (string, error) {
    return strings.TrimSpace(string(b)), nil
})
if err != nil {
    return err
}

_ = token

Security and Input Limits

• SecretBytes(prompt, requireTTY) uses term.ReadPassword when stdin is a TTY.
• If requireTTY is true and stdin is not a TTY, SecretBytes returns ErrSecretRequiresTTY.
• If requireTTY is false and stdin is not a TTY, SecretBytes reads one line from stdin and logs a warning; bufio internal buffers may retain secret data.
• PromptSecretBytes currently calls SecretBytes(prompt, false).
• PromptSecretBytes zeroes the returned secret byte slice after parsing.
• String and non-TTY SecretBytes enforce a per-line limit of 64 KiB; larger lines return ErrInputTooLong.

Error Behavior

• ErrTooManyDefaultValues: more than one optional default was provided.
• ErrInvalidDefaultChoice: a default choice is not present in the choices list.
• ErrEmptyChoices: Choices was called with an empty choices list.
• ErrSecretRequiresTTY: secret input required a terminal but stdin is not a TTY.
• ErrInputTooLong: a single input line exceeded 64 KiB.
• ErrNilStdin and ErrNilStdout: invalid nil streams passed to NewWithIO.
• ErrNilPrompter and ErrNilParser: invalid nil arguments passed to helper functions.

Documentation

Index

• Variables
• func PromptSecretBytes[T any](p Prompter, prompt string, parse ParseBytesFunc[T]) (T, error)
• func PromptValue[T any](p Prompter, prompt string, parse ParseFunc[T], defaultValue ...T) (T, error)
• type ParseBytesFunc
• type ParseFunc
• type Prompter
  • func NewStdio() (Prompter, error)
  • func NewWithIO(stdin io.Reader, stdout io.Writer) (Prompter, error)

Variables

var (
	// ErrTooManyDefaultValues is returned when more than one optional default
	// value is provided.
	ErrTooManyDefaultValues = errors.New("expected at most one default value")
	// ErrInvalidDefaultChoice is returned when a default choice is not present in
	// the choices set.
	ErrInvalidDefaultChoice = errors.New("invalid default choice")
	// ErrEmptyChoices is returned when Choices is called with no choices.
	ErrEmptyChoices = errors.New("empty choices")
	// ErrSecretRequiresTTY is returned when secret input requires a terminal but
	// stdin is not a TTY.
	ErrSecretRequiresTTY = errors.New("secret input requires TTY")
	// ErrNilPrompter is returned when a nil Prompter is provided.
	ErrNilPrompter = errors.New("nil prompter")
	// ErrNilParser is returned when a nil parse function is provided.
	ErrNilParser = errors.New("nil parser")
	// ErrNilStdin is returned when NewWithIO receives a nil stdin reader.
	ErrNilStdin = errors.New("nil stdin")
	// ErrNilStdout is returned when NewWithIO receives a nil stdout writer.
	ErrNilStdout = errors.New("nil stdout")
	// ErrInputTooLong is returned when a single input line exceeds the maximum
	// accepted byte length.
	ErrInputTooLong = errors.New("input too long")
)

Functions

func PromptSecretBytes

func PromptSecretBytes[T any](p Prompter, prompt string, parse ParseBytesFunc[T]) (T, error)

PromptSecretBytes prompts for secret input and parses it with parse. It uses SecretBytes with requireTTY set to false. The returned secret byte slice is zeroed after parse returns.

func PromptValue

func PromptValue[T any](p Prompter, prompt string, parse ParseFunc[T], defaultValue ...T) (T, error)

PromptValue prompts for a string and converts it to T via parse. If input is empty (after TrimSpace) and a default is provided, the default is returned and parse is not called.

Types

type ParseBytesFunc

type ParseBytesFunc[T any] func([]byte) (T, error)

ParseBytesFunc parses secret byte input into a typed value.

type ParseFunc

type ParseFunc[T any] func(string) (T, error)

ParseFunc parses a string input into a typed value.

type Prompter

type Prompter interface {
	// String prompts for a string value.
	// If the entered value is empty (after TrimSpace) and a default is provided,
	// the default is returned.
	String(prompt string, defaultValue ...string) (string, error)
	// SecretBytes prompts for secret input and returns it as bytes.
	// On TTY stdin, input is read via term.ReadPassword (no echo).
	// If requireTTY is true and stdin is not a TTY, ErrSecretRequiresTTY is returned.
	// If requireTTY is false and stdin is not a TTY, one line is read up to
	// maxInputLineBytes. In this mode, bufio.Reader internal buffers may retain
	// secret data.
	SecretBytes(prompt string, requireTTY bool) ([]byte, error)
	// Choices prompts until the input matches one of the provided choices.
	// If the entered value is empty (after TrimSpace) and a default is provided,
	// the default is returned.
	Choices(prompt string, choices []string, defaultValue ...string) (string, error)
	// Int64 prompts for a signed 64-bit integer.
	Int64(prompt string, defaultValue ...int64) (int64, error)
	// Float64 prompts for a float64.
	Float64(prompt string, defaultValue ...float64) (float64, error)
	// Duration prompts for a time.Duration.
	Duration(prompt string, defaultValue ...time.Duration) (time.Duration, error)
}

func NewStdio

func NewStdio() (Prompter, error)

NewStdio creates a Prompter backed by os.Stdin and os.Stdout. This is the recommended constructor for interactive terminal use.

func NewWithIO

func NewWithIO(stdin io.Reader, stdout io.Writer) (Prompter, error)

NewWithIO creates a Prompter from custom input and output streams. This is useful for tests and non-standard I/O wiring.