Shell Framework API Reference

This section documents the Shell Framework API.

Shell Core

enum escape_state_t

Escape sequence parser states.

Values:

enumerator ESC_STATE_NORMAL

Normal input state

enumerator ESC_STATE_ESC

Received ESC (0x1B)

enumerator ESC_STATE_CSI

Received CSI (ESC [)

enumerator ESC_STATE_SS3

Received SS3 (ESC O)

enum escape_result_t

Parsed escape sequence result.

Values:

enumerator ESC_RESULT_NONE

No complete sequence yet

enumerator ESC_RESULT_UP

Up arrow

enumerator ESC_RESULT_DOWN

Down arrow

enumerator ESC_RESULT_LEFT

Left arrow

enumerator ESC_RESULT_RIGHT

Right arrow

enumerator ESC_RESULT_HOME

Home key

enumerator ESC_RESULT_END

End key

enumerator ESC_RESULT_DELETE

Delete key

enumerator ESC_RESULT_INVALID

Invalid/unknown sequence

static shell_context_t g_shell_ctx

Global shell context

static const char *const g_error_messages[] = {"Success", "Generic error", "Invalid parameter", "Shell not initialized", "Shell already initialized", "Memory allocation failed", "Item not found", "Item already exists", "No backend configured", "Buffer is full",}

Error message strings for each status code.

shell_status_t shell_init(const shell_config_t *config)

Initialize the Shell module.

Parameters:

config – [in] Pointer to configuration structure

Returns:

SHELL_OK on success

Returns:

SHELL_ERROR_INVALID_PARAM if config is NULL or invalid

Returns:

SHELL_ERROR_ALREADY_INIT if already initialized

shell_status_t shell_deinit(void)

Deinitialize the Shell module.

Returns:

SHELL_OK on success

Returns:

SHELL_ERROR_NOT_INIT if not initialized

Returns:

SHELL_OK on success, error code otherwise

bool shell_is_initialized(void)

Check if Shell is initialized.

Returns:

true if initialized, false otherwise

shell_status_t shell_process(void)

Process Shell input.

Note

This function is non-blocking

Returns:

SHELL_OK on success

Returns:

SHELL_ERROR_NOT_INIT if not initialized

Returns:

SHELL_ERROR_NO_BACKEND if no backend configured

Returns:

SHELL_OK on success, error code otherwise

shell_status_t shell_get_last_error(void)

Get the last error code.

Returns:

Last error code

const char *shell_get_error_message(shell_status_t status)

Get error message string for a status code.

Parameters:

status – [in] Status code to get message for

Returns:

Pointer to error message string (never NULL)

void shell_print_error(shell_status_t status)

Print error message to shell output.

Parameters:

status – [in] Status code to print message for

void shell_print_error_context(shell_status_t status, const char *context)

Print error message with context.

Parameters:

• status – [in] Status code to print message for

• context – [in] Additional context string (can be NULL)

shell_status_t shell_recover(void)

Reset shell to a known good state after error.

Returns:

SHELL_OK on successful recovery, error code otherwise

const char *shell_get_version(void)

Get Shell version string.

Returns:

Version string (e.g., “1.0.0”)

Returns:

Version string

void shell_print_prompt(void)

Print the Shell prompt.

void shell_clear_screen(void)

Clear the terminal screen.

static shell_status_t validate_config(const shell_config_t *config)

Validate shell configuration.

Parameters:

config – [in] Configuration to validate

Returns:

SHELL_OK if valid, error code otherwise

static void reset_escape_state(void)

Reset escape sequence state machine.

static escape_result_t process_escape_char(uint8_t c)

Process a character in escape sequence.

Parameters:

c – [in] Character to process

Returns:

Escape result (key identified or still processing)

static void handle_escape_result(escape_result_t result)

Handle escape sequence result.

Parameters:

result – [in] Parsed escape sequence result

static void handle_printable_char(char c)

Handle printable character input.

Parameters:

c – [in] Character to insert

static void handle_control_char(uint8_t c)

Handle control character input.

Parameters:

c – [in] Control character

static void handle_tab_completion(void)

Handle Tab key for auto-completion.

static void execute_command_line(void)

Execute the current command line.

Parses and executes the command in the line editor buffer.

static void redraw_line(void)

Redraw the entire command line.

Clears the current line and redraws prompt and buffer content.

static void refresh_line_from_cursor(void)

Refresh line from cursor position to end.

Used after inserting or deleting characters.

history_manager_t *shell_get_history_manager(void)

Get the history manager.

Returns:

Pointer to history manager, or NULL if not initialized

SHELL_CONFIG_DEFAULT

Default Shell configuration.

SHELL_VERSION

Shell version string

SHELL_ESCAPE_BUFFER_SIZE

Maximum escape sequence buffer size

ANSI_CLEAR_SCREEN

ANSI escape sequences

ANSI_CURSOR_LEFT

ANSI_CURSOR_RIGHT

ANSI_ERASE_LINE

ANSI_CURSOR_SAVE

ANSI_CURSOR_RESTORE

SHELL_ERROR_MESSAGE_COUNT

Number of error messages

struct shell_config_t

#include <shell.h>

Shell configuration structure.

Public Members

const char *prompt

Prompt string (max 16 chars)

uint16_t cmd_buffer_size

Command buffer size (64-256)

uint8_t history_depth

History depth (4-32)

uint8_t max_commands

Max commands (default 32)

struct shell_context_t

Shell context structure.

Contains all state for the Shell module.

Public Members

bool initialized

Initialization flag

shell_config_t config

Configuration copy

const shell_backend_t *backend

I/O backend

line_editor_t editor

Line editor state

history_manager_t history

History manager state

char *cmd_buffer

Command buffer

char *saved_input

Saved input for history

shell_status_t last_error

Last error code

escape_state_t escape_state

Current escape state

uint8_t escape_buffer[8]

uint8_t escape_index

Escape buffer index

char **history_entries

History entry pointers

char *history_storage

History storage buffer

char prompt[SHELL_MAX_PROMPT_LEN + 1]

Definitions & Constants

enum shell_status_t

Shell operation status codes.

Values:

enumerator SHELL_OK

Operation successful

enumerator SHELL_ERROR

Generic error

enumerator SHELL_ERROR_INVALID_PARAM

Invalid parameter

enumerator SHELL_ERROR_NOT_INIT

Module not initialized

enumerator SHELL_ERROR_ALREADY_INIT

Module already initialized

enumerator SHELL_ERROR_NO_MEMORY

Memory allocation failed

enumerator SHELL_ERROR_NOT_FOUND

Item not found

enumerator SHELL_ERROR_ALREADY_EXISTS

Item already exists

enumerator SHELL_ERROR_NO_BACKEND

No backend configured

enumerator SHELL_ERROR_BUFFER_FULL

Buffer is full

SHELL_MAX_PROMPT_LEN

Maximum prompt string length

SHELL_MIN_CMD_BUFFER_SIZE

Minimum command buffer size

SHELL_MAX_CMD_BUFFER_SIZE

Maximum command buffer size

SHELL_DEFAULT_CMD_BUFFER_SIZE

Default command buffer size

SHELL_MIN_HISTORY_DEPTH

Minimum history depth

SHELL_MAX_HISTORY_DEPTH

Maximum history depth

SHELL_DEFAULT_HISTORY_DEPTH

Default history depth

SHELL_MAX_COMMANDS

Maximum number of registered commands

SHELL_MAX_ARGS

Maximum number of arguments per command

SHELL_MAX_CMD_NAME

Maximum command name length

SHELL_MAX_COMPLETIONS

Maximum number of auto-completion matches

SHELL_DEFAULT_PROMPT

Default prompt string

Command Management

typedef int (*shell_cmd_handler_t)(int argc, char *argv[])

Command handler function type.

Param argc:

[in] Number of arguments (including command name)

Param argv:

[in] Array of argument strings

Return:

0 on success, non-zero error code on failure

typedef void (*shell_completion_cb_t)(const char *partial, char *completions[], int *count)

Command completion callback type.

Param partial:

[in] Partial argument string to complete

Param completions:

[out] Array to store completion suggestions

Param count:

[out] Pointer to store number of completions found

shell_status_t shell_register_command(const shell_command_t *cmd)

Register a command with the Shell.

Parameters:

cmd – [in] Pointer to command structure (must remain valid)

Returns:

SHELL_OK on success

Returns:

SHELL_ERROR_INVALID_PARAM if cmd, name, or handler is NULL

Returns:

SHELL_ERROR_ALREADY_EXISTS if command name already registered

Returns:

SHELL_ERROR_NO_MEMORY if command registry is full

shell_status_t shell_unregister_command(const char *name)

Unregister a command from the Shell.

Parameters:

name – [in] Command name to unregister

Returns:

SHELL_OK on success

Returns:

SHELL_ERROR_INVALID_PARAM if name is NULL

Returns:

SHELL_ERROR_NOT_FOUND if command not found

const shell_command_t *shell_get_command(const char *name)

Get a command by name.

Parameters:

name – [in] Command name to look up

Returns:

Pointer to command structure, or NULL if not found

shell_status_t shell_get_commands(const shell_command_t **cmds[], int *count)

Get all registered commands.

Parameters:

• cmds – [out] Pointer to store command array pointer

• count – [out] Pointer to store number of commands

Returns:

SHELL_OK on success

int shell_get_command_count(void)

Get the number of registered commands.

Returns:

Number of currently registered commands

shell_status_t shell_set_completion_callback(shell_completion_cb_t callback)

Set global completion callback.

Parameters:

callback – [in] Completion callback function

Returns:

SHELL_OK on success

shell_completion_cb_t shell_get_completion_callback(void)

Get the global completion callback.

Returns:

Current completion callback, or NULL if not set

void shell_clear_commands(void)

Clear all registered commands (for testing)

struct shell_command_t

#include <shell_command.h>

Shell command structure.

Public Members

const char *name

Command name (max 16 chars)

shell_cmd_handler_t handler

Command handler function

const char *help

Short help description

const char *usage

Usage string (e.g., “cmd [options]”)

shell_completion_cb_t completion

Argument completion callback (optional)

Line Editor

void line_editor_init(line_editor_t *editor, char *buffer, uint16_t size)

Initialize line editor.

Parameters:

• editor – [inout] Pointer to line editor structure

• buffer – [in] Pointer to character buffer

• size – [in] Size of the buffer

bool line_editor_insert_char(line_editor_t *editor, char c)

Insert a character at cursor position.

Parameters:

• editor – [inout] Pointer to line editor

• c – [in] Character to insert

Returns:

true if character was inserted, false if buffer full

bool line_editor_delete_char(line_editor_t *editor)

Delete character at cursor position (Delete key)

Parameters:

editor – [inout] Pointer to line editor

Returns:

true if character was deleted, false if at end

bool line_editor_backspace(line_editor_t *editor)

Delete character before cursor (Backspace)

Parameters:

editor – [inout] Pointer to line editor

Returns:

true if character was deleted, false if at start

void line_editor_move_cursor(line_editor_t *editor, int offset)

Move cursor by offset.

Parameters:

• editor – [inout] Pointer to line editor

• offset – [in] Number of positions to move (can be negative)

void line_editor_move_to_start(line_editor_t *editor)

Move cursor to start of line (Home/Ctrl+A)

Parameters:

editor – [inout] Pointer to line editor

void line_editor_move_to_end(line_editor_t *editor)

Move cursor to end of line (End/Ctrl+E)

Parameters:

editor – [inout] Pointer to line editor

void line_editor_delete_to_end(line_editor_t *editor)

Delete from cursor to end of line (Ctrl+K)

Parameters:

editor – [inout] Pointer to line editor

void line_editor_delete_to_start(line_editor_t *editor)

Delete from start to cursor (Ctrl+U)

Parameters:

editor – [inout] Pointer to line editor

void line_editor_delete_word(line_editor_t *editor)

Delete word before cursor (Ctrl+W)

Parameters:

editor – [inout] Pointer to line editor

void line_editor_clear(line_editor_t *editor)

Clear the entire line.

Parameters:

editor – [inout] Pointer to line editor

const char *line_editor_get_buffer(const line_editor_t *editor)

Get current buffer content.

Parameters:

editor – [in] Pointer to line editor

Returns:

Pointer to null-terminated buffer content

uint16_t line_editor_get_length(const line_editor_t *editor)

Get current content length.

Parameters:

editor – [in] Pointer to line editor

Returns:

Current content length

uint16_t line_editor_get_cursor(const line_editor_t *editor)

Get current cursor position.

Parameters:

editor – [in] Pointer to line editor

Returns:

Current cursor position

void line_editor_set_content(line_editor_t *editor, const char *content)

Set buffer content.

Parameters:

• editor – [inout] Pointer to line editor

• content – [in] String to set as buffer content

struct line_editor_t

#include <shell_line_editor.h>

Line editor state structure.

Public Members

char *buffer

Input buffer pointer

uint16_t buffer_size

Buffer size (capacity)

uint16_t length

Current content length

uint16_t cursor

Cursor position (0 to length)

bool insert_mode

Insert mode (true) or overwrite mode

History

void history_init(history_manager_t *hist, char **entries, uint8_t capacity, uint16_t entry_size)

Initialize history manager.

Parameters:

• hist – [inout] Pointer to history manager structure

• entries – [in] Array of entry buffer pointers

• capacity – [in] Maximum number of history entries

• entry_size – [in] Maximum size of each entry (including null terminator)

void history_deinit(history_manager_t *hist)

Deinitialize history manager.

Parameters:

hist – [inout] Pointer to history manager structure

bool history_add(history_manager_t *hist, const char *cmd)

Add command to history.

Parameters:

• hist – [inout] Pointer to history manager

• cmd – [in] Command string to add

Returns:

true if command was added, false if skipped (empty or duplicate)

const char *history_get_prev(history_manager_t *hist)

Get previous command (Up arrow)

Parameters:

hist – [inout] Pointer to history manager

Returns:

Pointer to previous command, or NULL if at oldest

const char *history_get_next(history_manager_t *hist)

Get next command (Down arrow)

Parameters:

hist – [inout] Pointer to history manager

Returns:

Pointer to next command, or NULL if at newest (current input)

void history_reset_browse(history_manager_t *hist)

Reset browse position.

Parameters:

hist – [inout] Pointer to history manager

uint8_t history_get_count(const history_manager_t *hist)

Get current entry count.

Parameters:

hist – [in] Pointer to history manager

Returns:

Number of entries in history

const char *history_get_entry(const history_manager_t *hist, uint8_t index)

Get entry at index.

Parameters:

• hist – [in] Pointer to history manager

• index – [in] Index of entry (0 = most recent)

Returns:

Pointer to entry, or NULL if index out of range

void history_clear(history_manager_t *hist)

Clear all history.

Parameters:

hist – [inout] Pointer to history manager

bool history_is_browsing(const history_manager_t *hist)

Check if currently browsing history.

Parameters:

hist – [in] Pointer to history manager

Returns:

true if browsing history, false if at current input

struct history_manager_t

#include <shell_history.h>

History manager state structure.

Public Members

char **entries

Array of history entry pointers

uint16_t entry_size

Maximum size of each entry

uint8_t capacity

Maximum number of entries

uint8_t count

Current number of entries

uint8_t head

Index of newest entry (circular buffer)

int8_t browse_index

Current browse position (-1 = current input)

Autocomplete

shell_status_t autocomplete_init(void)

Initialize the auto-completion module.

Returns:

SHELL_OK on success

shell_status_t autocomplete_command(const char *partial, completion_result_t *result)

Find command completions for partial input.

Parameters:

• partial – [in] Partial command name to complete

• result – [out] Pointer to store completion results

Returns:

SHELL_OK on success

Returns:

SHELL_ERROR_INVALID_PARAM if partial or result is NULL

void autocomplete_show_matches(const completion_result_t *result)

Show all matching completions to the user.

Parameters:

result – [in] Pointer to completion results to display

int autocomplete_get_common_prefix(const completion_result_t *result, char *prefix, int prefix_size)

Get the common prefix from completion results.

Parameters:

• result – [in] Pointer to completion results

• prefix – [out] Buffer to store the common prefix

• prefix_size – [in] Size of the prefix buffer

Returns:

Length of the common prefix, or 0 if no common prefix

shell_status_t autocomplete_process(const char *input, int input_len, int cursor_pos, completion_result_t *result)

Process Tab key press for auto-completion.

Parameters:

• input – [in] Current input buffer

• input_len – [in] Length of current input

• cursor_pos – [in] Current cursor position

• result – [out] Pointer to store completion results

Returns:

SHELL_OK on success

Returns:

SHELL_ERROR_INVALID_PARAM if parameters are invalid

struct completion_result_t

#include <shell_autocomplete.h>

Auto-completion result structure.

Public Members

char matches[16][16 + 1]

Matching command names

int match_count

Number of matches found

int common_prefix_len

Length of common prefix

Parser

shell_status_t parse_command_line(char *line, parsed_command_t *result)

Parse a command line into command name and arguments.

Note

The line buffer is modified in place. The argv pointers point into the original line buffer.

Note

Empty lines result in argc=0 and cmd_name=NULL

Note

Unterminated quotes are handled gracefully (rest of string is argument)

Parameters:

• line – [inout] Input command line buffer (will be modified in place)

• result – [out] Output parsed command structure

Returns:

SHELL_OK on success

Returns:

SHELL_ERROR_INVALID_PARAM if line or result is NULL

Returns:

SHELL_ERROR_BUFFER_FULL if too many arguments (> SHELL_MAX_ARGS)

struct parsed_command_t

#include <shell_parser.h>

Parsed command structure.

Public Members

char *cmd_name

Command name (first token)

int argc

Argument count (including command name)

char *argv[8]

Argument array

Backend Interface

static const shell_backend_t *g_current_backend = NULL

Current backend pointer

shell_status_t shell_set_backend(const shell_backend_t *backend)

Set the Shell backend.

Parameters:

backend – [in] Pointer to backend interface structure

Returns:

SHELL_OK on success, error code otherwise

const shell_backend_t *shell_get_backend(void)

Get the current Shell backend.

Returns:

Pointer to current backend, or NULL if not set

int shell_printf(const char *format, ...)

Printf-style output to Shell.

Parameters:

• format – [in] Printf-style format string

• ... – [in] Format arguments

Returns:

Number of characters written, or negative on error

int shell_write(const uint8_t *data, int len)

Write raw data to Shell backend.

Parameters:

• data – [in] Data buffer to write

• len – [in] Number of bytes to write

Returns:

Number of bytes written

int shell_putchar(char c)

Write a single character to Shell backend.

Parameters:

c – [in] Character to write

Returns:

1 on success, 0 on failure

int shell_puts(const char *str)

Write a string to Shell backend.

Parameters:

str – [in] Null-terminated string to write

Returns:

Number of characters written

SHELL_PRINTF_BUFFER_SIZE

Printf buffer size

struct shell_backend_t

#include <shell_backend.h>

Shell backend interface structure.

Public Members

int (*read)(uint8_t *data, int max_len)

Non-blocking read function.

Param data:

[out] Buffer to store read data

Param max_len:

[in] Maximum number of bytes to read

Return:

Number of bytes actually read, 0 if no data available

int (*write)(const uint8_t *data, int len)

Blocking write function.

Param data:

[in] Data buffer to write

Param len:

[in] Number of bytes to write

Return:

Number of bytes actually written