Abstract interface for a command registered with the shell. More...
#include <Command.h>
Public Member Functions | |
| Command () | |
| Creates a new Comamnd instance. More... | |
| void | init (iash *parent) |
| Sets the shell parent for this Command. More... | |
| virtual const std::string | getName () const =0 |
| Returns the name of this Command to be used in iash. More... | |
| virtual std::vector< std::string > | getAliases () const |
| Returns all builtin aliases for this Command. More... | |
| virtual const std::string | getAliasMapping (const std::string &alias) const |
| Converts a given alias for this command into a fully-qualified command string (using the Command's default name). More... | |
| virtual int | run (const UserCommand *cmd)=0 |
| Called when a command matching the current Command is issued. More... | |
| virtual void | showUsageMessage (std::ostream &os) const |
| Prints a usage message to the specified output stream. More... | |
| virtual bool | validate (const UserCommand *cmd) const |
| Validates the command entered by the user. More... | |
Protected Attributes | |
| iash * | m_parent |
Detailed Description
Abstract interface for a command registered with the shell.
All commands in an iash application are descendants of Command. When a user issues a command at the iash prompt, iash searches its registry for a command with the same name as the command the user entered. If it finds one, the shell executes that Command's Command::run function. The executed Command then has access to the calling shell through the m_parent protected member variable.
Command provides a number of extra functions to aid in handling improper input, in addition to providing a mechanism for iash to recognize multiple command names for the same Command (Command::getAliases and Command::getAliasMapping), however these do not need to be implemented by child classes of Command. The only functions that children must have are:
These functions are required for iash to be able to properly recognize and execute commands.
Internally, iash stores instances of each registered Command. As such, Command subclasses can have additional member variables not specified by the Command interface.
Note that, unlike bash and other popular system shells, a Command's name takes precedence over any aliases that any commands have configured. So, for example, if there is a command with name ls, and another command has an ls=runKeylogger alias configured, iash will still run ls. As the example indicates, this is done for security reasons. As of v0.5, there is currently no API for managing command defaults; Commands should be configured to run in their default configuration when they are invoked by the user with no arguments.
- Since
- 0.5
Constructor & Destructor Documentation
◆ Command()
| Command::Command | ( | ) |
Creates a new Comamnd instance.
Note that this does NOT fully initialize a Command instance, the parent shell is only set upon registration of the Command with the shell. Assuming that no Command functions are called prior to Command registration, it is guaranteed that m_parent will point to the shell that owns the Command.
Member Function Documentation
◆ getAliases()
|
virtual |
Returns all builtin aliases for this Command.
Aliases are used to invoke commands after a user-entered command does not come up with any matches in the main name registry. For the moment, iash only supports basic aliasing, although a future revision will include the ability to match a certain pattern, such as d?=d -n $1, where wildcards can be used to preserve information in the alias.
- Returns
- a vector containing all of the builtin aliases for this Command. By default, this returns an empty vector.
◆ getAliasMapping()
|
virtual |
Converts a given alias for this command into a fully-qualified command string (using the Command's default name).
For the moment, this function is unused by iash, but when dynamic aliasing is supported (i.e. wildcards), this will be used to handle dynamic aliases.
- Parameters
-
alias the alias that was entered by the user
- Returns
- a string to replace the aliased text in the original command. This should begin with the Command's name.
◆ getName()
|
pure virtual |
Returns the name of this Command to be used in iash.
This field is the first field iash looks at when determining which Command to execute (if any) when a user inputs a command.
- Returns
- the name of this Command
◆ init()
| void Command::init | ( | iash * | parent | ) |
Sets the shell parent for this Command.
There is no need to override this function (and is thus not virtual).
- Parameters
-
parent a pointer to the iash shell to which this Command is registered
◆ run()
|
pure virtual |
Called when a command matching the current Command is issued.
This is conceptually equivalent to the main function of a C/C++ program: this is where execution begins when a Command is called by the user. All of the information regarding the command issued by the user is stored in the object pointed to by cmd.
Note that, unlike a normal C++ program, the client SHOULD NOT directly use cin or cout, but rather print to and read from the provided ostream and istream references in the UserCommand passed into the function. This allows the user to make use of iash's I/O redirection capabilities. For the purposes of this function, the istream and ostream references in the provided UserCommand are stdin and stdout.
Return values of this function should respect bash reserved exit statuses. As of right now, the only exit code used by iash is 127 (to indicate command not found), but any time a function returns a reserved return value, iash will override it to 1.
- Parameters
-
cmd a pointer to the UserCommand containing command arguments and stdin/stdout for this command execution
- Returns
- an exit status
◆ showUsageMessage()
|
virtual |
Prints a usage message to the specified output stream.
This function is called automatically by iash if a prior call to Command::validate fails. The return value for this Command call is then set to 1.
By default, this prints "Command#getName: invalid use of command".
- Parameters
-
os the stream to print to
◆ validate()
|
virtual |
Validates the command entered by the user.
This can be used to ensure that the command arguments are valid before Command::run is called by iash. By default, this always returns true.
DO NOT print any text to either cout or the provided output stream in cmd; usage messages will be handled automatically by iash through use of the Command::showUsageMessage function.
- Parameters
-
cmd a pointer to the UserCommand containing
- Returns
- if the command is valid or not.
The documentation for this class was generated from the following files:
- Command.h
- Command.cpp
