/*
 * Copyright (c) 2016 ARM Limited. All rights reserved.
 * SPDX-License-Identifier: Apache-2.0
 * Licensed under the Apache License, Version 2.0 (the License); you may
 * not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * \file ns_cmdline.h
 *
 * Command line library - mbedOS shell
 *
 * Usage example:
 *
 * \code
 * //simple print function
 * void myprint(const char* fmt, va_list ap){ vprintf(fmt, ap); }
 * // simple ready cb, which call next command to be execute
 * void cmd_ready_cb(int retcode) { cmd_next( retcode ); }
 *
 * // dummy command with some option
 * int cmd_dummy(int argc, char *argv[]){
 *  if( cmd_has_option(argc, argv, "o") ) {
 *    cmd_printf("This is o option");
 *  } else {
 *    return CMDLINE_RETCODE_INVALID_PARAMETERS;
 *  }
 *  return CMDLINE_RETCODE_SUCCESS;
 *}
 * // timer cb ( pseudo-timer-code )
 * void timer_ready_cb(void) {
 *   cmd_ready(CMDLINE_RETCODE_SUCCESS);
 * }
 * // long command, which need e.g. some events to finalize command execution
 * int cmd_long(int argc, char *argv[] ) {
     timer_start( 5000, timer_ready_cb );
 *   return CMDLINE_RETCODE_EXCUTING_CONTINUE;
 * }
 * void main(void) {
 *   cmd_init( &myprint );              // initialize cmdline with print function
 *   cmd_set_ready_cb( cmd_ready_cb );  // configure ready cb
 *   cmd_add("dummy", cmd_dummy, 0, 0); // add one dummy command
 *   cmd_add("long", cmd_long, 0, 0);   // add one dummy command
 *   //execute dummy and long commands
 *   cmd_exe( "dymmy;long" );
 * }
 * \endcode
 */
#ifndef _CMDLINE_H_
#define _CMDLINE_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <stdarg.h>
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

#define CMDLINE_RETCODE_COMMAND_BUSY            2   //!< Command Busy
#define CMDLINE_RETCODE_EXCUTING_CONTINUE       1   //!< Execution continue in background
#define CMDLINE_RETCODE_SUCCESS                 0   //!< Execution Success
#define CMDLINE_RETCODE_FAIL                    -1  //!< Execution Fail
#define CMDLINE_RETCODE_INVALID_PARAMETERS      -2  //!< Command parameters was incorrect
#define CMDLINE_RETCODE_COMMAND_NOT_IMPLEMENTED -3  //!< Command not implemented
#define CMDLINE_RETCODE_COMMAND_CB_MISSING      -4  //!< Command callback function missing
#define CMDLINE_RETCODE_COMMAND_NOT_FOUND       -5  //!< Command not found

/**
 * typedef for print functions
 */
typedef void (cmd_print_t)(const char *, va_list);
/**
 * Initialize cmdline class.
 * This is command line editor without any commands. Application
 * needs to add commands that should be enabled.
 * usage e.g.
 * \code
    cmd_init( &default_cmd_response_out );
 * \endcode
 * \param outf  console printing function (like vprintf)
 */
void cmd_init(cmd_print_t *outf);
/** Command ready function for __special__ cases.
 * This need to be call if command implementation return CMDLINE_RETCODE_EXECUTING_CONTINUE
 * because there is some background stuff ongoing before command is finally completed.
 * Normally there is some event, which call cmd_ready().
 * \param retcode return code for command
 */
void cmd_ready(int retcode);
/** typedef for ready cb function */
typedef void (cmd_ready_cb_f)(int);
/**
 * Configure cb which will be called after commands are executed
 * or cmd_ready is called
 * \param cb    callback function for command ready
 */
void cmd_set_ready_cb(cmd_ready_cb_f *cb);
/**
 * execute next command if any
 * \param retcode last command return value
 */
