Documentation ¶
Index ¶
- Variables
- type Command
- func (c *Command) Add(cmd *Command) *Command
- func (c *Command) AddArgumentCompletion(arg string, comps CompletionFunc)
- func (c *Command) AddArgumentCompletionDynamic(arg string, comps CompletionFuncDynamic)
- func (c *Command) AddCommand(name, short, long, group string, filters []string, data func() Commander) *Command
- func (c *Command) AddGlobalOptions(shortDescription, longDescription string, data func() interface{})
- func (c *Command) AddOptionCompletion(arg string, comps CompletionFunc)
- func (c *Command) AddOptionCompletionDynamic(option string, comps CompletionFuncDynamic)
- func (c *Command) CommandGroups() (grps []*commandGroup)
- func (c *Command) Commands() (cmds []*Command)
- func (c *Command) FindCommand(name string) (command *Command)
- func (c *Command) GoFlagsCommands() (cmds []*flags.Command)
- func (c *Command) OptionGroups() (grps []*optionGroup)
- type CommandCompleter
- func (c *CommandCompleter) ClientInterfaceAddrs() (comps []*readline.CompletionGroup)
- func (c *CommandCompleter) ClientInterfaceNetworks() (comps []*readline.CompletionGroup)
- func (c *CommandCompleter) EnvironmentVariables() (completions []*readline.CompletionGroup)
- func (c *CommandCompleter) LocalPath(last string) (string, []*readline.CompletionGroup)
- func (c *CommandCompleter) LocalPathAndFiles(last string) (string, []*readline.CompletionGroup)
- type Commander
- type CompletionFunc
- type CompletionFuncDynamic
- type Config
- type Console
- func (c *Console) Add(cmd *Command) *Command
- func (c *Console) AddCommand(name, short, long, group string, filters []string, data func() Commander) *Command
- func (c *Console) AddConfigCommand(name, group string)
- func (c *Console) AddConfigSubCommand(name, short, long, group string, filters []string, data func() Commander) *Command
- func (c *Console) AddGlobalOptions(shortDescription, longDescription string, data func() interface{})
- func (c *Console) AddHelpCommand(group string)
- func (c *Console) CommandParser() (parser *flags.Parser)
- func (c *Console) CurrentMenu() *Menu
- func (c *Console) FindCommand(name string) (command *Command)
- func (c *Console) GetCommandGroup(cmd *flags.Command) string
- func (c *Console) GetCommands() (groups map[string][]*flags.Command, groupNames []string)
- func (c *Console) GetConfig() (conf *Config)
- func (c *Console) GetMenu(name string) (ctx *Menu)
- func (c *Console) HideCommands(filter string)
- func (c *Console) LoadConfig(conf *Config)
- func (c *Console) NewMenu(name string) (ctx *Menu)
- func (c *Console) ParseExpansionVariables(args []string, pathSeparator rune) (processed []string, err error)
- func (c *Console) RefreshPromptCustom(log string, prompt string, offset int)
- func (c *Console) RefreshPromptInPlace(prompt string)
- func (c *Console) RefreshPromptLog(log string)
- func (c *Console) Run() (err error)
- func (c *Console) SetHistoryAltR(name string, hist readline.History)
- func (c *Console) SetHistoryCtrlR(name string, hist readline.History)
- func (c *Console) SetParserOptions(options flags.Options)
- func (c *Console) ShowCommands(filter string)
- func (c *Console) SwitchMenu(menu string)
- func (c *Console) SystemEditor(buffer []byte) (updated []byte, err error)
- type InputMode
- type Menu
- func (m *Menu) AddCommand(name, short, long, group string, filters []string, data func() Commander) *Command
- func (c *Menu) AddExpansionCompletion(expansion rune, comps CompletionFunc)
- func (m *Menu) AddGlobalOptions(shortDescription, longDescription string, data func() interface{})
- func (m *Menu) CommandGroups() (grps []*commandGroup)
- func (m *Menu) Commands() (cmds []*Command)
- func (m *Menu) OptionGroups() (grps []*optionGroup)
- func (m *Menu) PromptConfig() *PromptConfig
- func (m *Menu) SetHistoryAltR(name string, hist readline.History)
- func (m *Menu) SetHistoryCtrlR(name string, hist readline.History)
- type Prompt
- type PromptConfig
Constants ¶
This section is empty.
Variables ¶
Functions ¶
This section is empty.
Types ¶
type Command ¶
type Command struct { // Name - The name of the command, as typed in the shell. Name string // ShortDescription - A short string to be used in console completions, hints, etc. ShortDescription string // LongDescription - A longer description text to be printed in the help menus. LongDescription string // Group - Commands can be specified a group, by which they will appear in completions, etc. Group string // Filters - A list of filters against which the commands might be shown/hidden. // For example, adding the "windows" filter and calling the console.HideCommands("windows"), // will hide commands from now on, until console.ShowCommands("windows") is called. Filters []string // SubcommandsOptional - If this is false, the help usage will be printed for this command. SubcommandsOptional bool // Data - A function that must yield a pointer to a struct (which is, and will become a command instance) // Compatible interfaces must match https://github.com/jessevdk/go-flags.git requirements. Please refer // to either the go-flags documentation, or this library's one. Data func() Commander // contains filtered or unexported fields }
Command - A struct storing basic command info, functions used for command instantiation, completion generation, and any number of subcommand groups.
func NewCommand ¶
func NewCommand() *Command
NewCommand - Any user wishing to add a command to its application by passing a *Command struct directly, should use this constructor, becaus it must initialize a few private fields first.
func (*Command) Add ¶
Add - Same as AddCommand("", "", ...), but passing a populated Command struct.
func (*Command) AddArgumentCompletion ¶
func (c *Command) AddArgumentCompletion(arg string, comps CompletionFunc)
AddArgumentCompletion - Given a registered command, add one or more groups of completion items (with any display style/options) to one of the command's arguments. Does not need to return a prefix. It is VERY IMPORTANT to pass the case-sensitive name of the argument, as declared in the command struct. The type of the underlying argument does not matter, and gonsole will correctly yield suggestions based on wheteher list are required, are these arguments optional, etc.
func (*Command) AddArgumentCompletionDynamic ¶
func (c *Command) AddArgumentCompletionDynamic(arg string, comps CompletionFuncDynamic)
AddArgumentCompletionDynamic - Given a registered command, add one or more groups of completion items (with any display style/options) to one of the command's arguments. Needs to return a prefix in the compfunc. It is VERY IMPORTANT to pass the case-sensitive name of the argument, as declared in the command struct. The type of the underlying argument does not matter, and gonsole will correctly yield suggestions based on wheteher list are required, are these arguments optional, etc. The menu is needed in order to bind these completions to the good command, because several menus migh have some being identically named.
func (*Command) AddCommand ¶
func (c *Command) AddCommand(name, short, long, group string, filters []string, data func() Commander) *Command
AddCommand - Add a command to the given command (the console Contexts embed a command for this matter). If you are calling this function directly like gonsole.Console.AddCommand(), be aware that this will bind the command to the default menu named "". If you don't intend to use multiple menus this is fine, but if you do, you should create and name each of your menus, and add commands to them, like Console.NewContext("name").AddCommand("", "", ...)
func (*Command) AddGlobalOptions ¶
func (c *Command) AddGlobalOptions(shortDescription, longDescription string, data func() interface{})
AddGlobalOptions - Global options are available in all child commands of this command (or all commands of the parser). The data interface is a struct declared the same way as you'd declare a go-flags parsable option struct.
func (*Command) AddOptionCompletion ¶
func (c *Command) AddOptionCompletion(arg string, comps CompletionFunc)
AddOptionCompletion - Given a registered command and an option LONG name, add one or more groups of completion items to this option's arguments. Does not need to return a prefix. It is VERY IMPORTANT to pass the case-sensitive name of the option, as declared in the command struct. The type of the underlying argument does not matter, and gonsole will correctly yield suggestions based on wheteher list are required, are these arguments optional, etc.
func (*Command) AddOptionCompletionDynamic ¶
func (c *Command) AddOptionCompletionDynamic(option string, comps CompletionFuncDynamic)
AddOptionCompletionDynamic - Given a registered command and an option LONG name, add one or more groups of completion items to this option's arguments. It is VERY IMPORTANT to pass the case-sensitive name of the option, as declared in the command struct. The type of the underlying argument does not matter, and gonsole will correctly yield suggestions based on wheteher list are required, are these arguments optional, etc. The menu is needed in order to bind these completions to the good command, because several menus migh have some being identically named.
func (*Command) CommandGroups ¶
func (c *Command) CommandGroups() (grps []*commandGroup)
CommandGroups - Returns the command's child commands, structured in their respective groups. Commands having been assigned no specific group are the group named "".
func (*Command) Commands ¶
Commands - Returns the list of child gonsole.Commands for this command. You can set anything to them, these changes will persist for the lifetime of the application, or until you deregister this command or one of its childs.
func (*Command) FindCommand ¶
FindCommand - Find a subcommand of this command, given the command name.
func (*Command) GoFlagsCommands ¶
func (c *Command) GoFlagsCommands() (cmds []*flags.Command)
GoFlagsCommands - Returns the list of all GO-FLAGS subcommands for this command. This means that these commands in the list are temporary ones, they will be respawned at the next execution readline loop. Do NOT bind/assign anything to them, it will NOT persist.
func (*Command) OptionGroups ¶
func (c *Command) OptionGroups() (grps []*optionGroup)
OptionGroups - Returns all groups of options that are bound to this command. These groups (and their options) are available for use even in the command's child commands.
type CommandCompleter ¶
type CommandCompleter struct {
// contains filtered or unexported fields
}
CommandCompleter - A completer using a github.com/jessevdk/go-flags Command Parser, in order to build completions for commands, arguments, options and their arguments as well. This completer needs to be instantiated with its constructor, in order to ensure the parser is not nil.
func (*CommandCompleter) ClientInterfaceAddrs ¶
func (c *CommandCompleter) ClientInterfaceAddrs() (comps []*readline.CompletionGroup)
ClientInterfaceAddrs - All addresses (IPv4/v6) of the console-running host.
func (*CommandCompleter) ClientInterfaceNetworks ¶
func (c *CommandCompleter) ClientInterfaceNetworks() (comps []*readline.CompletionGroup)
ClientInterfaceNetworks - All networks (IPv4/v6, CIDR notation) to which the console-running host belongs.
func (*CommandCompleter) EnvironmentVariables ¶
func (c *CommandCompleter) EnvironmentVariables() (completions []*readline.CompletionGroup)
EnvironmentVariables - Returns all environment variables as suggestions.
func (*CommandCompleter) LocalPath ¶
func (c *CommandCompleter) LocalPath(last string) (string, []*readline.CompletionGroup)
LocalPath - Provides completion for the client console filesystem, (directories only)
func (*CommandCompleter) LocalPathAndFiles ¶
func (c *CommandCompleter) LocalPathAndFiles(last string) (string, []*readline.CompletionGroup)
LocalPathAndFiles - Provides completion for the client console filesystem, (directories and files)
type Commander ¶
type Commander = flags.Commander
Commander - A reexport of the go-flags Commander interface, which defines the only function that any command must implement to be a valid console Command. This Commander type is returned by the gonsole.Command.Data field, in order to generate a fresh command instance at each execution loop.
type CompletionFunc ¶
type CompletionFunc func() (comps []*readline.CompletionGroup)
CompletionFunc - Function yielding one or more completions groups. The user of this function does not have to worry about any prefix, he just has to yield values into a CompletionGroup, and set any option/behavior to it if wished.
type CompletionFuncDynamic ¶
type CompletionFuncDynamic func(prefix string) (pref string, comps []*readline.CompletionGroup)
CompletionFuncDynamic - A function that yields one or more completion groups. The prefix parameter should be used with a simple 'if strings.IsPrefix()' condition. Please see the project wiki for documentation on how to write more elaborated engines: For example, do NOT use or modify the `pref string` return paramater if you don't explicitely need to.
type Config ¶
type Config struct { InputMode InputMode `json:"input_mode"` Prompts map[string]*PromptConfig `json:"prompts"` Hints bool `json:"hints"` MaxTabCompleterRows int `json:"max_tab_completer_rows"` Highlighting map[string]string `json:"highlighting"` }
Config - The console configuration (prompts, hints, modes, etc)
func NewDefaultConfig ¶
func NewDefaultConfig() *Config
NewDefaultConfig - Users wishing to setup a special console configuration should use this function in order to ensure there are no nil maps anywhere, and with defaults.
type Console ¶
type Console struct { // Completer - The completion engine is available to the user for registering // default completion generators. A list of them is available to be bound // to either or both command/option argument completions. Console menus // are not relevant here, the user should not worry. Completer *CommandCompleter // PreLoopHooks - 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). PreLoopHooks []func() // PreRunHooks - Once the user has entered a command, but before executing it // with the application go-flags parser, the console will execute every func // in this list. PreRunHooks []func() // PreRunLineHooks - Same as PreRunHooks, 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. PreRunLineHooks []func(raw []string) (args []string, err error) // If true, leavs a newline between command line input and their output. LeaveNewline bool PreOutputNewline bool // contains filtered or unexported fields }
Console - An integrated console instance.
func NewConsole ¶
func NewConsole() (c *Console)
NewConsole - 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.
func (*Console) Add ¶
Add - Same as AddCommand("", "", ...), but passing a populated Command struct.
func (*Console) AddCommand ¶
func (c *Console) AddCommand(name, short, long, group string, filters []string, data func() Commander) *Command
AddCommand - Add a command to the default console menu, named "". Please check gonsole.CurrentContext().AddCommand(), if you intend to use multiple menus, for more detailed explanations
func (*Console) AddConfigCommand ¶
AddConfigCommand - The console will add a command used to manage all elements of the console for any menu, and to save such elements into configurations, ready for export. You can choose both the command name and the group, for avoiding command collision with your owns.
func (*Console) AddConfigSubCommand ¶
func (c *Console) AddConfigSubCommand(name, short, long, group string, filters []string, data func() Commander) *Command
AddConfigSubCommand - Allows the user to bind specialized subcommands to the config root command. This is useful if, for example, you want to save the console configuration on a remote server.
func (*Console) AddGlobalOptions ¶
func (c *Console) AddGlobalOptions(shortDescription, longDescription string, data func() interface{})
AddGlobalOptions - Add global options for this menu command parser. Will appear in all commands.
func (*Console) AddHelpCommand ¶
AddHelpCommand - The console will automatically add a command named "help", which accepts any (optional) command and/or any of its subcommands, and prints the corresponding help. If no argument is passed, prints the list of available of commands for the current menu. The name of the group is left to the user's discretion, for putting the command in a given group/topic. Command names and their subcommands will be automatically completed.
func (*Console) CommandParser ¶
func (c *Console) CommandParser() (parser *flags.Parser)
CommandParser - Returns the root command parser of the console. You can use it to find and query about the CURRENT Context commands, options, etc. The only limitation is simple: anything you change to these commands, options will NOT persist across execution loops, because commands are reinstantiated each time. Please the documentation wiki of this project, to see how to use this: can be very handy and powerful, even when programming your commands.
func (*Console) CurrentMenu ¶
CurrentMenu - Return the current console menu. Because the Context is just a reference, any modifications to this menu will persist.
func (*Console) FindCommand ¶
FindCommand - Find a command among the root ones in the application, for the current menu.
func (*Console) GetCommandGroup ¶
GetCommandGroup - Get the group for a command.
func (*Console) GetCommands ¶
GetCommands - Callers of this are for example the TabCompleter, which needs to call this regularly in order to have a list of commands belonging to the current menu.
func (*Console) GetMenu ¶
GetMenu - Given a name, return the appropriate menu. If the menu does not exists, it returns nil
func (*Console) HideCommands ¶
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 subsquently hidden, until ShowCommands("windows") is called.
func (*Console) LoadConfig ¶
LoadConfig - Loads a config struct, but does not immediately refresh the prompt. Settings will apply as they are needed by the console.
func (*Console) NewMenu ¶
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) ParseExpansionVariables ¶
func (c *Console) ParseExpansionVariables(args []string, pathSeparator rune) (processed []string, err error)
ParseExpansionVariables - This function can be used if you need to have access to a path in which your expansion variables have been evaluated. The splitter parameter is used to specify with path separators to use. If "", will be POSIX "/".
func (*Console) RefreshPromptCustom ¶
RefreshPromptCustom - Refresh the console prompt with custom values. This works differently from RefreshPromptLog, in that it does mandatorily erases the current (full) prompt if offset to one. However, like RefreshPromptLog, it will not reprint the prompt if the console is currently executing a command.
@log => An optional log message to print before refreshing the prompt. Does nothing if nil @prompt => If not nil (""), will use this prompt instead of the currently set prompt. @offset => Used to set the number of lines to go upward, before reprinting. Set to 0 if not used.
func (*Console) RefreshPromptInPlace ¶
RefreshPromptInPlace - Refreshes the prompt in the very same place he is, with a string that will list only until the next execution loop. This might be used in conjunction with c.Menu["myMenu"].Prompt.Render(). Like other Refresh functions, it will not reprint the prompt if the console is currently executing a command.
func (*Console) RefreshPromptLog ¶
RefreshPromptLog - A simple function to print a string message (a log, or more broadly, an asynchronous event) without bothering the user, and by "pushing" the prompt below the message. 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 (*Console) Run ¶
Run - 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) SetHistoryAltR ¶
SetHistoryAltR - Set the history source triggered with Alt-r
func (*Console) SetHistoryCtrlR ¶
SetHistoryCtrlR - Set the history source triggered with Ctrl-R
func (*Console) SetParserOptions ¶
func (c *Console) SetParserOptions(options flags.Options)
SetParserOptions - Set the general options that apply to the root command parser. Default options are: -h, --h options are available to all registered commands. Ignored option dashes are ignored and passed along the command tree. This function might be used by people who forked this library, and do not care about --help options triggering helps, but instead want lower level access to how arguments are parsed or on when/why/how errors should be raised.
func (*Console) ShowCommands ¶
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) SwitchMenu ¶
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 ¶
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.
type InputMode ¶
type InputMode string
InputMode - The input & navigation mode of the console. (Vim or Emacs)
type Menu ¶
type Menu struct { Name string // The name of the context, used for many things here and there. Prompt *Prompt // A dedicated prompt with its own callbacks and colors // UnknownCommandHandler - The user can specify a function that will // be executed if the error raised by the application parser is a // ErrUnknownCommand error. This might be used for executing the // input line directly via a system shell, or any os.Exec mean... UnknownCommandHandler func(args []string) error // 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) AddCommand ¶
func (m *Menu) AddCommand(name, short, long, group string, filters []string, data func() Commander) *Command
AddCommand - Add a command to this menu. This command will be available when this menu is active.
func (*Menu) AddExpansionCompletion ¶
func (c *Menu) AddExpansionCompletion(expansion rune, comps CompletionFunc)
AddExpansionCompletion - Add a completion generator that is triggered when the expansion string paramater is detected (anywhere, even in other completions) in the input line. Ex: you can pass '$' as an expansion, and a function that will yield environment variables.
func (*Menu) AddGlobalOptions ¶
AddGlobalOptions - Add global options for this menu command parser. Will appear in all commands.
func (*Menu) CommandGroups ¶
func (m *Menu) CommandGroups() (grps []*commandGroup)
CommandGroups - Returns the command's child commands, structured in their respective groups. Commands having been assigned no specific group are the group named "".
func (*Menu) Commands ¶
Commands - Returns the list of child gonsole.Commands for this command. You can set anything to them, these changes will persist for the lifetime of the application, or until you deregister this command or one of its childs.
func (*Menu) OptionGroups ¶
func (m *Menu) OptionGroups() (grps []*optionGroup)
OptionGroups - Returns all groups of options that are bound to this command. These groups (and their options) are available for use even in the command's child commands.
func (*Menu) PromptConfig ¶
func (m *Menu) PromptConfig() *PromptConfig
PromptConfig - Returns the prompt object used to setup the prompt. It is actually a configuration, because it can also be printed and exported by a config command.
func (*Menu) SetHistoryAltR ¶
SetHistoryAltR - Set the history source triggered with Alt-r
type Prompt ¶
type Prompt struct { // Callbacks - A list of value callbacks to be used, preferably of the following form: // "{key}": func() "value". (notice the brackets). Each of callbacks found // in the prompt strings will be replaced by the function they're mapped to. Callbacks map[string]func() string // Colors - A more optional feature, because this console library automatically // populates it with a few callback colors, coming from evilsocket's libs. // Please also use brackets (though not mandatory): "{key}": "value". Colors map[string]string // contains filtered or unexported fields }
Prompt - Computes all prompts used on the shell for a given menu. You can register two sorts of callbacks to it, so you can give customized prompt elements to be used by the end user.
type PromptConfig ¶
type PromptConfig struct { Left string `json:"left"` Right string `json:"right"` NewlineAfter bool `json:"newline_after"` NewlineBefore bool `json:"newline_before"` Multiline bool `json:"multiline"` MultilinePrompt string `json:"multiline_prompt"` }
PromptConfig - Contains all the information needed for the PromptConfig of a given menu.
Source Files ¶
- command-arguments.go
- command.go
- complete-config.go
- complete-env.go
- complete-net.go
- complete-path.go
- completion.go
- config.go
- default-command-config.go
- default-command-help.go
- execute.go
- expansion.go
- gonsole.go
- group.go
- help.go
- hint-completer.go
- menu.go
- option-arguments.go
- parser.go
- patterns.go
- prompt.go
- run.go
- syntax-highlighter.go
- tab-completer.go