prompt

README

Prompt

Prompt is a cross platform line-editing prompting library. Read the GoDoc page for more info and for API details.

Features

• Keyboard shortcuts in prompts
• Secure password prompt
• Custom prompt support
• Fallback prompt for unsupported terminals
• ANSI conversion for Windows

Todo

• Multi-line prompt as a Terminal option
• Make refresh less jittery on Windows(possible reason)
• Add support for BSD systems
• Add history functionality
• Multi-byte character support on Windows
• AnsiWriter should execute the equivalent ANSI escape code functionality on Windows
• Support for more ANSI escape codes on Windows.
• More keyboard shortcuts from Readlines shortcut list

Contributing

Make sure Go is setup and running the latest release version, and make sure your GOPATH is setup properly.

Follow the guidelines here.

Please be sure to gofmt any code before doing commits. You can simply run gofmt -w . to format all the code in the directory.

License

Prompt is MIT licensed, details can be found here.

Documentation

Overview

Package prompt implements a cross platform line-editing prompt. It also provides routines to use ANSI escape sequences across platforms for terminal connected io.Readers/io.Writers.

If os.Stdin isn't connected to a terminal or (on Unix)if the terminal doesn't support the ANSI escape sequences needed a fallback prompt is provided that doesn't do line-editing. Unix terminals that are not supported will have the TERM environment variable set to either "dumb" or "cons25".

The keyboard shortcuts are similar to those found in the Readline library:

• Enter / CTRL+D
• End the line.
• CTRL+C
• End the line, return error `ErrCTRLC`.
• Backspace
• Remove the character to the left.
• CTRL+L
• Clear the screen(keeping the current lines content).
• Home / End
• Jump to the beginning/end of the line.
• Left arrow / Right arrow
• Move left/right one character.
• Delete
• Remove the character to the right.

Index

• Variables
• func Ask(question string) (bool, error)
• func Basic(prefix string, required bool) (string, error)
• func BasicDefault(prefix, def string) (string, error)
• func Custom(prefix string, test func(string) (string, bool)) (string, error)
• func IsNotTerminal(err error) bool
• func Password(prefix string) (string, error)
• func TerminalSize(out *os.File) (int, int, error)
• type AnsiReader
  • func NewAnsiReader(in *os.File) *AnsiReader
• type AnsiWriter
  • func NewAnsiWriter(out *os.File) *AnsiWriter
• type Buffer
  • func NewBuffer(prompt string, out *os.File, echo bool) *Buffer
  • func (buf *Buffer) ClsScreen() error
  • func (buf *Buffer) Del() error
  • func (buf *Buffer) DelLeft() error
  • func (buf *Buffer) End() error
  • func (buf *Buffer) EndLine() error
  • func (buf *Buffer) Insert(rs ...rune) error
  • func (buf *Buffer) Left() error
  • func (buf *Buffer) Refresh() error
  • func (buf *Buffer) Right() error
  • func (buf *Buffer) Start() error
  • func (buf *Buffer) String() string
• type Terminal
  • func NewTerminal() (*Terminal, error)
  • func (term *Terminal) Close() error
  • func (term *Terminal) Password(prefix string) (string, error)
  • func (term *Terminal) Prompt(prefix string) (string, error)

Examples

• Basic
• Password

Variables

var (
	ErrCTRLC = errors.New("Interrupted (CTRL+C)")
)

Functions

func Ask

func Ask(question string) (bool, error)

Ask gets input and checks if it's truthy or not, and returns that in a boolean fashion.

func Basic

func Basic(prefix string, required bool) (string, error)

Basic gets input and if required tests to ensure input was given.

Example

package main

import (
	"net/mail"

	"github.com/Bowery/prompt"
)

func main() (string, error) {
	email, err := prompt.Basic("Email", true)
	if err != nil {
		return "", err
	}

	_, err = mail.ParseAddress(email)
	return email, err
}

func BasicDefault

func BasicDefault(prefix, def string) (string, error)

BasicDefault gets input and if empty uses the given default.

func Custom

func Custom(prefix string, test func(string) (string, bool)) (string, error)

Custom gets input and calls the given test function with the input to check if the input is valid, a true return will return the string.

func IsNotTerminal

func IsNotTerminal(err error) bool

IsNotTerminal checks if an error is related to io not being a terminal.

func Password

func Password(prefix string) (string, error)

Password retrieves a password from stdin without echoing it.

Example

package main

import (
	"github.com/Bowery/prompt"
	"golang.org/x/crypto/bcrypt"
)

func main() ([]byte, error) {
	clear, err := prompt.Password("Password")
	if err != nil {
		return nil, err
	}

	return bcrypt.GenerateFromPassword(clear, bcrypt.DefaultCost)
}

func TerminalSize

func TerminalSize(out *os.File) (int, int, error)

TerminalSize retrieves the cols/rows for the terminal connected to out.

Types

type AnsiReader

type AnsiReader struct {
	*os.File
}

AnsiReader is an io.Reader that wraps an *os.File.

func NewAnsiReader

func NewAnsiReader(in *os.File) *AnsiReader

NewAnsiReader creates a AnsiReader from the given input file.

type AnsiWriter

type AnsiWriter struct {
	*os.File
}

AnsiWriter is an io.Writer that wraps an *os.File.

func NewAnsiWriter

func NewAnsiWriter(out *os.File) *AnsiWriter

NewAnsiWriter creates a AnsiWriter from the given output file.

type Buffer

type Buffer struct {
	Out    *os.File
	Prompt string
	Echo   bool
	Cols   int
	// contains filtered or unexported fields
}

Buffer contains state for line editing and writing.

func NewBuffer

func NewBuffer(prompt string, out *os.File, echo bool) *Buffer

NewBuffer creates a buffer writing to out if echo is true.

func (*Buffer) ClsScreen

func (buf *Buffer) ClsScreen() error

ClsScreen clears the screen and refreshes.

func (*Buffer) Del

func (buf *Buffer) Del() error

Del removes the character at the cursor position.

func (*Buffer) DelLeft

func (buf *Buffer) DelLeft() error

DelLeft removes the character to the left.

func (*Buffer) End

func (buf *Buffer) End() error

End moves the cursor to the end.

func (*Buffer) EndLine

func (buf *Buffer) EndLine() error

EndLine ends the line with CRLF.

func (*Buffer) Insert

func (buf *Buffer) Insert(rs ...rune) error

Insert inserts characters at the cursors position.

func (*Buffer) Left

func (buf *Buffer) Left() error

Left moves the cursor one character left.

func (*Buffer) Refresh

func (buf *Buffer) Refresh() error

Refresh rewrites the prompt and buffer.

func (*Buffer) Right

func (buf *Buffer) Right() error

Right moves the cursor one character right.

func (*Buffer) Start

func (buf *Buffer) Start() error

Start moves the cursor to the start.

func (*Buffer) String

func (buf *Buffer) String() string

String returns the data as a string.

type Terminal

type Terminal struct {
	In  *os.File
	Out *os.File
	// contains filtered or unexported fields
}

Terminal contains the state for raw terminal input.

func NewTerminal

func NewTerminal() (*Terminal, error)

NewTerminal creates a terminal and sets it to raw input mode.

func (*Terminal) Close

func (term *Terminal) Close() error

Close disables the terminals raw input.

func (*Terminal) Password

func (term *Terminal) Password(prefix string) (string, error)

Password gets a line with the prefix and doesn't echo input.

func (*Terminal) Prompt

func (term *Terminal) Prompt(prefix string) (string, error)

Prompt gets a line with the prefix and echos input.