void cmd_next(int retcode);
/** Free cmd class */
void cmd_free(void);
/** Reset cmdline to default values
 *  detach external commands, delete all variables and aliases
 */
void cmd_reset(void);
/** Configure command history size (default 32)
 *  \param max  maximum history size
 *  max > 0 -> configure new value
 *  max = 0 -> just return current value
 *  \return current history max-size
 */
uint8_t cmd_history_size(uint8_t max);
/** command line print function
 *  This function should be used when user want to print something to the console
 *  \param fmt   console print function (like printf)
 */
#if defined(__GNUC__) || defined(__CC_ARM)
void cmd_printf(const char *fmt, ...)  __attribute__ ((__format__(__printf__, 1, 2)));
#else
void cmd_printf(const char *fmt, ...);
#endif
/** command line print function
 *  This function should be used when user want to print something to the console with vprintf functionality
 *  \param fmt  The format string is a character string, beginning and ending in its initial shift state, if any. The format string is composed of zero or more directives.
 *  \param ap   list of parameters needed by format string. This must correspond properly with the conversion specifier.
 */
#if defined(__GNUC__) || defined(__CC_ARM)
void cmd_vprintf(const char *fmt, va_list ap)  __attribute__ ((__format__(__printf__, 1, 0)));
#else
void cmd_vprintf(const char *fmt, va_list ap);
#endif
/** Reconfigure default cmdline out function (cmd_printf)
 *  \param outf  select console print function
 */
void cmd_out_func(cmd_print_t *outf);
/** Configure function, which will be called when Ctrl+A is pressed
 * \param sohf control function which called every time when user input control keys
 */
void cmd_ctrl_func(void (*sohf)(uint8_t c));
/**
 * Configure mutex wait function
 * By default, cmd_printf calls may not be thread safe, depending on the implementation of the used output.
 * This can be used to set a callback function that will be called before each cmd_printf call.
 * The specific implementation is up to the application developer, but simple mutex locking is assumed.
 */
void cmd_mutex_wait_func(void (*mutex_wait_f)(void));
/**
 * Configure mutex wait function
 * By default, cmd_printf calls may not be thread safe, depending on the implementation of the used output.
 * This can be used to set a callback function that will be called after each cmd_printf call.
 * The specific implementation is up to the application developer, but simple mutex locking is assumed.
 */
void cmd_mutex_release_func(void (*mutex_release_f)(void));
/**
 * Retrieve output mutex lock
 * This can be used to retrieve the output mutex when multiple cmd_printf/cmd_vprintf calls must be
 * guaranteed to be grouped together in a thread safe manner. Must be released by a following call to
 * cmd_mutex_unlock()
 * For example:
 * * \code
 * cmd_mutex_lock();
   for (i = 0; i < 10; i++) {
       cmd_printf("%02x ", i);
   }
   // without locking a print from another thread could happen here
   cmd_printf("\r\n);
   cmd_mutex_unlock();
 * \endcode
 * Exact behaviour depends on the implementation of the configured mutex,
 * but counting mutexes are required.
 */
void cmd_mutex_lock(void);
/**
 * Release output mutex lock
 * This can be used to release the output mutex once it has been retrieved with cmd_mutex_lock()
 * Exact behaviour depends on the implementation of the configured mutex,
 * but counting mutexes are required.
 */
void cmd_mutex_unlock(void);
/** Refresh output */
void cmd_output(void);
/** default cmd response function, use stdout
 *  \param fmt  The format string is a character string, beginning and ending in its initial shift state, if any. The format string is composed of zero or more directives.
 *  \param ap   list of parameters needed by format string. This must correspond properly with the conversion specifier.
 */
void default_cmd_response_out(const char *fmt, va_list ap);
/** Initialize screen */
void cmd_init_screen(void);
/** Get echo state
 * \return true if echo is on otherwise false
 */
