InputHandler.h

Include dependency graph for InputHandler.h:

This graph shows which files directly or indirectly include InputHandler.h:

InputHandler library header file.

Author

Douglas Quigg (dstroy0 dquigg123@gmail.com)

Version

1.2

Date

2023-02-06

Copyright

Copyright (c) 2022

namespace ih

User facing namespace.

class Command

#include <InputHandler.h>

Collaboration diagram for ih::Command:

Pointers to information about the command and the linked-list.

The purpose of this class is to set up the command for use with Input::addCommand(). It contains a pointer to the next command in the singly-linked-list which is NULL before the command is accepted into the process, a pointer to Parameters in PROGMEM, the length of the parameters array, the depth of the command tree you desire to add to the list, and a pointer to CommandRunTimeCalc if this command contains wildcard commands.

Public Functions

inline Command(const Parameters *parameters, const max_cmds_per_tree parameter_array_elements = 1, const max_tree_depth_per_cmd tree_depth = 0)

Constructor method.

Linked-list primer: https://www.programiz.com/dsa/linked-list

These are chained together as a linked-list; this object contains a reference to the next node in the linked-list. The list is linked together each call to Input::addCommand().

Before using, construct a Input object and a Parameters object.

Parameters:

• parameters – pointer to parameters struct or array of parameters structs

• parameter_array_elements – number of elements in the parameter array

• tree_depth – depth of command tree

Public Members

const Parameters *prm

pointer to PROGMEM Parameters array

const max_cmds_per_tree param_array_len

user input param array len, either as digits or through nprms

const max_cmds_per_tree tree_depth

user input depth + 1

CommandRuntimeCalc *calc

pointer to CommandRuntimeCalc struct

Command *next_command

Command iterator/pointer.

class Input

#include <InputHandler.h>

Collaboration diagram for ih::Input:

Parses user input, formats an output buffer if defined.

This class contains methods that deal with parsing user input by looking for “interesting” predefined combinations of 0-255 char values, and formatting an output buffer with useful human readable information.

Public Functions

inline Input(const InputParameters *input_prm = NULL, char *output_buffer = NULL, size_t output_buffer_len = 0)

Input constructor, no output by default.

Input has no output by default due to the default values passed in by the constructor. The constructor disables output by setting Input::output_enabled to false if output_buffer is NULL.

Parameters:

• input_prm – InputParameters PROGMEM pointer. NULL by default, which makess the ctor use ihc::default_parameters.

• output_buffer – class output char buffer, implementation specific. NULL by default.

• output_buffer_len – size of output_buffer, use buffsz() to prevent accidental buffer sizing errors.

void defaultFunction(void (*function)(Input*))

Sets Input::default_function. When there is no command match, or when input is invalid, this function is called if Input::default_function is not NULL.

The pointer to Input gives you access to ih::Input’s public methods inside of your defaultFunction(). such as Input::listSettings() lists settings and Input::listCommands() lists commands among many other options for redirection or debugging.

Input::defaultfunction source

Parameters:

function – a pointer to a user specified function to use as the default function with the format of void (*function)(Input*).

void addCommand(Command &command)

Adds user commands to the input process.

This function inspects the input parameters for errors and reports the errors to the user if the user has enabled output by defining an output buffer when instantiating Input. If an error is detected, the entire command tree is rejected.

No further action is taken by ih::Input, it will not recognize the root commandString.

Input::addCommand source

Parameters:

command – reference to Command object

bool begin()

Allocates memory to run the input process.

Allocates memory for: Input::data_pointers Input::input_type_match_flags

sets Input::begin to true if successful.

Input::begin source

Returns:

true if allocation successful

Returns:

false if allocation unsuccessful

void listSettings()

Lists Input class settings, useful for implementation debugging.

Lists class configuration, constructor variables, and the amount of pointers that were dynamically allocated in Input::begin().

REQUIRES an output_buffer. If an insufficient buffer size is declared, Input::ihout() will first empty the output buffer and then warn the user to increase the buffer to the required size.

Input::listSettings source

void listCommands()

Lists commands available to the user.

Lists commands that will respond to user input if Input::begin is true. Else it will inform the user to use Input::begin() in setup().

Input::listCommands source

void readCommandFromBuffer(uint8_t *data, size_t len, const size_t num_zdc = 0, const Parameters **zdc = NULL)

Reads predefined command(s) from a buffer.

Input::readCommandFromBuffer() source

Warning

This function will silent return if Input::begin is false!

Parameters:

• data – a buffer with characters

• len – the size of the buffer

• num_zdc – size of Parameters zero delimiter command pointers array

• zdc – array of Parameters zero delimiter command pointers

