Command-line shell access. More...

#include <Shell.h>

Inheritance diagram for Shell:

Public Member Functions
	Shell ()
	Constructs a new Shell instance. More...

virtual	~Shell ()
	Destroys this Shell object.

bool	begin (Stream &stream, size_t maxHistory=0, Terminal::Mode mode=Serial)
	Begin shell handling on an underlying character stream. More...

bool	begin (Client &client, size_t maxHistory=0, Terminal::Mode mode=Telnet)
	Begin shell handling on a connected TCP client. More...

void	end ()
	Ends shell processing on the underlying stream. More...

void	loop ()
	Performs regular activities on the shell. More...

const char *	prompt () const
	Gets the prompt string to display in the shell. More...

void	setPrompt (const char *prompt)
	Sets the prompt string to display in the shell. More...

int	userid () const
	Gets the user identifier for the currently logged in user, or -1 if there is no user logged in currently. More...

void	setUserid (int userid)
	Sets the user identifier for the currently logged in user. More...

void	help ()
	Displays help for all supported commands.

void	exit ()
	Exit from the shell back to the login prompt. More...

Public Member Functions inherited from Terminal
	Terminal ()
	Constructs a terminal object. More...

virtual	~Terminal ()
	Destroys this terminal object.

void	begin (Stream &stream, Mode mode=Serial)
	Begins terminal operations on an underlying stream. More...

void	end ()
	Ends terminal operations on an underlying stream. More...

Stream *	stream () const
	Returns a pointer to the underlying Stream, or NULL if the stream has not been set with begin() yet. More...

Terminal::Mode	mode () const
	Returns the mode this terminal is operating in, Serial or Telnet. More...

virtual int	available ()
	Returns the number of bytes that are available for reading. More...

virtual int	peek ()
	Peeks at the next byte from the underlying stream. More...

virtual int	read ()
	Reads the next byte from the underlying stream. More...

virtual void	flush ()
	Flushes all data in the underlying stream.

virtual size_t	write (uint8_t c)
	Writes a single byte to the underlying stream. More...

virtual size_t	write (const uint8_t *buffer, size_t size)
	Writes a buffer of data to the underlying stream. More...

void	writeProgMem (const char *str)
	Writes a static string that is stored in program memory. More...

int	readKey ()
	Reads the next key that was typed on this terminal. More...

long	unicodeKey () const
	Gets the Unicode version of the last key returned by readKey(). More...

size_t	writeUnicode (long code)
	Writes a Unicode code point to the output in UTF-8 encoding. More...

int	columns () const
	Gets the number of columns in the window; defaults to 80. More...

int	rows () const
	Gets the number of rows in the window; defaults to 24. More...

bool	setWindowSize (int columns, int rows)
	Sets the number of columns and rows in the window. More...

void	clear ()
	Move the cursor to the top-left position and clear the screen.

void	clearToEOL ()
	Clears from the current cursor position to the end of the line.

void	cursorMove (int x, int y)
	Moves the cursor to a specific location in the window. More...

void	cursorLeft ()
	Moves the cursor left by one character. More...

void	cursorRight ()
	Moves the cursor right by one character. More...

void	cursorUp ()
	Moves the cursor up by one line. More...

void	cursorDown ()
	Moves the cursor down by one line. More...

void	backspace ()
	Backspaces over the last character. More...

void	insertLine ()
	Inserts a line at the cursor position. More...

void	insertChar ()
	Inserts a blank character at the cursor position. More...

void	deleteLine ()
	Deletes a line at the cursor position. More...

void	deleteChar ()
	Deletes the character at the cursor position. More...

void	scrollUp ()
	Scrolls the contents of the window up one line. More...

void	scrollDown ()
	Scrolls the contents of the window down one line. More...

void	normal ()
	Selects normal text with all attributes and colors off. More...

void	bold ()
	Enables bold text. More...

void	underline ()
	Enables underlined text.

void	blink ()
	Enables blinking text.

void	reverse ()
	Reverse the foreground and background colors for inverted text.

void	color (Color fg)
	Selects a text foreground color with the default background color. More...

void	color (Color fg, Color bg)
	Selects text foreground and background colors. More...