bool cmd_echo_state(void);
/** Echo off */
void cmd_echo_off(void);
/** Echo on */
void cmd_echo_on(void);
/** Enter character to console.
 * insert key pressess to cmdline called from main loop of application
 * \param u_data char to be added to console
 */
void cmd_char_input(int16_t u_data);
/*
 * Set the passthrough mode callback function. In passthrough mode normal command input handling is skipped and any
 * received characters are passed to the passthrough callback function. Setting this to null will disable passthrough mode.
 * \param passthrough_fnc The passthrough callback function
 */
typedef void (*input_passthrough_func_t)(uint8_t c);
void cmd_input_passthrough_func(input_passthrough_func_t passthrough_fnc);

/* Methods used for adding and handling of commands and aliases
 */

/** Callback called when your command is run.
 * \param argc argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
 * \param argv argv is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
 */
typedef int (cmd_run_cb)(int argc, char *argv[]);
/** Add command to intepreter
 * \param name      command string
 * \param callback  This function is called when command line start executing
 * \param info      Command short description which is visible in help command, or null if not in use
 * \param man       Help page for this command. This is shown when executing command with invalid parameters or command with --help parameter. Can be null if not in use.
 */
void cmd_add(const char *name, cmd_run_cb *callback, const char *info, const char *man);

/** delete command from intepreter
 *  \param name command to be delete
 */
void cmd_delete(const char *name);
/** Command executer.
 * Command executer, which split&push command(s) to the buffer and
 * start executing commands in cmd tasklet.
 * if not, execute command directly.
 * If command implementation returns CMDLINE_RETCODE_EXCUTING_CONTINUE,
 * executor will wait for cmd_ready() before continue to next command.
 * \param str  command string, e.g. "help"
 */
void cmd_exe(char *str);
/** Add alias to interpreter.
 * Aliases are replaced with values before executing a command. All aliases must be started from beginning of line.
 * null or empty value deletes alias.
 * \code
   cmd_alias_add("print", "echo");
   cmd_exe("print \"hello world!\""); // this is now same as "echo \"hello world!\"" .
 * \endcode
 * \param alias     alias name
 * \param value     value for alias. Values can be any visible ASCII -characters.
 */
void cmd_alias_add(const char *alias, const char *value);
/** Add Variable to interpreter.
 * Variables are replaced with values before executing a command.
 * To use variables from cli, use dollar ($) -character so that interpreter knows user want to use variable in that place.
 * null or empty value deletes variable.
 * \code
   cmd_variable_add("world", "hello world!");
   cmd_exe("echo $world"); // this is now same as echo "hello world!" .
 * \endcode
 * \param variable  Variable name, which will be replaced in interpreter.
 * \param value     Value for variable. Values can contains white spaces and '"' or '"' characters.
 */
void cmd_variable_add(char *variable, char *value);

/** find command parameter index by key.
 * e.g.
 * \code
      int main(void){
            //..init cmd..
            //..
            cmd_exe("mycmd enable")
      }
      int mycmd_command(int argc, char *argv[]) {
        bool found = cmd_parameter_index( argc, argv, "enable" ) > 0;
      }
 * \endcode
 * \param argc  argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
 * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
 * \param key   option key, which index you want to find out.
 * \return index where parameter was or -1 when not found
 */
int cmd_parameter_index(int argc, char *argv[], const char *key);
/** check if command option is present.
 * e.g. cmd: "mycmd -c"
 * \code
 *    bool on = cmd_has_option( argc, argv, "p" );
 * \endcode
 * \param argc  argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
 * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
 * \param key   option key to be find
 * \return true if option found otherwise false
 */
