bubblecomplete

README

Bubblecomplete

Bubblecomplete is a command suggestion and autocompletion component for Bubble Tea applications.

Usage

See the example for a full working implementation.

The command structure expects the following:

command [subcommands] [flags] [positionalArguments]

• A command can have multiple subcommands or positional arguments, and flags

  Git can have multiple sub commands such as git commit, git stash and git status

• A command can have subcommands or positional arguments, but not both.

  i.e. the subcommand stash in git stash has more subcommands like git stash pop, git stash apply, etc. but the subcommand push in git push has positional arguments like git push origin main

• Any command or subcommand can have flags.

  Git can have a flag such as --version or a subcommand such as git commit -m "message"

• Any command or subcommand can have both positional arguments and flags.

  Cat expects the positional argument for the file and then flags cat file.txt -n

• The order of positional arguments is important

  cp file.txt destination is different from cp destination file.txt

Setup

Create a slice of bubblecomplete.Command structs to represent the available commands, with bubblecomplete.PositionalArgument structs for any required arguments and bubblecomplete.Flag structs for any flags that can be passed.

var commands = []*bubblecomplete.Command{
	{
		Command:     "cp",
		Description: "Copy files and directories",
		PositionalArguments: []*bubblecomplete.PositionalArgument{
			{
				Name:        "file",
				Description: "File to copy",
				Type:        bubblecomplete.FileDirArgument,
				Required:    true,
			},
			{
				Name:        "destination",
				Description: "Destination to copy the file to",
				Type:        bubblecomplete.DirArgument,
				Required:    true,
			},
		},
		Flags: []*bubblecomplete.Flag{
			{
				ShortFlag:   "-r",
				Description: "Copy directories recursively",
				Type:        bubblecomplete.BoolArgument,
			},
		},
	},
}

Commands

Field	Description	Type
Command	The command name	string
Description	A description of the command	string
Subcommands	A slice of bubblecomplete.Command structs representing subcommands	[]*bubblecomplete.Command
PositionalArguments	A slice of bubblecomplete.PositionalArgument structs representing required arguments	[]*bubblecomplete.PositionalArgument
Flags	A slice of bubblecomplete.Flag structs representing flags	[]*bubblecomplete.Flag

Positional Arguments

Field	Description	Type
Name	The argument name	string
Description	A description of the argument	string
Type	The type of the argument	bubblecomplete.argumentType
Required	Whether the argument is required	bool

Flags

Field	Description	Type
ShortFlag	The short flag identifier i.e. -v	string
LongFlag	The long flag identifier i.e. --verbose	string
Description	A description of the flag	string
Type	The type of argument the flag expects	bubblecomplete.argumentType
Persistent	A persistent flag is available to all subcommands of the command	bool

Argument Types

Type	Description
StringArgument	A string argument that can be set to any value
IntArgument	An integer argument that can be set to any integer value
FloatArgument	A float argument that can be set to any float value
BoolArgument	A boolean argument that can be set to true or false (or left empty for true)
FileArgument	A file argument that can be set to a valid file path
DirArgument	A directory argument that can be set to a valid directory path
FileDirArgument	A file or directory argument that can be set to a valid file or directory path

Create a bubblecomplete.Model struct with the commands and set any options you want to set, and assign it to your bubbletea program model.

type model struct {
	bubblecomplete bubblecomplete.Model
}

func createModel() tea.Model {
	bc := bubblecomplete.New(commands, 100)
  bc.HistoryLimit = 50

  m := model{
    bubblecomplete: ac,
  }

	return m
}

func (m model) View() string {
  return m.bubblecomplete.View()
}

Options

Option	Description	Default
Autotrim	Trim extra whitespace from the ends of the input	true
CompletionsAbove	Show the completion list above the input instead of below	false
CompletionsOffset	The left margin offset of the completion list	0
CompletionsPosition	The position of the completion list relative to the input	PositionBelow
CompletionRows	The number of rows to show in the completion list before scrolling	5
HistoryFilePath	The path to a .json file to store the command history for persistance between sessions	-
HistoryLimit	The maximum number of history entries to store and save	100
IndentCompletions	Indent the completion list to match the current input length	true
InvalidCommandStyle	Lipgloss style for invalid user input	(white/black)
ShowBorderScroll	Show different border colors around the completion list to indicate scrolling	true
ShowScrollbar	Show a horizontal scrollbar to indicate scrolling	false
ValidCommandStyle	Lipgloss style for valid user input	(green)

Roadmap

• Autocomplete for filepaths
  • Underlined white if part of a valid path
  • Green if full valid path
  • Red if invalid path
• Option to have flags disable other flags if they're mutually exclusive
• Improved documentation comments for public functions and structs
• Wider range of tests for more critical functions, for improved maintainability
• Option to not show the descriptions of the commands, flags etc
• More exposed color options for the completion list, scrolling etc

