console

README

Console

Closed-loop application library for Cobra commands

(ready-to-use menus, prompts, completions, and more)

Console is an all-in-one console application library built on top of a readline shell and using Cobra commands. It aims to provide users with a modern interface at at minimal cost while allowing them to focus on developing their commands and application core: the console will then transparently interface with these commands, and provide the various features below almost for free.

Features

Menus & Commands

• Bind cobra commands to provide the core functionality.
• Multiple menus with their own command tree, prompt engines and special handlers.
• All cobra settings can be modified, set and used freely, like in normal CLI workflows.
• Bind handlers to special interrupt errors (eg. CtrlC/CtrlD), per menu.

Shell interface

• Shell is powered by a readline instance, with full inputrc support and extended functionality.
• All features of readline are supported in the console. It also allows the console to give:
• Configurable bind keymaps, commands and options, sane defaults, and per-application configuration.
• Out-of-the-box, advanced completions for commands, flags, positional and flag arguments.
• Provided by readline and carapace: automatic usage & validation command/flags/args hints.
• Syntax highlighting for commands (might be extended in the future).

Others

• Support for an arbitrary number of history sources, per menu.
• Support for oh-my-posh prompts, per menu and with custom configuration files for each.
• Also with oh-my-posh, write and bind application/menu-specific prompt segments.
• Set of ready-to-use commands (commands/ directory) for readline binds/options manipulation.

Documentation

You can install and use the example application console. This example application will give you a taste of the behavior and supported features. The following documentation is also available in the wiki:

• Getting started
• Menus
• Prompts
• Binding commands
• Interrupt handlers
• History Sources
• Logging
• Readline shell
• Other utilities

Showcase

Status

The library is in a pre-release candidate status:

• Although quite simple and small, it has not been tested heavily.
• There are probably some features/improvements to be made.
• The API is quite stable. It is unlikely to change much in future versions.

Please open a PR or an issue if you wish to bring enhancements to it. Other contributions, as well as bug fixes and reviews are also welcome.

Possible Improvements

The following is a currently moving list of possible enhancements to be made in order to reach v1.0:

• Ensure to the best extent possible a thread-safe access to the command API.
• Clearer integration/alignment of the various I/O references between readline and commands.
• Clearer and sane model for asynchronous control/cancel of commands.
• Allow users to run the console command trees in one-exec style, with identical behavior.
• Test suite for most important or risky code paths.
• Set of helper functions for application-related directories.

Documentation

Index

• Constants
• type Commands
• type Console
  • func New(app string) *Console
  • func (c *Console) ActiveMenu() *Menu
  • func (c *Console) HideCommands(filters ...string)
  • func (c *Console) Menu(name string) *Menu
  • func (c *Console) NewMenu(name string) *Menu
  • func (c *Console) Printf(msg string, args ...any) (n int, err error)
  • func (c *Console) SetPrintLogo(f func(c *Console))
  • func (c *Console) Shell() *readline.Shell
  • func (c *Console) ShowCommands(filters ...string)
  • func (c *Console) Start() error
  • func (c *Console) SwitchMenu(menu string)
  • func (c *Console) SystemEditor(buffer []byte, filetype string) ([]byte, error)
  • func (c *Console) TransientPrintf(msg string, args ...any) (n int, err error)
• type Menu
  • func (m *Menu) ActiveFiltersFor(cmd *cobra.Command) []string
  • func (m *Menu) AddHistorySource(name string, source readline.History)
  • func (m *Menu) AddHistorySourceFile(name string, filepath string)
  • func (m *Menu) AddInterrupt(err error, handler func(c *Console))
  • func (m *Menu) CheckIsAvailable(cmd *cobra.Command) error
  • func (m *Menu) DelInterrupt(errs ...error)
  • func (m *Menu) DeleteHistorySource(name string)
  • func (m *Menu) Name() string
  • func (m *Menu) Printf(msg string, args ...any) (n int, err error)
  • func (m *Menu) Prompt() *Prompt
  • func (m *Menu) RunCommandArgs(args []string) (err error)
  • func (m *Menu) RunCommandLine(line string) (err error)
  • func (m *Menu) SetCommands(cmds Commands)
  • func (m *Menu) SetErrFilteredCommandTemplate(s string)
  • func (m *Menu) TransientPrintf(msg string, args ...any) (n int, err error)
• type Prompt

Constants

const (
	// CommandFilterKey should be used as a key to in a cobra.Annotation map.
	// The value will be used as a filter to disable commands when the console
	// calls the Filter("name") method on the console.
	// The string value will be comma-splitted, with each split being a filter.
	CommandFilterKey = "console-hidden"
)

Types

type Commands

type Commands func() *cobra.Command

Commands is a simple function a root cobra command containing an arbitrary tree of subcommands, along with any behavior parameters normally found in cobra. This function is used by each menu to produce a new, blank command tree after each execution run, as well as each command completion invocation.

type Console

