shellmatta/src/shellmatta_utils.c

/*
 * Copyright (c) 2019 - 2024 Stefan Strobel <stefan.strobel@shimatta.net>
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */

/**
 * @file    shellmatta_utils.c
 * @brief   util/helper functions of shellmatta
 * @author  Stefan Strobel <stefan.strobel@shimatta.net>
 */

/**
 * @addtogroup shellmatta_utils
 * @{
 */

#include "shellmatta_utils.h"
#include "shellmatta.h"
#ifdef SHELLMATTA_AUTHENTICATION
#include "shellmatta_auth.h"
#endif
#include <string.h>

/**
 * @brief       function to write an echo to the output depending on
 *              the echo enabled state of the instance
 * @param[in]   inst    pointer to a shellmatta instance
 * @param[in]   data    pointer to the data so send
 * @param[in]   length  length of the data to send (in byte)
 */
void utils_writeEcho(   shellmatta_instance_t   *inst,
                        const char              *data,
                        uint32_t                length)
{
    if(true == inst->echoEnabled)
    {
        SHELLMATTA_WRITE(data, length);
    }
}

/**
 * @brief           itoa like function to convert int to an ascii string
 * @warning         you have to provide a large enough buffer
 * @param[in]       value
 * @param[in,out]   buffer
 * @param[in]       base
 * @return          number of bytes in string
 */
uint32_t utils_shellItoa(int32_t value, char *buffer, uint32_t base)
{
    char tempBuffer[34u];
    uint32_t i;
    uint32_t bufferIdx = 0u;
    int8_t digitValue;

    /** -# check the base for plausibility */
    if((base >= 2) && (base <= 16))
    {
        /** -# check for sign */
        if(value < 0)
        {
            value       = value * (-1);
            buffer[0u]  = '-';
            bufferIdx   += 1u;
        }

        /** -# loop through all digits in reverse order */
        i = 0u;
        do
        {
            digitValue = (int8_t) (value % base);
            tempBuffer[i] = (digitValue < 10) ? ('0' + digitValue) : ('A' + (digitValue - 10));
            value /= base;
            i ++;
        }while(value > 0);

        /** -# store the string in the correct order onto the buffer */
        while(i > 0u)
        {
            buffer[bufferIdx] = tempBuffer[i - 1u];
            i --;
            bufferIdx ++;
        }
    }
    return bufferIdx;
}

/**
 * @brief       tells the terminal to save the current cursor position
 * @param[in]   inst    pointer to shellmatta instance
 */
void utils_saveCursorPos(shellmatta_instance_t *inst)
{
    utils_writeEcho(inst, "\x1b" "[s", 3u);
}

/**
 * @brief       tells the terminal to restore the saved cursor position
 * @param[in]   inst    pointer to shellmatta instance
 */
void utils_restoreCursorPos(shellmatta_instance_t *inst)
{
    utils_writeEcho(inst, "\x1b" "[u", 3u);
}

/**
 * @brief       tells the terminal to erase the line on the right side of the
 *              cursor
 * @param[in]   inst    pointer to shellmatta instance
 */
void utils_eraseLine(shellmatta_instance_t *inst)
{
    utils_writeEcho(inst, "\x1b" "[K", 3u);
}

/**
 * @brief       moves the cursor back by the given amoung of characters
 * @param[in]   inst    pointer to shellmatta instance
 * @param[in]   length  number of characters to rewind
 */
void utils_rewindCursor(shellmatta_instance_t *inst, uint32_t length)
{
    char    terminalCmd[16];
    size_t  size;

    length = SHELLMATTA_MIN (length, inst->cursor);
    if(length > 0u)
    {
        terminalCmd[0]  = '\x1b';
        terminalCmd[1]  = '[';
        size = 2u + utils_shellItoa(length, &terminalCmd[2], 10);
        terminalCmd[size] = 'D';
        utils_writeEcho(inst, terminalCmd, size + 1u);
        inst->cursor -= length;
    }
}

/**
 * @brief       moves the cursor forward by the given amoung of characters
 * @param[in]   inst    pointer to shellmatta instance
 * @param[in]   length  number of characters to move forward
 */
