promptui

README

promptui

Interactive prompt for command-line applications.

Fork from manifoldco/promptui and build for trzsz-ssh ( tssh ).

Code of Conduct | Contribution Guidelines

Overview

Promptui is a library providing a simple interface to create command-line prompts for go. It can be easily integrated into spf13/cobra, urfave/cli or any cli go application.

Promptui has two main input modes:

• Prompt provides a single line for user input. Prompt supports optional live validation, confirmation and masking the input.

• Select provides a list of options to choose from. Select supports pagination, search, detailed view and custom templates.

For a full list of options check GoDoc.

Basic Usage

Prompt

package main

import (
	"errors"
	"fmt"
	"strconv"

	"github.com/trzsz/promptui"
)

func main() {
	validate := func(input string) error {
		_, err := strconv.ParseFloat(input, 64)
		if err != nil {
			return errors.New("Invalid number")
		}
		return nil
	}

	prompt := promptui.Prompt{
		Label:    "Number",
		Validate: validate,
	}

	result, err := prompt.Run()

	if err != nil {
		fmt.Printf("Prompt failed %v\n", err)
		return
	}

	fmt.Printf("You choose %q\n", result)
}

Select

package main

import (
	"fmt"

	"github.com/trzsz/promptui"
)

func main() {
	prompt := promptui.Select{
		Label: "Select Day",
		Items: []string{"Monday", "Tuesday", "Wednesday", "Thursday", "Friday",
			"Saturday", "Sunday"},
	}

	_, result, err := prompt.Run()

	if err != nil {
		fmt.Printf("Prompt failed %v\n", err)
		return
	}

	fmt.Printf("You choose %q\n", result)
}

More Examples

See full list of examples

Documentation

Overview

Package promptui is a library providing a simple interface to create command-line prompts for go. It can be easily integrated into spf13/cobra, urfave/cli or any cli go application.

promptui has two main input modes:

Prompt provides a single line for user input. It supports optional live validation, confirmation and masking the input.

Select provides a list of options to choose from. It supports pagination, search, detailed view and custom templates.

Package promptui implements a write filter (tabwriter.Writer) that translates tabbed columns in input into properly aligned text.

The package is using the Elastic Tabstops algorithm described at http://nickgravgaard.com/elastictabstops/index.html.

The text/tabwriter package is frozen and is not accepting new features.

Example (Prompt)

This is an example for the Prompt mode of promptui. In this example, a prompt is created with a validator function that validates the given value to make sure its a number. If successful, it will output the chosen number in a formatted message.

validate := func(input string) error {
	_, err := strconv.ParseFloat(input, 64)
	if err != nil {
		return errors.New("Invalid number")
	}
	return nil
}

prompt := Prompt{
	Label:    "Number",
	Validate: validate,
}

result, err := prompt.Run()

if err != nil {
	fmt.Printf("Prompt failed %v\n", err)
	return
}

fmt.Printf("You choose %q\n", result)

Example (Select)

This is an example for the Select mode of promptui. In this example, a select is created with the days of the week as its items. When an item is selected, the selected day will be displayed in a formatted message.

prompt := Select{
	Label: "Select Day",
	Items: []string{"Monday", "Tuesday", "Wednesday", "Thursday", "Friday",
		"Saturday", "Sunday"},
}

_, result, err := prompt.Run()

if err != nil {
	fmt.Printf("Prompt failed %v\n", err)
	return
}

fmt.Printf("You choose %q\n", result)

Index

• Constants
• Variables
• func Styler(attrs ...attribute) func(interface{}) string
• type Cursor
  • func NewCursor(startinginput string, pointer Pointer, eraseDefault bool) Cursor
  • func (c *Cursor) Backspace()
  • func (c *Cursor) End()
  • func (c *Cursor) Format() string
  • func (c *Cursor) FormatMask(mask rune) string
  • func (c *Cursor) Get() string
  • func (c *Cursor) GetMask(mask rune) string
  • func (c *Cursor) Listen(line []rune, pos int, key rune) ([]rune, int, bool)
  • func (c *Cursor) Move(shift int)
  • func (c *Cursor) Place(position int)
  • func (c *Cursor) Replace(input string)
  • func (c *Cursor) Start()
  • func (c *Cursor) String() string
  • func (c *Cursor) Update(newinput string)
