General information

The shell's offers a very simple API which allows writing its plugins in any programming language. The communication between the shell and the plugin are made by standard input and output, where the API calls are sending as command line arguments. All arguments for the calls should be enclosed in quotes if they contain spaces. The plugin's system will probably change over time especially by adding new API calls. The plugins can reside in any location. The directory tools contains the example plugin testplugin.sh written in Bash.

API versions

The current version of API: 0.2

The minimum required version of API for plugins to work: 0.2

API calls from the shell

At this moment, available API calls from the shell:

• install: called during installation of the plugin (adding it to the shell).
• uninstall: called during removing of the plugin from the shell.
• enable: called during enabling the plugin.
• disable: called during disabling the plugin.
• init: called during initialization (starting) of the shell.
• info: called during showing information about the plugin. Requested response from the plugin should have form: answer [name of the plugin;description of the plugin;API version of the plugin;list of API used (separated by comma)]. IMPORTANT: This call is required for all plugins to work. If a plugin doesn't have it, it won't be added or enabled in the shell.
• preCommand [command]: called before the user's command will be executed. Command argument is the name of command and all its arguments entered by the user.
• postCommand [command]: called after the user's command execution. Command argument is the name of command and all its arguments entered by the user.
• [command] [arguments]: called when the plugin added the own or replaced one of the built-in commands. Command is the name of the command which will be executed, arguments are a string with arguments entered by the user.

ATTENTION: the calls set as the preCommand and postCommand will be executed every time before and after you execute your command. Thus, be sure it isn't too heavy for your system, or it isn't dangerous, for example, it doesn't steal credentials, harm your system, etc.

Unsupported by plugin API call

If the plugin doesn't answer on any API call from the shell, it should return error code 2, so the shell will known that the API's call isn't supported by the plugin.

API call from plugins

Available API calls from plugins:

• showError [text]: show the text in the standard error output
• showOutput [text] ?color?: show the text in the standard output. The optional argument is the color of the message. Available options are: fgBlack, fgRed, fgGreen, fgYellow, fgBlue, fgMagenta, fgCyan, fgWhite and fgDefault
• setOption [option name] [option value] [option description] [option type]: set the shell's option. If the option doesn't exist, create a new with selected parameters. Option type should be one of: integer (positive and negative), float, boolean (true or false), historySort, natural (0 or above), text, command (the value will be checked if is a valid command before added)
• removeOption [option name]: remove the selected option from the shell.
• getOption [option name]: get the value of the selected shell's option.
• answer [text]: set the answer for the shell. At this moment, used only in info call from the shell.
• addCommand [command name] ?subcommand? ?subcommand? ...: add the new command to the shell. The name must be unique. The command will not be added if there is registered the shell's command with that name. If you want to replace an existing command, use call replaceCommand (see below). Commands named exit, set, unset and cd can't be added. Optional arguments subcommand are names of the command's subcommands used in the commands' completion system.
• deleteCommand [command name]: remove the selected command from the shell. The name must be a name of an existing shell's command.
• replaceCommand [command name]: replace the selected command with code from the plugin. The name must be a name of an existing shell's command.
• addHelp [topic] [usage] [help content]: add the new help entry to the shell. The topic must be unique. The help entry will not be added if there is one with that topic. If you want to replace an existing help entry, use call updateHelp (see below).
• deleteHelp [topic]: delete the help entry with the selected topic. The topic must be the topic of an existing help entry.
• updateHelp [topic] [usage] [help content]: update the existing help entry with the new values. The topic must be a topic of an existing help entry.