void utils_forwardCursor(shellmatta_instance_t *inst, uint32_t length)
{
    char   terminalCmd[16];
    size_t size;

    length = SHELLMATTA_MIN (length, (inst->inputCount - inst->cursor));
    if (length > 0u)
    {
        terminalCmd[0]  = '\x1b';
        terminalCmd[1]  = '[';
        size = 2u + utils_shellItoa(length, &terminalCmd[2], 10);
        terminalCmd[size] = 'C';
        utils_writeEcho(inst, terminalCmd, size + 1u);
        inst->cursor += length;
    }
}

/**
 * @brief       inserts the given amount of characters at the cursor position
 * @param[in]   inst    pointer to shellmatta instance
 * @param[in]   data    pointer to the data to be inserted
 * @param[in]   length  length of the data to be inserted
 */
void utils_insertChars( shellmatta_instance_t   *inst,
                        const char              *data,
                        uint32_t                 length)
{
    uint32_t tmpLength = length;
    /** -# limit the length to the space left in the buffer */
    if((inst->inputCount + tmpLength) > inst->bufferSize)
    {
        tmpLength = inst->bufferSize - inst->inputCount;
    }

    if(0u != tmpLength)
    {

        /** -# check if we have to move chars in the buffer */
        if(     (inst->cursor     != inst->inputCount)
            &&  (SHELLMATTA_MODE_INSERT == inst->mode))
        {
            /** -# move the existing chars */
            for (uint32_t i = inst->inputCount; i > inst->cursor; i --)
            {
                inst->buffer[i + tmpLength - 1] = inst->buffer[i - 1];
            }

            /** -# store and print the new chars */
            memcpy(&(inst->buffer[inst->cursor]), data, tmpLength);

            utils_writeEcho(inst, data, tmpLength);

            /** -# print the other chars and restore the cursor to this position */
            utils_eraseLine(inst);
            utils_saveCursorPos(inst);
            utils_writeEcho(  inst,
                        &(inst->buffer[inst->cursor + tmpLength]),
                        inst->inputCount - inst->cursor);
            utils_restoreCursorPos(inst);
            inst->cursor        += tmpLength;
            inst->inputCount    += tmpLength;
        }
        /** -# overwrite - if the cursor reaches the end of the input it is pushed further */
        else
        {
            memcpy(&(inst->buffer[inst->cursor]), data, tmpLength);
            utils_writeEcho(inst, data, tmpLength);
            inst->cursor += tmpLength;
            if(inst->cursor > inst->inputCount)
            {
                inst->inputCount    =  inst->cursor;
            }
        }
    }
}

/**
 * @brief       removes the given amount of characters from the current cursor
 *              position
 * @param[in]   inst        pointer to a shellmatta instance
 * @param[in]   length      number of characters to remove
 * @param[in]   backspace   true    ==> remove characters left of the cursor
 *                          false   ==> remove characters right of the cursor
 */
void utils_removeChars( shellmatta_instance_t   *inst,
                        uint32_t                 length,
                        bool                     backspace)
{
    if((0u != length) && (inst->inputCount >= inst->cursor))
    {
        /** -# rewind the cursor in case of backspace */
        if(true == backspace)
        {
            length = SHELLMATTA_MIN (length, inst->cursor);
            utils_rewindCursor(inst, length);
        }
        else
        {
            length = SHELLMATTA_MIN (length, inst->inputCount - inst->cursor);
        }
        /** -# delete the char at the cursor position */
        for (   uint32_t i = inst->cursor;
                i < (inst->inputCount - length);
                i++)
        {
            inst->buffer[i] = inst->buffer[i + length];
        }

        /** -# print the rest of the line again */
        utils_eraseLine(inst);
        utils_saveCursorPos(inst);
        utils_writeEcho(    inst,
                    &(inst->buffer[inst->cursor]),
                     (inst->inputCount - inst->cursor - length));
        utils_restoreCursorPos(inst);

        inst->inputCount -= length;
    }
}

/**
 * @brief       clears the input buffer and removes the currend command from
 *              the terminal output
 * @param[in]   inst    pointer to a shellmatta instance
 */
void utils_clearInput(shellmatta_instance_t *inst)
{
    utils_rewindCursor(inst, inst->cursor);
    utils_eraseLine(inst);
    inst->inputCount = 0u;
    inst->dirty = false;
}

/**
 * @brief       prints the usage information of one passed command
 * @param[in]   inst    handle  shellmatta instance handle
 * @param[in]   cmd     pointer to a command structure to print
 * @return      #SHELLMATTA_OK
 *              #SHELLMATTA_ERROR
 */
