disgo

package module
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 11, 2019 License: MIT Imports: 8 Imported by: 1

README

Disgo

Simple library for building Go command-line interfaces.

Disgo provides four essential features for most user-friendly CLI applications:

  1. Simple output levels
  2. Output formatting
  3. Step-by-step outputs
  4. Simple user prompting

Table of content

  1. Examples
  2. Terminal
    1. Terminal options
    2. Writing to the Terminal
    3. Step-by-step Processes
    4. Confirmation Prompt
    5. String Input Prompt
  3. Style
    1. Output Formatting
    2. Symbols
  4. License

Examples

Here are a few examples of Disgo's output, used by other repositories:

Terminal

The disgo Terminal provides an easy way to build user-friendly command-line interfaces.

You can use it globally within your application, or you can instantiate your own Terminal.

Terminal options

When creating a Terminal instance or when using the global Terminal that this package provides, you might want to give it some options, such as:

  • WithDebug, which lets you enable or disable the debug output (it is disabled by default)
  • WithDefaultWriter, which lets you specify an io.Writer on which Debug and Info-level outputs should be written (it is set to os.Stdout by default)
  • WithErrorWriter, which lets you specify an io.Writer on which Error-level outputs should be written (it is set to os.Stderr by default)
  • WithReader, which lets you specify an io.Reader from which the Terminal will be able to prompt the user (it is set to os.Stdin by default)
  • WithColors, which lets you explicitely enable or disable colors in your output (it is enabled by default)
  • WithInteractive, which specifies whether the Terminal should run in an interactive way, meaning prompts should wait for user input. If set to false, prompts will instantaneously returns their configured default value (it is set to true by default)

You can either pass those options to disgo.NewTerminal() when creating a Terminal instance, like so:

    term := disgo.NewTerminal(disgo.WithDebug(true))

Or, if you are using the global terminal, you will simply need to call the SetTerminalOptions function:

    disgo.SetTerminalOptions(disgo.WithDebug(true))
Writing to the Terminal

Now that your terminal is set up, you can start writing to it.

Here is how to use them on an instantiated terminal:

    // All of those give the same output:
    // "Number of days in a year: 365" followed by a newline.
    term.Infoln("Number of days in a year:", 365)
    term.Infof("Number of days in a year: %d\n", 365)
    term.Info("Number of days in a year: 365\n")

    // Debug methods are similar to info, except that they are not printed
    // if debug outputs are not enabled on the terminal.
    term.Debugln("Number of days in a year:", 365)
    term.Debugf("Number of days in a year: %d\n", 365)
    term.Debug("Number of days in a year: 365\n")

    // Error methods are similar to info, except that they are written on
    // the error writer (os.Stderr by default).
    term.Errorln("Number of days in a year:", 365)
    term.Errorf("Number of days in a year: %d\n", 365)
    term.Error("Number of days in a year: 365\n")

When using the global terminal, call the terminal printing functions directly:

    // All of those give the same output:
    // "Number of days in a year: 365" followed by a newline.
    disgo.Infoln("Number of days in a year:", 365)
    disgo.Infof("Number of days in a year: %d\n", 365)
    disgo.Info("Number of days in a year: 365\n")

    // Debug methods are similar to info, except that they are not printed
    // if debug outputs are not enabled on the terminal.
    disgo.Debugln("Number of days in a year:", 365)
    disgo.Debugf("Number of days in a year: %d\n", 365)
    disgo.Debug("Number of days in a year: 365\n")


    // Error methods are similar to info, except that they are written on
    // the error writer (os.Stderr by default).
    disgo.Errorln("Number of days in a year:", 365)
    disgo.Errorf("Number of days in a year: %d\n", 365)
    disgo.Error("Number of days in a year: 365\n")
Step-by-step processes

A lot of command-line interfaces describe step-by-step processes to the user, but it's difficult to combine clean code, clear output and elegant user interfaces. Disgo attempts to solve that problem by associating steps to its terminal.

