cli

Documentation

Overview

Package cli provides utilities for building command-line applications.

Index

• Variables
• func Main(app App)
• func Run(ctx context.Context, app App, env *Env) error
• func SetDocComment(src []byte)
• type App
• type AppFunc
  • func (f AppFunc) Run(ctx context.Context, env *Env) error
• type Env
  • func OSEnv() *Env
  • func (e *Env) Logf(format string, args ...any)
• type HasFlags

Variables

var ErrExitVersion = &unprintableError{errors.New("version flag exit")}

ErrExitVersion is an error indicating the application should exit after showing version.

var ErrInvalidArgs = errors.New("invalid arguments")

This error should be wrapped with fmt.Errorf to provide a specific, user-friendly message explaining the nature of the invalid arguments.

For example:

return fmt.Errorf("%w: missing required argument 'filename'", cli.ErrInvalidArgs)

Functions

func Main

func Main(app App)

Main is a helper function that handles common startup tasks for command-line applications. It sets up signal handling for interrupts, runs the application, and prints errors to stderr.

func Run

func Run(ctx context.Context, app App, env *Env) error

Run handles the command-line application startup.

func SetDocComment

func SetDocComment(src []byte)

SetDocComment stores the provided byte slice as the source for the application's documentation comment.

The parsing process assumes that the documentation comment is enclosed within a single /* ... */ block and extracts the content line by line. Any other multi-line comments within the embedded file will be ignored.

The parsed documentation will be included in the help message.

Example usage

In application's doc.go:

/*
Amazinator does amazing things...

# Usage

	$ amazinator [flags...]

Amazinator amazes amazinations by amazing your amazinators.
*/
package main

import (
	_ "embed"

	"go.astrophena.name/tools/internal/cli"
)

//go:embed doc.go
var doc []byte

func init() { cli.SetDocComment(doc) }

Types

type App

type App interface {
	// Run runs the application.
	Run(context.Context, *Env) error
}

App represents a command-line application.

type AppFunc

type AppFunc func(context.Context, *Env) error

AppFunc is a function type that implements the App interface. It has no defined flags.

func (AppFunc) Run

func (f AppFunc) Run(ctx context.Context, env *Env) error

Run calls f(ctx, env).

type Env

type Env struct {
	Args   []string
	Getenv func(string) string
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
	// contains filtered or unexported fields
}

Env represents the application environment.

func OSEnv

func OSEnv() *Env

OSEnv returns the current operating system environment.

func (*Env) Logf

func (e *Env) Logf(format string, args ...any)

Logf writes the formatted message to standard error of this environment.

type HasFlags

type HasFlags interface {
	App

	// Flags adds flags to the flag set.
	Flags(*flag.FlagSet)
}

HasFlags represents a command-line application that has flags.