static shellmatta_retCode_t printUsage(const shellmatta_instance_t *inst, const shellmatta_cmd_t *cmd)
{
    shellmatta_retCode_t ret = SHELLMATTA_OK;

    /** -# write the command and alias if configured */
    SHELLMATTA_RET(ret, SHELLMATTA_WRITE("Help for command: ", 18u));
    SHELLMATTA_RET(ret, SHELLMATTA_WRITE(cmd->cmd, strlen(cmd->cmd)));
    if((NULL != cmd->cmdAlias) && (0u != strlen(cmd->cmdAlias)))
    {
        SHELLMATTA_RET(ret, SHELLMATTA_WRITE(" (", 2u));
        SHELLMATTA_RET(ret, SHELLMATTA_WRITE(cmd->cmdAlias, strlen(cmd->cmdAlias)));
        SHELLMATTA_RET(ret, SHELLMATTA_WRITE(")", 1u));
    }
    /** -# write the help text if configured */
    if((NULL != cmd->helpText) && (0u != strlen(cmd->helpText)))
    {
        SHELLMATTA_RET(ret, SHELLMATTA_WRITE("\r\n\r\n", 4u));
        SHELLMATTA_RET(ret, SHELLMATTA_WRITE(cmd->helpText, strlen(cmd->helpText)));
    }
    /** -# write the usage text if configured */
    if((NULL != cmd->usageText) && (0u != strlen(cmd->usageText)))
    {
        SHELLMATTA_RET(ret, SHELLMATTA_WRITE("\r\n\r\nUsage: \r\n", 13u));
        SHELLMATTA_RET(ret, SHELLMATTA_WRITE(cmd->usageText, strlen(cmd->usageText)));
    }
    SHELLMATTA_RET(ret, SHELLMATTA_WRITE("\r\n", 2u));

    return ret;
}

/**
 * @brief       prints all possible commands with description and usage
 * @param[in]   handle      handle  shellmatta instance handle
 * @param[in]   arguments   arguments containing a command name or alias
 * @param[in]   length      length of the arguments
 * @return      #SHELLMATTA_OK
 *              #SHELLMATTA_ERROR (buffer overflow)
 */
