cli

Documentation

Index

• Constants
• func InputChan(file *os.File) <-chan rune
• func ProcessInput(ctx context.Context, file *os.File, commands Commands)
• func Prompt(format string, v ...interface{})
• func PromptVerbose(format string, v ...interface{})
• func SetCommands(c Commands)
• func SetupLogging(setup LogSetupFunc)
• func SigWait(ctx context.Context, cancel context.CancelFunc) (os.Signal, error)
• func WithSigWait(parent context.Context, opt ...Option) (context.Context, context.CancelFunc)
• type Clock
  • func (c *Clock) Chars(tickInterval time.Duration) string
  • func (c *Clock) DisplayTime(tickInterval time.Duration) *DisplayTime
  • func (c *Clock) Start(ctx context.Context, tickTime time.Duration) <-chan *DisplayTime
• type Command
  • func (c *Command) Run()
  • func (c *Command) StartsWithKey() bool
• type CommandInfoFormatter
• type Commands
  • func GetCommands() Commands
  • func QuitCommands(fn func()) Commands
  • func (c Commands) Get(r rune) *Command
  • func (c Commands) Help() string
  • func (c Commands) Info(fn CommandInfoFormatter) []string
  • func (c Commands) Run(r rune) error
  • func (c Commands) RunScript(s string) error
  • func (c Commands) String() string
• type DisplayTime
• type LogSetupFunc
• type Option
  • func WithInput(commands []Command) Option
  • func WithQuit() Option
  • func WithoutClock() Option
• type RestoreFunc
  • func ClaimTerminal() (RestoreFunc, error)
• type Term
  • func AcquireTerm() (*Term, func())
  • func GetTerm() *Term
  • func (c *Term) GetClock() *Clock
  • func (c *Term) GetMessage() string
  • func (c *Term) Help()
  • func (c *Term) IsDebug() bool
  • func (c *Term) IsRaw() bool
  • func (c *Term) IsVerbose() bool
  • func (c *Term) Println(s string) (int, error)
  • func (c *Term) Prompt(v ...string)
  • func (c *Term) SetDebug(v bool) *Term
  • func (c *Term) SetMessage(msg string)
  • func (c *Term) SetVerbose(v bool) *Term
  • func (c *Term) StartClock(ctx context.Context)
  • func (c *Term) Sync() (int, error)
  • func (c *Term) WrapOutput(w io.Writer)
  • func (c *Term) Write(b []byte) (int, error)
  • func (c *Term) WriteString(s string) (int, error)

Constants

const (
	// TimeFormatHuman is the only reasonable time format for human readability.
	TimeFormatHuman = "2006-01-02 15:04:05"
	ClearAll        = "\r                                                                                          \r"
)

Supported logger types

const (
	// CR is the carriage return byte
	CR = byte(13)

	// NL is the newline byte
	NL = byte(10)
)

Functions

func InputChan

func InputChan(file *os.File) <-chan rune

InputChan listens for runes on stdin and writes them to the returned channel.

func ProcessInput

func ProcessInput(ctx context.Context, file *os.File, commands Commands)

ProcessInput reads runes from input chan and executes the `commands` mapped to the received input keys.

func Prompt

func Prompt(format string, v ...interface{})

Prompt sets the global prompt message displayed in the interactive log line.

func PromptVerbose

func PromptVerbose(format string, v ...interface{})

PromptVerbose sets the global prompt message if in debug mode.

func SetCommands

func SetCommands(c Commands)

SetCommands sets the global commands.

func SetupLogging

func SetupLogging(setup LogSetupFunc)

SetupLogging configures interactive logging for commandline applications.

func SigWait

func SigWait(ctx context.Context, cancel context.CancelFunc) (os.Signal, error)

SigWait waits for OS signals and cancels the given context on SIGINT or SIGTERM. It blocks until the context is canceled either by the awaited signal or externally. It returns the received signal and the context's error.

func WithSigWait

func WithSigWait(parent context.Context, opt ...Option) (context.Context, context.CancelFunc)

WithSigWait returns a context.Context that is canceled on OS signal.

WithSigWait starts a goroutine that waits for OS signals SIGINT or SIGTERM and cancels the returned context after receiving the signal. Depending on the options, WithSigWait starts processing input and sets up commands.

Types

type Clock

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

Clock stores the current clock step and text.

func (*Clock) Chars

func (c *Clock) Chars(tickInterval time.Duration) string

Chars returns the clock chars.

func (*Clock) DisplayTime

func (c *Clock) DisplayTime(tickInterval time.Duration) *DisplayTime

DisplayTime returns the current clock text.

func (*Clock) Start

