Documentation
¶
Overview ¶
Package inputsrc resolves a CLI input to a byte slice (or a stream) from one of six conventional sources: a positional argument, an explicit file path, an interactive file picker, an explicit URL, an interactive URL prompt, or a stdin pipe. The single-dash "-" positional is accepted as an alias for stdin, matching Unix convention.
Callers declare their input flags with NoOptDefVal set to FilePickSentinel or URLPromptSentinel so that `--file` or `--url` without a value triggers the interactive path. An empty flag value means the flag was not set.
Index ¶
Constants ¶
const ( FilePickSentinel = "(pick)" URLPromptSentinel = "(prompt)" )
Sentinel flag values set via pflag's NoOptDefVal. The parenthesised form is used so that pflag's help renderer — which prints `--file string[="<NoOptDefVal>"]` — produces something readable rather than whitespace or control characters. A user typing `--file=(pick)` or `--url=(prompt)` will hit the interactive flow, which is harmless since those literal filenames/URLs are effectively impossible in practice.
Variables ¶
var ErrNoInput = errors.New("no input provided")
ErrNoInput signals that no input method matched. Callers typically show command help in response. It is never wrapped, so callers can use errors.Is for a direct equality check.
var ErrNoTTY = errors.New("interactive prompt requires a terminal (stdin is piped or redirected)")
ErrNoTTY is returned when an interactive picker or prompt is requested but stdin is not a terminal. Callers can errors.Is against it to offer a non-interactive fallback or a clearer hint to the user.
Functions ¶
func IsStdinPipe ¶
func IsStdinPipe() bool
IsStdinPipe returns true when stdin is connected to a pipe or file (not a terminal). Exported so commands that need to branch on the presence of piped input before calling Resolve can do so without importing os.
func IsStdinTerminal ¶
func IsStdinTerminal() bool
IsStdinTerminal is the inverse of IsStdinPipe. Exported for clarity at call sites that gate interactive prompts on a real TTY.
Types ¶
type Options ¶
type Options struct {
// PositionalArg is the first positional argument, if any. An empty
// string means no positional arg was supplied.
PositionalArg string
// FileFlag is the value of --file (or equivalent). Empty = unset;
// FilePickSentinel triggers the interactive file picker; any other
// non-empty value is treated as a filesystem path.
FileFlag string
// URLFlag is the value of --url (or equivalent). Empty = unset;
// URLPromptSentinel triggers the interactive URL prompt; any other
// non-empty value is downloaded.
URLFlag string
// AllowStdin, when true, reads piped stdin as a fallback when no
// explicit input mode was selected. Ignored when stdin is a TTY.
AllowStdin bool
// AutoDetectURL, when true, treats a positional argument that parses
// as an http/https URL as a download source. Otherwise positional
// args are always treated as file paths.
AutoDetectURL bool
// PickerTitle, PickerExts configure the interactive file picker used
// when FileFlag == FilePickSentinel.
PickerTitle string
PickerExts []string
// URLPromptTitle, URLPromptPlaceholder configure the interactive URL
// prompt used when URLFlag == URLPromptSentinel.
URLPromptTitle string
URLPromptPlaceholder string
// MaxBytes caps in-memory reads from stdin and URLs. 0 = 64 MB.
// File paths are streamed straight from disk and are not affected.
MaxBytes int64
// HTTPTimeout is forwarded to the URL downloader. 0 = use the shared
// httpclient timeout (set during startup).
HTTPTimeout time.Duration
}
Options configures input resolution. Only the subset relevant to the caller's flag surface needs to be set; unset fields disable their mode.
type Source ¶
type Source struct {
Type SourceType
Path string
Size int64 // -1 when unknown
}
Source describes where the resolved bytes came from. Path holds a filesystem path (for SourceFile/SourcePicker) or a URL (for SourceURL). For SourceStdin, Path is "-" to match the Unix convention used by tools like sha256sum.
func Resolve ¶
Resolve reads the caller's selected input and returns its bytes along with a Source description. Priority (highest first):
- FileFlag (sentinel triggers picker, else filesystem path)
- URLFlag (sentinel triggers prompt, else URL)
- PositionalArg ("-" means stdin; http/https URL when AutoDetectURL; else path)
- Stdin pipe (only when AllowStdin is true and stdin is not a TTY)
Returns ErrNoInput when none of the above matched. The context is honoured for URL downloads and stdin reads.
func ResolveStream ¶
ResolveStream returns a streaming reader for the selected input. Used by the hash command to avoid buffering large files in memory. URL downloads still buffer into memory (capped by MaxBytes) because the shared HTTP client does not currently expose a streaming body helper.
func (Source) DisplayName ¶
DisplayName returns a human-friendly identifier for the source. Files and URLs use their path/URL; stdin renders as "-".
type SourceType ¶
type SourceType string
SourceType identifies where the resolved bytes came from.
const ( SourceFile SourceType = "file" SourceStdin SourceType = "stdin" SourceURL SourceType = "url" SourcePicker SourceType = "picker" )
Source Files