• type Key
• type Pointer
• type Prompt
  • func (p *Prompt) Run() (string, error)
• type PromptTemplates
• type Select
  • func (s *Select) GetCurrentIndex() int
  • func (s *Select) GetVisibleItems() []interface{}
  • func (s *Select) GetVisibleSize() int
  • func (s *Select) Run() (int, string, error)
  • func (s *Select) RunCursorAt(cursorPos, scroll int) (int, string, error)
  • func (s *Select) ScrollPosition() int
• type SelectKeys
• type SelectTemplates
• type SelectWithAdd
  • func (sa *SelectWithAdd) Run() (int, string, error)
• type ValidateFunc
• type Writer
  • func NewWriter(output io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) *Writer
  • func (b *Writer) Flush() error
  • func (b *Writer) Init(output io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) *Writer
  • func (b *Writer) Write(buf []byte) (n int, err error)

Examples

• Package (Prompt)
• Package (Select)
• Prompt
• Select
• SelectWithAdd

Constants

const (
	FGBold attribute
	FGFaint
	FGItalic
	FGUnderline
)

The possible state of text inside the application, either Bold, faint, italic or underline.

These constants are called through the use of the Styler function.

const (
	FGBlack attribute = iota + 30
	FGRed
	FGGreen
	FGYellow
	FGBlue
	FGMagenta
	FGCyan
	FGWhite
)

The possible colors of text inside the application.

These constants are called through the use of the Styler function.

const (
	BGBlack attribute = iota + 40
	BGRed
	BGGreen
	BGYellow
	BGBlue
	BGMagenta
	BGCyan
	BGWhite
)

The possible background colors of text inside the application.

These constants are called through the use of the Styler function.

const (
	// KeyRefresh is the key to refresh the current status
	KeyRefresh = '\x01'

	// KeyCtrlE is the key to erase the search keywords
	KeyCtrlE = '\x05'

	// KeySoftEnter is the key to lock the search keywords
	KeySoftEnter = '\x1e'
)

const (
	// Ignore html tags and treat entities (starting with '&'
	// and ending in ';') as single characters (width = 1).
	FilterHTML uint = 1 << iota

	// Strip Escape characters bracketing escaped text segments
	// instead of passing them through unchanged with the text.
	StripEscape

	// Force right-alignment of cell content.
	// Default is left-alignment.
	AlignRight

	// Handle empty columns as if they were not present in
	// the input in the first place.
	DiscardEmptyColumns

	// Always use tabs for indentation columns (i.e., padding of
	// leading empty cells on the left) independent of padchar.
	TabIndent

	// Print a vertical bar ('|') between columns (after formatting).
	// Discarded columns appear as zero-width columns ("||").
	Debug
)

Formatting can be controlled with these flags.

const Escape = '\xff'

Escape to escape a text segment, bracket it with Escape characters. For instance, the tab in this string "Ignore this tab: \xff\t\xff" does not terminate a cell and constitutes a single character of width one for formatting purposes.

The value 0xff was chosen because it cannot appear in a valid UTF-8 sequence.

const SelectedAdd = -1

SelectedAdd is used internally inside SelectWithAdd when the add option is selected in select mode. Since -1 is not a possible selected index, this ensure that add mode is always unique inside SelectWithAdd's logic.

Variables

var (
	// KeyEnter is the default key for submission/selection.
	KeyEnter rune = readline.CharEnter

	// KeyCtrlH is the key for deleting input text.
	KeyCtrlH rune = readline.CharCtrlH

	// KeyPrev is the default key to go up during selection.
	KeyPrev        rune = readline.CharPrev
	KeyPrevDisplay      = "↑"

	// KeyNext is the default key to go down during selection.
	KeyNext        rune = readline.CharNext
	KeyNextDisplay      = "↓"

	// KeyBackward is the default key to page up during selection.
	KeyBackward        rune = readline.CharBackward
	KeyBackwardDisplay      = "←"

	// KeyForward is the default key to page down during selection.
	KeyForward        rune = readline.CharForward
	KeyForwardDisplay      = "→"
)

These runes are used to identify the commands entered by the user in the command prompt. They map to specific actions of promptui in prompt mode and can be remapped if necessary.