void getCommandFromStream(Stream &stream, size_t rx_buffer_size = 128, const size_t num_zdc = 0, const Parameters **zdc = NULL)

Gets bytes from a Stream object and feeds a buffer to readCommandFromBuffer.

Stream object reference

Input::getCommandFromStream() source

Warning

This function will silent return if Input::begin is false!

Parameters:

• stream – the stream to reference

• rx_buffer_size – the size of our receive buffer

• num_zdc – size of Parameters zero delimiter command pointers array

• zdc – array of Parameters zero delimiter command pointers

char *nextArgument()

Returns a pointer to the next token in Input::token_buffer.

Returns NULL if no more tokens were parsed.

Input::nextArgument() source

Returns:

valid pointer if there is another token else NULL.

char *getArgument(size_t argument_number)

Returns a pointer to argument_number token in Input::token_buffer

Returns NULL if argument_number’s token doesn’t exist.

Input::getArgument() source

Parameters:

argument_number – The argument number to retrieve.

Returns:

valid pointer if argument_number exists else NULL.

size_t outputIsAvailable()

Output is available from Input if True.

(True) if greater than 0 (False) if 0

Input::outputIsAvailable() source

Returns:

The number of bytes available for output, or zero if there is no output available.

inline bool outputIsEnabled()

Input output flag.

Input::outputIsAvailable() source

Returns:

true if enabled

Returns:

false if not enabled

void outputToStream(Stream &stream)

Direct Input output to a Stream.

This also clears the output buffer automatically after writing to the Stream is complete.

Input::outputToStream() source

Parameters:

stream – The Stream to write to.

inline void clearOutputBuffer(bool overwrite_contents = false)

Clears the output buffer if defined.

Soft clear by default, writes null to the first char in the output buffer.

Input::outputIsAvailable() source

Parameters:

overwrite_contents – boolean switch, clearOutputBuffer(true) writes null to entire Input::output_buffer

size_t getTokens(getTokensParam &gtprm, const InputParameters &input_prm)

Puts tokens into the token buffer pointed to by the input Input::getTokensParam.

To use this function outside of Input you must declare a Input::getTokensParam.

This can be used with different InputParameters than the ones provided to the Input Constructor method.

Input::getTokens() source

Parameters:

• gtprm – Input::getTokensParam struct reference

• input_prm – reference to InputParameters struct

Returns:

size_t number of tokens retrieved

inline bool validateNullSepInput(validateNullSepInputParam &vprm)

Tries to determine if input is valid in NULL TERMINATED char arrays.

Input::validateNullSepInput() source

Parameters:

vprm – validateNullSepInputParam struct reference

Returns:

true argument-type is valid

Returns:

false argument-type is not valid

inline size_t mIndex(size_t m_width, size_t row, size_t col) const

Transform 2d matrix indices to flat array index.

Use this to access a dynamically allocated array like a 2d matrix, this is much more performant than looping to allocate a (n>1)d array, and looping again to free allocated ram.

// usage
#include <InputHandler.h>
size_t matrix_index = Input::mIndex(0,0,0);

// source
size_t mIndex(size_t m_width, size_t row, size_t col) const { return row * m_width + col; }

Parameters:

• m_width; –

• row – row you want to access

• col – column you want to access

Returns:

size_t the transformed index

void ihout(const char *fmt, ...)

Input vsnprintf https://www.cplusplus.com/reference/cstdio/vsprintf/.

Input::ihout() source

Puts the message into the defined output buffer.

Parameters:

• fmt – the format string

• ... – arguments

Private Functions

void _readCommandFromBufferErrorOutput(_rcfbprm &rprm)

ReadCommandFromBuffer error output.

Input::_readCommandFromBufferErrorOutput() source

Parameters:

rprm – reference to Input::_rcfbprm

inline void _launchFunction(_rcfbprm &rprm, const ProcessName &process_name)

launches either (this) function or the root command function

Input::_launchFunction() source

Parameters:

• rprm – reference to Input::_rcfbprm

• process_name – ProcessName char array

void _launchLogic(_rcfbprm &rprm)

function launch logic, recursive on subcommand match

Input::_launchLogic() source

Parameters:

rprm – reference to Input::_rcfbprm

inline char *_escapeCharactersSoTheyPrint(char input, char *buf)

Escapes control characters so they will print.

Input::_escapeCharactersSoTheyPrint() source

Parameters:

• input – the input char

• buf – the output buffer

Returns:

pointer to buf, so you can use this inside of ihout()

inline char _combineControlCharacters(char input)

Triggers on the input a control character sequence.

If the char immediately after the control char is a char known to Input::_combineControlCharacters this returns a control char, else it returns the input char.

Input::_combineControlCharacters() source

Parameters:

input – the char the control character sequence

Returns:

the control character char value

bool _addCommandErrorMessage(ihc::CMD_ERR_IDX error, char *cmd)

prints detected Parameters errors

Parameters:

• error – ihc::CMD_ERR_IDX member

• cmd – null term char array

Returns:

true never

Returns:

false each call

bool _addCommandAbort(Command &cmd, Parameters &prm)

determines if input Parameters struct is valid before adding to linked-list

Input::_addCommandAbort() source

Parameters:

• cmd – Command reference

• prm – reference to Parameters struct in addCommand

Returns:

true if there are no errors

Returns:

false if there were one or more errors

inline UITYPE _getArgType(Parameters &prm, size_t index = 0)

Get the UITYPE equivalent for the argument, internally we use uint8_t.

Input::_getArgType() source

Parameters:

• prm – command options structure reference

• index – argument number

Returns:

UITYPE argument type

void _getArgs(_rcfbprm &rprm)

validate the arguments as specified in the user defined Parameters struct

Input::_getArgs() source

Parameters:

rprm – reference to Input::_rcfbprm

char *_addEscapedControlCharToBuffer(char *buf, size_t &idx, const char *input, size_t input_len)

adds escaped control characters to a buffer

Input::_addEscapedControlCharToBuffer() source

Parameters:

• buf – output buffer

• idx – buffer index

• input – string to escape

• input_len – length of string

Returns:

pointer to null terminated escaped control char string

inline void _getTokensDelimiters(getTokensParam &gtprm, const InputParameters &input_prm)

find delimiters in input data

Input::_getTokensDelimiters() source

Parameters:

• gtprm – reference to getTokensParam struct in getTokens

• input_prm – reference to InputParameters struct

inline void _getTokensStartStop(getTokensParam &gtprm, const InputParameters &input_prm)

get delimited c-strings from input data

Input::_getTokensStartStop() source

Parameters:

• gtprm – reference to getTokensParam struct in getTokens

• input_prm – reference to InputParameters struct

void _getTokensChar(getTokensParam &gtprm, const InputParameters &input_prm)

add uchar to token_buffer

Input::_getTokensChar() source

Parameters:

• gtprm – reference to getTokensParam struct in getTokens

• input_prm – reference to InputParameters struct

inline bool _splitZDC(_rcfbprm &rprm, const size_t num_zdc, const Parameters **zdc)

split a zero delimiter command, separate command and string with token delimiter for further processing

Input::_splitZDC() source

Parameters:

• rprm – reference to Input::_rcfbprm

• num_zdc – zero delim commands

• zdc – num zdc

Returns:

true if split

Returns:

false no match no split

void _calcCmdMemcmpRanges(Command &command, Parameters &prm, size_t prm_idx, memcmp_idx_t &memcmp_ranges_idx, max_per_root_memcmp_ranges *memcmp_ranges)

calculates memcmp ranges for a given command around wildcard char, noninclusive

Input::_calcCmdMemcmpRanges source

Parameters:

• command – reference to a Command class

• prm – reference to a Parameters struct

• prm_idx – prm index

• memcmp_ranges_idx – index of memcmp_ranges

• memcmp_ranges – memcmp ranges array

inline UI_COMPARE _compareCommandToString(Command *cmd, size_t prm_idx, char *str)

compares (memcmp) str to cmd->prm[prm_idx].command

Input::_compareCommandToString source

Parameters:

• cmd – pointer to Command

• prm_idx – index of Parameters to compare

• str – c-string

Returns:

UI_COMPARE match type

bool _fatalError(ihc::VAR_ID var_id = ihc::VAR_ID::_reserved)

lib fatal error

Parameters:

var_id – _reserved by default, else prints fatal allocation message for var_id

Returns:

true if begin not set or halt is set or var_id != _reserved

Returns:

false on fallthrough

Private Members

const InputParameters *_input_prm_ptr_

user input constructor parameters pointer

char *_output_buffer_

pointer to the output char buffer

const size_t _output_buffer_len_

Input::output_buffer size in bytes.

bool _output_enabled_

true if Input::output_buffer is not NULL (the user has defined and passed an output buffer to Input’s constructor)

size_t _output_buffer_bytes_left_

index of Input::output_buffer, messages are appended to the output buffer and this keeps track of where to write to next without overwriting

uint8_t _term_len_

term length in characters, determined in Input::Input().

uint8_t _term_index_

term index, match all characters in term or reject input.

void (*_default_function_)(Input*)

pointer to the default function.

Command *_commands_head_

pointer to Command singly-linked-list head.

Command *_commands_tail_

pointer to Command singly-linked-list tail.

