gocular

README

gocular

A simple TUI library for Go.

For small, portable applications that don't need a major interface.

---

Colour

ColourSet : struct

Holds Primary, Secondary, Success, Error and Bracket colours. These are all used at various points in the program.

• Update(primary *colour.Color, ...)

  Used to update the values of a ColourSet object.

NewColourSet(primary *colour.Color, ...)

Returns a newly created ColourSet object from the colours provided. This can be used to create your own "themes" instead of using the default.

DefaultColourSet()

Generates the default ColourSet object: light cyan as primary, light magenta as secondary, green as success, red as error and grey as bracket.

Progress

Progress : struct

Holds presets for the progress functions. This is useful for re-using progress bars and cycles.

• Cycle(...), Dots(...) and Bar(...)

  Relays for the ProgressCycle, ProgressDots and ProgressBar functions that fill many of the tedious arguments with the values stored within Progress.

NewProgress(delay time.Duration, ...)

Creates a new instance of Progress with the given values.

DefaultProgress(colourSet *ColourSet)

Initialises and returns a default Progress object. If colourSet is nil, a DefaultColourSet() is generated instead.

ProgressCycle(...), ProgressDots(...) and ProgressBar(...)

All of these functions take tedious and often obsolete arguments for the sake of customability. To simplify the use of these functions, use a Progress object - it saves time, data and is easier to understand. Further documentation can be found within the source code, however I heavily suggest you use a Progress struct.

Input

Input : struct

Holds re-usable values for the input functions.

• Choices(...), Prompt(...) and Boolean(...)

  These functions are relays for the InputChoices, InputPrompt and InputBoolean functions.

InputChoices(choices []string, ...)

Presents each of the choices to the user with the prompt. When the user picks a choice by number, the choice's index in the choices slice is returned. If retry is true, when the choice is out of range or not a valid integer, the error will be returned rather than be ignored and prompt the user again.

InputPrompt(prompt string, ...)

Prompts the user with prompt and expects a response. If no response is provided and retry is true, the user will be prompted again. If retry is false, the empty response is returned.

InputBoolean(prompt string, ...)

Prints the prompt given and asks the user to provide y or n in traditional UNIX style. If fallback is true, then y will be the default option and will be capitalised in the console, if false: the same but for n.

Terminal

ClearLine()

Clears the previous line from the console.

ClearLines(x int)

Clears x previous lines from the console.

Documentation

Index

• func ClearLine()
• func ClearLines(x int)
• func InputBoolean(prompt string, fallback bool, colours *ColourSet) bool
• func InputChoices(choices []string, prompt string, retry bool, colours *ColourSet) (int, error)
• func InputPrompt(prompt string, retry bool, colours *ColourSet) string
• func ProgressBar(runner func(current *int, err *error), text string, success string, ...) error
• func ProgressCycle(runner func(done *bool, err *error), text string, success string, ...) error
• func ProgressDots(runner func(done *bool, err *error), text string, success string, ...) error
• type ColourSet
  • func DefaultColourSet() *ColourSet
  • func NewColourSet(primary *colour.Color, secondary *colour.Color, success *colour.Color, ...) *ColourSet
  • func (colours *ColourSet) Update(primary *colour.Color, secondary *colour.Color, success *colour.Color, ...)
• type Input
  • func NewInput(retry bool, fallback bool, colours *ColourSet) *Input
  • func (in *Input) Boolean(prompt string) bool
  • func (in *Input) Choices(choices []string, prompt string) (int, error)
  • func (in *Input) Prompt(prompt string) string
• type Progress
  • func DefaultProgress(colourSet *ColourSet) *Progress
  • func NewProgress(delay time.Duration, elements string, dotCount int, barLength int, ...) *Progress
  • func (pp *Progress) Bar(runner func(current *int, err *error), text string, success string, ...) error
  • func (pp *Progress) Cycle(runner func(done *bool, err *error), text string, success string, ...) error
  • func (pp *Progress) Dots(runner func(done *bool, err *error), text string, success string, ...) error

Functions

func ClearLine

func ClearLine()

Clears the previous line from the console.

func ClearLines

func ClearLines(x int)

Clears `x` lines from the console.

func InputBoolean

func InputBoolean(prompt string, fallback bool, colours *ColourSet) bool

