uCmd Documentation

uCmd is a very simple command line parser designed for use in microcontrollers. It is just a function pointer typedef, struct typedef and a single interface funcion. Check out Basic Usage to get started quickly.

All you need to do is define some Command callback functions, a Command List and then call ucmd_parse() with the command string that you want to parse.

Because this is designed for uControllers, I didn't want to include stdio.h by default. Thus it is up to you to write a function to print the command help. However, there is an example in the section Printing the command list.

Command callback functions

Command callbacks should match the Command_cb() typedef. They should arguments argc and argv in the same way as is standard for main in standard c programs. argc is the number of arguments, and argv is an array of char *'s to each of the arguments (including the command itself).

Thus for a command string of "cmd1 arg1 arg2 arg3", ucmd_parse() would attempt to match 'cmd' to a command in the Command List and call the function pointed to by it's Command_cb() with the following arguments:

argc = 4;
argv[] = {"cmd1", "arg1", "arg2", "arg3"};

Command List

The command list is an array of Command members. Below is an example that shows how to define it.

.cmd is the string that will be matched against input, .help is the help text that can be printed by a print function (Printing the command list) and .fn is the callback function that will be called when .cmd matches input.

Warning:

Do NOT forget the null terminator at the end! If you do, get ready for a segfault..

// an example \ref Command List
Command my_cmd_list[] = {
    {
        .cmd = "?",
        .help = "print available commands with their help text",
        .fn = print_help_cb,
    },
    {
        .cmd = "cmd1",
        .help = "help text for command 1",
        .fn = cmd1_callback,
    },
    {
        .cmd = "cmd2",
        .help = "help text for command 2",
        .fn = cmd2_callback,
    },
    {}, // null list terminator DON'T FORGET THIS!
}

Printing the command list

// a simple function to print available commands
int print_help_cb(int argc, char *argv[])
{
    printf("Available Commands:\n");
    Command *p = my_cmd_list;
    while (p->cmd) {
        printf("\t%s \t%s\n", p->cmd, p->help);
        p++;
    }

    return 0;
}

Basic Usage

// define some command callbacks

int print_help_cb(int argc, char *argv[])
{
    printf("Available Commands:\n");
    Command *p = my_cmd_list;
    while (p->cmd) {
        printf("\t%s \t%s\n", p->cmd, p->help);
        p++;
    }

    return 0;
}

int led_cb(int argc, char *argv[])
{
    if (argc < 2)
        printf("requires argument of 'ON' or 'OFF'\n");

    if (strcmp(argv[1], "ON")==0) {
        LED_ON();
    } else if (strcmp(argv[1], "OFF")==0) {
        LED_OFF();
    }
}


// define command list
Command my_cmd_list[] = {
    {
        .cmd = "?",
        .help = "print available commands with their help text",
        .fn = print_help_cb,
    },
    {
        .cmd = "led",
        .help = "<ON|OFF> turns led on or off",
        .fn = led_cb,
    },
    {}, // null list terminator DON'T FORGET THIS!
}

int main()
{
    char *str1 = "?";
    char *str2 = "led ON";
    char *str2 = "bad cmd";

    ucmd_parse(my_cmd_list, " ", str1);                   // prints help message
    ucmd_parse(my_cmd_list, " ", str2);                          // turns led on
    int ret = ucmd_parse(my_cmd_list, " ", str3);   // ret == UCMD_CMD_NOT_FOUND
}

Author:

Dan Fekete <thefekete@gmail.com>

Date:

March 13, 2015

Copyright:

Copyright 2015, Dan Fekete <thefekete@gmail.com>, Released under the GNU GPL v2