var (
	// IconInitial is the icon used when starting in prompt mode and the icon next to the label when
	// starting in select mode.
	IconInitial = Styler(FGBlue)("?")

	// IconGood is the icon used when a good answer is entered in prompt mode.
	IconGood = Styler(FGGreen)("✔")

	// IconWarn is the icon used when a good, but potentially invalid answer is entered in prompt mode.
	IconWarn = Styler(FGYellow)("⚠")

	// IconBad is the icon used when a bad answer is entered in prompt mode.
	IconBad = Styler(FGRed)("✗")

	// IconSelect is the icon used to identify the currently selected item in select mode.
	IconSelect = Styler(FGBold)("▸")
)

These are the default icons used by promptui for select and prompts. These should not be overridden and instead customized through the use of custom templates

var ErrAbort = errors.New("")

ErrAbort is the error returned when confirm prompts are supplied "n"

var ErrEOF = errors.New("^D")

ErrEOF is the error returned from prompts when EOF is encountered.

var ErrInterrupt = errors.New("^C")

ErrInterrupt is the error returned from prompts when an interrupt (ctrl-c) is encountered.

var FuncMap = template.FuncMap{
	"default":   Styler(reset),
	"black":     Styler(FGBlack),
	"red":       Styler(FGRed),
	"green":     Styler(FGGreen),
	"yellow":    Styler(FGYellow),
	"blue":      Styler(FGBlue),
	"magenta":   Styler(FGMagenta),
	"cyan":      Styler(FGCyan),
	"white":     Styler(FGWhite),
	"bgBlack":   Styler(BGBlack),
	"bgRed":     Styler(BGRed),
	"bgGreen":   Styler(BGGreen),
	"bgYellow":  Styler(BGYellow),
	"bgBlue":    Styler(BGBlue),
	"bgMagenta": Styler(BGMagenta),
	"bgCyan":    Styler(BGCyan),
	"bgWhite":   Styler(BGWhite),
	"bold":      Styler(FGBold),
	"faint":     Styler(FGFaint),
	"italic":    Styler(FGItalic),
	"underline": Styler(FGUnderline),
}

FuncMap defines template helpers for the output. It can be extended as a regular map.

The functions inside the map link the state, color and background colors strings detected in templates to a Styler function that applies the given style using the corresponding constant.

var (
	// KeyBackspace is the default key for deleting input text.
	KeyBackspace rune = readline.CharBackspace
)

var ResetCode = fmt.Sprintf("%s%dm", esc, reset)

ResetCode is the character code used to reset the terminal formatting

var SearchPrompt = "Search: "

SearchPrompt is the prompt displayed in search mode.

Functions

func Styler

func Styler(attrs ...attribute) func(interface{}) string

Styler is a function that accepts multiple possible styling transforms from the state, color and background colors constants and transforms them into a templated string to apply those styles in the CLI.

The returned styling function accepts a string that will be extended with the wrapping function's styling attributes.

Types

type Cursor

type Cursor struct {
	// shows where the user inserts/updates text
	Cursor Pointer

	// Put the cursor before this slice
	Position int
	// contains filtered or unexported fields
}

Cursor tracks the state associated with the movable cursor The strategy is to keep the prompt, input pristine except for requested modifications. The insertion of the cursor happens during a `format` call and we read in new input via an `Update` call

func NewCursor

func NewCursor(startinginput string, pointer Pointer, eraseDefault bool) Cursor

NewCursor create a new cursor, with the DefaultCursor, the specified input, and position at the end of the specified starting input.

func (*Cursor) Backspace

func (c *Cursor) Backspace()

Backspace removes the rune that precedes the cursor

It handles being at the beginning or end of the row, and moves the cursor to the appropriate position.

func (*Cursor) End

func (c *Cursor) End()

End is a convenience for c.Place(len(c.input)) so you don't have to know how I indexed.

func (*Cursor) Format

func (c *Cursor) Format() string

Format renders the input with the Cursor appropriately positioned.

func (*Cursor) FormatMask

func (c *Cursor) FormatMask(mask rune) string

FormatMask replaces all input runes with the mask rune.

func (*Cursor) Get

func (c *Cursor) Get() string

Get returns a copy of the input

func (*Cursor) GetMask

func (c *Cursor) GetMask(mask rune) string

GetMask returns a mask string with length equal to the input

func (*Cursor) Listen

func (c *Cursor) Listen(line []rune, pos int, key rune) ([]rune, int, bool)