For example, when beginning a task, you can use StartStep and specify the description of that step. Then, until that task is over, all calls to Disgo's printing functions will be queued. Once the task is complete (by calling EndStep, FailStep or by starting another step with StartStep), the task status is printed and all of the outputs that were queued during the task are printed with an indent, under the task, like so:

It is also important to note that FailStep and FailStepf can be used to return errors at the same time as they report a step as having failed. This allows you to write:

    disgo.StartStep("Doing something")
    if err := doSomething(); err != nil {
        return disgo.FailStepf("unable to do something: %v", err)
    }

Instead of having to call FailStep in your error handling before returning. You are still free to do so if you prefer, though.

Using the global terminal for step management is not thread-safe though, as it was built with simplicity in mind and can only handle one step at a time.

Confirmation prompt

The confirmation prompt lets you prompt users for a yes or no answer.

    result, err := disgo.Confirm(disgo.Confirmation{
        Label:              "Install with current database?",
    })

Will produce the following output:

Install with current database? [y/n]

To which the user can answer by y, n, Y, N, yes, no, YES, NO, 0, 1, true, false, etc.

The confirmation prompt supports default values, like so:

    result, err := disgo.Confirm(disgo.Confirmation{
        EnableDefaultValue: true,
        DefaultValue:       false,
        Label:              "Install with current database?",
    })

This will set the default value to false, so that when the user does not have access to a TTY or that he simply presses enter to skip the prompt, a value of your choosing is used.

It's also possible to add your own confirmation parsers, if you don't want the user to answer to a yes/no question for example. This also means that you can customize the choices that will be presented to the user:

    result, err := disgo.Confirm(disgo.Confirmation{
        Label:              "Install with current database?",
        Choices:            []string{"yes", "no"},
        Parser:             func(input string) (bool, error) {
            switch input {
            case "yes":
                return true, nil
            case "no":
                return false, nil
            default:
                return false, fmt.Errorf("invalid input %q", input)
            }
        },
    })

This will output:

Install with current database? [yes/no]

And will use a custom parser for parsing the user's answer.

String input prompt

Not implemented yet.

Style

The style package provides simple output formatting functions as well as some cherry-picked UTF-8 symbols that can be useful for building rich command-line interfaces.

Output Formatting

The style package exposes six different output formats, which print its argument with a specific color, font-weight and font-style depending on what the output's content should convey to the user. For example, if you want to attract a user's attention to an error, you might use the style.Failure() formatting function, like so:

    if err := validateConfiguration; err != nil {
        disgo.Errorln("Invalid configuration detected:", style.Failure(err))
        return err
    }

Other output formats include Success, Trace, Important and Link.

You can of course combine those formats in elegant ways, like shown in the examples section.

Symbols

Disgo provides aliases to UTF-8 characters that could be useful to build your command-line interfaces.

    disgo.Infoln(style.SymbolCheck) // ✔
    disgo.Infoln(style.SymbolCross) // ✖
    disgo.Infoln(style.SymbolLeftArrow) // ❮
    disgo.Infoln(style.SymbolRightArrow) // ❯
    disgo.Infoln(style.SymbolLeftTriangle) // ◀
    disgo.Infoln(style.SymbolRightTriangle) // ▶

License

MIT License

Copyright (c) 2019

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation

Overview

Package disgo is a simple library for building Go command-line interfaces.

It does not provide structured logging and is not built with performance in mind, since it is aimed at building user-friendly command line interfaces, and not applications.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// DefaultConfirmationChoices is the default value
	// for the choices that are given to
	// the users in a confirmation prompt.
	DefaultConfirmationChoices = []string{"y", "n"}
)

Functions

func Confirm 

func Confirm(config Confirmation) (bool, error)

Confirm prompts the user to confirm something using the global terminal.

func Debug 

func Debug(a ...interface{})

Debug writes a debug output on the global terminal's default writer if the debug outputs are enabled.

func Debugf 

