#ifndef SCPI_COMMANDS_H
#define SCPI_COMMANDS_H
    #include <stdbool.h>
    #include "app/fseq/fseq.h"
    #include "app/scpi/scpi_base.h" // eScpiStatus_t
    #include "app/tlst/tree_list.h" // sTreeList_t

    // @scpi_commands_root
    // Entire the supported SCPI commands tree.
    extern const sTreeList_t scpi_commands_root_node;

    // ==============================================================================================
    // @scpiSearchCommandHandler
    // Searches for the registered SCPI-command handler for the
    // ... command specified by pair of @shead and @stail.
    // @proot - pointer to the root element pointer to search in, neither the 
    // ... @proot nor the value referred by @proot can not be NULL;
    // @shead - string head (begining), can not be NULL;
    // @stail - string tail (ending), can not be NULL;
    // @cmdType - the command header type, see @eScpiEntityType_t.
    // @pFoundHandler - pointer to the string token structure to store found handler mnemonic (optional);
    // @bRememberOverride - force remember last successful branch;
    // Returns: the command handler entry pointer in success case, 
    // ... and NULL in case no command handler found or on error condition.
    // Note: pair of @shead and @stail shall represent a valid SCPI Command 
    // ... Program Header ("7.6.1 <COMMAND PROGPRAM HEADER>", [1]), processed
    // ... by @parseCommandProgramHeader function.
    // Note: if this call is the first one for the request, the @bRememberOverride shall be
    // ... true to remember the first subsystem (branch) to search the next commands in.
    // References:
    //    6.2.4 Traversal of the Header Tree, [2]
    //    A.1.1 Use of the Compound Header Rules, [1]
    const sScpiCommandHandlerEntry_t * scpiSearchCommandHandler(
                                               const sTreeList_t * * proot,
                                               const char * shead,
                                               const char * stail, 
                                               uint8_t cmdType,
                                               sStrToken_t * pFoundHandler,
                                               bool bRememberOverride );

    // ==============================================================================================
    // @processCharacterArgument
    // Argument Validation Function
    // Processes specified SCPI Character Parameter (Character Program Data) and searches it in the allowed values list.
    // Function uses smart comparing the source parameter to each one of the list allowing short and long form of value. 
    // References:
    //     "7.7.1 <CHARACTER PROGRAM DATA>", [1]
    //     "7.7.1.2 Encoding Syntax", [1]
    // @allowedList - values allowed list, use @DECLARE_ARGUMENT_CHARACTER_ALLOWED_LIST to create this parameter;
    //  Note 1: each element in the list must be a NULL-terminated string;
    //  Note 2: the list must contain NULL-pointer in the end of list;
    // @arg - parsed argument token filled by @parseArguments (SCPI_PARSE_ARGUMENTS macro)
    // @pIdx - optional pointer to the variable to store index of matched element in the @allowedList array, only valid if
    // the 'true' is returned; only positive number is returned;
    // Return:
    //  - true: parameter processed successfully, passed parameter is valid due to it matchs to
    //  one of the element of allowed list;
    //  - false: parameter fail, passed parameter not recognized or invalid function parameter; 
    bool processCharacterArgument( const xArgument_t * allowedList, const sStrToken_t * arg, int8_t * pIdx );

#endif