FAQ

Colors

Bubblecomplete (and Bubble Tea applications in general) work best with a terminal that supports 24-bit color. If you're using a terminal that doesn't support 24-bit color, you may see some odd colors. If you're using a terminal that supports 24-bit color, ensure that it's enabled in your terminal emulator, tmux config (if you're using tmux) etc and that your $TERM environment variable is set to a value that supports 24-bit color (such as xterm-256color) and your $COLORTERM environment variable is set to truecolor.

Documentation

Index

• Constants
• type Argument
• type Command
  • func (c *Command) Validate() error
• type Completion
• type Flag
  • func (f *Flag) Validate() error
• type Model
  • func New(commands []*Command, width int) (Model, error)
  • func (m *Model) ClearHistory()
  • func (m *Model) CloseCompletions()
  • func (m *Model) SetHistoryFilePath(path string)
  • func (m *Model) SetPlaceholder(placeholder string)
  • func (m *Model) SetWidth(width int)
  • func (m *Model) ShowingCompletions() bool
  • func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)
  • func (m Model) View() string
• type Position
  • func (p Position) String() string
• type PositionalArgument
  • func (p *PositionalArgument) Validate() error
• type SelectedCommandMsg

Constants

const (
	StringArgument  argumentType = "string"
	IntArgument     argumentType = "int"
	FloatArgument   argumentType = "float"
	BoolArgument    argumentType = "bool"
	FileArgument    argumentType = "file"
	DirArgument     argumentType = "dir"
	FileDirArgument argumentType = "filedir"
)

Types

type Argument

type Argument interface {
	// contains filtered or unexported methods
}

type Command

type Command struct {
	Command             string
	Description         string
	SubCommands         []*Command
	PositionalArguments []*PositionalArgument
	Flags               []*Flag
}

func (*Command) Validate

func (c *Command) Validate() error

type Completion

type Completion interface {
	// contains filtered or unexported methods
}

type Flag

type Flag struct {
	ShortFlag   string
	LongFlag    string
	Description string
	Type        argumentType
	Persistent  bool
}

func (*Flag) Validate

func (f *Flag) Validate() error

type Model

type Model struct {

	// The commands available
	Commands []*Command

	// Slice that holds the history of commands
	History []string

	Err error

	// The maximum number of history items to store
	HistoryLimit int
	// Whether to indent completions to match the input
	IndentCompletions bool
	// Whether to trim the input on enter
	Autotrim bool
	// The base offset from the left, applied to the completions
	CompletionsOffset int
	// The text style for valid commands
	ValidCommandStyle lipgloss.Style
	// The text style for invalid commands
	InvalidCommandStyle lipgloss.Style
	// Whether to show different border styles to indicate scrolling
	ShowBorderScroll bool
	// Whether to show the horizontal scrollbar to indicate scrolling
	ShowScrollbar bool
	// The position of the completions relative to the input
	CompletionsPosition Position
	// The number of rows to show in the completions
	CompletionRows int
	// contains filtered or unexported fields
}

func New

func New(commands []*Command, width int) (Model, error)

New creates a new model with the given commands

Returns an error if any of the commands are invalid

func (*Model) ClearHistory

func (m *Model) ClearHistory()

ClearHistory clears the command history from all previous commands.

If the history file path is set, it also clears the history on file.

func (*Model) CloseCompletions

func (m *Model) CloseCompletions()

CloseCompletions hides the list of completions so it's no longer visible

Sets the input back to what the user had typed, if completions were being cycled through

func (*Model) SetHistoryFilePath

func (m *Model) SetHistoryFilePath(path string)

SetHistoryFilePath sets the file path to the file used for persisting the command history.

It creates the file if it doesn't exist. The directory of the file path must exist. The file path must be a valid JSON file with a .json extension.

func (*Model) SetPlaceholder

func (m *Model) SetPlaceholder(placeholder string)

Set the input placeholder text

func (*Model) SetWidth

func (m *Model) SetWidth(width int)

SetWidth sets the width of the model

This is used to calculate the offset for the completions and when text should be wrapped

func (*Model) ShowingCompletions

func (m *Model) ShowingCompletions() bool

ShowingCompletions returns true if the completions are currently visible

func (Model) Update

func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)

func (Model) View

func (m Model) View() string

type Position

type Position int

const (
	PositionAbove Position = iota
	PositionBelow
)

func (Position) String

func (p Position) String() string

type PositionalArgument

type PositionalArgument struct {
	Name        string
	Description string
	Type        argumentType
	Required    bool
}

func (*PositionalArgument) Validate

func (p *PositionalArgument) Validate() error

type SelectedCommandMsg

type SelectedCommandMsg struct {
	Command string
	Err     error
}