static shellmatta_retCode_t helpCmdFct(const shellmatta_handle_t handle, const char *arguments, uint32_t length)
{
    shellmatta_retCode_t        ret = SHELLMATTA_OK;
    const shellmatta_instance_t *inst = (const shellmatta_instance_t*) handle;
    shellmatta_cmd_t            *cmd            = NULL;
    size_t                      maxCmdLen       = 0u;
    size_t                      maxCmdAliasLen  = 0u;
    size_t                      cmdLen          = 0u;
    const char                  *subCmd         = NULL;
    size_t                      cmdAliasLen;
    uint32_t                    tabCnt;
    uint32_t                    i;
    static const char           tabBuffer[] = { ' ', ' ', ' ', ' ',
                                                ' ', ' ', ' ', ' ',
                                                ' ', ' ', ' ', ' ',
                                                ' ', ' ', ' ', ' '};

    /** -# check if help is called with a command - find first space */
    for(i = 1u; i < length; i ++)
    {
        if(' ' == arguments[i - 1])
        {
            subCmd  = &(arguments[i]);

            /** -# determine subcommand length*/
            cmdLen  = 0u;
            while(      ((i + cmdLen)   <   length)
                    &&  (' '            !=  arguments[i + cmdLen])
                    &&  ('\r'           !=  arguments[i + cmdLen])
                    &&  ('\n'           !=  arguments[i + cmdLen])
                    &&  ('\0'           !=  arguments[i + cmdLen]))
            {
                cmdLen ++;
            }
            break;
        }
    }

    /* print detailled help */
    if(NULL != subCmd)
    {
        cmd = inst->cmdList;

        /** -# search for a matching command */
        while (NULL != cmd)
        {
            /** -# compare command and alias string and length */
            if (    ((cmdLen    == strlen(cmd->cmd))
                    && (0       == strncmp(subCmd, cmd->cmd, cmdLen)))
                || ((NULL != cmd->cmdAlias)
                    && (cmdLen  == strlen(cmd->cmdAlias))
                    && (0       == strncmp(subCmd, cmd->cmdAlias, cmdLen))))
            {
                SHELLMATTA_RET(ret, printUsage(inst, cmd));
                break;
            }

            cmd = cmd->next;
        }
    }

    /** -# print help list if no sub cmd was found */
    if(NULL == cmd)
    {
        /** -# loop through all commands to determine the lengths of each cmd */
        cmd = inst->cmdList;
        while(NULL != cmd)
        {
#ifdef SHELLMATTA_AUTHENTICATION
            if (SHELLMATTA_OK != shellmatta_auth_is_cmd_permitted(inst, cmd))
            {
                cmd = cmd->next;
                continue;
            }
#endif
            maxCmdLen           = SHELLMATTA_MAX(maxCmdLen,         strlen(cmd->cmd));
            if(NULL != cmd->cmdAlias)
            {
                maxCmdAliasLen  = SHELLMATTA_MAX(maxCmdAliasLen,    strlen(cmd->cmdAlias));
            }
            cmd = cmd->next;
        }

        /** -# loop through all commands and print all possible information */
        cmd = inst->cmdList;
        while(NULL != cmd)
        {
#ifdef SHELLMATTA_AUTHENTICATION
            if (SHELLMATTA_OK != shellmatta_auth_is_cmd_permitted(inst, cmd))
            {
                cmd = cmd->next;
                continue;
            }
#endif
            /** -# determine the length of each field to add padding */
            cmdLen       = strlen(cmd->cmd);
            cmdAliasLen  = (NULL != cmd->cmdAlias) ? strlen(cmd->cmdAlias) : 0u;

            SHELLMATTA_RET(ret, SHELLMATTA_WRITE(cmd->cmd, strlen(cmd->cmd)));
            tabCnt = (maxCmdLen - cmdLen) + 2u;

            /** -# add padding if there is anything to be printed afterwards */
            if(    ((NULL != cmd->cmdAlias) && (0u != strlen(cmd->cmdAlias)))
                || ((NULL != cmd->helpText) && (0u != strlen(cmd->helpText))))
            {
                SHELLMATTA_PRINT_BUFFER(tabBuffer, tabCnt);
            }

            if((NULL != cmd->cmdAlias) && (0u != strlen(cmd->cmdAlias)))
            {
                SHELLMATTA_RET(ret, SHELLMATTA_WRITE(cmd->cmdAlias, cmdAliasLen));
            }
            tabCnt = (maxCmdAliasLen - cmdAliasLen) + 2u;

            if((NULL != cmd->helpText) && (0u != strlen(cmd->helpText)))
            {
                SHELLMATTA_PRINT_BUFFER(tabBuffer, tabCnt);
                SHELLMATTA_RET(ret, SHELLMATTA_WRITE(cmd->helpText, strlen(cmd->helpText)));
            }

            SHELLMATTA_RET(ret, SHELLMATTA_WRITE("\r\n", 2u));

            cmd = cmd->next;
        }
    }

    return ret;
}
const shellmatta_cmd_t helpCmd = {SHELLMATTA_HELP_COMMAND
                                , SHELLMATTA_HELP_ALIAS
                                , SHELLMATTA_HELP_HELP_TEXT
                                , SHELLMATTA_HELP_USAGE_TEXT
                                , helpCmdFct
                                , NULL
#ifdef SHELLMATTA_AUTHENTICATION
                                , NULL
#endif
                                };

/**
 * @brief       terminates an input and prints the prompt again
 * @param[in]   inst    pointer to a shellmatta instance
 */
void utils_terminateInput(shellmatta_instance_t *inst)
{
    inst->inputCount        = 0u;
    inst->lastNewlineIdx    = 0u;
    inst->hereLength        = 0u;
    inst->cursor            = 0u;
    inst->stdinIdx          = 0u;
    inst->stdinLength       = 0u;
    inst->continuousCmd     = NULL;
    inst->busyCmd           = NULL;
    SHELLMATTA_WRITE("\r\n", 2u);
#ifdef SHELLMATTA_AUTHENTICATION
    inst->loginState        = SHELLMATTA_AUTH_IDLE;
    if (NULL != inst->userPointer)
    {
        SHELLMATTA_WRITE(inst->userPointer->username, strlen(inst->userPointer->username));
        SHELLMATTA_WRITE("@", 1);
    }
#endif
    SHELLMATTA_WRITE(inst->prompt, strlen(inst->prompt));
}

/**
 * @}
 */