Base class for a command shell. More...

#include <uuid/console.h>

Inheritance diagram for uuid::console::Shell:

[legend]

Collaboration diagram for uuid::console::Shell:

[legend]

Classes
class	BlockingData
	Data for the Mode::BLOCKING shell mode. More...

class	DelayData
	Data for the Mode::DELAY shell mode. More...

class	ModeData
	Base class of data for a shell mode. More...

class	PasswordData
	Data for the Mode::PASSWORD shell mode. More...

class	QueuedLogMessage
	Log message that has been queued. More...

Public Types
using	password_function = std::function< void(Shell &shell, bool completed, const std::string &password)>
	Function to handle the response to a password entry prompt. More...

using	delay_function = std::function< void(Shell &shell)>
	Function to handle the end of an execution delay. More...

using	blocking_function = std::function< bool(Shell &shell, bool stop)>
	Function to handle a blocking operation. More...

Public Member Functions
	Shell (Stream &stream, std::shared_ptr< Commands > commands, unsigned int context=0, unsigned int flags=0)
	Create a new Shell operating on a Stream with the given commands, default context and initial flags. More...

void	start ()
	Perform startup process for this shell. More...

void	loop_one ()
	Perform one execution step of this shell. More...

bool	running () const
	Determine if this shell is still running. More...

void	stop ()
	Stop this shell from running. More...

virtual void	operator<< (std::shared_ptr< uuid::log::Message > message)
	Add a new log message. More...

uuid::log::Level	log_level () const
	Get the current log level. More...

void	log_level (uuid::log::Level level)
	Set the current log level. More...

size_t	maximum_command_line_length () const
	Get the maximum length of a command line. More...

void	maximum_command_line_length (size_t length)
	Set the maximum length of a command line. More...

size_t	maximum_log_messages () const
	Get the maximum number of queued log messages. More...

void	maximum_log_messages (size_t count)
	Set the maximum number of queued log messages. More...

unsigned long	idle_timeout () const
	Get the idle timeout. More...

void	idle_timeout (unsigned long timeout)
	Set the idle timeout. More...

unsigned int	context () const
	Get the context at the top of the stack. More...

void	enter_context (unsigned int context)
	Push a new context onto the stack. More...

virtual bool	exit_context ()
	Pop a context off the stack. More...

void	add_flags (unsigned int flags)
	Add one or more flags to the current flags. More...

bool	has_flags (unsigned int flags, unsigned int not_flags=0) const
	Check if the current flags include all of the specified flags and none of the specified not_flags. More...

bool	has_all_flags (unsigned int flags) const
	Check if the current flags include all of the specified flags. More...

bool	has_any_flags (unsigned int flags) const
	Check if the current flags include any of the specified flags. More...

void	remove_flags (unsigned int flags)
	Remove one or more flags from the current flags. More...

void	enter_password (const __FlashStringHelper *prompt, password_function function)
	Prompt for a password to be entered on this shell. More...

void	delay_for (unsigned long ms, delay_function function)
	Stop executing anything on this shell for a period of time. More...

void	delay_until (uint64_t ms, delay_function function)
	Stop executing anything on this shell until a future time is reached. More...

void	block_with (blocking_function function)
	Execute a blocking function on this shell until it returns true. More...

int	available () final override
	Check for available input. More...

int	read () final override
	Read one byte from the available input. More...

int	peek () final override
	Read one byte from the available input without advancing to the next one. More...

size_t	write (uint8_t data) final override
	Write one byte to the output stream. More...

size_t	write (const uint8_t *buffer, size_t size) final override
	Write an array of bytes to the output stream. More...

void	flush () final override
	Does nothing. More...

size_t	print (const std::string &data)
	Output a string. More...

size_t	println (const std::string &data)
	Output a string followed by CRLF end of line characters. More...

size_t	printf (const char *format,...)
	Output a message. More...

size_t	printf (const __FlashStringHelper *format,...)
	Output a message. More...

size_t	printfln (const char *format,...)
	Output a message followed by CRLF end of line characters. More...

size_t	printfln (const __FlashStringHelper *format,...)
	Output a message followed by CRLF end of line characters. More...

Commands::AvailableCommands	available_commands () const
	Get the available commands in the current context and with the current flags. More...

void	print_all_available_commands ()
	Output a list of all available commands with their arguments. More...

Static Public Member Functions
static void	loop_all ()
	Loop through all registered shell objects. More...

static const uuid::log::Logger &	logger ()
	Get the built-in uuid::log::Logger instance for shells. More...

Static Public Attributes
static constexpr size_t	MAX_COMMAND_LINE_LENGTH = 80