Listen is a readline Listener that updates internal cursor state appropriately.

func (*Cursor) Move

func (c *Cursor) Move(shift int)

Move moves the cursor over in relative terms, by shift indices.

func (*Cursor) Place

func (c *Cursor) Place(position int)

Place moves the cursor to the absolute array index specified by position

func (*Cursor) Replace

func (c *Cursor) Replace(input string)

Replace replaces the previous input with whatever is specified, and moves the cursor to the end position

func (*Cursor) Start

func (c *Cursor) Start()

Start is convenience for c.Place(0) so you don't have to know how I indexed.

func (*Cursor) String

func (c *Cursor) String() string

func (*Cursor) Update

func (c *Cursor) Update(newinput string)

Update inserts newinput into the input []rune in the appropriate place. The cursor is moved to the end of the inputed sequence.

type Key

type Key struct {
	// Code is a rune that will be used to compare against typed keys with readline.
	// Check https://github.com/chzyer/readline for a list of codes
	Code rune

	// Display is the string that will be displayed inside the help menu to help inform the user
	// of which key to use on his keyboard for various functions.
	Display string
}

Key defines a keyboard code and a display representation for the help menu.

type Pointer

type Pointer func(to []rune) []rune

Pointer is A specific type that translates a given set of runes into a given set of runes pointed at by the cursor.

var (
	// DefaultCursor is a big square block character. Obscures whatever was
	// input.
	DefaultCursor Pointer = defaultCursor
	// BlockCursor is a cursor which highlights a character by inverting colors
	// on it.
	BlockCursor Pointer = blockCursor
	// PipeCursor is a pipe character "|" which appears before the input
	// character.
	PipeCursor Pointer = pipeCursor
)

type Prompt

type Prompt struct {
	// Label is the value displayed on the command line prompt.
	//
	// The value for Label can be a simple string or a struct that will need to be accessed by dot notation
	// inside the templates. For example, `{{ .Name }}` will display the name property of a struct.
	Label interface{}

	// Default is the initial value for the prompt. This value will be displayed next to the prompt's label
	// and the user will be able to view or change it depending on the options.
	Default string

	// AllowEdit lets the user edit the default value. If false, any key press
	// other than <Enter> automatically clears the default value.
	AllowEdit bool

	// Validate is an optional function that fill be used against the entered value in the prompt to validate it.
	Validate ValidateFunc

	// Mask is an optional rune that sets which character to display instead of the entered characters. This
	// allows hiding private information like passwords.
	Mask rune

	// HideEntered sets whether to hide the text after the user has pressed enter.
	HideEntered bool

	// Templates can be used to customize the prompt output. If nil is passed, the
	// default templates are used. See the PromptTemplates docs for more info.
	Templates *PromptTemplates

	// IsConfirm makes the prompt ask for a yes or no ([Y/N]) question rather than request an input. When set,
	// most properties related to input will be ignored.
	IsConfirm bool

	// IsVimMode enables vi-like movements (hjkl) and editing.
	IsVimMode bool

	// the Pointer defines how to render the cursor.
	Pointer Pointer

	Stdin  io.ReadCloser
	Stdout io.WriteCloser
}

Prompt represents a single line text field input with options for validation and input masks.

Example

This example shows how to use the prompt validator and templates to create a stylized prompt. The validator will make sure the value entered is a parseable float while the templates will color the value to show validity.

// The validate function follows the required validator signature.
validate := func(input string) error {
	_, err := strconv.ParseFloat(input, 64)
	return err
}

// Each template displays the data received from the prompt with some formatting.
templates := &PromptTemplates{
	Prompt:  "{{ . }} ",
	Valid:   "{{ . | green }} ",
	Invalid: "{{ . | red }} ",
	Success: "{{ . | bold }} ",
}

prompt := Prompt{
	Label:     "Spicy Level",
	Templates: templates,
	Validate:  validate,
}

result, err := prompt.Run()

if err != nil {
	fmt.Printf("Prompt failed %v\n", err)
	return
}

// The result of the prompt, if valid, is displayed in a formatted message.
fmt.Printf("You answered %s\n", result)

func (*Prompt) Run

func (p *Prompt) Run() (string, error)

Run executes the prompt. Its displays the label and default value if any, asking the user to enter a value. Run will keep the prompt alive until it has been canceled from the command prompt or it has received a valid value. It will return the value and an error if any occurred during the prompt's execution.