func Debugf(format string, a ...interface{})

Debugf formats according to a format specifier and writes to the global terminal's default writer if the debug outputs are enabled.

func Debugln 

func Debugln(a ...interface{})

Debugln writes a debug output on the global terminal's default writer if the debug outputs are enabled and appends a newline to its input.

func DefaultConfirmation 

func DefaultConfirmation(input string) (bool, error)

DefaultConfirmation is a confirmation parser that covers most cases for confirmation. It converts y/Y/yes/YES/t/T/true/True/1 to true. It converts n/N/no/NO/f/F/false/FALSE/0 to false.

func EndStep 

func EndStep()

EndStep ends a step with a success state on the global. terminal. It then prints all of the outputs that were queued while the step was in progress. Warning: This is not thread-safe.

func Error 

func Error(a ...interface{})

Error writes an error output on the global terminal's error writer.

func Errorf 

func Errorf(format string, a ...interface{})

Errorf formats according to a format specifier and writes to the global terminal's error writer.

func Errorln 

func Errorln(a ...interface{})

Errorln writes an error output on the global terminal's error writer. It appends a newline to its input.

func FailStep 

func FailStep(err error) error

FailStep ends a step with a failure state. It then prints all of the outputs that were queued while the step was in progress, and returns the given error for error handling. Warning: This is not thread-safe.

func FailStepf 

func FailStepf(format string, a ...interface{}) error

FailStepf ends a step with a failure state on the global. terminal. It then prints all of the outputs that were queued while the step was in progress, and returns an error created from the given format and arguments. Warning: This is not thread-safe.

func Info 

func Info(a ...interface{})

Info writes an info output on the global terminal's default writer.

func Infof 

func Infof(format string, a ...interface{})

Infof formats according to a format specifier and writes to the global terminal's default writer.

func Infoln 

func Infoln(a ...interface{})

Infoln writes an info output on the global terminal's default writer and appends a newline to its input.

func SetTerminalOptions added in v0.3.0 

func SetTerminalOptions(options ...func(*Terminal))

SetTerminalOptions applies options to the global terminal.

func StartStep 

func StartStep(label string)

StartStep sets a step in the global terminal, which prints the step's label and makes the terminal queue outputs until the step is ended or failed. If a step was already in progress, it is considered to have been ended successfully. Warning: This is not thread-safe.

func StartStepf 

func StartStepf(format string, a ...interface{})

StartStepf sets a step in the terminal, which prints the step's label and makes the terminal queue outputs until the step is ended or failed. If a step was already in progress, it is considered to have been ended successfully. Warning: This is not thread-safe.

func WithColors 

func WithColors(enabled bool) func(*Terminal)

WithColors sets the use of colors in the terminal. By default, whether or not colors are enabled depends on the user's TTY, but this option can be used to force colors to be enabled or disabled.

func WithDebug 

func WithDebug(enabled bool) func(*Terminal)

WithDebug enables or disables the terminal debug mode.

func WithDefaultOutput 

func WithDefaultOutput(writer io.Writer) func(*Terminal)

WithDefaultOutput sets the default writer on the terminal.

func WithErrorOutput 

func WithErrorOutput(writer io.Writer) func(*Terminal)

WithErrorOutput sets the error writer on the terminal.

func WithInteractive 

func WithInteractive(enabled bool) func(*Terminal)

WithInteractive enables or disables the terminal interactive mode.

func WithReader 

func WithReader(reader io.Reader) func(*Terminal)

WithReader sets the reader on the Terminal. By default, if this option is not used, the default reader will be os.Stdin.

Types

type Confirmation 