static constexpr size_t	MAX_LOG_MESSAGES = 20

Protected Member Functions
virtual void	erase_current_line ()
	Output ANSI escape sequence to erase the current line. More...

virtual void	erase_characters (size_t count)
	Output ANSI escape sequence to erase characters. More...

virtual void	started ()
	Startup complete event. More...

virtual void	display_banner ()
	Output the startup banner. More...

virtual std::string	hostname_text ()
	Get the hostname to be included in the command prompt. More...

virtual std::string	context_text ()
	Get the text indicating the current context, to be included in the command prompt. More...

virtual std::string	prompt_prefix ()
	Get the prefix to be used at the beginning of the command prompt. More...

virtual std::string	prompt_suffix ()
	Get the prefix to be used at the end of the command prompt. More...

virtual void	end_of_transmission ()
	The end of transmission character has been received. More...

virtual void	stopped ()
	Stop request event. More...

void	invoke_command (const std::string &line)
	Invoke a command on the shell. More...

Private Types
enum	Mode : uint8_t { Mode::NORMAL, Mode::PASSWORD, Mode::DELAY, Mode::BLOCKING }
	Current mode of the shell. More...

Private Member Functions
	Shell (const Shell &)=delete

Shell &	operator= (const Shell &)=delete

void	loop_normal ()
	Perform one execution step in Mode::NORMAL mode. More...

void	loop_password ()
	Perform one execution step in Mode::PASSWORD mode. More...

void	loop_delay ()
	Perform one execution step in Mode::DELAY mode. More...

void	loop_blocking ()
	Perform one execution step in Mode::BLOCKING mode. More...

void	display_prompt ()
	Output a prompt on the shell. More...

void	output_logs ()
	Output queued log messages for this shell. More...

void	process_command ()
	Try to execute a command with the current command line. More...

void	process_completion ()
	Try to complete a command from the current command line. More...

void	process_password (bool completed)
	Finish password entry. More...

void	check_idle_timeout ()
	Check idle timeout expiry. More...

void	delete_buffer_word (bool display)
	Delete a word from the command line buffer. More...

size_t	vprintf (const char *format, va_list ap)
	Output a message. More...

size_t	vprintf (const __FlashStringHelper *format, va_list ap)
	Output a message. More...

Static Private Member Functions
static std::set< std::shared_ptr< Shell > > &	registered_shells ()
	Get registered running shells to be executed. More...

Private Attributes
Stream &	stream_

std::shared_ptr< Commands >	commands_

std::deque< unsigned int >	context_

unsigned int	flags_ = 0

std::mutex	mutex_

unsigned long	log_message_id_ = 0

std::list< QueuedLogMessage >	log_messages_

size_t	maximum_log_messages_ = MAX_LOG_MESSAGES

std::string	line_buffer_

size_t	maximum_command_line_length_ = MAX_COMMAND_LINE_LENGTH

unsigned char	previous_ = 0

Mode	mode_ = Mode::NORMAL

std::unique_ptr< ModeData >	mode_data_ = nullptr

bool	stopped_ = false

bool	prompt_displayed_ = false

uint64_t	idle_time_ = 0

uint64_t	idle_timeout_ = 0

Detailed Description

Base class for a command shell.

Must be constructed within a std::shared_ptr.

Since: 0.1.0

Definition at line 772 of file console.h.

Member Typedef Documentation

◆ blocking_function

using uuid::console::Shell::blocking_function = std::function<bool(Shell &shell, bool stop)>

Function to handle a blocking operation.

Parameters

[in]	shell	Shell instance where execution is blocked.
[in]	stop	Request to return so that the shell can stop (true) or continue (false).

Returns: True if the blocking operation is finished, otherwise false.

Since: 0.2.0

Definition at line 806 of file console.h.

◆ delay_function

using uuid::console::Shell::delay_function = std::function<void(Shell &shell)>

Function to handle the end of an execution delay.

Parameters

[in] shell Shell instance where execution was delayed.

Since: 0.1.0

Definition at line 795 of file console.h.

◆ password_function

using uuid::console::Shell::password_function = std::function<void(Shell &shell, bool completed, const std::string &password)>

Function to handle the response to a password entry prompt.

Parameters

[in]	shell	Shell instance where the password entry prompt was requested.
[in]	completed	Password entry at the prompt was either completed (true) or aborted (false).
[in]	password	Password entered at the prompt (may be empty).

Since: 0.1.0

Definition at line 788 of file console.h.

Member Enumeration Documentation

◆ Mode

enum uuid::console::Shell::Mode : uint8_t

strongprivate

Current mode of the shell.

Since: 0.1.0