func (c *Clock) Start(ctx context.Context, tickTime time.Duration) <-chan *DisplayTime

Start starts the clock.

type Command

type Command struct {
	Name string
	Key  rune
	Fn   func()
}

Command define a command.

func (*Command) Run

func (c *Command) Run()

Run runs the command and sets the Prompt to indicate that the command was run.

func (*Command) StartsWithKey

func (c *Command) StartsWithKey() bool

StartsWithKey tells if a command name starts with the command key.

type CommandInfoFormatter

type CommandInfoFormatter func(Command) string

CommandInfoFormatter formats a command.

type Commands

type Commands []Command

Commands provides convenient functions on a list of commands.

func GetCommands

func GetCommands() Commands

GetCommands returns a copy of the global commands.

func QuitCommands

func QuitCommands(fn func()) Commands

QuitCommands returns quit commands.

func (Commands) Get

func (c Commands) Get(r rune) *Command

Get returns a command or nil.

func (Commands) Help

func (c Commands) Help() string

Help returns the command names and keys, one command per line.

func (Commands) Info

func (c Commands) Info(fn CommandInfoFormatter) []string

Info returns the command names and keys as strings.

func (Commands) Run

func (c Commands) Run(r rune) error

Run runs a command or returns a NotFound error.

func (Commands) RunScript

func (c Commands) RunScript(s string) error

RunScript runs the given script with the Commands.

func (Commands) String

func (c Commands) String() string

String returns the command names and keys on a single line.

type DisplayTime

type DisplayTime struct {
	time.Time
	// contains filtered or unexported fields
}

DisplayTime defines the visible values for a time.

type LogSetupFunc

type LogSetupFunc func(out io.Writer, timeFormat string) error

LogSetupFunc configures a specific Logger.

type Option

type Option func(*options)

Option defines a sigwait option.

func WithInput

func WithInput(commands []Command) Option

WithInput makes sigwait run the given commands on receiving user input. The keys q, Q, CTRL-C, and CTRL-D are reserved to quit the program.

func WithQuit

func WithQuit() Option

WithQuit add the default quit commands and enables user input.

func WithoutClock

func WithoutClock() Option

WithoutClock disabled the default ascii/unicode clock in the last terminal line.

type RestoreFunc

type RestoreFunc func() error

RestoreFunc restores the terminal.

func ClaimTerminal

func ClaimTerminal() (RestoreFunc, error)

ClaimTerminal sets the terminal to raw input mode and returns a RestoreFunc for resetting the terminal to normal mode.

type Term

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

Term stores shared terminal state about loggers, the underlying terminals, and commands.

func AcquireTerm

func AcquireTerm() (*Term, func())

AcquireTerm locks and returns the global terminal.

func GetTerm

func GetTerm() *Term

GetTerm returns the global terminal state.

func (*Term) GetClock

func (c *Term) GetClock() *Clock

GetClock returns the global clock.

func (*Term) GetMessage

func (c *Term) GetMessage() string

GetMessage set the promt message.

func (*Term) Help

func (c *Term) Help()

Help prints and prompts help for the configured Commands.

func (*Term) IsDebug

func (c *Term) IsDebug() bool

IsDebug returns the debug state.

func (*Term) IsRaw

func (c *Term) IsRaw() bool

IsRaw returns the raw state.

func (*Term) IsVerbose

func (c *Term) IsVerbose() bool

IsVerbose returns the verbose state.

func (*Term) Println

func (c *Term) Println(s string) (int, error)

Println writes the string + "\n" to the terminal.

func (*Term) Prompt

func (c *Term) Prompt(v ...string)

Prompt prints the prompt string in the termnial line.

func (*Term) SetDebug

func (c *Term) SetDebug(v bool) *Term

SetDebug enabled or disables debug output on stderr.

func (*Term) SetMessage

func (c *Term) SetMessage(msg string)

SetMessage set the promt message.

func (*Term) SetVerbose

func (c *Term) SetVerbose(v bool) *Term

SetVerbose enabled or disables verbose output on stderr.

func (*Term) StartClock

func (c *Term) StartClock(ctx context.Context)

StartClock starts the terminal clock to ingest clock output into the status line.

func (*Term) Sync

func (c *Term) Sync() (int, error)

Sync flushes buffers (appending newlines if needed) and clears all output.

func (*Term) WrapOutput

func (c *Term) WrapOutput(w io.Writer)

WrapOutput wraps the given output.

func (*Term) Write

func (c *Term) Write(b []byte) (int, error)

func (*Term) WriteString

func (c *Term) WriteString(s string) (int, error)

WriteString writes the string to the terminal.