tui

package module
Version: v0.0.0-...-c1aa844 Latest Latest
Warning

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

Go to latest
Published: Feb 15, 2018 License: MIT Imports: 8 Imported by: 0

README

TUI

GoDoc MIT License

This is a Basic Implementation of a text ui D.O.S style, that can be used to run CLI commands or you can define your own HandlerCommand to run Go functions

Basic Structure is:

  • Menu

  • Commands - Each menu can have a set of commands to present

  • Args - Each command can have a set of arguments that get passed

The idea behing TUI is provide a simple library similar to the cli libs like https://github.com/urfave/cli that allows you to build a menu based application for terminal users.

By default a CLI command handler is provided that is able to pass parameters as flag, options or Enviroment variables You can find an example app in the /sampleapp folder

screenshot

Sample app

The project comes with a sample app under the folder /sampleapp

 cd sampleapp
 godep get
 go run app.go

Getting started with tui

A basic shell

Lets write a small application, You need to import the package, and create a basic menu with no option:

package main

import (
   "github.com/vtuson/tui"
)

func main() {
   menu := tui.NewMenu(tui.DefaultStyle())
   menu.Title = "Test"
   menu.Description = "Test app"
   menu.Show()

// This function handles input events like key strokes
   go menu.EventManager()

//Menu contains a channel that lets you know when the user has exited it
   <-menu.Wait

//Quits the menu, and cleans the screen
   menu.Quit()
}
Adding a command without arguments

Now lets add a small OS command that will run without need for arguments.

package main

import (
	"github.com/vtuson/tui"
)

func main() {
	menu := tui.NewMenu(tui.DefaultStyle())
	menu.Title = "Test"
	menu.Description = "Test app"

	menu.Commands = []tui.Command{
		tui.Command{
			Title:       "No Args",
			Cli:         "echo hello!",
			Description: "just being polite",
			Success:     "Yey it works",
			PrintOut:    true,
		},
	}

	menu.Show()
	go menu.EventManager()
	<-menu.Wait
	menu.Quit()
}

The option Printout allows for the output of the command to be shown to the user. The Description and Success are strings that will be use to add more context to the command execution. They are optional and dont need to be set if you don't want to.

Commands with arguments

You can also add argument to command that a user can input

package main

import (
	"github.com/vtuson/tui"
)

func main() {
	menu := tui.NewMenu(tui.DefaultStyle())
	menu.Title = "Test"
	menu.Description = "Test app"

	menu.Commands = []tui.Command{
		tui.Command{
			Title:       "Args CLI",
			Cli:         "echo",
			PrintOut:    true,
			Description: "test of running a tui.Command with arguments",
			Args: []tui.Argument{
				tui.Argument{
					Title: "Please say hi",
				},
			},
		},
	}

	menu.Show()
	go menu.EventManager()
	<-menu.Wait
	menu.Quit()
}

Arguments can also be boolean flags, they can have a name (which can be passed as input to the command) or can be set as environment variables.

Adding your own handler

The library assumes that the command is an OS command to be executed using the provided OSCmdHandler function if the Execute is nil. If another handler is passed by setting the Excute value, then it will be called when the users selects that command.

Here is a simple echo example:

package main

import (
	"github.com/vtuson/tui"
	"errors"
)

//This is the customer handler 
//c is the command object for the command to be executed. 
//ch is the channel that can be used to return text to be displayed back to the user.
//The hadnler is executed async from the main program,
//so you must close the channel when completed or the menu will hang 
//waiting for your command to complete.

func CustomHandler(c *tui.Command, ch chan string) {
	//defer close to make sure when you exit the menu knows to continue giving user the output
	defer close(ch)
	for _, a := range c.Args {
		ch <- a.Value
	}
	//if you want the command to fail set Error in the command variable
	c.Error=errors.New("It failed!")
}

func main() {
	menu := tui.NewMenu(tui.DefaultStyle())
	menu.Title = "Test"
	menu.Description = "Test app"

	menu.Commands = []tui.Command{
		tui.Command{
			Execute:     CustomHandler,
			Title:       "Args CLI",
			Cli:         "echo",
			PrintOut:    true,
			Description: "test of running a tui.Command with arguments",
			Args: []tui.Argument{
				tui.Argument{
					Title: "Please say hi",
				},
			},
		},
	}

	menu.Show()
	go menu.EventManager()
	<-menu.Wait
	menu.Quit()
}

Documentation

Overview

This is a Basic Implementation of a text ui that can be used to run CLI commands or you can define your own HandlerCommand to run Go functions Basic Structure is: Menu

[]Command
     []Args

By default a CLI command handler is provided that is able to pass parameters as flag, options or Enviroment variables

You can find an example app in the /example folder

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func OSCmdHandler