type Confirmation struct {
	// The label that will be prompted to the user.
	// Example: `Are you sure?`
	Label string

	// The choices that will be presented to the user.
	// Example: `Y/n`. (A good practice is to uppercase
	// the default value, if there is one).
	Choices []string

	// EnableDefaultValue tells the terminal whether or not
	// there is a default value that will be used when the
	// user doesn't input any data.
	EnableDefaultValue bool

	// DefaultValue is the default value that will be used when
	// the user doesn't input any data, if EnableDefaultValue
	// is set to true OR that the terminal is set to not
	// interactive.
	DefaultValue bool

	// The parser that will be used to convert the user's input
	// into a true/false value.
	Parser ConfirmationParser
}

Confirmation represents a confirmation prompt's configuration.

type ConfirmationParser 

type ConfirmationParser func(string) (bool, error)

ConfirmationParser is a function that parses an input and returns a confirmation value as well as an error, if the input can't be parsed.

type Terminal added in v0.3.0 

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

Terminal represents a disgo Terminal. It can write to and prompt users in a command-line interface.

func NewTerminal added in v0.3.0 

func NewTerminal(options ...func(*Terminal)) *Terminal

NewTerminal creates a new Terminal.

func (Terminal) Confirm added in v0.3.0 

func (t Terminal) Confirm(config Confirmation) (bool, error)

Confirm prompts the user to confirm something.

func (Terminal) Debug added in v0.3.0 

func (t Terminal) Debug(a ...interface{})

Debug writes a debug output on the terminal's default writer if the debug outputs are enabled.

func (Terminal) Debugf added in v0.3.0 

func (t Terminal) Debugf(format string, a ...interface{})

Debugf formats according to a format specifier and writes to the terminal's default writer if the debug outputs are enabled.

func (Terminal) Debugln added in v0.3.0 

func (t Terminal) Debugln(a ...interface{})

Debugln writes a debug output on the terminal's default writer if the debug outputs are enabled and appends a newline to its input.

func (*Terminal) EndStep added in v0.3.0 

func (t *Terminal) EndStep()

EndStep ends a step with a success state. It then prints all of the outputs that were queued while the step was in progress.

func (Terminal) Error added in v0.3.0 

func (t Terminal) Error(a ...interface{})

Error writes an error output on the terminal's error writer.

func (Terminal) Errorf added in v0.3.0 

func (t Terminal) Errorf(format string, a ...interface{})

Errorf formats according to a format specifier and writes to the terminal's error writer.

func (Terminal) Errorln added in v0.3.0 

func (t Terminal) Errorln(a ...interface{})

Errorln writes an error output on the terminal's error writer. It appends a newline to its input.

func (*Terminal) FailStep added in v0.3.0 

func (t *Terminal) FailStep(err error) error

FailStep ends a step with a failure state. It then prints all of the outputs that were queued while the step was in progress, and returns the given error for error handling.

func (*Terminal) FailStepf added in v0.3.0 

func (t *Terminal) FailStepf(format string, a ...interface{}) error

FailStepf ends a step with a failure state. It then prints all of the outputs that were queued while the step was in progress, and returns an error created from the given format and arguments.

func (Terminal) Info added in v0.3.0 

func (t Terminal) Info(a ...interface{})

Info writes an info output on the terminal's default writer.

func (Terminal) Infof added in v0.3.0 

func (t Terminal) Infof(format string, a ...interface{})

Infof formats according to a format specifier and writes to the terminal's default writer.

func (Terminal) Infoln added in v0.3.0 

func (t Terminal) Infoln(a ...interface{})

Infoln writes an info output on the terminal's default writer and appends a newline to its input.

func (*Terminal) StartStep added in v0.3.0 

func (t *Terminal) StartStep(label string)

StartStep sets a step in the terminal, which prints the step's label and makes the terminal queue outputs until the step is ended or failed. If a step was already in progress, it is considered to have been ended successfully.

func (*Terminal) StartStepf added in v0.3.0 

func (t *Terminal) StartStepf(format string, a ...interface{})

StartStepf sets a step in the terminal, which prints the step's label and makes the terminal queue outputs until the step is ended or failed. If a step was already in progress, it is considered to have been ended successfully.

Source Files

View all Source files

Directories

Path Synopsis
examples
advanced
global

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.