cli.c

/**
 * Simple Command Line Interface (CLI) driver.
 * Features:
 * - Single- and double-quoting
 * - Command line history
 * - Auto-complete
 * - UTF-8 support
 *
 * URL: <https://github.com/erkia/cli>
 *
 * Copyright (C) 2016 Erki Aring
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */

#include <stdlib.h>
#include <string.h>
#include <unistd.h>

#include "cli.h"


#define CLI_LINE_BUFSIZE 32 /**< Maximum length of the command line that can be handled */
#define CLI_ARGV_LEN 11 /**< Maximum number of allowed arguments, including command name */
#define CLI_HISTORY 8 /**< Number of command lines to remember */
#define CLI_HIST_IGNORE_DUP (1 << 0) /**< Flag to indicate, that duplicate entry should be discarded */
#define CLI_HIST_TEMPORARY (1 << 1) /**< Flag to indicate, that entry is temporary */
#define CLI_HIST_DIRTY (1 << 2) /**< Flag to indicate, that command line is modified */
#define CLI_HIST_CLEAR (1 << 3) /**< Flag to indicate, that history should be cleared */


#if (CLI_HISTORY > 0)
 #define CLI_HAS_HISTORY /**< If defined, history functionality is included */
#endif

#define CLI_HAS_AUTOCOMPLETE /**< If defined, auto-complete functionality is included */


/**
 * A structure containing information about the current command line.
 */
typedef struct {
 char buf[CLI_LINE_BUFSIZE];
 size_t len;
 uint8_t ready;
} cli_line_t;


/**
 * A structure containing information about the command line history.
 */
typedef struct {
 char lines[CLI_HISTORY][CLI_LINE_BUFSIZE];
 size_t pos;
 size_t len;
 int flags;
} cli_history_t;


/**
 * A structure containing the state of the driver
 */
typedef struct {
 cli_line_t line;
#ifdef CLI_HAS_HISTORY
 cli_history_t history;
#endif
 const cli_cmd_list_t *cmdlist;
 uint8_t utf8_enabled;
} cli_control_t;


static cli_control_t _CliCtrl;
static cli_control_t *CliCtrl = &_CliCtrl;


static void CLI_AddChar (char c);
static void CLI_DelChar (void);


/**
 * Write a buffer to the standard output.
 *
 * @param buf Buffer
 * @param len Length of the buffer
 *
 * @return Number of bytes written
 */
static int CLI_Write (const void *buf, size_t len)
{
 return write (1, buf, len);
}


/**
 * Write a string to the standard output.
 *
 * @param str Null-terminated string
 *
 * @return Number of bytes written
 */
static int CLI_WriteStr (const char *str)
{
 return CLI_Write (str, strlen (str));
}


/**
 * Write out command prompt and current command.
 */
static void CLI_Prompt (void)
{
 CLI_WriteStr ("\r\ncli> ");
 CLI_Write (CliCtrl->line.buf, CliCtrl->line.len);
}


/**
 * Erase the old command and replace it with a new one.
 *
 * @param line Command
 * @param len Length of the command
 */
static void CLI_ReplaceCmd (const char *line, size_t len)
{
 if (len < CLI_LINE_BUFSIZE) {

 // Clear the old command
 while (CliCtrl->line.len > 0){
 CLI_DelChar ();
 }

 // Load the command from history
 strncpy (CliCtrl->line.buf, line, len);
 CliCtrl->line.buf[len] = '\0';
 CliCtrl->line.len = len;

 // Write the new command
 CLI_Write (CliCtrl->line.buf, CliCtrl->line.len);

 }
}


#ifdef CLI_HAS_AUTOCOMPLETE

/**
 * Auto-complete a command or print out possible completions in case of ambiguity
 *
 * @param tab_count Number of times the tab is pressed consequently (counting from '0')
 */
static void CLI_AutoComplete (int tab_count)
{
 size_t i;
 int found = 0;

 if (CliCtrl->cmdlist != NULL) {

 // Find all matches
 for (i = 0; i < CliCtrl->cmdlist->count; i++) {
 if (!strncmp (CliCtrl->line.buf, CliCtrl->cmdlist->commands[i].name, CliCtrl->line.len)) {
 found++;
 }
 }

 if (found == 1) {
 // One match found - use it for auto-completion
 for (i = 0; i < CliCtrl->cmdlist->count; i++) {
 if (!strncmp (CliCtrl->line.buf, CliCtrl->cmdlist->commands[i].name, CliCtrl->line.len)) {
 CLI_ReplaceCmd (CliCtrl->cmdlist->commands[i].name, strlen (CliCtrl->cmdlist->commands[i].name));
 CLI_AddChar (' ');
 }
 }
 } else if (found > 1) {
 // Multiple matches found - print out all possible completions on every second tab-press
 if (tab_count % 2) {
 for (i = 0; i < CliCtrl->cmdlist->count; i++) {
 if (!strncmp (CliCtrl->line.buf, CliCtrl->cmdlist->commands[i].name, CliCtrl->line.len)) {
 CLI_WriteStr ("\r\n");
 CLI_WriteStr (CliCtrl->cmdlist->commands[i].name);
 }
 }
 CLI_Prompt ();
 }
 }
 }
}

#endif


#ifdef CLI_HAS_HISTORY

/**
 * Set history related flags.
 *
 * @param flags Bitmask of flags to set
 */
static void CLI_HistorySetFlags (int flags)
{
 CliCtrl->history.flags |= flags;
}


/**
 * Clear history related flags.
 *
 * @param flags Bitmask of flags to clear
 */
static void CLI_HistoryClearFlags (int flags)
{
 CliCtrl->history.flags &= ~flags;
}


/**
 * Add a command to the history.
 *
 * @param flags Bitmask of flags
 */
static void CLI_HistoryAdd (int flags)
{
 size_t i;
 int last_non_temp;

 // Ignore duplicates
 if (flags & CLI_HIST_IGNORE_DUP) {
 last_non_temp = CliCtrl->history.len - 1;
 if (CliCtrl->history.flags & CLI_HIST_TEMPORARY) {
 last_non_temp--;
 }
 if (last_non_temp >= 0) {
 if (strncmp (CliCtrl->history.lines[last_non_temp], CliCtrl->line.buf, CLI_LINE_BUFSIZE) == 0) {
 if (CliCtrl->history.flags & CLI_HIST_TEMPORARY) {
 CliCtrl->history.len--;
 CLI_HistoryClearFlags (CLI_HIST_TEMPORARY);
 }
 CliCtrl->history.pos = CliCtrl->history.len;
 return;
 }
 }
 }

 // Find a place in history to add the new line
 if (CliCtrl->history.flags & CLI_HIST_TEMPORARY) {
 // Last entry is temporary, reuse it
 if (CliCtrl->history.len > 0) {
 CliCtrl->history.len--;
 }
 } else {
 // If history is full, shift and make room
 if (CliCtrl->history.len >= CLI_HISTORY) {
 for (i = 0; i < CLI_HISTORY - 1; i++) {
 strncpy (CliCtrl->history.lines[i], CliCtrl->history.lines[i + 1], CLI_LINE_BUFSIZE);
 }
 CliCtrl->history.len = CLI_HISTORY - 1;
 }
 }

 // Add current line to the last position in history
 strncpy (CliCtrl->history.lines[CliCtrl->history.len], CliCtrl->line.buf, CLI_LINE_BUFSIZE);
 CliCtrl->history.len++;
 CliCtrl->history.pos = CliCtrl->history.len;

 // Remember the 'temporary' flag
 if (flags & CLI_HIST_TEMPORARY) {
 CLI_HistorySetFlags (CLI_HIST_TEMPORARY);
 } else {
 CLI_HistoryClearFlags (CLI_HIST_TEMPORARY);
 }
}


/**
 * Fetch a command from the history and place it on the command line.
 *
 * @param step Direction to step in history
 */
static void CLI_HistoryFetch (int step)
{
 char *line;
 int pos;

 // If line buffer is modified, add it as a temporary entry to the history
 if (CliCtrl->history.flags & CLI_HIST_DIRTY) {
 if (CliCtrl->line.len < CLI_LINE_BUFSIZE) {
 CliCtrl->line.buf[CliCtrl->line.len] = '\0';
 CLI_HistoryAdd (CLI_HIST_TEMPORARY);
 CliCtrl->history.pos--;
 }
 CLI_HistoryClearFlags (CLI_HIST_DIRTY);
 }

 // Walk the history
 pos = CliCtrl->history.pos;
 pos += step;
 if (pos < 0) {
 pos = 0;
 } else if (pos > (CliCtrl->history.len - 1)) {
 pos = (CliCtrl->history.len - 1);
 }
 CliCtrl->history.pos = pos;

 // Load the command from history
 line = CliCtrl->history.lines[CliCtrl->history.pos];
 CLI_ReplaceCmd (line, strlen (line));
}


/**
 * Marks history to be cleared in the next call to CLI_Parse().
 */
void CLI_HistoryClear (void)
{
 CLI_HistorySetFlags (CLI_HIST_CLEAR);
}

#endif // CLI_HAS_HISTORY


/**
 * Execute a command with given arguments.
 *
 * @param argc Number of arguments in argv
 * @param argv Arguments, first argument is command name
 *
 * @return Result returned by the command or '127' in case command is not found
 */