type Console struct {

	// Leave an empty line before executing the command.
	NewlineBefore bool

	// Leave an empty line after executing the command.
	// Note that if you also want this newline to be used when logging messages
	// with TransientPrintf(), Printf() calls, you should leave this to false,
	// and add a leading newline to your prompt instead: the readline shell will
	// know how to handle it in all situations.
	NewlineAfter bool

	// PreReadlineHooks - All the functions in this list will be executed,
	// in their respective orders, before the console starts reading
	// any user input (ie, before redrawing the prompt).
	PreReadlineHooks []func() error

	// PreCmdRunLineHooks - Same as PreCmdRunHooks, but will have an effect on the
	// input line being ultimately provided to the command parser. This might
	// be used by people who want to apply supplemental, specific processing
	// on the command input line.
	PreCmdRunLineHooks []func(args []string) ([]string, error)

	// PreCmdRunHooks - Once the user has entered a command, but before executing
	// the target command, the console will execute every function in this list.
	// These hooks are distinct from the cobra.PreRun() or OnInitialize hooks,
	// and might be used in combination with them.
	PreCmdRunHooks []func() error

	// PostCmdRunHooks are run after the target cobra command has been executed.
	// These hooks are distinct from the cobra.PreRun() or OnFinalize hooks,
	// and might be used in combination with them.
	PostCmdRunHooks []func() error
	// contains filtered or unexported fields
}

Console is an integrated console application instance.

func New

func New(app string) *Console

New - Instantiates a new console application, with sane but powerful defaults. This instance can then be passed around and used to bind commands, setup additional things, print asynchronous messages, or modify various operating parameters on the fly. The app parameter is an optional name of the application using this console.

func (*Console) ActiveMenu

func (c *Console) ActiveMenu() *Menu

ActiveMenu - Return the currently used console menu.

func (*Console) HideCommands

func (c *Console) HideCommands(filters ...string)

HideCommands - Commands, in addition to their menus, can be shown/hidden based on a filter string. For example, some commands applying to a Windows host might be scattered around different groups, but, having all the filter "windows". If "windows" is used as the argument here, all windows commands for the current menu are subsequently hidden, until ShowCommands("windows") is called.

func (*Console) Menu

func (c *Console) Menu(name string) *Menu

Menu returns one of the console menus by name, or nil if no menu is found.

func (*Console) NewMenu

func (c *Console) NewMenu(name string) *Menu

NewMenu - Create a new command menu, to which the user can attach any number of commands (with any nesting), as well as some specific items like history sources, prompt configurations, sets of expanded variables, and others.

func (*Console) Printf

func (c *Console) Printf(msg string, args ...any) (n int, err error)

Printf prints a string message (a log, or more broadly, an asynchronous event) below the current prompt. The message is printed regardless of the current menu.

If this function is called while a command is running, the console will simply print the log below the line, and will not print the prompt. In any other case this function works normally.

func (*Console) SetPrintLogo

func (c *Console) SetPrintLogo(f func(c *Console))

SetPrintLogo - Sets the function that will be called to print the logo.

func (*Console) Shell

func (c *Console) Shell() *readline.Shell

Shell returns the console readline shell instance, so that the user can further configure it or use some of its API for lower-level stuff.

func (*Console) ShowCommands

func (c *Console) ShowCommands(filters ...string)

ShowCommands - Commands, in addition to their menus, can be shown/hidden based on a filter string. For example, some commands applying to a Windows host might be scattered around different groups, but, having all the filter "windows". Use this function if you have previously called HideCommands("filter") and want these commands to be available back under their respective menu.

func (*Console) Start

func (c *Console) Start() error

Start - Start the console application (readline loop). Blocking. The error returned will always be an error that the console application does not understand or cannot handle.

func (*Console) SwitchMenu

func (c *Console) SwitchMenu(menu string)

SwitchMenu - Given a name, the console switches its command menu: The next time the console rebinds all of its commands, it will only bind those that belong to this new menu. If the menu is invalid, i.e that no commands are bound to this menu name, the current menu is kept.

func (*Console) SystemEditor

func (c *Console) SystemEditor(buffer []byte, filetype string) ([]byte, error)

SystemEditor - This function is a renamed-reexport of the underlying readline.StartEditorWithBuffer function, which enables you to conveniently edit files/buffers from within the console application. Naturally, the function will block until the editor is exited, and the updated buffer is returned. The filename parameter can be used to pass a specific filename.ext pattern, which might be useful if the editor has builtin filetype plugin functionality.

func (*Console) TransientPrintf

func (c *Console) TransientPrintf(msg string, args ...any) (n int, err error)

TransientPrintf prints a string message (a log, or more broadly, an asynchronous event) without bothering the user, displaying the message and "pushing" the prompt below it. The message is printed regardless of the current menu.

If this function is called while a command is running, the console will simply print the log below the line, and will not print the prompt. In any other case this function works normally.

type Menu

type Menu struct {

	// The root cobra command/parser is the one returned by the handler provided
	// through the `menu.SetCommands()` function. This command is thus renewed after
	// each command invocation/execution.
	// You can still use it as you want, for instance to introspect the current command
	// state of your menu.
	*cobra.Command
	// contains filtered or unexported fields
}