Prints the `prompt` given and asks the user to provide 'y' or 'n'. `fallback` determines the default state - if the user provides a character or phrase that is not `y` or `n`, the boolean value returned will default to `fallback`.

func InputChoices

func InputChoices(choices []string, prompt string, retry bool, colours *ColourSet) (int, error)

Provides `choices` to the user with a `prompt`. Returns the index of the chosen choice. If `retry` is `true`, when the index of the choice is out of range, or not an integer, the user will be prompted again - otherwise, the `error` generated will be returned.

func InputPrompt

func InputPrompt(prompt string, retry bool, colours *ColourSet) string

Prints the `prompt` to the console and awaits a response from the user. If `retry` is `true`, when a blank input is provided from the user, they will be prompted again until a non-blank response is provided.

func ProgressBar

func ProgressBar(runner func(current *int, err *error), text string, success string, failure string, max int, bar int, showPercentage bool, delay time.Duration, colours *ColourSet) error

Receives progress from the goroutine `runner` through `current`. Current is parsed as a fraction of `max` and displayed in the terminal as a progress bar. The length of the progress bar is determined by the `bar` value. The progress bar will changed to a finished state when `current` is equal to `max`. `delay` is the update frequency.

func ProgressCycle

func ProgressCycle(runner func(done *bool, err *error), text string, success string, failure string, cycle string, delay time.Duration, colours *ColourSet) error

Prints `text` with a cyclic prefix (e.g. \ -> | -> / -> -). The cycle characters are specified through the `cycle` slice. Changes to the next `cycle` string every `delay` duration. Stops when `done` is `true`.

func ProgressDots

func ProgressDots(runner func(done *bool, err *error), text string, success string, failure string, count int, delay time.Duration, colours *ColourSet) error

Displays `text` with a series of trailing dots. Adds another dot every `delay` duration. The maximum number of dots is specified by the `count` integer. Changes to finished text when `done` is equal to `true`.

Types

type ColourSet

type ColourSet struct {
	Primary   *colour.Color
	Secondary *colour.Color
	Success   *colour.Color
	Error     *colour.Color
	Bracket   *colour.Color
}

Holds primary, secondary, success, error and bracket colours.

func DefaultColourSet

func DefaultColourSet() *ColourSet

Creates and returns a default `ColourSet` object.

func NewColourSet

func NewColourSet(primary *colour.Color, secondary *colour.Color, success *colour.Color, error_ *colour.Color, bracket *colour.Color) *ColourSet

Returns a new `ColourSet` from the provided values.

func (*ColourSet) Update

func (colours *ColourSet) Update(primary *colour.Color, secondary *colour.Color, success *colour.Color, error_ *colour.Color, bracket *colour.Color)

Updates the `ColourSet`'s values.

type Input

type Input struct {
	Retry    bool
	Fallback bool

	// colourset
	Colours *ColourSet
}

Holds re-usable values for the InputXXXX functions.

func NewInput

func NewInput(retry bool, fallback bool, colours *ColourSet) *Input

Creates a new input from the values given.

func (*Input) Boolean

func (in *Input) Boolean(prompt string) bool

func (*Input) Choices

func (in *Input) Choices(choices []string, prompt string) (int, error)

func (*Input) Prompt

func (in *Input) Prompt(prompt string) string

type Progress

type Progress struct {
	// general
	Delay time.Duration

	// cycle
	Elements string
	DotCount int

	// bar
	BarLength      int
	ShowPercentage bool

	// colourSet
	Colours *ColourSet
}

Holds presets for the progress functions. This is useful if you re-use progress bars or cycles in your project.

func DefaultProgress

func DefaultProgress(colourSet *ColourSet) *Progress

Initialises and returns a default `Progress` instance.

func NewProgress

func NewProgress(delay time.Duration, elements string, dotCount int, barLength int, showPercentage bool, colours *ColourSet) *Progress

Creates a new `Progress` instance given the provided values.

func (*Progress) Bar

func (pp *Progress) Bar(runner func(current *int, err *error), text string, success string, failure string, size int) error

func (*Progress) Cycle

func (pp *Progress) Cycle(runner func(done *bool, err *error), text string, success string, failure string) error

func (*Progress) Dots

func (pp *Progress) Dots(runner func(done *bool, err *error), text string, success string, failure string) error