func OSCmdHandler(c *Command, ch chan string)

OS execution default handler Error in command is updated in completion

Types

type Argument

type Argument struct {
	Envar       string
	Name        string
	IsFlag      bool
	Title       string
	Description string
	Value       string
	IsBoolean   bool
	Valuebool   bool
}

Argument can be a flag (IsFlag) or a Envar (if defined). If IsFalg is false the Name is passed without a - appended IsBoolean means that the argument is passed with no additional value flag bool: -foo flag: -foo bar noflag bool: foo

type Command

type Command struct {
	Title       string
	Description string
	Cli         string
	Execute     HandlerCommand
	Args        []Argument
	Optional    bool
	Selected    bool
	Error       error
	Success     string
	Fail        string

	Disable bool
	Status  string

	PrintOut bool
	// contains filtered or unexported fields
}

func (*Command) BreadCrum

func (c *Command) BreadCrum() string

gets a breadcrum for a command

type HandlerCommand

type HandlerCommand func(c *Command, screen chan string)

type def for a handler function, pass a command and a channel to return screen stdout, channel will be close when execution is completed

type Menu struct {
	Title         string
	Description   string
	Commands      []Command
	Cursor        int
	BottomBar     bool
	BottomBarText string   //text for default top menu
	BackText      string   //text for back text on command
	BoolText      string   //text when an arg is a bool
	ValueText     string   //text when an arg is a value string
	Wait          chan int //channel to wait completion
	// contains filtered or unexported fields
}

func NewMenu

func NewMenu(style *Style) *Menu

Returns an initialised default Menu

func (m *Menu) BreadCrum() string

gets a breadcrum for a menus

func (m *Menu) CurrentCommand() *Command
func (menu *Menu) EventCommandManager()

Handles key events for commnands

func (menu *Menu) EventManager()

Handles Key events for Menu

func (m *Menu) IsToggle() bool
func (m *Menu) Next()

Moves to the next command in a list

func (m *Menu) NextArgument()

Moves menu to the Next Argument in a Command

func (m *Menu) Prev()

Moves back to the prev command

func (m *Menu) Quit()

Leaves a menu

func (m *Menu) RunCommand(c *Command)

Run commands and waits to complete, then calls menu ShowResult

func (m *Menu) SelectToggle()
func (m *Menu) Show()

Show Menu

func (m *Menu) ShowCommand()

Displays a command in the screen as incated by Cursor in Menu

func (m *Menu) ShowResult(c *Command)

Displays result of running a command, using test Fail and Success, plus adds error message for Fail

type Printing

type Printing struct {
	Cursor int
	// contains filtered or unexported fields
}

func NewPrinting

func NewPrinting(s tcell.Screen, style *Style) *Printing

returns printing object

func (*Printing) Bottom

func (p *Printing) Bottom()

moves cursor to the last line

func (*Printing) BottomBar

func (p *Printing) BottomBar(str string)

prints the bottome bar

func (*Printing) Clear

func (p *Printing) Clear()

Clears screen and goes back to the top

func (*Printing) Put

func (p *Printing) Put(str string, highlight bool)

same as Putln but continues on x

func (*Printing) PutEcho

func (p *Printing) PutEcho(str string, style tcell.Style)

prints string but does not move cursor

func (*Printing) PutH1

func (p *Printing) PutH1(str string, highlight bool)

putsln with H1 style

func (*Printing) Putln

func (p *Printing) Putln(str string, highlight bool)

adds a ln with a return at the end. hightlight uses the highlight style for the full line text

func (*Printing) PutlnDisable

func (p *Printing) PutlnDisable(str string)

add a line disabled style

func (*Printing) Return

func (p *Printing) Return()

add blank line

func (*Printing) Screen

func (p *Printing) Screen() tcell.Screen

gets the screen object

func (*Printing) Show

func (p *Printing) Show()

shows the screen

func (*Printing) Sync

func (p *Printing) Sync()

syncs the screen

func (*Printing) Top

func (p *Printing) Top()

moves cursor to the top

type ProgressBar

type ProgressBar struct {
	Interval int

	Text string
	// contains filtered or unexported fields
}

func NewProgressBar

func NewProgressBar(p *Printing) *ProgressBar

func (*ProgressBar) Start

func (p *ProgressBar) Start()

func (*ProgressBar) Stop

func (p *ProgressBar) Stop()

type Style

type Style struct {
	Indent     int
	Hightlight tcell.Style
	Default    tcell.Style
	Menu       tcell.Style
	H1         tcell.Style
	Input      tcell.Style
	Disable    tcell.Style
}

Defines style to be used on a menu Default styles are provide Indent is the number of spaces from the right side

func DefaultStyle

func DefaultStyle() *Style

returns default style

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL