API Reference

All public types, functions, and macros defined in xelp.h. Version 0.3.3.

Types

Type	Description
`XELP`	Runtime instance of the interpreter. Holds all state.
`XELPRESULT`	Return type (`int`). 0 = OK, negative = error, positive = warning.
`XELPREG`	Register type (default `int`, overridable in xelpcfg.h).
`XELPKEYCODE`	Key code type (`unsigned long`). Single-char keys are their natural value; multi-byte ANSI sequences are packed little-endian.
`XelpBuf`	Buffer wrapper with start, position, and end pointers.
`XELPKeyFuncMapEntry`	Single-key command entry: `XELPRESULT fn(XELP *ths, XELPKEYCODE key)`, key code, help string.
`XELPCLIFuncMapEntry`	CLI command entry: `XELPRESULT fn(XELP ths, const char args, int len)`, command name, help string.

Return Codes

Constant	Value	Meaning
`XELP_S_OK`	0	Success
`XELP_W_WARN`	1	Warning (still success)
`XELP_S_NOTFOUND`	2	Token or command not found
`XELP_E_ERR`	-1	General error
`XELP_E_CMDBUFFULL`	-2	Command buffer full
`XELP_E_CMDNOTFOUND`	-3	Command not found during dispatch

XELP_T_OK(r) -- macro that returns true if r >= 0 (OK or warning).

Initialization

`XelpInit`

XELPRESULT XelpInit(XELP *ths, const char *pAboutMsg);

Initialize an XELP instance. Must be called before any other function. pAboutMsg is displayed at the start of help output.

Setup Macros

Macro	Purpose
`XELP_SET_FN_OUT(ths, fn)`	Set output function: `void fn(char)`
`XELP_SET_FN_ERR(ths, fn)`	Set error output function
`XELP_SET_FN_BKSP(ths, fn)`	Set backspace handler: `void fn(void)`
`XELP_SET_FN_THR(ths, fn)`	Set pass-through function
`XELP_SET_FN_EMCHG(ths, fn)`	Set mode-change callback: `void fn(int)`
`XELP_SET_FN_CLI(ths, tbl)`	Set CLI command table
`XELP_SET_FN_KEY(ths, tbl)`	Set KEY command table
`XELP_SET_FN_DEF_CLI(ths, fn)`	Set default CLI handler: called when no command matches
`XELP_SET_FN_DEF_KEY(ths, fn)`	Set default KEY handler: called when no key matches
`XELP_SET_VAL_CLI_PROMPT(ths, str)`	Set CLI prompt string (stored by pointer, must be null-terminated and remain valid)
`XELP_SET_ABOUT(ths, str)`	Change the about/help message (stored by pointer, must be null-terminated and remain valid)

Core Functions

`XelpParseKey`

XELPRESULT XelpParseKey(XELP *ths, char key);

Feed a single character from the input stream. This is the main entry point for interactive use. Call this for every character received from UART, keyboard, BLE, etc.

`XelpParse`

XELPRESULT XelpParse(XELP *ths, const char *buf, int blen);

Parse and execute a command string. Used for scripting -- pass a complete command or multi-statement script.

`XelpParseXB`

XELPRESULT XelpParseXB(XELP *ths, XelpBuf *script);

Same as XelpParse but takes a XelpBuf.

`XelpExecKC`

XELPRESULT XelpExecKC(XELP *ths, XELPKEYCODE key);

Execute a single-key command directly (bypasses mode checking).

`XelpOut`

XELPRESULT XelpOut(XELP *ths, const char *msg, int maxlen);

Output a string through the instance's output function. If maxlen > 0, prints at most that many characters. If maxlen <= 0, prints until null terminator.

`XelpPutc`

XELPRESULT XelpPutc(XELP *ths, char c);

Output a single character through the instance's output function. Respects mOutEnable (muted when disabled). Use this instead of XelpOut when emitting a single character.

`XelpHelp`

XELPRESULT XelpHelp(XELP *ths);

Print help listing all registered KEY and CLI commands. Only available when XELP_ENABLE_HELP is defined.

Tokenizer

