builtinutil

func Align ¶

func Align(rows [][]string, sep string) string

Align takes a sequence of rows (each row is a sequence of cells) and renders them as a column-aligned table. Cells in the same column are padded with sep so their right edges align. The trailing column is NOT padded.

Empty rows produce an empty line. nil rows is a zero-length result. The separator must be non-empty.

Used by the `column -t` built-in (Wave C) and is shared with Wave B's `ls` long-form / multi-column output.

func Errorf ¶

func Errorf(stderr io.Writer, cmd string, code int, format string, args ...any) command.Result

Errorf writes "<cmd>: <msg>\n" to stderr and returns a Result with the given exit code. The "<cmd>: " prefix mirrors coreutils diagnostics (e.g. "basename: missing operand"). Pass an empty cmd to suppress the prefix.

func HumanSize ¶

func HumanSize(n int64) string

HumanSize formats n using IEC suffixes (B, K, M, G, T, P, E) with a 1024 divisor, matching coreutils `du -h` / `ls -h` rounding rules:

• n < 1024 -> "<n>" (no suffix; integer)
• otherwise pick the largest unit with quotient >= 1
• render with one decimal place if quotient < 10, else integer ("9.8K", "10K", "1023K")
• always round UP (ceiling) to match coreutils behavior

func OpenInput ¶

func OpenInput(c *command.Context, name string) (io.Reader, io.Closer, error)

OpenInput returns an io.Reader for the given operand. The literal "-" or "" means c.Stdin (returning a discard-on-nil reader). Otherwise the path is resolved against c.Cwd and opened via c.FS. The caller is responsible for closing any returned io.Closer.

func ParseChmodMode ¶

func ParseChmodMode(spec string, current os.FileMode, isDir bool) (os.FileMode, error)

ParseChmodMode parses a chmod mode string (numeric like "755" or symbolic like "u+x,g-w,o=r") and applies it on top of the given current file mode, returning the resulting mode.

Numeric mode: parsed as octal; the returned value masks current special bits (setuid/setgid/sticky) when only three digits supplied — coreutils behavior.

Symbolic mode: one or more comma-separated clauses. Each clause is "[ugoa]*[-+=][rwxXst]*". Empty user-set defaults to "a", subject to umask (we do NOT apply umask here — the caller decides). 'X' is a conditional execute (only set when target is a directory or any execute bit is already set — caller passes isDir).

func PrintHelp ¶

func PrintHelp(w io.Writer, usage string)

PrintHelp writes usage + a trailing newline to w. The spec contract: --help exits 0 with usage written to stdout. The trailing newline matches real GNU coreutils.

func ReadAllInputs ¶

func ReadAllInputs(c *command.Context, names []string) ([]byte, error)

ReadAllInputs reads each operand sequentially (with the same "-" convention as OpenInput) and returns the concatenated bytes. If names is empty, stdin is read.

func ResolvePath ¶

func ResolvePath(cwd, p string) string

ResolvePath joins a possibly-relative path against the dispatch Cwd and returns the cleaned absolute form. Empty cwd is treated as "/" so paths still resolve to a usable absolute form.

func ScanLines ¶

func ScanLines(r io.Reader) *bufio.Scanner

ScanLines returns a *bufio.Scanner sized to handle long lines (16 MiB max). The scanner uses bufio.ScanLines (no trailing \n in the returned token).

func UsageError ¶

func UsageError(stderr io.Writer, usage string) command.Result

UsageError writes "usage: <usage>\n" to stderr and returns the canonical exit-2 result. The spec contract: unknown options exit 2 with "usage: ..." to stderr, except where real bash silently ignores them (callers that need the bash-silent behavior should not call this helper).