dpse / tcli

Tiny command line interface for embedded systems

TinyCLI

TinyCLI is a command line interface for embedded systems that is intended to be very easy to use. Typical applications would e.g. be to provide a simple CLI over a serial line or over a Telnet connection.

Features

• No dynamic allocations.
• Configurable prompt(s).
• Output buffering.
• Command history in ringbuffer.
• Backwards history search.
• Tab-completion.
• Custom SIGINT handler.
• Functions for printing e.g. log data without disturbing the prompt.

History and output buffering can be disabled to reduce memory requirements for use on smaller systems.

Wrapper Extensions (tclie)

• Extension functions for automatic handling of users, commands and tab-completion.
• Optional pattern matching system:
  • Automatic validation of command syntax and command options.
  • Context-sensitive tab-completion.
• Default commands (help, clear, login, and logout)

Users can be registered so that only certain commands are available to certain users. Login is possible with either password only or with usernames and optional passwords. Only users with a level matching the minimum required level for a command can execute the command.

Commands are registered with a command, the minimum user level required (if users are enabled), a description, and optionally a pattern with some options (if pattern matching is enabled). The description along with any pattern and options (if used) are automatically printed when the built-in help command is called.

Pattern Matching

The following syntax can be used in patterns:

Pattern	Description
abc	Matches abc.
"a b" or 'a b'	Matches a b including whitespace.
[abc]	Optionally matches abc.
a|b|cd	Matches a, b or cd.
<abc>	Wildcard; matches any word.
[<abc>]	Optional wildcard; optionally matches any word.
a|(b c) or a|{b c}	Matches a or b c.
...	Matches none or all remaining tokens.

• The pattern matching system currently only supports matching word-tokens (i.e. no matches inside words).
• The pattern matcher is recursive and stack requirements will increase with pattern complexity.

Usage

1. Define output function and initialize:

#include "tclie.h"

void output(void * arg, const char * str)
{
    printf("%s", str); // Or send through serial interface
}

tclie_t tclie;
tclie_init(&tclie, output, NULL);

2. Register user table (if needed):

static const tclie_user_t users[] = {
    // Name,  password, level
    {"debug", NULL,     1}, // No password required
    {"admin", "12345",  2}
};

tclie_reg_users(&tclie, users, 2);

3. Register command table:

int echo(void * arg, int argc, const char ** argv)
{
    if(argc > 1)
        printf("%s\r\n", argv[1]);
    
    return 0;
}

static const tclie_cmd_t cmds[] = {
    // Name, callback, minimum user level, description (for help)    
    {"echo", echo, 1, "Echo input."}
};

tclie_reg_cmds(&tclie, cmds, 1);

4. Feed input characters:

while (1) {
    char c = getchar(); // Read e.g. serial input
    tclie_input_char(&tclie, c);
}

See the examples directory for more details.

Logging

In a multithreaded environment it can be useful to be able to log stuff without disturbing the prompt:

tclie_log(&tclie, "Some message...\r\n");

char buf[64];
tclie_log_printf(&tclie, buf, sizeof(buf), "Hello %s\r\n", "world!");

Supported Keyboard Shortcuts

Shortcut	Description
Ctrl+a	Move cursor to line start.
Ctrl+b	Move cursor back one character.
Ctrl+c	Sends SIGINT to registred handler.
Ctrl+d	Delete current character.
Ctrl+e	Move cursor to line end.
Ctrl+f	Move cursor forward one character.
Ctrl+g	Exit reverse search mode.
Ctrl+h	Delete previous character.
Ctrl+i	Equivalent to the tab key.
Ctrl+j	Equivalent to the enter key.
Ctrl+k	Clear line after cursor.
Ctrl+l	Clear screen content.
Ctrl+n	Recall next command.
Ctrl+p	Recall previous command.
Ctrl+r	Reverse search through command history.
Ctrl+u	Clear line before cursor.
Ctrl+w	Clear word before cursor.
Alt+b	Move cursor backward one word.
Alt+d	Delete word after cursor.
Alt+f	Move cursor forward one word.
Alt+r	Cancel changes to history line.
Tab	Tab-complete at cursor or select from multiple matches.
Esc	Exit tab-completion or reverse search mode.

Note! Esc needs to be pressed twice since it is impossible to differentiate from an escape sequence otherwise.

Miscellaneous

Telnet

Telnet newlines (<CR><NUL>) are automatically handled but it may be necessary to tell connecting clients (e.g. PuTTY) how to behave. This can be done by sending the following sequences to the client:

• IAC DO ECHO: Tell client to echo received characters from server.
• IAC WILL ECHO: Tell client that the server will echo back received characters.
• IAC DO SUPPRESS-GO-AHEAD: Tell client to not send GO AHEAD when transmitting.
• IAC WILL SUPPRESS-GO-AHEAD: Tell client that the server won't send GO AHEAD when transmitting.