`XelpTokLineXB`

XELPRESULT XelpTokLineXB(XelpBuf *buf, XelpBuf *tok, int srchType);

Get the next token or line from a buffer. srchType is XELP_TOK_ONLY (token) or XELP_TOK_LINE (full line).

`XelpTokN`

XELPRESULT XelpTokN(XelpBuf *buf, int n, XelpBuf *tok);

Get the Nth token (0-indexed) from a buffer.

`XelpNumToks`

XELPRESULT XelpNumToks(XelpBuf *buf, int *n);

Count the number of tokens in a buffer.

XelpArgs -- Sequential Argument Iterator

A left-to-right token iterator for CLI command handlers. Preferred over XelpTokN when arguments are processed sequentially (O(1) per token instead of O(n) re-scan).

`XelpArgsInit`

XELPRESULT XelpArgsInit(XelpArgs *a, const char *args, int len);

Initialize an argument iterator. args and len come directly from the CLI command callback parameters.

`XelpNextTok`

XELPRESULT XelpNextTok(XelpArgs *a, XelpBuf *tok);

Get the next token. On success, tok->s points to the first character and tok->p points one past the last. Pass NULL for tok to skip a token (useful for skipping the command name).

Returns XELP_S_OK on success, non-OK when no more tokens remain.

`XelpNextInt`

XELPRESULT XelpNextInt(XelpArgs *a, int *val);

Get the next token and parse it as an integer (decimal or hex).

`XelpArgCount`

XELPRESULT XelpArgCount(XelpArgs *a, int *n);

Count the total number of tokens without consuming them. The iteration position is preserved.

Example

XELPRESULT cmd_divmod(XELP *ths, const char *args, int len) {
    XelpArgs a;
    int dividend, divisor;
    XelpArgsInit(&a, args, len);
    XelpNextTok(&a, 0);              /* skip command name */
    XelpNextInt(&a, &dividend);
    XelpNextInt(&a, &divisor);
    if (divisor == 0) return XELP_E_ERR;
    ths->mR[1] = dividend / divisor;
    ths->mR[2] = dividend % divisor;
    return XELP_S_OK;
}

`XelpArgInt`

XELPRESULT XelpArgInt(const char *args, int len, int n, int *val);

Get argument n (0-indexed) and parse it as an integer in a single call. Wraps XelpTokN + XelpParseNum. Returns XELP_S_OK on success, XELP_E_ERR if the token does not exist or is not a valid number.

`XelpArgStr`

XELPRESULT XelpArgStr(const char *args, int len, int n,
                      const char **s, int *slen);

Get argument n (0-indexed) as a string span. On success, *s points to the first character of the token and *slen is its length. The token is NOT null-terminated. Returns XELP_S_OK on success, XELP_E_ERR if the token does not exist.

Example

XELPRESULT cmd_set(XELP *ths, const char *args, int len) {
    const char *key;
    int klen, value;
    XelpArgStr(args, len, 1, &key, &klen);  /* arg 1 = key name */
    XelpArgInt(args, len, 2, &value);        /* arg 2 = int value */
    /* ... use key/klen and value ... */
    return XELP_S_OK;
}

XelpBuf2Argv -- Structured argc/argv Parsing

Requires XELP_ENABLE_ARGV. Tokenizes a command line into a standard argc/argv array using ths->mArgvBuf as scratch. Strips quotes, processes escape sequences (via XELP_ESC_MAP), and null-terminates each token.

`XelpBuf2Argv`

XELPRESULT XelpBuf2Argv(XELP *ths, const char *args, int len,
                         int *argc, const char **argv, int maxargs);

Tokenize args into argv[0]..argv[argc-1]. argv[0] is the command name (per argc/argv convention). Returns XELP_E_ERR if input exceeds XELP_ARGVBUFSZ or there are more than maxargs tokens.

`XELP_PARSE_ARGV`

XELP_PARSE_ARGV(ths, args, len);

Convenience macro (C99+ / C++). Declares const char *argv[XELP_ARGV_MAX] and int argc, calls XelpBuf2Argv, and returns XELP_E_ERR on failure. Place at the top of a command handler body, before other statements.

