API Reference

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

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_VAL_CLI_PROMPT(ths, str)`	Set CLI prompt string
`XELP_SET_ABOUT(ths, str)`	Change the about/help message

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.

`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. O(1) per token.

`XelpArgsInit`

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

Initialize an argument iterator from the callback’s args and len.

`XelpNextTok`

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

Get the next token. Pass NULL for tok to skip.

`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 total tokens without consuming them.

Direct Argument Access

`XelpArgInt`

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

Get argument n (0-indexed) as an integer in one call. Wraps XelpTokN + XelpParseNum.

`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 token and *slen is its length. Not null-terminated.

`XelpPutc`

XELPRESULT XelpPutc(XELP *ths, char c);

Output a single character through the instance’s output function. Respects mOutEnable.

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).

`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_TOP(xb)`	Reset position to start

Registers

Each XELP instance contains an array of XELPREG (default int) registers used to pass return values between the engine and command handlers. Convention: callee-clobbers-all — any command call may overwrite all registers.

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.

Constants

Constant	Value	Description
`XELP_VERSION`	0x00000302	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	Default command buffer size
`XELP_MODE_CLI`	0x00	CLI mode identifier
`XELP_MODE_KEY`	0x01	KEY mode identifier
`XELP_MODE_THR`	0x02	THRU mode identifier