Enumerator
NORMAL	Normal command execution. Since 0.1.0
PASSWORD	Password entry prompt. Since 0.1.0
DELAY	Delay execution until a future time. Since 0.1.0
BLOCKING	Block execution by calling a function repeatedly. Since 0.2.0

Definition at line 1380 of file console.h.

Constructor & Destructor Documentation

◆ Shell()

uuid::console::Shell::Shell	(	Stream &	stream,
		std::shared_ptr< Commands >	commands,
		unsigned int	context = `0`,
		unsigned int	flags = `0`
	)

Create a new Shell operating on a Stream with the given commands, default context and initial flags.

The default context is put on the stack and cannot be removed.

The Stream must remain valid until the Shell has been destroyed. Monitor the Shell using a std::weak_ptr and destroy the Stream only after it has expired.

Parameters

[in]	stream	Stream used for the input/output of this shell.
[in]	commands	Commands available for execution in this shell.
[in]	context	Default context for the shell.
[in]	flags	Initial flags for the shell.

Since: 3.0.0

Definition at line 49 of file shell.cpp.

Member Function Documentation

◆ add_flags()

void uuid::console::Shell::add_flags ( unsigned int flags )

inline

Add one or more flags to the current flags.

Flags are not affected by execution context. The current flags affect which commands are available (for access control).

Parameters

[in] flags Flag bits to add.

Since: 0.1.0

Definition at line 1017 of file console.h.

◆ available()

int uuid::console::Shell::available ( )

finaloverride

Check for available input.

The shell must be currently executing a blocking function otherwise it will always return 0.

Returns: The number of bytes available to read.

Since: 0.2.0

Definition at line 27 of file shell_stream.cpp.

◆ available_commands()

Commands::AvailableCommands uuid::console::Shell::available_commands ( ) const

Get the available commands in the current context and with the current flags.

The iterable object and its iterators are invalidated if the commands, context or flags for the shell change.

Returns: An iterable object describing the available commands.

Since: 0.9.0

Definition at line 98 of file shell.cpp.

◆ block_with()

void uuid::console::Shell::block_with ( blocking_function function )

Execute a blocking function on this shell until it returns true.

The function will be executed every time loop_one() is called, which allows commands that do not complete immediately to be run asynchronously.

The shell must not be currently executing a blocking function.

Parameters

[in] function Function to be executed on every loop_one() until normal execution resumes.

Definition at line 373 of file shell.cpp.

◆ check_idle_timeout()

void uuid::console::Shell::check_idle_timeout ( )

private

Check idle timeout expiry.

Since: 0.7.2

Definition at line 506 of file shell.cpp.

◆ context()

unsigned int uuid::console::Shell::context ( ) const

inline

Get the context at the top of the stack.

The current context affects which commands are available.

Returns: Current shell context.

Since: 0.1.0

Definition at line 979 of file console.h.

◆ context_text()

std::string uuid::console::Shell::context_text ( )

protectedvirtual

Get the text indicating the current context, to be included in the command prompt.

Defaults to "".

Returns: Text indicating the current context, or an empty string for no context description.

Since: 0.1.0

Definition at line 35 of file shell_prompt.cpp.

◆ delay_for()

void uuid::console::Shell::delay_for	(	unsigned long	ms,
		delay_function	function
	)

Stop executing anything on this shell for a period of time.

There is an assumption that 2^64 milliseconds uptime will always be enough time for this delay process.

The shell must not be currently executing a blocking function.

Parameters

[in]	ms	Time in milliseconds to delay execution for.
[in]	function	Function to be executed at a future time, prior to resuming normal execution.

Since: 0.1.0

Definition at line 362 of file shell.cpp.

◆ delay_until()

void uuid::console::Shell::delay_until	(	uint64_t	ms,
		delay_function	function
	)

Stop executing anything on this shell until a future time is reached.

There is an assumption that 2^64 milliseconds uptime will always be enough time for this delay process.

The reference time is uuid::get_uptime_ms().

The shell must not be currently executing a blocking function.

Parameters

[in]	ms	Uptime in the future (in milliseconds) when the function should be executed.
[in]	function	Function to be executed at a future time, prior to resuming normal execution.

Since: 0.1.0

Definition at line 366 of file shell.cpp.

◆ delete_buffer_word()

void uuid::console::Shell::delete_buffer_word ( bool display )

private

Delete a word from the command line buffer.

Parameters

[in] display True if output to erased characters is required, false for no output.

Since: 0.1.0

Definition at line 380 of file shell.cpp.

◆ display_banner()

void uuid::console::Shell::display_banner ( )

protectedvirtual

Output the startup banner.

There is no default banner.

Since: 0.1.0

Definition at line 27 of file shell_prompt.cpp.

◆ display_prompt()

void uuid::console::Shell::display_prompt ( )

private

Output a prompt on the shell.

Based on the current mode this will output the appropriate text, e.g. the command prompt with the current command line (for Mode::NORMAL mode).

Since: 0.1.0

Definition at line 54 of file shell_prompt.cpp.

◆ end_of_transmission()

void uuid::console::Shell::end_of_transmission ( )

protectedvirtual

The end of transmission character has been received.

A command can be invoked using invoke_command(). All other actions may result in an inconsistent display of the command prompt. If the shell is stopped without invoking a command then a blank line should usually be printed first.

If an idle timeout is set then the default action (since 0.7.2) is to stop the shell, otherwise there is no default action.

Since: 0.1.0

Definition at line 47 of file shell_prompt.cpp.

◆ enter_context()

void uuid::console::Shell::enter_context ( unsigned int context )

inline

Push a new context onto the stack.

The current context affects which commands are available.

Parameters

[in] context New context.

Since: 0.1.0

Definition at line 994 of file console.h.

◆ enter_password()

void uuid::console::Shell::enter_password	(	const __FlashStringHelper *	prompt,
		password_function	function
	)

Prompt for a password to be entered on this shell.

Password entry is not visible and can be interrupted by the user.

The shell must not be currently executing a blocking function.

Parameters

[in]	prompt	Message to display prompting for password input.
[in]	function	Function to be executed after the password has been entered prior to resuming normal execution.

Since: 0.1.0

Definition at line 355 of file shell.cpp.

◆ erase_characters()

void uuid::console::Shell::erase_characters ( size_t count )

protectedvirtual

Output ANSI escape sequence to erase characters.

Parameters

[in] count The number of characters to erase.

Since: 0.1.0

Definition at line 135 of file shell_print.cpp.

◆ erase_current_line()

void uuid::console::Shell::erase_current_line ( )

protectedvirtual

Output ANSI escape sequence to erase the current line.

Since: 0.1.0

Definition at line 131 of file shell_print.cpp.

◆ exit_context()

bool uuid::console::Shell::exit_context ( )

virtual

Pop a context off the stack.

The current context affects which commands are available.

Returns: True if there was a context to be exited, false if there are no more contexts to exit.

Since: 0.1.0

Definition at line 89 of file shell.cpp.

◆ flush()

void uuid::console::Shell::flush ( )

finaloverride

Does nothing.

This is a pure virtual function in Arduino's Stream class, which makes no sense because that class is for input and this is an output function. Later versions move it to Print as an empty virtual function so this is here for backward compatibility.

Since: 3.0.0

Definition at line 125 of file shell_stream.cpp.

◆ has_all_flags()

bool uuid::console::Shell::has_all_flags ( unsigned int flags ) const

inline

Check if the current flags include all of the specified flags.

Flags are not affected by execution context. The current flags affect which commands are available (for access control).

Parameters

[in] flags Flag bits to check for.

Returns: True if the current flags includes all of the specified flags, otherwise false.

Since: 0.8.0

Definition at line 1045 of file console.h.

◆ has_any_flags()

bool uuid::console::Shell::has_any_flags ( unsigned int flags ) const

inline

Check if the current flags include any of the specified flags.

Flags are not affected by execution context. The current flags affect which commands are available (for access control).

Parameters

[in] flags Flag bits to check for.

Returns: True if the current flags includes any of the specified flags, otherwise false.

Since: 0.8.0

Definition at line 1057 of file console.h.

◆ has_flags()

bool uuid::console::Shell::has_flags	(	unsigned int	flags,
		unsigned int	not_flags = `0`
	)		const

inline

Check if the current flags include all of the specified flags and none of the specified not_flags.

Flags are not affected by execution context. The current flags affect which commands are available (for access control).

Parameters

[in]	flags	Flag bits to check for presence of.
[in]	not_flags	Flag bits to check for absence of.

Returns: True if the current flags includes all of the specified flags and none of the specified not_flags, otherwise false.

Since: 0.8.0

Definition at line 1031 of file console.h.

◆ hostname_text()

std::string uuid::console::Shell::hostname_text ( )

protectedvirtual

Get the hostname to be included in the command prompt.

Defaults to "".

Returns: The current hostname of the device, or an empty string for no hostname.

Since: 0.1.0

Definition at line 31 of file shell_prompt.cpp.

◆ idle_timeout() [1/2]

unsigned long uuid::console::Shell::idle_timeout ( ) const

Get the idle timeout.

Returns: The idle timeout in seconds.