Static Public Member Functions
static void	registerCommand (ShellCommandRegister *cmd)
	Registers a command with the shell. More...

Static Public Member Functions inherited from Terminal
static bool	isWideCharacter (long code)
	Determine if a Unicode character is wide. More...

static size_t	utf8Length (long code)
	Determines the length of a Unicode code point in the UTF-8 encoding. More...

static size_t	utf8Format (uint8_t *buffer, long code)
	Formats a Unicode code point in a buffer in the UTF-8 encoding. More...

Protected Member Functions
virtual void	beginSession ()
	Begins a login session.

virtual void	printPrompt ()
	Prints the current prompt string.

virtual void	execute ()
	Executes the command in the buffer.

Friends
class	LoginShell

Related Functions
(Note that these are not member functions.)
	ShellCommandFunc
	Type of functions that provide shell command handlers. More...

#define	ShellCommand(name, help, function)
	Registers a command with the shell. More...

Additional Inherited Members
Public Types inherited from Terminal
enum	Mode { Serial, Telnet }
	Mode to operate in, Serial or Telnet. More...

enum	Color { Black = 0x00, DarkRed = 0x01, DarkGreen = 0x02, DarkYellow = 0x03, DarkBlue = 0x04, DarkMagenta = 0x05, DarkCyan = 0x06, LightGray = 0x07, DarkGray = 0x08, Red = 0x09, Green = 0x0A, Yellow = 0x0B, Blue = 0x0C, Magenta = 0x0D, Cyan = 0x0E, White = 0x0F }
	Terminal foreground or background colors. More...

Detailed Description

Command-line shell access.

This class provides a command-line shell via serial ports, TCP connections, or any other type of Stream.

The following example is the minimal setup for a command-line shell on a serial port. The application calls begin() to set the underlying Stream, and periodically calls loop() to manage shell-related events.

Shell shell;
void setup() {
    Serial.begin(9600);
    shell.setPrompt("$ ");
    shell.begin(Serial);
}
void loop() {
    shell.loop();
}

Commands can be registered with the shell by the application to be invoked when the user types in the corresponding command. Each command is associated with a handler function:

void cmdMotor(Shell &shell, int argc, const ShellArguments &argv)
{
    ...
}
ShellCommand(motor, "Turn the motor on or off", cmdMotor);

There are two standard commands built into Shell: "help" and "exit". The "help" command provides a list of all registered commands with the short help string from the ShellCommand() registration. The "exit" command logs the user out and returns to the login prompt, or stops the underlying connection in the case of TCP streams.

The F1 key can be used as a synonym for "help" and CTRL-D can be used as a synonym for "exit".

Shell provides some limited history editing for scrolling back through previous commands. The size of the history stack is provided in the second argument to begin():

shell.begin(Serial, 5);

See Also: LoginShell, Terminal

Definition at line 62 of file Shell.h.

Constructor & Destructor Documentation

Shell::Shell ( )

Constructs a new Shell instance.

This constructor must be followed by a call to begin() to specify the underlying I/O stream.

Definition at line 122 of file Shell.cpp.

Member Function Documentation

bool Shell::begin	(	Stream &	stream,
		size_t	maxHistory = `0`,
		Terminal::Mode	mode = `Serial`
	)

Begin shell handling on an underlying character stream.

Parameters

stream	The stream to apply the shell to. Usually this is a serial port or TCP network connection.
maxHistory	The number of commands to allocate in the history stack for scrolling back through using Up/Down arrow keys.
mode	The terminal mode to operate in, Terminal::Serial or Terminal::Telnet. Default is Terminal::Serial.

Returns: Returns false if there is insufficient memory for the history stack. The session will continue but without command history.

This function will print the prompt() in preparation for entry of the first command. The default prompt is "$ "; call setPrompt() before begin() to change this:

Serial.begin(9600);
shell.setPrompt("Command: ");
shell.begin(Serial);

The maxHistory parameter indicates the number of commands of maximum length that can be stored in the history. If the actual entered commands are shorter, then more commands can be stored in the history.

See Also: end(), setPrompt()

Definition at line 176 of file Shell.cpp.

