wmenu

README

WMenu

Package wmenu creates menus for cli programs. It uses wlog for it's interface with the command line. It uses os.Stdin, os.Stdout, and os.Stderr with concurrency by default. wmenu allows you to change the color of the different parts of the menu. This package also creates it's own error structure so you can type assert if you need to. wmenu will validate all responses before calling any function. It will also figure out which function should be called so you don't have to.

Import

I try and keep up with my tags. To use the version and stable it is recommended to use govendor or another vendoring tool that allows you to build your project for specific tags.

govendor fetch github.com/dixonwille/wmenu@v4

The above will grab the latest v4 at that time and mark it. It will then be stable for you to use.

I will try to support as many versions as possable but please be patient.

V1.0.0 - Major Release

V2.0.0 - Allowing an interface to be passed in for options

V3.0.0 - Pass in the option to that option's function

V4.0.0 - Now have an Action that supports multiple options

Features

• Force single selection
• Allow multiple selection
• Change the delimiter
• Change the color of different parts of the menu
• Easily see which option(s) are default
• Change the symbol used for default option(s)
• Ask simple yes and no questions
• Validate all responses before calling any functions
• With yes and no can accept:
  • yes, Yes, YES, y, Y
  • no, No, NO, n, N
• Figure out which Action should be called (Options, Default, or Multiple Action)
• Re-ask question if invalid response up to a certain number of times
• Can change max number of times to ask before failing output
• Change reader and writer
• Clear the screen whenever the menu is brought up
• Has its own error structure so you can type assert menu errors

V2 - Adds these Features

• Allowing any interface to be passed through for the options.

V3 - Adds these Features

• Pass the option chosen to that options function

V4 - Adds these Features

• Have one function for both single and multiple select. Allowing the user to an easier way of handeling the request.

Usage

This is a simple use of the package. (NOTE: THIS IS A V4 SAMPLE)

menu := wmenu.NewMenu("What is your favorite food?")
menu.Action(func (opts []wmenu.Opt) error {fmt.Printf(opts[0].Text + " is your favorite food."); return nil})
menu.Option("Pizza", nil, true, nil)
menu.Option("Ice Cream", nil, false, nil)
menu.Option("Tacos", nil, false, func() error {
  fmt.Printf("Tacos are great")
})
err := menu.Run()
if err != nil{
  log.Fatal(err)
}

The output would look like this:

0) *Pizza
1) Ice Cream
2) Tacos
What is your favorite food?

If the user just presses [Enter] then the option(s) with the * will be selected. This indicates that it is a default function. If they choose 1 then they would see Ice Cream is your favorite food.. This used the Action's function because the option selected didn't have a function along with it. But if they choose 2 they would see Tacos are great. That option did have a function with it which take precedence over Action.

You can you also use:

menu.AllowMultiple()

This will allow the user to select multiple options. The default delimiter is a [space], but can be changed by using:

menu.SetSeperator("some string")

Another feature is the ability to ask yes or no questions.

menu.IsYesNo(0)

This will remove any options previously added options and hide the ones used for the menu. It will simply just ask yes or no. Menu will parse and validate the response for you. This option will always call the Action's function and pass in the option that was selected.

V3+ - Release

Allows the user to pass anything for the value so it can be retrieved later in the function. The following is to show case the power of this.

The following was written in V3 but the concept holds for V4. V4 just changed actFunc to be func([]wmenu.Opt) error instead.

type NameEntity struct {
  FirstName string
  LastName  string
}

optFunc := func(opt wmenu.Opt) error {
  fmt.Println("Option 0 was chosen.")
  return nil
}
actFunc := func(opt wmenu.Opt) error {
  name, ok := opt.Value.(NameEntity)
  if !ok {
    log.Fatal("Could not cast option's value to NameEntity")
  }
  fmt.Printf("%s has an id of %d.\n", opt.Text, opt.ID)
  fmt.Printf("Hello, %s %s.\n", name.FirstName, name.LastName)
  return nil
}
menu := NewMenu("Choose an option.")
menu.ChangeReaderWriter(reader, os.Stdout, os.Stderr)
menu.Action(actFunc)
menu.Option("Option 0", NameEntity{"Bill", "Bob"}, true, optFunc)
menu.Option("Option 1", NameEntity{"John", "Doe"}, false, nil)
menu.Option("Option 2", NameEntity{"Jane", "Doe"}, false, nil)
err := menu.Run()
if err != nil {
  log.Fatal(err)
}