`XelpArgvInt`

XELPRESULT XelpArgvInt(const char **argv, int argc, int n, int *val);

Get argv[n] as an integer. Returns XELP_E_ERR if out of range or not a valid number.

`XelpArgvStr`

XELPRESULT XelpArgvStr(const char **argv, int argc, int n,
                        const char **s, int *slen);

Get argv[n] as a string pointer and length. Returns XELP_E_ERR if out of range.

Example

XELPRESULT cmd_set(XELP *ths, const char *args, int len) {
    XELP_PARSE_ARGV(ths, args, len);
    /* argv[0] = "set", argv[1] = key, argv[2] = value */
    int val;
    if (XelpArgvInt(argv, argc, 2, &val) != XELP_S_OK)
        return XELP_E_ERR;
    /* ... use argv[1] and val ... */
    return XELP_S_OK;
}

Which argument API to use

Situation	Recommended
C handler, multiple args	`XELP_PARSE_ARGV` + `XelpArgvInt`/`XelpArgvStr`
C++ Easy API lambda	Auto-argv built-in + `XelpCLI::argInt`/`argStr`
Minimal code size, left-to-right	`XelpArgs` iterator
Quick single-arg access	`XelpArgInt`/`XelpArgStr`

String Utilities

`XelpStrLen`

int XelpStrLen(const char *c);

Compute length of a null-terminated string. No stdlib dependency.

`XelpStrEq`

XELPRESULT XelpStrEq(const char *pbuf, int blen, const char *cmd);

Compare a buffer of length blen against a null-terminated string cmd. Returns XELP_S_OK if equal.

`XelpStr2Int`

int XelpStr2Int(const char *s, int maxlen);

Parse a string to integer. Accepts decimal and hex (FFh suffix or 0xFF prefix). Supports uppercase and lowercase hex digits.

`XelpParseNum`

XELPRESULT XelpParseNum(const char *s, int maxlen, int *n);

Safer string-to-integer: returns a result code and writes the parsed value to *n.

`XelpBufCmp`

XELPRESULT XelpBufCmp(const char *as, const char *ae,
                      const char *bs, const char *be, int cmpType);

Compare two buffers. cmpType controls null-terminator handling:

XELP_CMP_TYPE_BUF (0x00) -- pure byte comparison by length
XELP_CMP_TYPE_A0 (0x01) -- buffer A also terminates on \0
XELP_CMP_TYPE_A0B0 (0x11) -- both buffers terminate on \0

XelpBuf Macros

Macro	Purpose
`XELP_XB_INIT(xb, buf, len)`	Initialize from pointer + length
`XELP_XB_INIT_PTRS(xb, s, p, e)`	Initialize from three pointers
`XELP_XB_INIT_BP(xb, buf, pos, len)`	Initialize with cursor position
`XELP_XB_COPY(a, b)`	Copy XelpBuf a to b
`XELP_XB_LEN(xb)`	Total buffer length
`XELP_XB_POS(xb)`	Current position as int offset
`XELP_XB_PUTC(xb, ch)`	Write char with bounds check
`XELP_XB_GETC(xb, ch)`	Read char and advance position
`XELP_XB_TOP(xb)`	Reset position to start
`XELP_XB_OUT(x, xb)`	Print XelpBuf contents from current position

Registers

Each XELP instance contains an array of XELPREG (default int) registers used to pass return values between the engine and command handlers.

XELP_REGS_SZ -- register count (default 4, minimum 4).
XELPREG -- register type (default int, overridable in xelpcfg.h).
Convention: callee-clobbers-all -- any command call may overwrite all registers. Do not rely on values persisting across calls.

Macro	Description
`XELP_R0(ths)`	Command status (written by engine after dispatch). Read-only by convention.
`XELP_R1(ths)`	Command-specific return value 1 (engine never touches).
`XELP_R2(ths)`	Command-specific return value 2 (engine never touches).
`XELP_R3(ths)`	Command-specific return value 3 (engine never touches).

ths is a struct (not a pointer). For pointer access inside command handlers, use ths->mR[1] directly.