type PromptTemplates

type PromptTemplates struct {
	// Prompt is a text/template for the prompt label displayed on the left side of the prompt.
	Prompt string

	// Prompt is a text/template for the prompt label when IsConfirm is set as true.
	Confirm string

	// Valid is a text/template for the prompt label when the value entered is valid.
	Valid string

	// Invalid is a text/template for the prompt label when the value entered is invalid.
	Invalid string

	// Success is a text/template for the prompt label when the user has pressed entered and the value has been
	// deemed valid by the validation function. The label will keep using this template even when the prompt ends
	// inside the console.
	Success string

	// Prompt is a text/template for the prompt label when the value is invalid due to an error triggered by
	// the prompt's validation function.
	ValidationError string

	// FuncMap is a map of helper functions that can be used inside of templates according to the text/template
	// documentation.
	//
	// By default, FuncMap contains the color functions used to color the text in templates. If FuncMap
	// is overridden, the colors functions must be added in the override from promptui.FuncMap to work.
	FuncMap template.FuncMap
	// contains filtered or unexported fields
}

PromptTemplates allow a prompt to be customized following stdlib text/template syntax. Custom state, colors and background color are available for use inside the templates and are documented inside the Variable section of the docs.

Examples

text/templates use a special notation to display programmable content. Using the double bracket notation, the value can be printed with specific helper functions. For example

This displays the value given to the template as pure, unstylized text.

'{{ . }}'

This displays the value colored in cyan

'{{ . | cyan }}'

This displays the value colored in red with a cyan background-color

'{{ . | red | cyan }}'

See the doc of text/template for more info: https://golang.org/pkg/text/template/

type Select

type Select struct {
	// Label is the text displayed on top of the list to direct input. The IconInitial value "?" will be
	// appended automatically to the label so it does not need to be added.
	//
	// The value for Label can be a simple string or a struct that will need to be accessed by dot notation
	// inside the templates. For example, `{{ .Name }}` will display the name property of a struct.
	Label interface{}

	// Items are the items to display inside the list. It expect a slice of any kind of values, including strings.
	//
	// If using a slice of strings, promptui will use those strings directly into its base templates or the
	// provided templates. If using any other type in the slice, it will attempt to transform it into a string
	// before giving it to its templates. Custom templates will override this behavior if using the dot notation
	// inside the templates.
	//
	// For example, `{{ .Name }}` will display the name property of a struct.
	Items interface{}

	// Size is the number of items that should appear on the select before scrolling is necessary. Defaults to 5.
	Size int

	// CursorPos is the initial position of the cursor.
	CursorPos int

	// IsVimMode sets whether to use vim mode when using readline in the command prompt. Look at
	// https://godoc.org/github.com/chzyer/readline#Config for more information on readline.
	IsVimMode bool

	// HideHelp sets whether to hide help information.
	HideHelp bool

	// HideSelected sets whether to hide the text displayed after an item is successfully selected.
	HideSelected bool

	// Templates can be used to customize the select output. If nil is passed, the
	// default templates are used. See the SelectTemplates docs for more info.
	Templates *SelectTemplates

	// Keys is the set of keys used in select mode to control the command line interface. See the SelectKeys docs for
	// more info.
	Keys *SelectKeys

	// Searcher is a function that can be implemented to refine the base searching algorithm in selects.
	//
	// Search is a function that will receive the searched term and the item's index and should return a boolean
	// for whether or not the terms are alike. It is unimplemented by default and search will not work unless
	// it is implemented.
	Searcher list.Searcher

	// StartInSearchMode sets whether or not the select mode should start in search mode or selection mode.
	// For search mode to work, the Search property must be implemented.
	StartInSearchMode bool

	// A function that determines how to render the cursor
	Pointer Pointer

	Stdin  io.ReadCloser
	Stdout io.WriteCloser

	// Shortcuts are the shortcuts to display on the top.
	Shortcuts []string

	// Keywords for search
	Keywords string
	// contains filtered or unexported fields
}

Select represents a list of items used to enable selections, they can be used as search engines, menus or as a list of items in a cli based prompt.

Example

This examples shows a complex and customized select.

package main

import (
	"fmt"
	"strings"
)