static int CLI_Exec (int argc, char **argv)
{
 size_t i;

 CLI_WriteStr ("\r\n");

 if (CliCtrl->cmdlist != NULL) {
 for (i = 0; i < CliCtrl->cmdlist->count; i++) {
 if (!strcmp (argv[0], CliCtrl->cmdlist->commands[i].name)) {
 return CliCtrl->cmdlist->commands[i].callback (argc, argv);
 }
 }
 }

 CLI_WriteStr ("CLI_Exec: ");
 CLI_WriteStr (argv[0]);
 CLI_WriteStr (": command not found");

 return 127;
}


/**
 * Handle special keys (command line sequences)
 *
 * @param cmd Command identifier
 */
static void CLI_HandleCSI (uint8_t cmd)
{
 switch (cmd) {
 case 'A':
 // UP
#ifdef CLI_HAS_HISTORY
 CLI_HistoryFetch (-1);
#endif
 break;
 case 'B':
 // DOWN
#ifdef CLI_HAS_HISTORY
 CLI_HistoryFetch (1);
#endif
 break;
 case 'C':
 // RIGHT
 break;
 case 'D':
 // LEFT
 break;
 }
}


/**
 * Add a character to the command line.
 *
 * @param c Character to add
 */
static void CLI_AddChar (char c)
{
 uint8_t bits;

 if (CliCtrl->line.len < CLI_LINE_BUFSIZE) {

 // Add the byte to the command buffer
 CliCtrl->line.buf[CliCtrl->line.len] = c;
 CliCtrl->line.len++;

#ifdef CLI_HAS_HISTORY
 CLI_HistorySetFlags (CLI_HIST_DIRTY);
#endif

 } else {

 // If it doesn't fit into buffer, then only count code points
 bits = (c & 0xC0);
 if (!CliCtrl->utf8_enabled || (bits != 0x80)) {
 CliCtrl->line.len++;
 }

 }

 CLI_Write (&c, 1);
}


/**
 * Delete a character from the command line.
 */
static void CLI_DelChar (void)
{
 uint8_t bits;

 if (CliCtrl->line.len > 0) {

 CLI_WriteStr ("\x08 \x08");

 // Remove the whole code point from the buffer -
 // no code point validation is done
 while (CliCtrl->line.len > 0) {
 CliCtrl->line.len--;
 if (CliCtrl->line.len < CLI_LINE_BUFSIZE) {
 bits = (CliCtrl->line.buf[CliCtrl->line.len] & 0xC0);
 if (!CliCtrl->utf8_enabled || (bits != 0x80)) {
 break;
 }
 } else {
 break;
 }
 }

 }
}


/**
 * Parse incoming data and control the command line interface.
 *
 * @param ptr Buffer of incoming data
 * @param len Length of the buffer
 *
 * @return Number of bytes parsed before the end of the buffer or the end
 * of the current command was reached
 */
int CLI_Parse (const char *ptr, size_t len)
{
 static uint8_t ignore_next_newline = 0;
 static uint8_t esc = 0;
 static uint8_t tab = 0;

 size_t i;

 // If CLI_Parse() is called before previous line is handled then drop it
 if (CliCtrl->line.ready) {
 CliCtrl->line.len = 0;
 CliCtrl->line.ready = 0;
 }

#ifdef CLI_HAS_HISTORY
 // If CLI_HIST_CLEAR is set, then clear the history now
 if (CliCtrl->history.flags & CLI_HIST_CLEAR) {
 memset (&(CliCtrl->history), 0, sizeof (cli_history_t));
 CLI_HistoryClearFlags (CLI_HIST_CLEAR);
 }
#endif

 for (i = 0; i < len; i++) {

 // ANSI escape code
 if (esc) {
 if (esc == 1) {
 if (ptr[i] >= 64 && ptr[i] <= 95) {
 if (ptr[i] == '[') {
 // Control Sequence Introducer (CSI)
 esc = 2;
 } else {
 // Sequence complete
 CLI_HandleCSI (ptr[i]);
 esc = 0;
 }
 continue;
 }
 } else {
 if (ptr[i] >= 64 && ptr[i] <= 126) {
 // Sequence complete
 CLI_HandleCSI (ptr[i]);
 esc = 0;
 continue;
 }
 }
 esc = 0;
 }

 if (ptr[i] == '\r' || ptr[i] == '\n') {

 if (!ignore_next_newline || ptr[i] != '\n') {

 // Handle the received command
 if (CliCtrl->line.len) {
 CliCtrl->line.ready = 1;
 return (i + 1);
 } else {
 CLI_Prompt ();
 }

 }

 } else if (ptr[i] == '\b' || ptr[i] == 127) {

 CLI_DelChar ();
#ifdef CLI_HAS_HISTORY
 CLI_HistorySetFlags (CLI_HIST_DIRTY);
#endif


 } else if (ptr[i] == '\t') {

#ifdef CLI_HAS_AUTOCOMPLETE
 CLI_AutoComplete (tab);
#endif
 tab++;

 } else if (ptr[i] == 27) {

 // ANSI ESC
 esc = 1;

 } else if (ptr[i] >= 32) {

 CLI_AddChar (ptr[i]);

 } else {

 // Unrecognizable character
 // printf ("%d\r\n", ptr[i]);

 }

 // Handle CRLF-s
 if (ptr[i] == '\r') {
 ignore_next_newline = 1;
 } else {
 ignore_next_newline = 0;
 }

 // Reset the TAB counter
 if (ptr[i] != '\t') {
 tab = 0;
 }
 }

 return len;
}