bool cmd_has_option(int argc, char *argv[], const char *key);
/** find command parameter by key.
 * if exists, return true, otherwise false.
 * e.g. cmd: "mycmd enable 1"
 * \code
  int mycmd_command(int argc, char *argv[]) {
        bool value;
        bool found = cmd_parameter_bool( argc, argv, "mykey", &value );
        if( found ) return CMDLINE_RETCODE_SUCCESS;
        else return CMDLINE_RETCODE_FAIL;
    }
 * \endcode
 * \param argc  argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
 * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
 * \param key   parameter key to be find
 * \param value parameter value to be fetch, if key not found value are untouched. "1" and "on" and "true" and "enable" and "allow" are True -value, all others false.
 * \return true if parameter key and value found otherwise false
 */
bool cmd_parameter_bool(int argc, char *argv[], const char *key, bool *value);
/** find command parameter by key and return value (next parameter).
 * if exists, return parameter pointer, otherwise null.
 * e.g. cmd: "mycmd mykey myvalue"
 * \code
    int mycmd_command(int argc, char *argv[]) {
        char *value;
        bool found = cmd_parameter_val( argc, argv, "mykey", &value );
        if( found ) return CMDLINE_RETCODE_SUCCESS;
        else return CMDLINE_RETCODE_FAIL;
    }
 * \endcode
 * \param argc  argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
 * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
 * \param key   parameter key to be find
 * \param value pointer to pointer, which will point to cli input data when key and value found. if key or value not found this parameter are untouched.
 * \return true if parameter key and value found otherwise false
 */
bool cmd_parameter_val(int argc, char *argv[], const char *key, char **value);
/** find command parameter by key and return value (next parameter) in integer. Only whitespaces are allowed in addition to the float to be read.
 * e.g. cmd: "mycmd mykey myvalue"
 * \code
     int32_t value;
     cmd_parameter_int( argc, argv, "key", &value );
 * \endcode
 * \param argc  argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the item 0 in the list argv is a string to name of command.
 * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
 * \param key   parameter key to be found
 * \param value A pointer to a variable where to write the converted number. If value cannot be converted, it is not touched.
 * \return true if parameter key and an integer is found, otherwise return false
 */
bool cmd_parameter_int(int argc, char *argv[], const char *key, int32_t *value);
/** find command parameter by key and return value (next parameter) in float. Only whitespaces are allowed in addition to the float to be read.
 * e.g. cmd: "mycmd mykey myvalue"
 * \code
     float value;
     cmd_parameter_float( argc, argv, "key", &value );
 * \endcode
 * \param argc  argc is the count of arguments given in argv pointer list. values begin from 1 and this means that the item 0 in the list argv is a string to name of command.
 * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
 * \param key   parameter key to be found
 * \param value A pointer to a variable where to write the converted number. If value cannot be converted, it is not touched.
 * \return true if parameter key and a float found, otherwise return false
 */
bool cmd_parameter_float(int argc, char *argv[], const char *key, float *value);
/** Get last command line parameter as string.
 * e.g.
 *     cmd: "mycmd hello world"
 *     cmd_parameter_last -> "world"
 *     cmd: "mycmd"
 *     cmd_parameter_last() -> NULL
 * \code
    cmd_parameter_last(argc, argv)
 * \endcode
 * \param argc  argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
 * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
 * \return pointer to last parameter or NULL when there is no any parameters.
 */
char *cmd_parameter_last(int argc, char *argv[]);

/** find command parameter by key and return value (next parameter) in int64.
 * e.g. cmd: "mycmd mykey myvalue"
 * \code
     uint32_t i;
     cmd_parameter_timestamp( argc, argv, "mykey", &i );
 * \endcode
 *
 * Supports following formats:
 *  number -> direct conversion
 *  11:22:33:44:55:66:77:88 -> converts to number
 *  seconds,tics -> converts thread type timestamp to int64
 *
 * \param argc  argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
 * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
 * \param key   parameter key to be find
 * \param value parameter value to be fetch, if key not found value are untouched.
 * \return true if parameter key and value found otherwise false
 */
bool cmd_parameter_timestamp(int argc, char *argv[], const char *key, int64_t *value);

#ifdef __cplusplus
}
#endif
#endif /*_CMDLINE_H_*/