// Any type can be given to the select's item as long as the templates properly implement the dot notation
// to display it.
type pepper struct {
	Name     string
	HeatUnit int
	Peppers  int
}

// This examples shows a complex and customized select.
func main() {
	// The select will show a series of peppers stored inside a slice of structs. To display the content of the struct,
	// the usual dot notation is used inside the templates to select the fields and color them.
	peppers := []pepper{
		{Name: "Bell Pepper", HeatUnit: 0, Peppers: 0},
		{Name: "Banana Pepper", HeatUnit: 100, Peppers: 1},
		{Name: "Poblano", HeatUnit: 1000, Peppers: 2},
		{Name: "Jalapeño", HeatUnit: 3500, Peppers: 3},
		{Name: "Aleppo", HeatUnit: 10000, Peppers: 4},
		{Name: "Tabasco", HeatUnit: 30000, Peppers: 5},
		{Name: "Malagueta", HeatUnit: 50000, Peppers: 6},
		{Name: "Habanero", HeatUnit: 100000, Peppers: 7},
		{Name: "Red Savina Habanero", HeatUnit: 350000, Peppers: 8},
		{Name: "Dragon’s Breath", HeatUnit: 855000, Peppers: 9},
	}

	// The Active and Selected templates set a small pepper icon next to the name colored and the heat unit for the
	// active template. The details template is show at the bottom of the select's list and displays the full info
	// for that pepper in a multi-line template.
	templates := &SelectTemplates{
		Label:    "{{ . }}?",
		Active:   "\U0001F336 {{ .Name | cyan }} ({{ .HeatUnit | red }})",
		Inactive: "  {{ .Name | cyan }} ({{ .HeatUnit | red }})",
		Selected: "\U0001F336 {{ .Name | red | cyan }}",
		Details: `
--------- Pepper ----------
{{ "Name:" | faint }}	{{ .Name }}
{{ "Heat Unit:" | faint }}	{{ .HeatUnit }}
{{ "Peppers:" | faint }}	{{ .Peppers }}`,
	}

	// A searcher function is implemented which enabled the search mode for the select. The function follows
	// the required searcher signature and finds any pepper whose name contains the searched string.
	searcher := func(input string, index int) bool {
		pepper := peppers[index]
		name := strings.Replace(strings.ToLower(pepper.Name), " ", "", -1)
		input = strings.Replace(strings.ToLower(input), " ", "", -1)

		return strings.Contains(name, input)
	}

	prompt := Select{
		Label:     "Spicy Level",
		Items:     peppers,
		Templates: templates,
		Size:      4,
		Searcher:  searcher,
	}

	i, _, err := prompt.Run()

	if err != nil {
		fmt.Printf("Prompt failed %v\n", err)
		return
	}

	// The selected pepper will be displayed with its name and index in a formatted message.
	fmt.Printf("You choose number %d: %s\n", i+1, peppers[i].Name)
}

func (*Select) GetCurrentIndex

func (s *Select) GetCurrentIndex() int

GetCurrentIndex returns the index of the item currently selected inside the searched list. If no item is selected, the NotFound (-1) index is returned.

func (*Select) GetVisibleItems

func (s *Select) GetVisibleItems() []interface{}

GetVisibleItems returns the current visible items.

func (*Select) GetVisibleSize

func (s *Select) GetVisibleSize() int

GetVisibleSize returns the size of the current visible items.

func (*Select) Run

func (s *Select) Run() (int, string, error)

Run executes the select list. It displays the label and the list of items, asking the user to chose any value within to list. Run will keep the prompt alive until it has been canceled from the command prompt or it has received a valid value. It will return the value and an error if any occurred during the select's execution.

func (*Select) RunCursorAt

func (s *Select) RunCursorAt(cursorPos, scroll int) (int, string, error)

RunCursorAt executes the select list, initializing the cursor to the given position. Invalid cursor positions will be clamped to valid values. It displays the label and the list of items, asking the user to chose any value within to list. Run will keep the prompt alive until it has been canceled from the command prompt or it has received a valid value. It will return the value and an error if any occurred during the select's execution.

func (*Select) ScrollPosition

func (s *Select) ScrollPosition() int

ScrollPosition returns the current scroll position.

type SelectKeys