max_cmds_per_tree _commands_count_

How many commands were accepted from input Parameters.

max_tree_depth_per_cmd _max_depth_

Max command depth found in the accepted input Parameters.

max_args_per_cmd _max_args_

Max command or subcommand arguments found in the accepted input Parameters.

type_match_flags *_input_type_match_flags_

Bool array the size of Input::max_args.

bool _output_flag_

Output is available flag, set by member functions.

char *_token_buffer_

pointer to tokenized c-string

char **_data_pointers_

token_buffer pointers

max_args_per_cmd _data_pointers_index_

data_pointer index

max_args_per_cmd _data_pointers_index_max_

data_pointer index max

max_args_per_cmd _p_num_ptrs_

Input process number of pointers, computed in Input::begin().

max_args_per_cmd _rec_num_arg_strings_

number of tokens after first valid token

max_num_child_cmds _failed_on_subcommand_

subcommand error index

max_tree_depth_per_cmd _current_search_depth_

current subcommand search depth

char _null_

char null

char _neg_

char ‘-’

char _dot_

char ‘.’

bool _stream_buffer_allocated_

this flag is set true on GetCommandFromStream entry if a buffer is not allocated

bool _new_stream_data_

if there is new data in *stream_data this is true

uint8_t *_stream_data_

pointer to stream input, a string of char

uint16_t _stream_data_index_

the index of stream_data

bool _begin_

begin() error flag

bool _halt_

fatal error flag

InputParameters _input_prm_

user input process parameters pointer struct

struct _rcfbprm

Collaboration diagram for ih::Input::_rcfbprm:

Used internally by Input::readCommandFromBuffer() and passed by reference.

Instantiated in Input::readCommandFromBuffer() and passed by reference to subfunctions.

Public Members

bool launch_attempted

function launch attempted if true

bool command_matched

matched root command if true

bool all_arguments_valid

argument error sentinel

bool subcommand_matched

matched a subcommand

Command *cmd

pointer to Command

Command *all_wcc_cmd

pointer to Command

UI_COMPARE result

result of Input::_compareCommandToString()

cmd_id_grp command_id

type set by macro

size_t idx

Parameters index.

size_t all_wcc_idx

index of Parameters that has an all wcc command

size_t input_len

length of input data

size_t token_buffer_len

length of token buffer

size_t tokens_received

how many tokens we received

Parameters prm

Parameters struct.

uint8_t *input_data

pointer to input_data

uint8_t *split_input

pointer to Input::_splitZDC() modified data

struct getTokensParam

#include <InputHandler.h>

Input::getTokens() input data structure.

Public Members

uint8_t *data

pointer to uint8_t array

size_t len

length of uint8_t array

size_t data_pos

index of data

char *token_buffer

pointer to null terminated char array

size_t token_buffer_len

size of data + 1 + 1(if there are zero delim commands)

size_t token_buffer_index

index of token_buffer

size_t num_token_ptrs

token_pointers[MAX]

uint8_t &token_pointer_index

index of token_pointers

char **token_pointers

array of token_buffer pointers

bool point_to_beginning_of_token

assign pointer to &token_buffer[token_buffer_index] if true

char &token_buffer_sep

token_buffer token delimiter

struct validateNullSepInputParam

#include <InputHandler.h>

null separated input

Public Members

UITYPE arg_type

the UITYPE to test

char **token_pointers

pointers to null separated tokens

size_t token_pointer_index

index of token_pointers to test

char &neg_sign

single char neg sign, if different than ‘-’ parseInt and the like will not assign your input negative

char &float_sep

whole and fraction separator

struct Parameters

#include <InputHandler.h>

Command parameters setup.

Every command and subcommand has an associated Parameters object, this is the information that the input process needs to know about your command.

Public Members

void (*function)(Input*)

void function pointer, void your_function(Input *inputProcess)

bool has_wildcards

if true this command has one or more wildcard char

char command[32 + 1U]

command string + nullchar

max_cmd_str_len command_length

command length in characters

cmd_id_grp parent_command_id

parent command’s unique id root-MAX

cmd_id_grp command_id

this command’s unique id root-MAX

max_tree_depth_per_cmd depth

command tree depth root-MAX

max_num_child_cmds sub_commands

how many subcommands does this command have 0 - UI_MAX_SUBCOMMANDS

UI_ARG_HANDLING argument_flag

argument handling flag

max_args_per_cmd num_args

minimum number of arguments this command expects 0 - UI_MAX_ARGS

max_args_per_cmd max_num_args

maximum number of arguments this command expects 0 - UI_MAX_ARGS, cannot be less than num_args

UITYPE arg_type_arr[32]

argument UITYPE array