/* * Copyright (c) 2019 - 2021 Stefan Strobel * * 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.h * @brief API definition of the Shellmatta terminal implementation * @author Stefan Strobel */ /** * @addtogroup shellmatta_api Shellmatta API description * @{ */ #ifndef _SHELLMATTA_H_ #define _SHELLMATTA_H_ #include #include /* global defines */ /** * @brief definition of a shellmatta handle */ typedef void* shellmatta_handle_t; /** * @brief definition of shellmatta return codes */ typedef enum { SHELLMATTA_OK = 0u, /**< everything is OK */ SHELLMATTA_ERROR , /**< error occured */ SHELLMATTA_CONTINUE , /**< the function is not over */ SHELLMATTA_USE_FAULT , /**< parameter error - wrong usage */ SHELLMATTA_DUPLICATE , /**< duplicate command */ SHELLMATTA_BUSY /**< command is busy keep calling */ } shellmatta_retCode_t; /** * @brief definition of shellmatta insert mode */ typedef enum { SHELLMATTA_MODE_INSERT = 0u, /**< insert mode */ SHELLMATTA_MODE_OVERWRITE , /**< overwrite mode */ } shellmatta_mode_t; /** * @brief definition of shellmatta optionparser agument type */ typedef enum { SHELLMATTA_OPT_ARG_NONE = 0u, /**< no argument expected */ SHELLMATTA_OPT_ARG_REQUIRED, /**< argument is required */ SHELLMATTA_OPT_ARG_OPTIONAL, /**< argument is optional */ } shellmatta_opt_argtype_t; /** * @brief definition of shellmatta optionparser agument type */ typedef struct { const char *paramLong; /**< long parameter string */ const char paramShort; /**< short parameter char */ shellmatta_opt_argtype_t argtype; /**< argument type expected */ } shellmatta_opt_long_t; /** * @brief definition of shellmatta optionparser structure */ typedef struct { uint32_t argStart; /**< start of the arguments of the command */ uint32_t offset; /**< current offset of the option parser */ uint32_t nextOffset; /**< offset of the next hunk */ uint32_t len; /**< length of the current hunk */ } shellmatta_opt_t; /** * @brief shellmatta command function definition * @param[in] handle pointer to the instance which is calling the cmd * @param[in] arguments argument string called to run this command beginning * with the command itself * @param[in] length length of the argument string */ typedef shellmatta_retCode_t (*shellmatta_cmdFct_t)(const shellmatta_handle_t handle, const char *arguments, uint32_t length); /** * @brief shellmatta write function definition * @param[in] data data to be written to the output * @param[in] length length of the data to be written */ typedef shellmatta_retCode_t (*shellmatta_write_t)(const char* data, uint32_t length); /** * @brief structure of one shellmatta command */ typedef struct shellmatta_cmd { char *cmd; /**< command name */ char *cmdAlias; /**< command alias */ char *helpText; /**< help text to print in "help" command */ char *usageText; /**< usage text - printed on "help cmd" */ shellmatta_cmdFct_t cmdFct; /**< pointer to the cmd callack function */ struct shellmatta_cmd *next; /**< pointer to next command or NULL */ } shellmatta_cmd_t; /** * @brief structure of one shellmatta instance */ typedef struct { uint32_t magic; /**< magic number to check if initialized */ char *buffer; /**< input buffer */ uint32_t bufferSize; /**< size of the input buffer */ uint32_t inputCount; /**< offset of the current write operation */ uint32_t byteCounter; /**< counter used to loop over input data */ uint32_t lastNewlineIdx; /**< index of the lest newline */ uint32_t cursor; /**< offset where the cursor is at */ uint32_t stdinIdx; /**< start index of stdin in buffer */ uint32_t stdinLength; /**< length of the stdin data */ char *historyBuffer; /**< buffer to store the last commands */ uint32_t historyBufferSize; /**< size of the history buffer */ uint32_t historyStart; /**< index of the oldest stored command */ uint32_t historyEnd; /**< index of the newest stored command */ uint32_t historyRead; /**< index of the current search */ bool historyReadUp; /**< flag to show the last history dir */ uint32_t tabCounter; /**< counts the tabulator key presses */ uint32_t escapeCounter; /**< counts the characters of an escape seq */ char escapeChars[4u]; /**< buffer to save the escape characters */ uint32_t hereStartIdx; /**< heredoc start of "<<" */ uint32_t hereDelimiterIdx; /**< heredoc delimiter index in input */ uint32_t hereLength; /**< length of the heredoc delimiter */ bool echoEnabled; /**< if true the input is printed */ bool dirty; /**< dirty flag to show changes */ const char *prompt; /**< prompt is printed after every command */ char delimiter; /**< delimiter (return) to terminate a cmd */ shellmatta_mode_t mode; /**< mode of the shell */ shellmatta_write_t write; /**< pointer to write function */ shellmatta_cmd_t helpCmd; /**< help command structure */ shellmatta_cmd_t *cmdList; /**< pointer to the first command */ shellmatta_cmd_t *continuousCmd; /**< command to be called continuously */ shellmatta_cmd_t *busyCmd; /**< command to be polled (busy mode) */ bool cmdListIsConst; /**< true if the #cmdList was passed during initialization */ shellmatta_opt_t optionParser; /**< option parser sructure */ } shellmatta_instance_t; shellmatta_retCode_t shellmatta_doInit( shellmatta_instance_t *inst, shellmatta_handle_t *handle, char *buffer, uint32_t bufferSize, char *historyBuffer, uint32_t historyBufferSize, const char *prompt, const shellmatta_cmd_t *cmdList, shellmatta_write_t writeFct); shellmatta_retCode_t shellmatta_resetShell( shellmatta_handle_t handle, bool printPrompt); shellmatta_retCode_t shellmatta_addCmd( shellmatta_handle_t handle, shellmatta_cmd_t *cmd); shellmatta_retCode_t shellmatta_removeCmd( shellmatta_handle_t handle, shellmatta_cmd_t *cmd); shellmatta_retCode_t shellmatta_configure( shellmatta_handle_t handle, shellmatta_mode_t mode, bool echoEnabled, char delimiter); shellmatta_retCode_t shellmatta_processData(shellmatta_handle_t handle, char *data, uint32_t size); shellmatta_retCode_t shellmatta_write( shellmatta_handle_t handle, char *data, uint32_t length); shellmatta_retCode_t shellmatta_read( shellmatta_handle_t handle, char **data, uint32_t *length); shellmatta_retCode_t shellmatta_opt( shellmatta_handle_t handle, const char *optionString, char *option, char **argument, uint32_t *argLen); shellmatta_retCode_t shellmatta_opt_long( shellmatta_handle_t handle, const shellmatta_opt_long_t *longOptions, char *option, char **argument, uint32_t *argLen); #ifndef SHELLMATTA_STRIP_PRINTF shellmatta_retCode_t shellmatta_printf( shellmatta_handle_t handle, const char *fmt, ...); #endif #endif /** @} */