type SelectKeys struct {
	// Next is the key used to move to the next element inside the list. Defaults to down arrow key.
	Next Key

	// Prev is the key used to move to the previous element inside the list. Defaults to up arrow key.
	Prev Key

	// PageUp is the key used to jump back to the first element inside the list. Defaults to left arrow key.
	PageUp Key

	// PageUp is the key used to jump forward to the last element inside the list. Defaults to right arrow key.
	PageDown Key

	// Search is the key used to trigger the search mode for the list. Default to the "/" key.
	Search Key
}

SelectKeys defines the available keys used by select mode to enable the user to move around the list and trigger search mode. See the Key struct docs for more information on keys.

type SelectTemplates

type SelectTemplates struct {
	// Label is a text/template for the main command line label. Defaults to printing the label as it with
	// the IconInitial.
	Label string

	// Active is a text/template for when an item is currently active within the list.
	Active string

	// Inactive is a text/template for when an item is not currently active inside the list. This
	// template is used for all items unless they are active or selected.
	Inactive string

	// Selected is a text/template for when an item was successfully selected.
	Selected string

	// Details is a text/template for when an item current active to show
	// additional information. It can have multiple lines.
	//
	// Detail will always be displayed for the active element and thus can be used to display additional
	// information on the element beyond its label.
	//
	// promptui will not trim spaces and tabs will be displayed if the template is indented.
	Details string

	// Help is a text/template for displaying instructions at the top. By default
	// it shows keys for movement and search.
	Help string

	// Shortcuts is a text/template for displayin shortcuts on the top.
	Shortcuts string

	// SearchTips is a text/template for displaying search tips while search having results.
	SearchTips string

	// Keywords is a text/template for the search keywords.
	Keywords string

	// HideLabel sets whether to hide the label.
	HideLabel bool

	// ItemsRenderer is a custom rendering visible items function.
	ItemsRenderer func(items []interface{}, idx int) string

	// DetailsRenderer is a custom rendering active item function.
	DetailsRenderer func(item interface{}) string

	// FuncMap is a map of helper functions that can be used inside of templates according to the text/template
	// documentation.
	//
	// By default, FuncMap contains the color functions used to color the text in templates. If FuncMap
	// is overridden, the colors functions must be added in the override from promptui.FuncMap to work.
	FuncMap template.FuncMap
	// contains filtered or unexported fields
}

SelectTemplates allow a select list to be customized following stdlib text/template syntax. Custom state, colors and background color are available for use inside the templates and are documented inside the Variable section of the docs.

Examples

text/templates use a special notation to display programmable content. Using the double bracket notation, the value can be printed with specific helper functions. For example

This displays the value given to the template as pure, unstylized text. Structs are transformed to string with this notation.

'{{ . }}'

This displays the name property of the value colored in cyan

'{{ .Name | cyan }}'

This displays the label property of value colored in red with a cyan background-color

'{{ .Label | red | cyan }}'

See the doc of text/template for more info: https://golang.org/pkg/text/template/

Notes

Setting any of these templates will remove the icons from the default templates. They must be added back in each of their specific templates. The styles.go constants contains the default icons.

type SelectWithAdd

type SelectWithAdd struct {
	// Label is the text displayed on top of the list to direct input. The IconInitial value "?" will be
	// appended automatically to the label so it does not need to be added.
	Label string

	// Items are the items to display inside the list. Each item will be listed individually with the
	// AddLabel as the first item of the list.
	Items []string

	// AddLabel is the label used for the first item of the list that enables adding a new item.
	// Selecting this item in the list displays the add item prompt using promptui/prompt.
	AddLabel string

	// Validate is an optional function that fill be used against the entered value in the prompt to validate it.
	// If the value is valid, it is returned to the callee to be added in the list.
	Validate ValidateFunc

	// IsVimMode sets whether to use vim mode when using readline in the command prompt. Look at
	// https://godoc.org/github.com/chzyer/readline#Config for more information on readline.
	IsVimMode bool

	// a function that defines how to render the cursor
	Pointer Pointer

	// HideHelp sets whether to hide help information.
	HideHelp bool
}

SelectWithAdd represents a list for selecting a single item inside a list of items with the possibility to add new items to the list.

Example

This example shows how to create a SelectWithAdd that will add each new item it is given to the list of items until one is chosen.

items := []string{"Vim", "Emacs", "Sublime", "VSCode", "Atom"}
index := -1
var result string
var err error