The immediate output would be:

Output:
0) *Option 0
1) Option 1
2) Option 2
Choose an option.

Now if the user pushes [ENTER] the output would be Options 0 was chosen.. But now if either option 1 or 2 were chosen it would cast the options value to a NameEntity allowing the function to be able to gather both the first name and last name of the NameEntity. If you want though you can just pass in nil as the value or even a string ("hello") since both of these implement the empty interface required by value. Just make sure to cast the values so you can use them appropriately.

Further Reading

This whole package has been documented and has a few examples in:

• godocs V1
• godocs V2
• godocs V3
• godocs V4

You should read the docs to find all functions and structures at your finger tips.

Documentation

Overview

Package wmenu creates menus for cli programs. It uses wlog for it's interface with the command line. It uses os.Stdin, os.Stdout, and os.Stderr with concurrency by default. wmenu allows you to change the color of the different parts of the menu. This package also creates it's own error structure so you can type assert if you need to. wmenu will validate all responses before calling any function. It will also figure out which function should be called so you don't have to.

Example (ErrorDuplicate)

reader := strings.NewReader("1 1\r\n") //Simulates the user typing "1 1" and hitting the [enter] key
optFunc := func(option Opt) error {
	fmt.Println("Option 0 was chosen.")
	return nil
}
actFunc := func(opts []Opt) error {
	for _, opt := range opts {
		fmt.Printf("%s has an id of %d.\n", opt.Text, opt.ID)
	}
	return nil
}
menu := NewMenu("Choose an option.")
menu.ChangeReaderWriter(reader, os.Stdout, os.Stderr)
menu.Action(actFunc)
menu.AllowMultiple()
menu.Option("Option 0", "0", false, optFunc)
menu.Option("Option 1", "1", false, nil)
menu.Option("Option 2", "2", false, nil)
err := menu.Run()
if err != nil {
	if IsDuplicateErr(err) {
		fmt.Println("We caught the err: " + err.Error())
	} else {
		log.Fatal(err)
	}
}

Output:

0) Option 0
1) Option 1
2) Option 2
Choose an option.
We caught the err: Duplicated response: 1

Example (ErrorInvalid)

reader := strings.NewReader("3\r\n") //Simulates the user typing "3" and hitting the [enter] key
optFunc := func(option Opt) error {
	fmt.Println("Option 0 was chosen.")
	return nil
}
menu := NewMenu("Choose an option.")
menu.ChangeReaderWriter(reader, os.Stdout, os.Stderr)
menu.Option("Option 0", "0", false, optFunc)
menu.Option("Option 1", "1", false, nil)
menu.Option("Option 2", "2", false, nil)
err := menu.Run()
if err != nil {
	if IsInvalidErr(err) {
		fmt.Println("We caught the err: " + err.Error())
	} else {
		log.Fatal(err)
	}
}

Output:

0) Option 0
1) Option 1
2) Option 2
Choose an option.
We caught the err: Invalid response: 3

Example (ErrorNoResponse)

reader := strings.NewReader("\r\n") //Simulates the user hitting the [enter] key
optFunc := func(option Opt) error {
	fmt.Println("Option 0 was chosen.")
	return nil
}
menu := NewMenu("Choose an option.")
menu.ChangeReaderWriter(reader, os.Stdout, os.Stderr)
menu.Option("Option 0", "0", false, optFunc)
menu.Option("Option 1", "1", false, nil)
menu.Option("Option 2", "2", false, nil)
err := menu.Run()
if err != nil {
	if IsNoResponseErr(err) {
		fmt.Println("We caught the err: " + err.Error())
	} else {
		log.Fatal(err)
	}
}

