Command Line Interpreter (xwsh) on XWOS

Core

Mon, 01 Jan 0001 00:00:00 +0000

Command Parsing Algorithm

XWSH uses the xwsh_split_cmdline() function (xwmd/cli/xwsh/core.c:126) to split a command line string into an argument array. The algorithm employs a single-pass strategy, modifying the input string in place to avoid additional memory allocation.

Algorithm Principle

xwer_t xwsh_split_cmdline(char * line, xwsz_t * argc, char * argv[], xwsz_t argvsize)
{
        char * p = line;
        xwsz_t count = 0;
        char * start = NULL;
        xwer_t rc = XWOK;

        while (*p) {
                if ((NULL == start) && (' ' == *p)) {
                        p++;  // Skip leading spaces
                } else {
                        if (NULL == start) {
                                start = p;  // Record argument start position
                        }
                        if (*p == ' ') {
                                if (count < argvsize) {
                                        *p = '\0';           // Terminate current argument
                                        argv[count] = start; // Save argument pointer
                                        count++;
                                } else {
                                        rc = -E2BIG;        // Too many arguments error
                                        break;
                                }
                                start = NULL;               // Reset start position
                        }
                        p++;
                }
        }
        // ... Handle the last argument
}

Algorithm Characteristics

Time complexity O(n): Only traverses the string once
In-place modification: Replaces spaces with \0, does not copy the string
Argument pointer array: The argv array stores pointers to parts of the original string
Error detection:
- Returns -E2BIG when argument count exceeds argvsize
- Maximum argument count: XWSH_MAX_PARAM_NUM (16)

Argument Format Limitations

No quote support: Cannot handle arguments with spaces (e.g. "file name")
Simple splitting: Splits only by spaces; consecutive spaces are treated as a single delimiter
Trailing spaces: Automatically ignores trailing spaces at the end of the command

Thread Model

XWSH provides two thread running modes to suit different application scenarios.

Command System

Mon, 01 Jan 0001 00:00:00 +0000

Command Structure

All XWSH commands are defined using the struct xwsh_cmd structure (xwmd/cli/xwsh/mi.h:21):

struct xwsh_cmd {
        char * name;                               /**< Command name */
        xwer_t (*func)(xwsz_t argc, char ** argv); /**< Command function */
        char * desc;                               /**< Command description */
};

Field Descriptions

Field	Type	Description
`name`	`char *`	Command name string (case-sensitive)
`func`	Function pointer	Command handler function, accepts argument count and array
`desc`	`char *`	Command description, displayed in help information

Command Handler Function Signature

xwer_t cmd_handler(xwsz_t argc, char ** argv);

argc: Number of arguments (including the command name itself, argv[0])
argv: Argument pointer array, each element points to a \0-terminated string
Return value: XWOK (0) indicates success, negative value indicates error code

Built-in Commands

XWSH has four built-in basic commands, defined in xwmd/cli/xwsh/cmd.c.

Extension

Mon, 01 Jan 0001 00:00:00 +0000

CherryRL Library Integration

XWSH uses the CherryRL library to provide professional command line editing features, including history, auto-completion, ANSI escape sequence processing, etc. The integration code is located in xwmd/cli/xwsh/readline.c.

CherryRL Instance

// readline.c:35-37
chry_readline_t xwsh_cherryrl;                    // CherryRL instance
char xwsh_cherryrl_prompt[XWSH_RL_PROMPT_MAXSIZE]; // Prompt buffer (64 bytes)
char xwsh_cherryrl_history[XWSH_RL_HISTORY_MAXSIZE]; // History buffer (1024 bytes)

Buffer size requirements:

History buffer size must be a power of 2 (1024 qualifies)
Prompt buffer should be large enough to hold a complete ANSI escape sequence

Initialization Process

The xwsh_cherryrl_init() function (readline.c:125) completes the following steps:

Integration Guide

Mon, 01 Jan 0001 00:00:00 +0000

Integration Mode Overview

XWSH provides two integration modes to suit different application scenarios and resource constraints. The choice depends on thread management requirements, resource availability, and system architecture.

Mode Comparison Matrix

Feature	Standalone Thread Mode (`xwsh_start()`)	Embedded Mode (`xwsh_init()` + `xwsh_loop()`)
Thread Resources	Requires dedicated stack space (1-2 KB)	Uses caller’s thread stack
Thread Management	XWSH internally creates and manages thread	User controls the loop call
Priority	`XWSH_THD_PRIORITY` (realtime priority downgrade)	Same as caller’s thread
Blocking Mode	Thread blocks in `xwsh_loop()`	Blocks in user’s loop
Freeze Support	Automatic thread freeze support	User needs to handle manually
Use Case	Standalone CLI task, system debugging	Integration into existing tasks, resource-constrained environments
Code Complexity	Low (automatic management)	Medium (user manages the loop)

Standalone Thread Mode

Working Principle

Standalone thread mode creates a dedicated thread to run XWSH, managed internally by the XWSH module.

API Reference

Mon, 01 Jan 0001 00:00:00 +0000

Overview

This document provides a complete reference for all API functions of the XWSH module. APIs are divided into two categories:

Public API: Declared in mi.h, used by module consumers
Internal API: Declared in core.h, used internally by the module or by advanced users

Public API

The public API provides the basic integration interface of the XWSH module, located in xwmd/cli/xwsh/mi.h.

Data Structures

`struct xwsh_cmd`

Command structure, used to define XWSH commands.