for index < 0 {
	prompt := SelectWithAdd{
		Label:    "What's your text editor",
		Items:    items,
		AddLabel: "Add your own",
	}

	index, result, err = prompt.Run()

	if index == -1 {
		items = append(items, result)
	}
}

if err != nil {
	fmt.Printf("Prompt failed %v\n", err)
	return
}

fmt.Printf("You choose %s\n", result)

func (*SelectWithAdd) Run

func (sa *SelectWithAdd) Run() (int, string, error)

Run executes the select list. Its displays the label and the list of items, asking the user to chose any value within to list or add his own. Run will keep the prompt alive until it has been canceled from the command prompt or it has received a valid value.

If the addLabel is selected in the list, this function will return a -1 index with the added label and no error. Otherwise, it will return the index and the value of the selected item. In any case, if an error is triggered, it will also return the error as its third return value.

type ValidateFunc

type ValidateFunc func(string) error

ValidateFunc is a placeholder type for any validation functions that validates a given input. It should return a ValidationError if the input is not valid.

type Writer

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

A Writer is a filter that inserts padding around tab-delimited columns in its input to align them in the output.

The Writer treats incoming bytes as UTF-8-encoded text consisting of cells terminated by horizontal ('\t') or vertical ('\v') tabs, and newline ('\n') or formfeed ('\f') characters; both newline and formfeed act as line breaks.

Tab-terminated cells in contiguous lines constitute a column. The Writer inserts padding as needed to make all cells in a column have the same width, effectively aligning the columns. It assumes that all characters have the same width, except for tabs for which a tabwidth must be specified. Column cells must be tab-terminated, not tab-separated: non-tab terminated trailing text at the end of a line forms a cell but that cell is not part of an aligned column. For instance, in this example (where | stands for a horizontal tab):

aaaa|bbb|d
aa  |b  |dd
a   |
aa  |cccc|eee

the b and c are in distinct columns (the b column is not contiguous all the way). The d and e are not in a column at all (there's no terminating tab, nor would the column be contiguous).

The Writer assumes that all Unicode code points have the same width; this may not be true in some fonts or if the string contains combining characters.

If DiscardEmptyColumns is set, empty columns that are terminated entirely by vertical (or "soft") tabs are discarded. Columns terminated by horizontal (or "hard") tabs are not affected by this flag.

If a Writer is configured to filter HTML, HTML tags and entities are passed through. The widths of tags and entities are assumed to be zero (tags) and one (entities) for formatting purposes.

A segment of text may be escaped by bracketing it with Escape characters. The tabwriter passes escaped text segments through unchanged. In particular, it does not interpret any tabs or line breaks within the segment. If the StripEscape flag is set, the Escape characters are stripped from the output; otherwise they are passed through as well. For the purpose of formatting, the width of the escaped text is always computed excluding the Escape characters.

The formfeed character acts like a newline but it also terminates all columns in the current line (effectively calling Flush). Tab- terminated cells in the next line start new columns. Unless found inside an HTML tag or inside an escaped text segment, formfeed characters appear as newlines in the output.

The Writer must buffer input internally, because proper spacing of one line may depend on the cells in future lines. Clients must call Flush when done calling Write.

func NewWriter

func NewWriter(output io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) *Writer

NewWriter allocates and initializes a new tabwriter.Writer. The parameters are the same as for the Init function.

func (*Writer) Flush

func (b *Writer) Flush() error

Flush should be called after the last call to Write to ensure that any data buffered in the Writer is written to output. Any incomplete escape sequence at the end is considered complete for formatting purposes.

func (*Writer) Init

func (b *Writer) Init(output io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) *Writer

Init a Writer must be initialized with a call to Init. The first parameter (output) specifies the filter output. The remaining parameters control the formatting:

minwidth	minimal cell width including any padding
tabwidth	width of tab characters (equivalent number of spaces)
padding		padding added to a cell before computing its width
padchar		ASCII char used for padding
		if padchar == '\t', the Writer will assume that the
		width of a '\t' in the formatted output is tabwidth,
		and cells are left-aligned independent of align_left
		(for correct-looking results, tabwidth must correspond
		to the tab width in the viewer displaying the result)
flags		formatting control

func (*Writer) Write

func (b *Writer) Write(buf []byte) (n int, err error)

Write writes buf to the writer b. The only errors returned are ones encountered while writing to the underlying output stream.