Output:

0) Option 0
1) Option 1
2) Option 2
Choose an option.
We caught the err: No response

Example (ErrorTooMany)

reader := strings.NewReader("1 2\r\n") //Simulates the user typing "1 2" and hitting the [enter] key
optFunc := func(option Opt) error {
	fmt.Println("Option 0 was chosen.")
	return nil
}
menu := NewMenu("Choose an option.")
menu.ChangeReaderWriter(reader, os.Stdout, os.Stderr)
menu.Option("Option 0", "0", false, optFunc)
menu.Option("Option 1", "1", false, nil)
menu.Option("Option 2", "2", false, nil)
err := menu.Run()
if err != nil {
	if IsTooManyErr(err) {
		fmt.Println("We caught the err: " + err.Error())
	} else {
		log.Fatal(err)
	}
}

Output:

0) Option 0
1) Option 1
2) Option 2
Choose an option.
We caught the err: Too many responses

Example (Multiple)

reader := strings.NewReader("1,2\r\n") //Simulates the user typing "1,2" and hitting the [enter] key
optFunc := func(option Opt) error {
	fmt.Println("Option 0 was chosen.")
	return nil
}
actFunc := func(opts []Opt) error {
	for _, opt := range opts {
		fmt.Printf("%s has an id of %d.\n", opt.Text, opt.ID)
	}
	return nil
}
menu := NewMenu("Choose an option.")
menu.ChangeReaderWriter(reader, os.Stdout, os.Stderr)
menu.Action(actFunc)
menu.AllowMultiple()
menu.SetSeparator(",")
menu.Option("Option 0", "0", true, optFunc)
menu.Option("Option 1", "1", false, nil)
menu.Option("Option 2", "2", true, nil)
err := menu.Run()
if err != nil {
	log.Fatal(err)
}

Output:

0) *Option 0
1) Option 1
2) *Option 2
Choose an option.
Option 1 has an id of 1.
Option 2 has an id of 2.

Example (MultipleDefault)

reader := strings.NewReader("\r\n") //Simulates the user hitting the [enter] key
optFunc := func(option Opt) error {
	fmt.Println("Option 0 was chosen.")
	return nil
}
actFunc := func(opts []Opt) error {
	for _, opt := range opts {
		fmt.Printf("%s has an id of %d.\n", opt.Text, opt.ID)
	}
	return nil
}
menu := NewMenu("Choose an option.")
menu.ChangeReaderWriter(reader, os.Stdout, os.Stderr)
menu.Action(actFunc)
menu.AllowMultiple()
menu.Option("Option 0", "0", true, optFunc)
menu.Option("Option 1", "1", false, nil)
menu.Option("Option 2", "2", true, nil)
err := menu.Run()
if err != nil {
	log.Fatal(err)
}

Output:

0) *Option 0
1) Option 1
2) *Option 2
Choose an option.
Option 0 has an id of 0.
Option 2 has an id of 2.

Example (OptionValue)

type NameEntity struct {
	FirstName string
	LastName  string
}

reader := strings.NewReader("1\r\n") //Simulates the user typing "1" and hitting the [enter] key
optFunc := func(option Opt) error {
	fmt.Println("Option 0 was chosen.")
	return nil
}
actFunc := func(opts []Opt) error {
	name, ok := opts[0].Value.(NameEntity)
	if !ok {
		log.Fatal("Could not cast option's value to NameEntity")
	}
	fmt.Printf("%s has an id of %d.\n", opts[0].Text, opts[0].ID)
	fmt.Printf("Hello, %s %s.\n", name.FirstName, name.LastName)
	return nil
}
menu := NewMenu("Choose an option.")
menu.ChangeReaderWriter(reader, os.Stdout, os.Stderr)
menu.Action(actFunc)
menu.Option("Option 0", NameEntity{"Bill", "Bob"}, true, optFunc)
menu.Option("Option 1", NameEntity{"John", "Doe"}, false, nil)
menu.Option("Option 2", NameEntity{"Jane", "Doe"}, false, nil)
err := menu.Run()
if err != nil {
	log.Fatal(err)
}