/**
 * Handle the last received command.
 *
 * @return The result of the executed command
 */
int CLI_HandleLine (void)
{
 size_t i;
 char c;
 int res = -1;

 if (CliCtrl->line.ready) {

 // Leave room for terminating '\0'
 if (CliCtrl->line.len < CLI_LINE_BUFSIZE) {

 size_t argstart = 0;
 size_t bufpos = 0;
 char *argv[CLI_ARGV_LEN];
 int argc = 0;
 uint8_t is_squotes = 0;
 uint8_t is_dquotes = 0;
 uint8_t is_escape = 0;

 CliCtrl->line.buf[CliCtrl->line.len] = '\0';

#ifdef CLI_HAS_HISTORY
 CLI_HistoryAdd (CLI_HIST_IGNORE_DUP);
 CLI_HistorySetFlags (CLI_HIST_DIRTY);
#endif

 for (i = 0; i < CliCtrl->line.len; i++) {

 c = CliCtrl->line.buf[i];

 if (is_escape) {
 CliCtrl->line.buf[bufpos++] = c;
 is_escape = 0;
 } else {
 if (is_squotes) {
 if (c == '\'') {
 is_squotes = 0;
 } else {
 CliCtrl->line.buf[bufpos++] = c;
 }
 } else if (is_dquotes) {
 if (c == '\"') {
 is_dquotes = 0;
 } else if (c == '\\') {
 is_escape = 1;
 } else {
 CliCtrl->line.buf[bufpos++] = c;
 }
 } else {
 if (c == '\\') {
 is_escape = 1;
 } else if (c == '\'') {
 is_squotes = 1;
 } else if (c == '\"') {
 is_dquotes = 1;
 } else if (c == ' ') {
 if (bufpos - argstart > 0) {
 CliCtrl->line.buf[bufpos++] = '\0';
 if (argc < CLI_ARGV_LEN) {
 argv[argc] = &(CliCtrl->line.buf[argstart]);
 }
 argc++;
 }
 argstart = bufpos;
 } else {
 CliCtrl->line.buf[bufpos++] = c;
 }
 }
 }
 }

 if (is_escape || is_squotes || is_dquotes) {

 CLI_WriteStr ("\r\nCLI_HandleLine: command parse error");

 } else if ((argc > CLI_ARGV_LEN) || ((argc == CLI_ARGV_LEN) && (bufpos - argstart > 0))) {

 CLI_WriteStr ("\r\nCLI_HandleLine: too many arguments");

 } else {

 // Handle last argument
 if (bufpos - argstart > 0) {
 CliCtrl->line.buf[bufpos++] = '\0';
 argv[argc++] = &(CliCtrl->line.buf[argstart]);
 }

 if (argc > 0) {

 // Set all unused arguments refer to empty string, to avoid accidental invalid dereferences
 // by command handlers (in case they do not check the argument count)
 char *empty_string = "";
 for (i = argc; i < (sizeof (argv) / sizeof (char *)); i++) {
 argv[i] = empty_string;
 }

 res = CLI_Exec (argc, argv);
 }
 }

 } else {

 CLI_WriteStr ("\r\nCLI_HandleLine: command too long");

 }

 CliCtrl->line.len = 0;
 CliCtrl->line.ready = 0;
 CLI_Prompt ();

 }

 return res;
}


/**
 * Enable/disable UTF-8 support (only affects backspace).
 *
 * @param enable 0 - disable, 1 - enable
 */
void CLI_Utf8 (uint8_t enable)
{
 CliCtrl->utf8_enabled = enable;
}


/**
 * Initialize the driver.
 *
 * @param cmdlist List of available commands and their handlers
 */
void CLI_Init (const cli_cmd_list_t *cmdlist)
{
 memset (CliCtrl, 0, sizeof (cli_control_t));
 CliCtrl->cmdlist = cmdlist;
 CLI_Utf8 (1);
 CLI_Prompt ();
}