shellmatta/README.md

# Shellmatta

A tiny and flexible shell implementation to be used on embedded devices.

## Name

The name `shellmatta` is the combination of `shell` and `shimatta`.

What the hell is `shimatta` you might ask.

...well if you really wanna know you might reach out to these nerds that are
running domains like [shimatta.net](https://git.shimatta.net) or
[shimatta.de](https://git.shimatta.de).

Do not pretend i didn't warn you.

## Intention

The intention is to enable a software project of nearly any size to have a
runtime command line interface to simplify debugging or
configuration/calibration of any kind of device.

The `shellmatta` is designed to fit in most tiny microcontroller.

It is based on a simple character based interface and can work with for example
network sockets or simple uarts.
Some features are removable at build time to save ressources on really tiny
platforms.

## Features

The `shellmatta` piled up some features over time:

1. history buffer (configurable)
2. auto complete
3. heredoc like interface to pass multiline data
4. option parser (getopt like)

## Documentation

Besides this readme most documentation is integrated directly in the sourcecode
as doxygen parsable comments.

To build the doxygen documentation just run `make doc`.

The html and latex documentation will be exported to `output/doc`

## Integration into your project

The basic integration into a softwareproject is quite easy.

1. add all *.c files from the `src` to your build
2. include the `api/shellmatta.h` file
3. implement a write function to output the data from the shell
4. initialize the shell providing static buffers
5. implement and add commands
6. pass data into the shellmatta and watch the magic happen
7. static constant command list (if you do not like dynamic lists)

Code example:

```
#include "shellmatta.h"
#include <unistd.h>

shellmatta_retCode_t writeFct(const char* data, uint32_t length)
{
    write(1, data, length);
    return SHELLMATTA_OK;
}

static shellmatta_retCode_t exampleCmdFct(shellmatta_handle_t handle, const char *arguments, uint32_t length)
{
    shellmatta_retCode_t ret;
    char option;

    static const shellmatta_opt_long_t options[] = 
    {
        {"version",  'v',   SHELLMATTA_OPT_ARG_NONE},
        {NULL,      '\0',   SHELLMATTA_OPT_ARG_NONE}
    };

    ret = shellmatta_opt_long(handle, options, &option, NULL, NULL);
    while(SHELLMATTA_OK == ret)
    {
        switch(option)
        {
            case 'v':
                shellmatta_printf(handle, "This should represent the version of this command");
                break;
            default:
                shellmatta_printf(handle, "Unknown option: %c\r\n", option);
                break;
        }
        ret = shellmatta_opt_long(handle, options, &option, NULL, NULL);
    }

    (void)arguments;
    (void)length;
    return SHELLMATTA_OK;
}
shellmatta_cmd_t exampleCmd = { "example",                                              /**< command name       */
                                "e",                                                    /**< command alias      */
                                "example command",                                      /**< command help       */
                                "example [options]\n"                                   /**< command usage text */
                                "\t-v, --version - print the version of the command",
                                exampleCmdFct,                                          /**< command function   */
                                NULL};                                                  /**< intenally used     */

int main(void)
{
    static char buffer[1024];               /**< memory for inptu buffer    */
    static char historyBuffer[4096];        /**< memory for history buffer  */
    static shellmatta_instance_t instance;  /**< instance variable          */
    shellmatta_handle_t handle;             /**< handle used for accessing  */

    /** -# initialize the shellmatta instance */
    shellmatta_doInit(  &instance,
                        &handle,
                        buffer,
                        sizeof(buffer),
                        historyBuffer,
                        sizeof(historyBuffer),
                        "shellmatta->",         /**< prompt text                    */
                        NULL,                   /**< optional static command list   */
                        writeFct);              /**< write function                 */

    /** -# add the command - one command can only be added to one instance */
    shellmatta_addCmd(handle, &exampleCmd);

    /** -# ready to put some data in there */
    shellmatta_processData(handle, "example --version\r", 18u);

    return 0;
}

```

## Compile time configuration

There are some defines you can use to change the behaviour of the shellmatta:

| Define                     | Description                                    |
| -------------------------- | ---------------------------------------------- |
| SHELLMATTA_STRIP_PRINTF    | removes stdio dependencies to reduce footprint |
| SHELLMATTA_HELP_COMMAND    | string to overwrite the help command name      |
| SHELLMATTA_HELP_ALIAS      | string to overwrite the help command alias     |
| SHELLMATTA_HELP_HELP_TEXT  | string to overwrite the help command help      |
| SHELLMATTA_HELP_USAGE_TEXT | string to overwrite the help command usage     |

## Example

There is a quite confusing example in this repo to show and test some features.

To build it just rum `make example`.
The binary will be built to `output/example/example`

It requires a serial device as parameter to run e.g. `/dev/tty0`

To be able to play around a bit you can create a local serial loopback using
socat.
```
socat -d -d pty,raw,echo=0 pty,raw,echo=0
```

This will create two serial devices which are connected with a loopback.
The device numbers in this example might change on your system.

You can use one of them starting the example e.g.
```
./output/example/example /dev/pts2
```
And use the other one to connect using the terminal tool of your choice e.g.
```
minicom -D /dev/pts3
```

## Running tests

There are some tests implemented using catch2 and the function fake framework.

To run the tests just do:
```
make test
```

To be able to build the coverage report you need an installation of
(gcovr)[https://pypi.org/project/gcovr].