Since: 0.7.0

Definition at line 498 of file shell.cpp.

◆ idle_timeout() [2/2]

void uuid::console::Shell::idle_timeout ( unsigned long timeout )

Set the idle timeout.

Defaults to 0 (no idle timeout).

Parameters

[in] timeout Idle timeout in seconds.

Since: 0.7.0

Definition at line 502 of file shell.cpp.

◆ invoke_command()

void uuid::console::Shell::invoke_command ( const std::string & line )

protected

Invoke a command on the shell.

This will output a prompt with the provided command line and then try to execute it.

Intended for use from end_of_transmission() to execute an "exit" or "logout" command.

Parameters

[in] line The command line to be executed.

Since: 0.1.0

Definition at line 485 of file shell.cpp.

◆ log_level() [1/2]

uuid::log::Level uuid::console::Shell::log_level ( ) const

Get the current log level.

This only affects newly received log messages, not messages that have already been queued.

Returns: The current log level.

Since: 0.6.0

Definition at line 67 of file shell_log.cpp.

◆ log_level() [2/2]

void uuid::console::Shell::log_level ( uuid::log::Level level )

Set the current log level.

This only affects newly received log messages, not messages that have already been queued.

Parameters

[in] level Minimum log level that the shell will receive messages for.

Since: 0.6.0

Definition at line 71 of file shell_log.cpp.

◆ logger()

const uuid::log::Logger & uuid::console::Shell::logger ( )

static

Get the built-in uuid::log::Logger instance for shells.

Returns: Logger instance.

Since: 0.1.0

Definition at line 44 of file shell_log.cpp.

◆ loop_all()

void uuid::console::Shell::loop_all ( )

static

Loop through all registered shell objects.

Call loop_one() on every Shell (if it has not been stopped). Any Shell that is stopped is then unregistered.

Since: 0.1.0

Definition at line 34 of file shell_loop_all.cpp.

◆ loop_blocking()

void uuid::console::Shell::loop_blocking ( )

private

Perform one execution step in Mode::BLOCKING mode.

Wait until the function returns true.

Since: 0.2.0

Definition at line 329 of file shell.cpp.

◆ loop_delay()

void uuid::console::Shell::loop_delay ( )

private

Perform one execution step in Mode::DELAY mode.

Wait until the delay uptime is reached.

Since: 0.1.0

Definition at line 305 of file shell.cpp.

◆ loop_normal()

void uuid::console::Shell::loop_normal ( )

private

Perform one execution step in Mode::NORMAL mode.

Read characters and execute commands or invoke tab completion.

Since: 0.1.0

Definition at line 129 of file shell.cpp.

◆ loop_one()

void uuid::console::Shell::loop_one ( )

Perform one execution step of this shell.

Depending on the current mode, either read input characters and process them or check if an execution delay has passed.

Since: 0.1.0

Definition at line 102 of file shell.cpp.

◆ loop_password()

void uuid::console::Shell::loop_password ( )

private

Perform one execution step in Mode::PASSWORD mode.

Read characters until interrupted or password entry is complete.

Since: 0.1.0

Definition at line 227 of file shell.cpp.

◆ maximum_command_line_length() [1/2]

size_t uuid::console::Shell::maximum_command_line_length ( ) const

Get the maximum length of a command line.

Returns: The maximum length of a command line in bytes.

Since: 0.6.0

Definition at line 398 of file shell.cpp.

◆ maximum_command_line_length() [2/2]

void uuid::console::Shell::maximum_command_line_length ( size_t length )

Set the maximum length of a command line.

Defaults to Shell::MAX_COMMAND_LINE_LENGTH.

Parameters

[in] length The maximum length of a command line in bytes.

Since: 0.6.0

Definition at line 402 of file shell.cpp.

◆ maximum_log_messages() [1/2]

size_t uuid::console::Shell::maximum_log_messages ( ) const

Get the maximum number of queued log messages.

Returns: The maximum number of queued log messages.

Since: 0.6.0

Definition at line 75 of file shell_log.cpp.

◆ maximum_log_messages() [2/2]

void uuid::console::Shell::maximum_log_messages ( size_t count )

Set the maximum number of queued log messages.

Defaults to Shell::MAX_LOG_MESSAGES.

Parameters

[in] count The maximum number of queued log messages.

Since: 0.6.0

Definition at line 83 of file shell_log.cpp.

◆ operator<<()

void uuid::console::Shell::operator<< ( std::shared_ptr< uuid::log::Message > message )

virtual

Add a new log message.

This will be put in a queue for output at the next loop_one() process. The queue has a maximum size of maximum_log_messages() and will discard the oldest message first.

Parameters

[in] message New log message, shared by all handlers.

Since: 0.1.0

Implements uuid::log::Handler.

Definition at line 55 of file shell_log.cpp.

◆ output_logs()

void uuid::console::Shell::output_logs ( )

private

Output queued log messages for this shell.

Since: 0.1.0

Definition at line 94 of file shell_log.cpp.

◆ peek()

int uuid::console::Shell::peek ( )

finaloverride

Read one byte from the available input without advancing to the next one.

The shell must be currently executing a blocking function otherwise it will always return -1.

Returns: An unsigned char if input is available, otherwise -1.

Since: 0.2.0

Definition at line 90 of file shell_stream.cpp.

◆ print()

size_t uuid::console::Shell::print ( const std::string & data )

Output a string.

Parameters

[in] data String to be output.

Returns: The number of bytes that were output.

Since: 0.1.0

Definition at line 30 of file shell_print.cpp.

◆ print_all_available_commands()

void uuid::console::Shell::print_all_available_commands ( )

Output a list of all available commands with their arguments.

Since: 0.4.0

Definition at line 122 of file shell_print.cpp.

◆ printf() [1/2]

size_t uuid::console::Shell::printf	(	const __FlashStringHelper *	format,
			...
	)

Output a message.

Parameters

[in]	format	Format string (flash string).
[in]	...	Format string arguments.

Returns: The number of bytes that were output.

Since: 0.1.0

Definition at line 54 of file shell_print.cpp.

◆ printf() [2/2]

size_t uuid::console::Shell::printf	(	const char *	format,
			...
	)

Output a message.

Parameters

[in]	format	Format string.
[in]	...	Format string arguments.

Returns: The number of bytes that were output.

Since: 0.1.0

Definition at line 44 of file shell_print.cpp.

◆ printfln() [1/2]

size_t uuid::console::Shell::printfln	(	const __FlashStringHelper *	format,
			...
	)

Output a message followed by CRLF end of line characters.

Parameters

[in]	format	Format string (flash string).
[in]	...	Format string arguments.

Returns: The number of bytes that were output, including CRLF.

Since: 0.1.0

Definition at line 75 of file shell_print.cpp.

◆ printfln() [2/2]

size_t uuid::console::Shell::printfln	(	const char *	format,
			...
	)

Output a message followed by CRLF end of line characters.

Parameters

[in]	format	Format string.
[in]	...	Format string arguments.

Returns: The number of bytes that were output, including CRLF.

Since: 0.1.0

Definition at line 64 of file shell_print.cpp.

◆ println()

size_t uuid::console::Shell::println ( const std::string & data )

Output a string followed by CRLF end of line characters.

Parameters

[in] data String to be output.

Returns: The number of bytes that were output, including CRLF.

Since: 0.1.0

Definition at line 38 of file shell_print.cpp.

◆ process_command()

void uuid::console::Shell::process_command ( )

private

Try to execute a command with the current command line.

Since: 0.1.0

Definition at line 407 of file shell.cpp.

◆ process_completion()

void uuid::console::Shell::process_completion ( )

private

Try to complete a command from the current command line.

Since: 0.1.0

Definition at line 432 of file shell.cpp.

◆ process_password()

void uuid::console::Shell::process_password ( bool completed )

private

Finish password entry.

The entered password is in the command line buffer.

Parameters

[in] completed Password entry at the prompt was either completed (true) or aborted (false).

Since: 0.1.0

Definition at line 468 of file shell.cpp.

◆ prompt_prefix()

std::string uuid::console::Shell::prompt_prefix ( )

protectedvirtual

Get the prefix to be used at the beginning of the command prompt.

Defaults to "".

Returns: Text for the beginning of the command prompt, or an empty string.

Since: 0.1.0

Definition at line 39 of file shell_prompt.cpp.

◆ prompt_suffix()

std::string uuid::console::Shell::prompt_suffix ( )

protectedvirtual

Get the prefix to be used at the end of the command prompt.

Defaults to "$".

Returns: Text for the end of the command prompt, or an empty string.

Since: 0.1.0

Definition at line 43 of file shell_prompt.cpp.

◆ read()

int uuid::console::Shell::read ( )

finaloverride

Read one byte from the available input.

The shell must be currently executing a blocking function otherwise it will always return -1.

Returns: An unsigned char if input is available, otherwise -1.

Since: 0.2.0

Definition at line 62 of file shell_stream.cpp.

◆ registered_shells()

std::set< std::shared_ptr< Shell > > & uuid::console::Shell::registered_shells ( )

staticprivate

Get registered running shells to be executed.

Returns: Registered running shells to be executed.

Since: 0.7.4

Definition at line 28 of file shell_loop_all.cpp.

◆ remove_flags()

void uuid::console::Shell::remove_flags ( unsigned int flags )

inline

Remove one or more flags from the current flags.

Flags are not affected by execution context. The current flags affect which commands are available (for access control).

Parameters

[in] flags Flag bits to remove.

Since: 0.1.0

Definition at line 1067 of file console.h.

◆ running()

bool uuid::console::Shell::running ( ) const

Determine if this shell is still running.

Returns: Running status of this Shell, false if the Shell has been stopped using stop().

Since: 0.1.0

Definition at line 68 of file shell.cpp.

◆ start()

void uuid::console::Shell::start ( )

Perform startup process for this shell.

Register as a uuid::log::Handler at the uuid::log::Level::NOTICE log level, output the banner and register this Shell with the loop_all() set.

The started() function will be called after startup is complete.

Do not call this function more than once.

Since: 0.1.0

Definition at line 54 of file shell.cpp.

◆ started()

void uuid::console::Shell::started ( )

protectedvirtual

Startup complete event.

The shell is ready to start executing commands.

Since: 0.1.0

Definition at line 64 of file shell.cpp.

◆ stop()

void uuid::console::Shell::stop ( )

Stop this shell from running.

If the shell is currently executing a blocking function, that must complete before the shell will stop.

It is not possible to restart the Shell, which must be destroyed after it has been stopped.

Since: 0.1.0

Definition at line 72 of file shell.cpp.

◆ stopped()

void uuid::console::Shell::stopped ( )

protectedvirtual

Stop request event.

The shell is going to stop executing.

Since: 0.1.0

Definition at line 85 of file shell.cpp.

◆ vprintf() [1/2]

size_t uuid::console::Shell::vprintf	(	const __FlashStringHelper *	format,
		va_list	ap
	)

private

Output a message.

Parameters

[in]	format	Format string (flash string).
[in]	ap	Variable arguments pointer for format string.

Returns: The number of bytes that were output.

Since: 0.1.0

Definition at line 104 of file shell_print.cpp.

◆ vprintf() [2/2]

size_t uuid::console::Shell::vprintf	(	const char *	format,
		va_list	ap
	)

private

Output a message.

Parameters

[in]	format	Format string.
[in]	ap	Variable arguments pointer for format string.

Returns: The number of bytes that were output.

Since: 0.1.0

Definition at line 86 of file shell_print.cpp.

◆ write() [1/2]

size_t uuid::console::Shell::write	(	const uint8_t *	buffer,
		size_t	size
	)

finaloverride

Write an array of bytes to the output stream.

Parameters

[in]	buffer	Buffer to be output.
[in]	size	Length of the buffer.

Returns: The number of bytes that were output.

Since: 3.0.0

Definition at line 120 of file shell_stream.cpp.

◆ write() [2/2]

size_t uuid::console::Shell::write ( uint8_t data )

finaloverride

Write one byte to the output stream.

Parameters

[in] data Data to be output.

Returns: The number of bytes that were output.

Since: 3.0.0

Definition at line 116 of file shell_stream.cpp.

Member Data Documentation

◆ commands_

std::shared_ptr<Commands> uuid::console::Shell::commands_

private

Commands available for execution in this shell.

Since: 0.1.0

Definition at line 1616 of file console.h.

◆ context_

std::deque<unsigned int> uuid::console::Shell::context_

private

Context stack for this shell. Affects which commands are available. Should never be empty.

Since: 0.1.0

Definition at line 1617 of file console.h.

◆ flags_

unsigned int uuid::console::Shell::flags_ = 0

private

Current flags for this shell. Affects which commands are available.

Since: 0.1.0

Definition at line 1618 of file console.h.

◆ idle_time_

uint64_t uuid::console::Shell::idle_time_ = 0

private

Time the shell became idle.

Since: 0.7.0

Definition at line 1632 of file console.h.

◆ idle_timeout_

uint64_t uuid::console::Shell::idle_timeout_ = 0

private

Idle timeout (in milliseconds).

Since: 0.7.0

Definition at line 1633 of file console.h.

◆ line_buffer_

std::string uuid::console::Shell::line_buffer_

private

Command line buffer. Limited to maximum_command_line_length() bytes.

Since: 0.1.0

Definition at line 1625 of file console.h.

◆ log_message_id_

unsigned long uuid::console::Shell::log_message_id_ = 0

private

The next identifier to use for queued log messages.

Since: 0.1.0

Definition at line 1622 of file console.h.

◆ log_messages_

std::list<QueuedLogMessage> uuid::console::Shell::log_messages_

