inquire

package module
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Mar 25, 2018 License: MIT Imports: 3 Imported by: 1

README

inquire

A collection of common interactive command line user interfaces

inquire attempts to replicate the look and feel of the Node package inquirer, but for Go.

WIP

This is a work in progress. See demo/grail.go for a demonstration of using the API.

Demo

API

The API is not yet stable. I'm torn between building a permissive style API with interface types and maps -- or -- having a strongly typed interface with compile-time checking, etc. Perhaps there can be both, but for now, its the latter. Suggestions are welcome.

API documentation can be found at godoc.org.

License

This library is under the MIT License

Documentation

Overview

Package inquire provides a set of widgets for creating simple line-oriented terminal user interfaces.

User interfaces consist of line-oriented "widgets" of the following types:

YesNo  - prompt for yes/no answer
Input  - single line text input with optional default
Menu   - vertical menu of choices, chose one
Select - vertical menu of checkboxes, chose many

Widgets may be easily declared and bound to variables to receive input from the user.

Optional validation may be tied to widgets and validation error text will be displayed in the (always available and otherwise blank) line below each widget.

Widgets may also be conditionally skipped based on conditions that msut be met in a 'When' callback.

inquire uses a modified termbox-go library that is made to render part of the termbox buffer into a region of lines as a "viewport," without taking over the entire screen.

Example
package main

import (
	"github.com/burl/inquire"
)

func main() {
	// Variables for the answers to questions:
	name := ""
	really := false

	// Create a new list of questions to ask:
	questions := inquire.Query()

	// add questions
	questions.Input(&name, "what is your name", nil)
	questions.YesNo(&really, "is that really your name")

	// ask all the questions...
	questions.Exec()

}
Output:

Example (Chaining)
package main

import (
	"github.com/burl/inquire"
)

func main() {

	// All widget methods return the questions object, so
	// you can also just chain calls to the Questions() method:
	name := ""
	really := false
	inquire.Query().
		Input(&name, "what is your name", nil).
		YesNo(&really, "is that really your name").
		Exec()
}
Output:

Example (Login)
package main

import (
	"os"

	"github.com/burl/inquire"
	"github.com/burl/inquire/widget"
)

func main() {
	// Example of asking for a password (no terminal echo)
	user := os.Getenv("LOGNAME")
	pass := ""

	inquire.Query().
		Input(&user, "Username", nil).
		Input(&pass, "Password", func(w *widget.Input) {
			w.MaskInput() // Or pass a custom mask char: w.MaskInput('*')
		}).
		Exec()
}
Output:

Example (Valid)
package main

import (
	"github.com/burl/inquire"
	"github.com/burl/inquire/widget"
)

func main() {

	// Example of input validation

	planet := ""

	inquire.Query().
		Input(&planet, "what planet do you live on", func(w *widget.Input) {
			w.Valid(func(value string) string {
				if value != "earth" {
					// return a non-empty string if data is invalid, it will
					// be used as error text for the user
					return "nope, I don't believe it, you could not breathe on " + value
				}
				// return an empty string if the data is valid
				return ""
			})
		}).
		Exec()
}
Output:

Example (When)
package main

import (
	"github.com/burl/inquire"
	"github.com/burl/inquire/widget"
)

func main() {

	// Widgets may be optionally displayed based on
	// arbitrary conditions from a 'When' callback:
	mayImbibe := false
	beer := ""
	wine := ""

	// In this example, the user will only be asked about their favorite
	// beer or wine if they answered 'Yes' to the first question.

	inquire.Query().
		YesNo(&mayImbibe, "are you over 21 years of age").
		Input(&beer, "what is your favorite beer", func(w *widget.Input) {
			w.When(func() bool {
				return mayImbibe
			})
		}).
		Input(&wine, "what is your favorite wine", func(w *widget.Input) {
			// since testing equality is common, this is a shortcut
			// for the above/generic Wnen() callback
			w.WhenEqual(&mayImbibe, true)
		}).
		Exec()
}
Output:

Index

Examples

Constants

View Source
const Version = "0.0.3"

Version is the API version of inquire

Variables

This section is empty.

Functions

This section is empty.

Types

type Questions

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

Questions is an opaque type that represents a set of widgets for interacting with the user.

func Query

func Query() *Questions

Query creates a new Questions type

func (*Questions) Exec

func (inq *Questions) Exec()

Exec will execute the event loop, prompting the user for input for each question defined

func (*Questions) Input

func (inq *Questions) Input(value *string, prompt string, more func(*widget.Input)) *Questions

Input adds an Input widget to a set of questions. The argument 'value' should point to a string var, which will be assigned the result of the user interaction with the Input widget. If the initial content of 'value' is non-empty, then it will be used as the default answer.

A callback function may be passed as the final argument in order to register validation callbacks or set up conditional inqury. If this is not needed, then “nil“ should be passed.

func (*Questions) Menu

func (inq *Questions) Menu(value *string, prompt string, more func(*widget.Menu)) *Questions

Menu displays a veritcal menu of choices for the user to select one of. The final argument may be nil or a function that will be called back with the menu widget for further configuration. The value string pointed to by the first argument will receive the value of the "tag" string for the menu item chosen

func (*Questions) MenuItem

func (inq *Questions) MenuItem(tag, prompt string) *Questions

MenuItem may be used to append a menu item to the most recently added 'Menu' widget.

func (*Questions) Select

func (inq *Questions) Select(prompt string, more func(*widget.Select)) *Questions

Select displays a vertical menu of "checkbox" type entries for the user to select zero or more of. The variables bound to these entries must be bool vars and are associated with each entry.

func (*Questions) SelectItem

func (inq *Questions) SelectItem(value *bool, prompt string) *Questions

SelectItem may be used to append a select menu item to the most recently declared Select widget.

func (*Questions) YesNo

func (inq *Questions) YesNo(value *bool, prompt string) *Questions

YesNo adds a YesNo widget to a set of questions. value will be set to true for yes and false for no, based on user input.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL