Console Component

Interactive console with REPL and command registration. More...

Namespaces
namespace	idfxx
namespace	idfxx::console

Classes
struct	idfxx::console::command
	Command descriptor for registration. More...
struct	idfxx::console::config
	Configuration for low-level console initialization. More...
class	idfxx::console::repl
	Interactive REPL (Read-Eval-Print Loop) console. More...

Typedefs
using	idfxx::console::handler = std::move_only_function< int(int argc, char **argv)>
	Command handler callback type.

Functions
void	idfxx::console::register_command (const command &cmd, handler callback)
	Registers a command with a callback handler.
void	idfxx::console::deregister_command (std::string_view name)
	Deregisters a previously registered command.
void	idfxx::console::register_help_command ()
	Registers the built-in 'help' command.
void	idfxx::console::deregister_help_command ()
	Deregisters the built-in 'help' command.
result< void >	idfxx::console::try_register_command (const command &cmd, handler callback)
	Registers a command with a callback handler.
result< void >	idfxx::console::try_deregister_command (std::string_view name)
	Deregisters a previously registered command.
result< void >	idfxx::console::try_register_help_command ()
	Registers the built-in 'help' command.
result< void >	idfxx::console::try_deregister_help_command ()
	Deregisters the built-in 'help' command.
void	idfxx::console::init (const config &cfg={})
	Initializes the console module.
void	idfxx::console::deinit ()
	Deinitializes the console module.
int	idfxx::console::run (std::string_view cmdline)
	Runs a command line string.
result< void >	idfxx::console::try_init (const config &cfg={})
	Initializes the console module.
result< void >	idfxx::console::try_deinit ()
	Deinitializes the console module.
result< int >	idfxx::console::try_run (std::string_view cmdline)
	Runs a command line string.

Detailed Description

Interactive console with REPL and command registration.

Provides an interactive command-line console for ESP32 devices, supporting UART, USB CDC, and USB Serial JTAG backends. Commands can be registered with C++ callbacks (including lambdas with captures) or raw function pointers.

The console uses a global command registry – commands registered via the free functions in this namespace are available across all backends.

Depends on Core Utilities for error handling.

Typedef Documentation

handler

using idfxx::console::handler = typedef std::move_only_function<int(int argc, char** argv)>

Command handler callback type.

Called when a registered command is executed. The callback receives the argument count and argument vector, and returns an integer status code (0 for success).

Definition at line 51 of file console.hpp.

Function Documentation

deinit()

void idfxx::console::deinit

(

)

Deinitializes the console module.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on failure.

deregister_command()

void idfxx::console::deregister_command

(

std::string_view

name

)

Deregisters a previously registered command.

Parameters

name	The command name to deregister.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on failure.

deregister_help_command()

void idfxx::console::deregister_help_command

(

)

Deregisters the built-in 'help' command.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on failure.

init()

void idfxx::console::init

(

const config &

cfg = {}

)

Initializes the console module.

Call this before using command registration or run() in non-REPL mode. Not needed when using the REPL, which initializes the console internally.

Parameters

cfg	Console configuration.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on failure.

register_command()

void idfxx::console::register_command	(	const command &	cmd,
		handler	callback
	)

Registers a command with a callback handler.

The callback can be any callable, including lambdas with captures and raw function pointers. The callback and command strings are stored internally and remain valid until the command is deregistered or the console is deinitialized.

int counter = 0;
idfxx::console::register_command(
    {.name = "count", .help = "Increment counter"},
    [&counter](int argc, char** argv) {
        ++counter;
        std::printf("Count: %d\n", counter);
        return 0;
    });

Parameters

cmd	Command descriptor.
callback	Function to call when the command is executed.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on failure.

register_help_command()

void idfxx::console::register_help_command

(

)

Registers the built-in 'help' command.

The help command lists all registered commands with their help text.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on failure.

run()

int idfxx::console::run

(

std::string_view

cmdline

)

Runs a command line string.

Parses and executes the given command line. The console must be initialized first via init() or by creating a REPL.

idfxx::console::init();
idfxx::console::register_command(
    {.name = "hello", .help = "Say hello"},
    [](int, char**) { std::printf("Hello!\n"); return 0; });
int ret = idfxx::console::run("hello");

Parameters

cmdline

The command line string to execute.

Returns

The command's return code.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

if the command is not found or the console is not initialized.

try_deinit()

result< void > idfxx::console::try_deinit

(

)

Deinitializes the console module.

Returns

Success, or an error.

Return values

invalid_state

If not initialized.

try_deregister_command()

result< void > idfxx::console::try_deregister_command

(

std::string_view

name

)

Deregisters a previously registered command.

Parameters

name	The command name to deregister.

Returns

Success, or an error.

Return values

invalid_arg

If the command is not registered.

try_deregister_help_command()

result< void > idfxx::console::try_deregister_help_command

(

)

Deregisters the built-in 'help' command.

Returns

Success, or an error.

try_init()

result< void > idfxx::console::try_init

(

const config &

cfg = {}

)

Initializes the console module.

Call this before using command registration or try_run() in non-REPL mode. Not needed when using the REPL, which initializes the console internally.

Parameters

cfg	Console configuration.

Returns

Success, or an error.

Return values

invalid_state	If already initialized.
invalid_arg	If the configuration is invalid.

try_register_command()

result< void > idfxx::console::try_register_command	(	const command &	cmd,
		handler	callback
	)

Registers a command with a callback handler.

The callback can be any callable, including lambdas with captures and raw function pointers. The callback and command strings are stored internally and remain valid until the command is deregistered or the console is deinitialized.

Parameters

cmd	Command descriptor.
callback	Function to call when the command is executed.

Returns

Success, or an error.

Return values

invalid_arg

If the command name is empty or contains spaces.

try_register_help_command()

result< void > idfxx::console::try_register_help_command

(

)

Registers the built-in 'help' command.

The help command lists all registered commands with their help text.

Returns

Success, or an error.

Return values

invalid_state

If the console is not initialized.

try_run()

result< int > idfxx::console::try_run

(

std::string_view

cmdline

)

Runs a command line string.

Parses and executes the given command line. The console must be initialized first via try_init() or by creating a REPL.

Parameters

cmdline

The command line string to execute.

Returns

The command's return code, or an error.

Return values

invalid_arg	If the command line is empty or only whitespace.
not_found	If the command is not registered.
invalid_state	If the console is not initialized.