README
¶
chalk
Task-oriented I/O helper for Golang CLI. It wires together flag-driven input/output routing (local filesystem, S3, stdin/stdout) with a live terminal progress UI so you can focus on the processing logic.
Features
- Resolves input from a local directory (
-I ./path), an S3 bucket (-I s3://bucket), explicit file arguments, or stdin - Resolves output to a local directory (
-O ./path), an S3 bucket (-O s3://bucket), a single file (-o out.txt), or stdout - Renders a live progress tree with elapsed timers, spinner, and per-task pass/fail status
Quick Start
package main
import (
"context"
"github.com/fogfish/chalk"
)
func process(ctx context.Context, path string, r io.Reader, w io.Writer) error {
chalk.Task(0, path)
// Subtask at level 1
chalk.Task(1, "read")
// ... read from fs
chalk.Done()
chalk.Task(1, "transform")
// ... do work
chalk.Done()
chalk.Done()
return nil
}
func main() {
chalk.Start(process)
}
Run it:
mytool -I ./input -O ./output
mytool -I s3://my-bucket -O s3://out-bucket
cat file.txt | mytool
License
See LICENSE.
Documentation
¶
Index ¶
- func Commit[T any](key string, val T)
- func Done(suffix ...string)
- func Fail(err error)
- func NoColor()
- func NoTTY()
- func Panic(err error)
- func Printf(format string, args ...any)
- func Recover[T any](key string, def T) T
- func Start(f spool.Spooler)
- func Sub(ctx context.Context) context.Context
- func Task(ctx context.Context, label string, args ...any)
- type Proxy
- type Reporter
- type Stdio
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Done ¶
func Done(suffix ...string)
Done marks the current task as successfully completed. An optional note is appended after the task label, e.g. Done("(hits 50)").
func NoColor ¶ added in v0.0.6
func NoColor()
NoColor disables color output in TTY mode, using plain black & white styles. Must be called before Start.
func NoTTY ¶ added in v0.0.6
func NoTTY()
NoTTY forces log-mode output (structured slog records, no colour, no spinner) even when stderr is an interactive terminal. Must be called before Start.
func Start ¶
Start wires up the default Reporter, parses flags, and runs the provided Spooler. It is the main entry-point for CLI tools built on this library.
Types ¶
type Reporter ¶
type Reporter struct {
// contains filtered or unexported fields
}
Reporter manages progress output using one of two printer strategies: ttyPrinter (colours + spinner) when stderr is an interactive terminal, or logPrinter (structured slog records) otherwise.
func Init ¶ added in v0.0.8
func Init() *Reporter
Init creates a Reporter that writes to stderr, automatically selecting the ttyPrinter or logPrinter strategy based on whether stderr is a terminal. If NoTTY has been called, logPrinter is always used regardless of the terminal.
func (*Reporter) Done ¶
Done marks the current (innermost) task as successfully completed. An optional note is appended after the task label, e.g. Done("(hits 50)").
func (*Reporter) Fail ¶
Fail marks the current (innermost) task as failed. err is printed beneath the task line (ttyPrinter) or included as a structured field (logPrinter).
func (*Reporter) Printf ¶ added in v0.0.4
Printf prints a formatted message indented under the current task.
func (*Reporter) Quit ¶
func (r *Reporter) Quit()
Quit stops any animation and marks all remaining tasks as done.
func (*Reporter) Sub ¶ added in v0.0.8
Sub returns a child context with the task nesting level incremented by one. Pass the returned context to Task to start a nested sub-task.
func (*Reporter) Task ¶
Task begins a new task at the nesting level carried by ctx. Use WithLevel to produce a context for sub-tasks. Any currently active tasks at the same or deeper level are automatically completed before the new task starts, which simplifies error handling — callers do not need to guarantee a matching Done/Fail on every code path.
type Stdio ¶ added in v0.0.8
type Stdio interface {
Sub(ctx context.Context) context.Context
Task(ctx context.Context, label string, args ...any)
Done(suffix ...string)
Fail(err error)
Printf(format string, args ...any)
}
Stdio is the progress-reporting interface implemented by *Reporter. Accept Stdio in your own APIs to decouple callers from this package: any value whose method set matches Stdio satisfies the interface without importing chalk.
Source Files
Directories