cli

Documentation

Overview

Package cli provides common utilities for building command-line interfaces.

Index

• Variables
• type CheckCmd
  • func (cmd *CheckCmd) Run(ctx *kong.Context, globals *Globals) error
• type CommandError
  • func NewCommandError(exitCode int) *CommandError
  • func (e *CommandError) Error() string
  • func (e *CommandError) ExitCode() int
• type CommandResult
  • func Failure(err error) CommandResult
  • func Success() CommandResult
• type Commands
• type DoctorCmd
• type ErrorRenderer
  • func NewErrorRenderer(source []byte) *ErrorRenderer
  • func (r *ErrorRenderer) Render(err error) string
  • func (r *ErrorRenderer) RenderAll(errs []error) string
• type FileOrStdin
  • func (f *FileOrStdin) Decode(ctx *kong.DecodeContext) error
  • func (f *FileOrStdin) EnsureContents() error
  • func (f *FileOrStdin) GetAbsoluteFilename() string
  • func (f *FileOrStdin) GetSourceContent() ([]byte, error)
  • func (f *FileOrStdin) LoadAST(ctx context.Context, ldr *loader.Loader) (*ast.AST, error)
• type FormatCmd
  • func (cmd *FormatCmd) Run(ctx *kong.Context, globals *Globals) error
• type Globals
• type LexCmd
  • func (cmd *LexCmd) Run(ctx *kong.Context, globals *Globals) error
• type WebCmd
  • func (cmd *WebCmd) Run(ctx *kong.Context, globals *Globals) error

Variables

var (
	Version   = ""
	CommitSHA = ""
)

Types

type CheckCmd

type CheckCmd struct {
	File FileOrStdin `help:"Beancount input filename (use '-' for stdin, or omit for stdin)." arg:"" optional:""`
}

func (*CheckCmd) Run

func (cmd *CheckCmd) Run(ctx *kong.Context, globals *Globals) error

type CommandError

type CommandError struct {
	// contains filtered or unexported fields
}

CommandError signals a command failure with a specific exit code. Commands return this after handling all output (printing errors/warnings to stderr). Main centralizes exit handling instead of commands calling os.Exit directly.

func NewCommandError

func NewCommandError(exitCode int) *CommandError

NewCommandError creates a new CommandError with the given exit code.

func (*CommandError) Error

func (e *CommandError) Error() string

Error implements the error interface.

func (*CommandError) ExitCode

func (e *CommandError) ExitCode() int

ExitCode returns the exit code associated with this error.

type CommandResult

type CommandResult struct {
	// ExitCode is the exit code to return to the OS.
	// 0 indicates success, non-zero indicates failure.
	ExitCode int

	// Err is any error that occurred during command execution.
	// Commands should populate this for non-zero exit codes.
	Err error
}

CommandResult encapsulates the outcome of a command execution. It allows commands to return structured results instead of calling os.Exit directly, enabling better testability and centralizing exit handling in main().

func Failure

func Failure(err error) CommandResult

Failure returns a CommandResult indicating failure with the given error.

func Success

func Success() CommandResult

Success returns a CommandResult indicating successful execution.

type Commands

type Commands struct {
	Globals

	Check  CheckCmd  `cmd:"" help:"Parse, check and realize a beancount input file."`
	Doctor DoctorCmd `cmd:"" help:"Doctor utilities for debugging beancount files."`
	Format FormatCmd `cmd:"" help:"Format a beancount file to align numbers and currencies."`
	Web    WebCmd    `cmd:"" help:"Start a web server."`
}

type DoctorCmd

type DoctorCmd struct {
	Lex LexCmd `cmd:"" help:"Show lexical tokens from a beancount file."`
}

DoctorCmd provides doctor utilities for debugging beancount files.

type ErrorRenderer

type ErrorRenderer struct {
	// contains filtered or unexported fields
}

ErrorRenderer renders errors with terminal styling and source context.

func NewErrorRenderer

func NewErrorRenderer(source []byte) *ErrorRenderer

NewErrorRenderer creates a renderer with source content for context.

func (*ErrorRenderer) Render

func (r *ErrorRenderer) Render(err error) string

Render formats a single error with styling and context.

func (*ErrorRenderer) RenderAll

func (r *ErrorRenderer) RenderAll(errs []error) string

RenderAll formats multiple errors, separating them with blank lines.

type FileOrStdin

type FileOrStdin struct {
	Filename string
	Contents []byte
}

FileOrStdin accepts either a file path or "-" for stdin. For stdin: Filename="<stdin>", Contents populated. For files: Filename set, Contents nil (read by loader).

func (*FileOrStdin) Decode

func (f *FileOrStdin) Decode(ctx *kong.DecodeContext) error

Decode implements kong.MapperValue.

func (*FileOrStdin) EnsureContents

func (f *FileOrStdin) EnsureContents() error

EnsureContents populates Contents from stdin if Filename is empty.

func (*FileOrStdin) GetAbsoluteFilename

func (f *FileOrStdin) GetAbsoluteFilename() string

GetAbsoluteFilename returns the absolute path, or "<stdin>" for stdin.

func (*FileOrStdin) GetSourceContent

func (f *FileOrStdin) GetSourceContent() ([]byte, error)

GetSourceContent returns source content for error formatting.

func (*FileOrStdin) LoadAST

func (f *FileOrStdin) LoadAST(ctx context.Context, ldr *loader.Loader) (*ast.AST, error)

LoadAST loads the AST using LoadBytes for stdin or Load for files.

type FormatCmd

type FormatCmd struct {
	File           FileOrStdin `help:"Beancount input filename (use '-' for stdin, or omit for stdin)." arg:"" optional:""`
	CurrencyColumn int         `` /* 130-byte string literal not displayed */
	PrefixWidth    int         `help:"Width in characters for account names (auto if 0)." default:"0"`
	NumWidth       int         `help:"Width for numbers (auto if 0)." default:"0"`
}

func (*FormatCmd) Run

func (cmd *FormatCmd) Run(ctx *kong.Context, globals *Globals) error

type Globals

type Globals struct {
	Telemetry bool `help:"Show timing telemetry for operations."`
}

Globals defines global flags available to all commands.

type LexCmd

type LexCmd struct {
	File FileOrStdin `help:"Beancount input filename (use '-' for stdin, or omit for stdin)." arg:"" optional:""`
}

LexCmd shows lexical tokens from a beancount file.

func (*LexCmd) Run

func (cmd *LexCmd) Run(ctx *kong.Context, globals *Globals) error

Run executes the lex command.

type WebCmd

type WebCmd struct {
	File     string `help:"Beancount ledger file to serve." arg:""`
	Host     string `help:"Host to bind to." default:"127.0.0.1"`
	Port     int    `help:"Port to listen on." default:"8080"`
	Create   bool   `help:"Automatically create file if it doesn't exist (no confirmation prompt)." short:"c"`
	ReadOnly bool   `help:"Enable read-only mode (no write operations allowed)." short:"r"`
	Watch    bool   `help:"Watch files for changes and auto-reload." short:"w"`
}

func (*WebCmd) Run

func (cmd *WebCmd) Run(ctx *kong.Context, globals *Globals) error