Example: command returning multiple values

XELPRESULT cmd_divmod(XELP *ths, const char *args, int len) {
    int a = 17, b = 5;
    ths->mR[1] = a / b;  /* quotient  -> R1 */
    ths->mR[2] = a % b;  /* remainder -> R2 */
    return XELP_S_OK;    /* engine writes R0 */
}

/* caller reads results via macros */
XELP_R1(cli)  /* 3 */
XELP_R2(cli)  /* 2 */

Multi-byte Key Codes

XELPKEYCODE constants for ANSI escape sequences. Packed little-endian: byte[0] in bits 0-7, byte[1] in 8-15, etc. Single-char keys are their natural value (e.g. 'a' == 0x61). Multi-byte keys are >= 0x100.

Constant	Value	Sequence
`XELP_KEYCODE_UP`	`0x00415B1BUL`	ESC [ A
`XELP_KEYCODE_DOWN`	`0x00425B1BUL`	ESC [ B
`XELP_KEYCODE_RIGHT`	`0x00435B1BUL`	ESC [ C
`XELP_KEYCODE_LEFT`	`0x00445B1BUL`	ESC [ D
`XELP_KEYCODE_HOME`	`0x00485B1BUL`	ESC [ H
`XELP_KEYCODE_END`	`0x00465B1BUL`	ESC [ F
`XELP_KEYCODE_INS`	`0x7E325B1BUL`	ESC [ 2 ~
`XELP_KEYCODE_KDEL`	`0x7E335B1BUL`	ESC [ 3 ~
`XELP_KEYCODE_PGUP`	`0x7E355B1BUL`	ESC [ 5 ~
`XELP_KEYCODE_PGDN`	`0x7E365B1BUL`	ESC [ 6 ~

Key code accessor macros

Macro	Description
`XELP_KC_B0(k)`	Extract byte 0 (bits 0-7)
`XELP_KC_B1(k)`	Extract byte 1 (bits 8-15)
`XELP_KC_B2(k)`	Extract byte 2 (bits 16-23)
`XELP_KC_B3(k)`	Extract byte 3 (bits 24-31)
`XELP_KC_IS_MULTI(k)`	True if key code is multi-byte (>= 0x100)

Constants

Constant	Value	Description
`XELP_VERSION`	0x00000303	Library version (32-bit hex: `0x00MMmmpp`)
`XELP_VER_MAJOR(v)`		Extract major version byte
`XELP_VER_MINOR(v)`		Extract minor version byte
`XELP_VER_PATCH(v)`		Extract patch version byte
`XELP_CMDBUFSZ`	64	CLI input buffer size
`XELP_ARGVBUFSZ`	`XELP_CMDBUFSZ`	Scratch buffer size for `XelpBuf2Argv`
`XELP_ARGV_MAX`	8	Default max arguments for `XelpBuf2Argv` / `XELP_PARSE_ARGV`
`XELP_ENTER_LF`	1	Accept `\n` (0x0A) as ENTER in interactive input
`XELP_ENTER_CR`	1	Accept `\r` (0x0D) as ENTER in interactive input
`XELP_ESC_MAP`	`"n\x0A" "t\x09" ""`	Escape expansion table for quoted strings in `XelpBuf2Argv`
`XELP_MODE_CLI`	0x00	CLI mode identifier
`XELP_MODE_KEY`	0x01	KEY mode identifier
`XELP_MODE_THR`	0x02	THRU mode identifier
`XELP_ECHO_NORMAL`	`'\0'`	Echo typed character as-is (default)
`XELP_ECHO_OFF`	`'\1'`	Suppress character echo entirely

Build Profiles

xelp is modular -- enable only what you need. Sizes shown for ARM Cortex-M0 (Thumb, -Os):

Profile	.text (bytes)	Flags
KEY only	532	`XELP_ENABLE_KEY`
CLI only	1512	`XELP_ENABLE_CLI`
CLI + help	1612	+ `XELP_ENABLE_HELP`
CLI + key	1616	+ `XELP_ENABLE_KEY`
CLI + help + key	1990	+ both
CLI + help + key + thru	2030	+ `XELP_ENABLE_THR`
CLI + line edit	1956	+ `XELP_ENABLE_LINE_EDIT`
CLI + LE + help	2052	+ `XELP_ENABLE_HELP`
CLI + LE + help + key	2470	+ `XELP_ENABLE_KEY`
Full	2510	+ `XELP_ENABLE_THR`
Full + argv	2855	+ `XELP_ENABLE_ARGV`
Full + history	2926	+ `XELP_ENABLE_HISTORY`
Full + argv + history	3275	+ both

Use dev/size_profiles.sh to regenerate this table for your toolchain.

Output Control

Two independent mechanisms control what an XELP instance sends to its output function:

Output Enable (`mOutEnable`)

Gates all output: XelpOut, help, prompt, character echo, and redraw. Useful for silent scripting or batch mode.

Macro	Description
`XELP_SET_OUT_ENABLE(ths, val)`	Set output enable: 0 = mute, nonzero = normal
`XELP_GET_OUT_ENABLE(ths)`	Read current output-enable state

Default after XelpInit: 1 (enabled).

Echo Control (`mEchoChar`)

Controls how printable characters are echoed during interactive input. Does not affect XelpOut calls from commands, ENTER newline echo, cursor movement, or prompt output.

Macro	Description
`XELP_SET_ECHO(ths, ch)`	Set echo mode: `XELP_ECHO_NORMAL`, `XELP_ECHO_OFF`, or a mask character
`XELP_GET_ECHO(ths)`	Read current echo character

Values:

XELP_ECHO_NORMAL ('\0') -- echo the typed character (default)
XELP_ECHO_OFF ('\1') -- suppress echo entirely
Any other character (e.g. '*') -- echo that character instead

Default after XelpInit: XELP_ECHO_NORMAL.

Password Entry Example

XELPRESULT cmd_pass(XELP *ths, const char *args, int len) {
    XELP_SET_ECHO(*ths, '*');       /* mask input */
    /* ... user types password, sees ****** ... */
    /* on ENTER, read buffer, then: */
    XELP_SET_ECHO(*ths, XELP_ECHO_NORMAL);  /* restore */
    return XELP_S_OK;
}

FilesExpand file tree

api-reference.md

Latest commit

History

api-reference.md

File metadata and controls

API Reference

Types

Return Codes

Initialization

XelpInit

Setup Macros

Core Functions

XelpParseKey

XelpParse

XelpParseXB

XelpExecKC

XelpOut

XelpPutc

XelpHelp

Tokenizer

XelpTokLineXB

XelpTokN

XelpNumToks

XelpArgs -- Sequential Argument Iterator

XelpArgsInit

XelpNextTok

XelpNextInt

XelpArgCount

Example

XelpArgInt

XelpArgStr

Example

XelpBuf2Argv -- Structured argc/argv Parsing

XelpBuf2Argv

XELP_PARSE_ARGV

XelpArgvInt

XelpArgvStr

Example

Which argument API to use

String Utilities

XelpStrLen

XelpStrEq

XelpStr2Int

XelpParseNum

XelpBufCmp

XelpBuf Macros

Registers

Example: command returning multiple values

Multi-byte Key Codes

Key code accessor macros

Constants

Build Profiles

Output Control

Output Enable (mOutEnable)

Echo Control (mEchoChar)

Password Entry Example

`XelpInit`

`XelpParseKey`

`XelpParse`

`XelpParseXB`

`XelpExecKC`

`XelpOut`

`XelpPutc`

`XelpHelp`

`XelpTokLineXB`

`XelpTokN`

`XelpNumToks`

`XelpArgsInit`

`XelpNextTok`

`XelpNextInt`

`XelpArgCount`

`XelpArgInt`

`XelpArgStr`

`XelpBuf2Argv`

`XELP_PARSE_ARGV`

`XelpArgvInt`

`XelpArgvStr`

`XelpStrLen`

`XelpStrEq`

`XelpStr2Int`

`XelpParseNum`

`XelpBufCmp`

Output Enable (`mOutEnable`)

Echo Control (`mEchoChar`)