Output:

0) *Option 0
1) Option 1
2) Option 2
Choose an option.
Option 1 has an id of 1.
Hello, John Doe.

Example (SimpleDefault)

reader := strings.NewReader("\r\n") //Simulates the user hitting the [enter] key
optFunc := func(option Opt) error {
	fmt.Fprint(os.Stdout, "Option 0 was chosen.")
	return nil
}
menu := NewMenu("Choose an option.")
menu.ChangeReaderWriter(reader, os.Stdout, os.Stderr)
menu.Option("Option 0", "0", true, optFunc)
menu.Option("Option 1", "1", false, nil)
menu.Option("Option 2", "2", false, nil)
err := menu.Run()
if err != nil {
	log.Fatal(err)
}

Output:

0) *Option 0
1) Option 1
2) Option 2
Choose an option.
Option 0 was chosen.

Example (YesNo)

reader := strings.NewReader("y\r\n") //Simulates the user typing "y" and hitting the [enter] key
actFunc := func(opts []Opt) error {
	fmt.Printf("%s has an id of %d.\n", opts[0].Text, opts[0].ID)
	fmt.Printf("But has a value of %s.\n", opts[0].Value.(string))
	return nil
}
menu := NewMenu("Would you like to start?")
menu.ChangeReaderWriter(reader, os.Stdout, os.Stderr)
menu.Action(actFunc)
menu.IsYesNo(0)
err := menu.Run()
if err != nil {
	log.Fatal(err)
}

Output:

Would you like to start? (Y/n)
y has an id of 0.
But has a value of yes.

Index

• Variables
• func Clear()
• func IsDuplicateErr(err error) bool
• func IsInvalidErr(err error) bool
• func IsMenuErr(err error) bool
• func IsNoResponseErr(err error) bool
• func IsTooManyErr(err error) bool
• type Menu
  • func NewMenu(question string) *Menu
  • func (m *Menu) Action(function func([]Opt) error)
  • func (m *Menu) AddColor(optionColor, questionColor, responseColor, errorColor wlog.Color)
  • func (m *Menu) AllowMultiple()
  • func (m *Menu) ChangeReaderWriter(reader io.Reader, writer, errorWriter io.Writer)
  • func (m *Menu) ClearOnMenuRun()
  • func (m *Menu) IsYesNo(def int)
  • func (m *Menu) LoopOnInvalid()
  • func (m *Menu) Option(title string, value interface{}, isDefault bool, function func(Opt) error)
  • func (m *Menu) Run() error
  • func (m *Menu) SetDefaultIcon(icon string)
  • func (m *Menu) SetSeparator(sep string)
  • func (m *Menu) SetTries(i int)
• type MenuError
  • func (e *MenuError) Error() string
• type Opt

Examples

• Package (ErrorDuplicate)
• Package (ErrorInvalid)
• Package (ErrorNoResponse)
• Package (ErrorTooMany)
• Package (Multiple)
• Package (MultipleDefault)
• Package (OptionValue)
• Package (SimpleDefault)
• Package (YesNo)

Variables

var (
	//ErrInvalid is returned if a response from user was an invalid option
	ErrInvalid = errors.New("Invalid response")

	//ErrTooMany is returned if multiSelect is false and a user tries to select multiple options
	ErrTooMany = errors.New("Too many responses")

	//ErrNoResponse is returned if there were no responses and no action to call
	ErrNoResponse = errors.New("No response")

	//ErrDuplicate is returned is a user selects an option twice
	ErrDuplicate = errors.New("Duplicated response")
)

Functions

func Clear

func Clear()

Clear simply clears the command line interface (os.Stdout only).

func IsDuplicateErr

func IsDuplicateErr(err error) bool

IsDuplicateErr checks to see if err is of type duplicate returned by menu.

func IsInvalidErr

func IsInvalidErr(err error) bool

IsInvalidErr checks to see if err is of type invalid error returned by menu.

func IsMenuErr

func IsMenuErr(err error) bool