private

Queued log messages, in the order they were received.

Since: 0.1.0

Definition at line 1623 of file console.h.

◆ MAX_COMMAND_LINE_LENGTH

constexpr size_t uuid::console::Shell::MAX_COMMAND_LINE_LENGTH = 80

staticconstexpr

Maximum length of a command line.

Since: 0.1.0

Definition at line 774 of file console.h.

◆ MAX_LOG_MESSAGES

constexpr size_t uuid::console::Shell::MAX_LOG_MESSAGES = 20

staticconstexpr

Maximum number of log messages to buffer before they are output.

Since: 0.1.0

Definition at line 775 of file console.h.

◆ maximum_command_line_length_

size_t uuid::console::Shell::maximum_command_line_length_ = MAX_COMMAND_LINE_LENGTH

private

Maximum command line length in bytes.

Since: 0.6.0

Definition at line 1626 of file console.h.

◆ maximum_log_messages_

size_t uuid::console::Shell::maximum_log_messages_ = MAX_LOG_MESSAGES

private

Maximum command line length in bytes.

Since: 0.6.0

Definition at line 1624 of file console.h.

◆ mode_

Mode uuid::console::Shell::mode_ = Mode::NORMAL

private

Current execution mode.

Since: 0.1.0

Definition at line 1628 of file console.h.

◆ mode_data_

std::unique_ptr<ModeData> uuid::console::Shell::mode_data_ = nullptr

private

Data associated with the current execution mode.

Since: 0.1.0

Definition at line 1629 of file console.h.

◆ mutex_

std::mutex uuid::console::Shell::mutex_

mutableprivate

Mutex for queued log messages.

Since: 1.0.0

Definition at line 1620 of file console.h.

◆ previous_

unsigned char uuid::console::Shell::previous_ = 0

private

Previous character that was entered on the command line. Used to detect CRLF line endings.

Since: 0.1.0

Definition at line 1627 of file console.h.

◆ prompt_displayed_

bool uuid::console::Shell::prompt_displayed_ = false

private

Indicates that a command prompt has been displayed, so that the output of invoke_command() is correct.

Since: 0.1.0

Definition at line 1631 of file console.h.

◆ stopped_

bool uuid::console::Shell::stopped_ = false

private

Indicates that the shell has been stopped.

Since: 0.1.0

Definition at line 1630 of file console.h.

◆ stream_

Stream& uuid::console::Shell::stream_

private

Stream used for the input/output of this shell.

Since: 3.0.0

Definition at line 1615 of file console.h.

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

mcu-uuid-console/src/uuid/console.h
mcu-uuid-console/src/shell.cpp
mcu-uuid-console/src/shell_log.cpp
mcu-uuid-console/src/shell_loop_all.cpp
mcu-uuid-console/src/shell_print.cpp
mcu-uuid-console/src/shell_prompt.cpp
mcu-uuid-console/src/shell_stream.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ blocking_function

◆ delay_function

◆ password_function

Member Enumeration Documentation

◆ Mode

Constructor & Destructor Documentation

◆ Shell()

Member Function Documentation

◆ add_flags()

◆ available()

◆ available_commands()

◆ block_with()

◆ check_idle_timeout()

◆ context()

◆ context_text()

◆ delay_for()

◆ delay_until()

◆ delete_buffer_word()

◆ display_banner()

◆ display_prompt()

◆ end_of_transmission()

◆ enter_context()

◆ enter_password()

◆ erase_characters()

◆ erase_current_line()

◆ exit_context()

◆ flush()

◆ has_all_flags()

◆ has_any_flags()

◆ has_flags()

◆ hostname_text()

◆ idle_timeout() [1/2]

◆ idle_timeout() [2/2]

◆ invoke_command()

◆ log_level() [1/2]

◆ log_level() [2/2]

◆ logger()

◆ loop_all()

◆ loop_blocking()

◆ loop_delay()

◆ loop_normal()

◆ loop_one()

◆ loop_password()

◆ maximum_command_line_length() [1/2]

◆ maximum_command_line_length() [2/2]

◆ maximum_log_messages() [1/2]

◆ maximum_log_messages() [2/2]

◆ operator<<()

◆ output_logs()

◆ peek()

◆ print()

◆ print_all_available_commands()

◆ printf() [1/2]

◆ printf() [2/2]

◆ printfln() [1/2]

◆ printfln() [2/2]

◆ println()

◆ process_command()

◆ process_completion()

◆ process_password()

◆ prompt_prefix()

◆ prompt_suffix()

◆ read()

◆ registered_shells()

◆ remove_flags()

◆ running()

◆ start()

◆ started()