Menu - A menu is a simple way to seggregate commands based on the environment to which they belong. For instance, when using a menu specific to some host/user, or domain of activity, commands will vary.

func (*Menu) ActiveFiltersFor

func (m *Menu) ActiveFiltersFor(cmd *cobra.Command) []string

ActiveFiltersFor returns all the active menu filters that a given command does not declare as compliant with (added with console.Hide/ShowCommand()).

func (*Menu) AddHistorySource

func (m *Menu) AddHistorySource(name string, source readline.History)

AddHistorySource adds a source of history commands that will be accessible to the shell when the menu is active.

func (*Menu) AddHistorySourceFile

func (m *Menu) AddHistorySourceFile(name string, filepath string)

AddHistorySourceFile adds a new source of history populated from and writing to the specified "filepath" parameter. On the first call to this function, the default in-memory history source is removed.

func (*Menu) AddInterrupt

func (m *Menu) AddInterrupt(err error, handler func(c *Console))

AddInterrupt registers a handler to run when the console receives a given interrupt error from the underlying readline shell. Mainly two interrupt signals are concerned: io.EOF (returned when pressing CtrlD), and console.ErrCtrlC. Many will want to use this to switch menus. Note that these interrupt errors only work when the console is NOT currently executing a command, only when reading input.

func (*Menu) CheckIsAvailable

func (m *Menu) CheckIsAvailable(cmd *cobra.Command) error

CheckIsAvailable checks if a target command is marked as filtered by the console application registered/and or active filters (added with console.Hide/ShowCommand()). If filtered, returns a template-formatted error message showing the list of incompatible filters. If not filtered, no error is returned.

func (*Menu) DelInterrupt

func (m *Menu) DelInterrupt(errs ...error)

DelInterrupt removes one or more interrupt handlers from the menu registered ones. If no error is passed as argument, all handlers are removed.

func (*Menu) DeleteHistorySource

func (m *Menu) DeleteHistorySource(name string)

DeleteHistorySource removes a history source from the menu. This normally should only be used in two cases: - You want to replace the default in-memory history with another one. - You want to replace one of your history sources for some reason.

func (*Menu) Name

func (m *Menu) Name() string

Name returns the name of this menu.

func (*Menu) Printf

func (m *Menu) Printf(msg string, args ...any) (n int, err error)

Printf prints a message to the console, but only if the current menu is active. If the menu is not active, the message is buffered and will be printed the next time the menu is active.

Unlike TransientPrintf, this function will not print the message above the current prompt, but will instead print it below it.

If this function is called while a command is running, the console will simply print the log below the current line, and will not print the prompt. In any other case this function will work normally.

func (*Menu) Prompt

func (m *Menu) Prompt() *Prompt

Prompt returns the prompt object for this menu.

func (*Menu) RunCommandArgs

func (m *Menu) RunCommandArgs(args []string) (err error)

RunCommandArgs is a convenience function to run a command line in a given menu. After running, the menu's commands are reset, and the prompts reloaded, therefore mostly mimicking the behavior that is the one of the normal readline/run/readline workflow. Although state segregation is a priority for this library to be ensured as much as possible, you should be cautious when using this function to run commands.

func (*Menu) RunCommandLine

func (m *Menu) RunCommandLine(line string) (err error)

RunCommandLine is the equivalent of menu.RunCommandArgs(), but accepts an unsplit command line to execute. This line is split and processed in *sh-compliant form, identically to how lines are in normal console usage.

func (*Menu) SetCommands

func (m *Menu) SetCommands(cmds Commands)

SetCommands requires a function returning a tree of cobra commands to be used.

func (*Menu) SetErrFilteredCommandTemplate

func (m *Menu) SetErrFilteredCommandTemplate(s string)

SetErrFilteredCommandTemplate sets the error template to be used when a called command can't be executed because it's mark filtered.

func (*Menu) TransientPrintf

func (m *Menu) TransientPrintf(msg string, args ...any) (n int, err error)

TransientPrintf prints a message to the console, but only if the current menu is active. If the menu is not active, the message is buffered and will be printed the next time the menu is active.

The message is printed as a transient message, meaning that it will be printed above the current prompt, effectively "pushing" the prompt down.

If this function is called while a command is running, the console will simply print the log below the current line, and will not print the prompt. In any other case this function will work normally.

type Prompt

type Prompt struct {
	Primary   func() string            // Primary is the main prompt.
	Secondary func() string            // Secondary is the prompt used when the user is typing a multi-line command.
	Transient func() string            // Transient is used if the console shell is configured to be transient.
	Right     func() string            // Right is the prompt printed on the right side of the screen.
	Tooltip   func(word string) string // Tooltip is used to hint on the root command, replacing right prompts if not empty.
	// contains filtered or unexported fields
}

Prompt - A prompt is a set of functions that return the strings to print for each prompt type. The console will call these functions to retrieve the prompt strings to print. Each menu has its own prompt.