IsMenuErr checks to see if it is a menu err. This is a general check not a specific one.

func IsNoResponseErr

func IsNoResponseErr(err error) bool

IsNoResponseErr checks to see if err is of type no response returned by menu.

func IsTooManyErr

func IsTooManyErr(err error) bool

IsTooManyErr checks to see if err is of type too many returned by menu.

Types

type Menu

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

Menu is used to display options to a user. A user can then select options and Menu will validate the response and perform the correct action.

func NewMenu

func NewMenu(question string) *Menu

NewMenu creates a menu with a wlog.UI as the writer.

func (*Menu) Action

func (m *Menu) Action(function func([]Opt) error)

Action adds a default action to use in certain scenarios. If the selected option (by default or user selected) does not have a function applied to it this will be called. If there are no default options and no option was selected this will be called with an option that has an ID of -1.

func (*Menu) AddColor

func (m *Menu) AddColor(optionColor, questionColor, responseColor, errorColor wlog.Color)

AddColor will change the color of the menu items. optionColor changes the color of the options. questionColor changes the color of the questions. errorColor changes the color of the question. Use wlog.None if you do not want to change the color.

func (*Menu) AllowMultiple

func (m *Menu) AllowMultiple()

AllowMultiple will tell the menu to allow multiple selections. The menu will fail if this is not called and mulple selections were selected.

func (*Menu) ChangeReaderWriter

func (m *Menu) ChangeReaderWriter(reader io.Reader, writer, errorWriter io.Writer)

ChangeReaderWriter changes where the menu listens and writes to. reader is where user input is collected. writer and errorWriter is where the menu should write to.

func (*Menu) ClearOnMenuRun

func (m *Menu) ClearOnMenuRun()

ClearOnMenuRun will clear the screen when a menu is ran. This is checked when LoopOnInvalid is activated. Meaning if an error occurred then it will clear the screen before asking again.

func (*Menu) IsYesNo

func (m *Menu) IsYesNo(def int)

IsYesNo sets the menu to a yes/no state. Does not show options but does ask question. Will also parse the answer to allow for all variants of yes/no (IE Y yes No ...) Specify the default value using def. 0 is for yes and 1 is for no. Both will call the Action function you specified. Opt{ID: 0, Text: "y"} for yes and Opt{ID: 1, Text: "n"} for no will be passed to the function.

func (*Menu) LoopOnInvalid

func (m *Menu) LoopOnInvalid()

LoopOnInvalid is used if an invalid option was given then it will prompt the user again.

func (*Menu) Option

func (m *Menu) Option(title string, value interface{}, isDefault bool, function func(Opt) error)

Option adds an option to the menu for the user to select from. value is an empty interface that can be used to pass anything through to the function. title is the string the user will select isDefault is whether this option is a default option (IE when no options are selected). function is what is called when only this option is selected. If function is nil then it will default to the menu's Action.

func (*Menu) Run

func (m *Menu) Run() error

Run is used to execute the menu. It will print to options and question to the screen. It will only clear the screen if ClearOnMenuRun is activated. This will validate all responses. Errors are of type MenuError.

func (*Menu) SetDefaultIcon

func (m *Menu) SetDefaultIcon(icon string)

SetDefaultIcon sets the icon used to identify which options will be selected by default

func (*Menu) SetSeparator

func (m *Menu) SetSeparator(sep string)

SetSeparator sets the separator to use when multiple options are valid responses. Default value is a space.

func (*Menu) SetTries

func (m *Menu) SetTries(i int)

SetTries sets the number of tries on the loop before failing out. Default is 3. Negative values act like 0.

type MenuError

type MenuError struct {
	Err       error
	Res       string
	TriesLeft int
}

MenuError records menu errors

func (*MenuError) Error

func (e *MenuError) Error() string

Error prints the error in an easy to read string.

type Opt

type Opt struct {
	ID    int
	Text  string
	Value interface{}
	// contains filtered or unexported fields
}

Opt is what Menu uses to display options to screen. Also holds information on what should run and if it is a default option