gocular

README

gocular

A simple TUI library for Go.

Documentation

Index

• Constants
• 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

Constants

const (
	DEFAULT_DELAY           = time.Millisecond * 500
	DEFAULT_ELEMENTS        = "/|\\-"
	DEFAULT_DOT_COUNT       = 3
	DEFAULT_BAR_LENGTH      = 20
	DEFAULT_SHOW_PERCENTAGE = true
)

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