const char options[] = {255, 253, 1,  // IAC DO ECHO
                        255, 251, 1,  // IAC WILL ECHO
                        255, 253, 3,  // IAC DO SUPPRESS-GO-AHEAD
                        255, 251, 3}; // IAC WILL SUPPRESS-GO-AHEAD

tcli's Issues

tclie_pattern_match: Add missing #if TCLI_COMPLETE

Add missing TCLI_COMPLETE preprocessor barrier:

diff -u a/source/tclie.c b/source/tclie.c
--- a/source/tclie.c    2022-09-20 15:36:47.499476363 -0400
+++ b/source/tclie.c    2022-09-20 15:37:59.739855525 -0400
@@ -645,8 +645,10 @@ static bool tclie_pattern_match(tclie_t
    };
 
    const bool matches = tclie_pattern_match_token(&token, &p);
+#if TCLI_COMPLETE
    if (arg_index != 0)
        tclie_pattern_match_complete_options(&p);
+#endif
    return matches && arg_index == argc;
 }
 #endif

config structs: Pointers to inviolate strings should be 'const char *', not 'char *'

Pointers to strings that will not be modified by the library should be const char *, not char *.

Notably: tclie_cmd_t's name & desc fields, and tclie_user_t's name and password fields.

This is very important in embedded systems, as const char * strings can be allocated in ROM, saving precious RAM.

'compl' is a reserved keyword in C++.

compl is a reserved keyword in C++, it should not be used in .h files.

https://en.cppreference.com/w/cpp/keyword/compl

Add examples for embedded systems

feature request: pattern matched commands

A feature I've used in past embedded CLI systems was a regularly formed syntax for the command usage description, which the command parser used to determine the validity of arguments.

Here's some examples of the 'usage descriptions':

Description	Comment
reset	Single word command, must match exactly.
config save	Two word command, spaces around the words are ignored.
can speed <rate>	Two word command, with mandatory argument.
set <attr> [value]	One word command, with mandatory and optional argument.
echo ...	One word command, with arbitrary number of arguments.
<reg> = <value>	One word command ('=') embedded between mandatory arguments.
when <reg> is <value> echo ...	Three word command, with two mandatory arguments and arbitrary optional.

The command handler worked just as yours does now, passing in all words in the argument as argc, argv.

The improvements over what you have now is:

• Encourgaing usage document strings along with description
• min_args/max_args can go away (determined when matching the input against the usage string)
• Supports commands embedded between arguments (ie the <reg> = <value> case)

add instance pointer to callbacks

Reverse search should support navigation

tcli_out()/tcli_flush()/tcli_clear_screen() - should be exported functions.

The following functions are very useful to have exported outside the library, when using a raw UART for output from a command:

void tcli_clear_screen(tcli_t *tcli);

void tcli_out(tcli_t *tcli, const char *str);
void tcli_flush(tcli_t *tcli);

config structs: struct typedef should not itself be 'const'

The typedef for a struct should not itself be 'const', ie:

This is bad:

typedef const struct foo_s {
} foo_t;

This is preferred:

typedef struct foo_s {
} foo_t;

Rationale is that with the former, it is not possible to dynamically construct command definitions at runtime.

Add notes on Telnet IAC

tclie_pattern_compare: Do not assume all strings have unique storage.

The assert(target != subject) in tclie_pattern_compare() fails on systems when the compiler optimizes const char * strings that have the same content to the same memory location (ie GCC optimization level -Os or -fmerge-constants).

If two pointers are equal, then by definition the strings are the same. Return true instead of assert.

Suggested patch:

diff -u a/source/tclie.c b/source/tclie.c
--- a/source/tclie.c    2022-09-20 15:36:47.499476363 -0400
+++ b/source/tclie.c    2022-09-20 15:37:59.739855525 -0400
@@ -112,7 +112,10 @@ static bool tclie_pattern_compare(const
 {
    assert(target);
    assert(subject);
-   assert(target != subject);
+
+   if (target == subject) {
+       return true;
+    }
 
    while (target_len != 0 && *target != '\0' && *subject != '\0') {
        if (*target++ != *subject++)

Make pattern matcher less greedy

By e.g. building whole token tree before matching.

Add possiblity to save/restore history

input_str doesn't increment string pointer

tclie_init(): Output function gets &tclie_t, not arg as expected.

When using tclie_init(&tclie, output_fn, output_fn_arg), the output function is being called with &tclie instead of arg.

Is this expected?

When using tcli_init(&tcli, output_fn, output_fn_arg), the output function is called with output_fn_arg, as I would expect.

Release tag?

Could you tag a commit you are particularly happy with to make a release?