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"
"io"
"github.com/fogfish/chalk"
"github.com/fogfish/chalk/rt/cli"
)
func process(ctx context.Context, path string, r io.Reader, w io.Writer) error {
chalk.Task(ctx, path)
// Subtask at level 1
chalk.Task(chalk.Sub(ctx), "read")
// ... read from fs
chalk.Done()
chalk.Task(chalk.Sub(ctx), "transform")
// ... do work
chalk.Done()
chalk.Done()
return nil
}
func main() {
cli.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 Done(suffix ...string)
- func Fail(err error)
- func Panic(err error)
- func Printf(format string, args ...any)
- func SetDefault(r *Reporter)
- func Sub(ctx context.Context) context.Context
- func Task(ctx context.Context, label string, args ...any)
- type Entry
- type Option
- type Printer
- 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 SetDefault ¶ added in v0.0.13
func SetDefault(r *Reporter)
SetDefault replaces the package-level Reporter used by Task/Done/Fail/ Printf/Panic and by Stdout.
Types ¶
type Entry ¶ added in v0.0.13
type Entry struct {
Level int // nesting level (0 = top-level)
Label string // formatted task label
Note string // optional Done() suffix
StartTime time.Time // when Task() was called for this entry
}
Entry describes a task at a point in its lifecycle. It is passed to Printer methods by value.
type Option ¶ added in v0.0.13
type Option func(*config)
Option configures a Reporter built by New.
func WithColor ¶ added in v0.0.13
WithColor enables or disables ANSI colour in TTY mode. Defaults to true.
func WithLogger ¶ added in v0.0.13
WithLogger sets the slog.Logger used by the log printer. Defaults to slog.Default().
func WithOutput ¶ added in v0.0.13
WithOutput sets the writer used by the TTY/log printers. Defaults to os.Stderr.
func WithPrinter ¶ added in v0.0.13
WithPrinter overrides the printer selection entirely with p.
func WithSilent ¶ added in v0.0.13
func WithSilent() Option
WithSilent disables all output, including errors.
type Printer ¶ added in v0.0.13
type Printer interface {
// Running is called for a parent task that remains active while a
// child task starts — i.e. the parent becomes "displaced" and needs
// its own visible record.
Running(e Entry)
// Done is called when a task completes successfully.
Done(e Entry)
// Failed is called when a task completes with an error.
Failed(e Entry, err error)
// Text emits an informational message (Printf) at the given indent
// level. level == -1 means "no active task".
Text(level int, text string)
// Panic is called after all pending tasks have been failed.
// Implementations typically print and os.Exit(1).
Panic(err error)
}
Printer renders task lifecycle events. Implement this interface to ship progress to a custom sink (database, websocket, OpenTelemetry span, ...). All methods are called while the Reporter's internal mutex is held — implementations must not call back into the Reporter.
func MultiPrinter ¶ added in v0.0.13
MultiPrinter returns a Printer that forwards every event to each of printers, in order.
type Reporter ¶
type Reporter struct {
// contains filtered or unexported fields
}
Reporter manages progress output using a Printer strategy: ttyPrinter (colours + spinner), logPrinter (structured slog records), silentPrinter, or any user-supplied Printer.
func Default ¶ added in v0.0.13
func Default() *Reporter
Default returns the package-level Reporter used by Task/Done/Fail/Printf.
func New ¶ added in v0.0.13
New builds a Reporter. With no options it auto-detects: ttyPrinter on os.Stderr if it's an interactive terminal, logPrinter otherwise.
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 Sub 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
¶
| Path | Synopsis |
|---|---|
|
Package checkpoint provides a small file-based cache for resumable, task-oriented CLIs: Recover loads a previously Commit-ed value by key, or returns the supplied default if no cache is configured or the value is missing/unreadable.
|
Package checkpoint provides a small file-based cache for resumable, task-oriented CLIs: Recover loads a previously Commit-ed value by key, or returns the supplied default if no cache is configured or the value is missing/unreadable. |
|
rt
|
|
|
cli
Package cli is a stdlib flag-based runner for chalk-based, task-oriented CLIs.
|
Package cli is a stdlib flag-based runner for chalk-based, task-oriented CLIs. |
|
cobra
Package cobra integrates chalk with github.com/spf13/cobra (or any other flag library exposing a pflag.FlagSet-shaped API) without importing cobra/pflag directly.
|
Package cobra integrates chalk with github.com/spf13/cobra (or any other flag library exposing a pflag.FlagSet-shaped API) without importing cobra/pflag directly. |
|
internal/spool
Package spool resolves chalk's standard input/output routing (local directory, S3 bucket, explicit file list, stdin/stdout) to github.com/fogfish/stream/spool primitives.
|
Package spool resolves chalk's standard input/output routing (local directory, S3 bucket, explicit file list, stdin/stdout) to github.com/fogfish/stream/spool primitives. |