bool Shell::begin	(	Client &	client,
		size_t	maxHistory = `0`,
		Terminal::Mode	mode = `Telnet`
	)

Begin shell handling on a connected TCP client.

Parameters

client	The client to apply the shell to. This must be a connected TCP client.
maxHistory	The number of commands to allocate in the history stack for scrolling back through using Up/Down arrow keys.
mode	The terminal mode to operate in, Terminal::Serial or Terminal::Telnet. Default is Terminal::Telnet.

Returns: Returns true if the shell was initialized, or false if there is insufficient memory for the history stack.

This override is provided as a convenience for starting a shell on a TCP connection. This function also modifies the behaviour of the builtin "exit" command to forcibly stop the TCP connection rather than returning to the login prompt.

The maxHistory parameter indicates the number of commands of maximum length that can be stored in the history. If the actual entered commands are shorter, then more commands can be stored in the history.

See Also: end(), setPrompt()

Definition at line 208 of file Shell.cpp.

void Shell::end ( )

Ends shell processing on the underlying stream.

This function is intended to be called when a TCP network connection is closed to clean up the shell state that was in use by the connection.

See Also: begin()

Definition at line 262 of file Shell.cpp.

void Shell::exit ( )

Exit from the shell back to the login prompt.

If the underlying stream is a TCP client, then this function will stop the client, causing disconnection.

Definition at line 577 of file Shell.cpp.

void Shell::loop ( )

Performs regular activities on the shell.

This function must be called regularly from the application's main loop to process input for the shell.

Definition at line 294 of file Shell.cpp.

const char * Shell::prompt ( ) const

inline

Gets the prompt string to display in the shell.

Returns: The current prompt. The default is "$ ".

See Also: setPrompt()

Definition at line 76 of file Shell.h.

void Shell::registerCommand ( ShellCommandRegister * cmd )

static

Registers a command with the shell.

Note: This function is internal. The ShellCommand() macro should be used instead.

Definition at line 472 of file Shell.cpp.

void Shell::setPrompt ( const char * prompt )

inline

Sets the prompt string to display in the shell.

Parameters

prompt The new prompt string. The caller is responsible to ensure that the string persists after this call returns. The Shell class does not make a copy of the string.

Calling this function will change the prompt for the next line of input.

See Also: prompt()

Definition at line 77 of file Shell.h.

void Shell::setUserid ( int userid )

inline

Sets the user identifier for the currently logged in user.

Parameters

userid The new user identifier to set, or -1 if there is no user logged in currently.

Normally the user identifier is set when LoginShell detects a successful login. This function can be used to alter the access rights of the logged-in user after login.

See Also: userid(), ShellPasswordCheckFunc

Definition at line 80 of file Shell.h.

int Shell::userid ( ) const

inline

Gets the user identifier for the currently logged in user, or -1 if there is no user logged in currently.

The user identifier can be used by applications to restrict the set of commands that are available to the user, or to restrict the behaviour of those commands when acting on critical resources.

See Also: setUserid(), ShellPasswordCheckFunc

Definition at line 79 of file Shell.h.

Friends And Related Function Documentation

#define ShellCommand	(	name,
		help,
		function
	)

static char const shell_id_##name[] PROGMEM = #name; \
    static char const shell_help_##name[] PROGMEM = help; \
    static ShellCommandInfo const shell_info_##name PROGMEM = { \
        shell_id_##name, \
        shell_help_##name, \
        (function) \
    }; \
    static ShellCommandRegister shell_cmd_##name(&shell_info_##name)

Registers a command with the shell.

Parameters

name	The name of the command.
help	Help string to display that describes the command.
function	The function to call to handle the command.

The name and help parameters must be constant strings that can be placed into program memory.

void cmdMotor(Shell &shell, int argc, const ShellArguments &argv)
{
    ...
}
ShellCommand(motor, "Turn the motor on or off", cmdMotor);

If there are multiple Shell instances active in the system, then the command will be registered with all of them.

Definition at line 153 of file Shell.h.

ShellCommandFunc

Parameters

shell	Points to the shell instance that executed the command, which can be used to print command results or read more input.
argc	Number of arguments to the command, including the command's name.
argv	The arguments to the command.

See Also: ShellCommand()

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Related Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation