AceUtils  0.3
Useful Arduino utilties which are too small as separate libraries, but complex enough to have external dependencies to other libraries.
Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
cli::CommandDispatcher Class Reference

A coroutine that reads lines from the Serial port, tokenizes the line on whitespace boundaries, and calls the appropriate command handler to handle the command. More...

#include <CommandDispatcher.h>

Inheritance diagram for cli::CommandDispatcher:
Inheritance graph
[legend]
Collaboration diagram for cli::CommandDispatcher:
Collaboration graph
[legend]

Public Member Functions

 CommandDispatcher (ace_routine::Channel< InputLine > &channel, Print &printer, const CommandHandler *const *commands, uint8_t numCommands, const char **argv, uint8_t argvSize, const char *prompt)
 Constructor. More...
 
virtual ~CommandDispatcher ()
 Destructor. More...
 
int runCoroutine () override
 
const CommandHandlerfindCommand (const char *cmd) const
 Find the CommandHandler of the given command name. More...
 

Static Public Member Functions

static uint8_t tokenize (char *line, const char **argv, uint8_t argvSize)
 Tokenize the line, separating tokens delimited by whitespace (space, formfeed, carriage return, newline, tab, and vertical tab) and fill argv with each token until argvSize is reached. More...
 

Protected Member Functions

 CommandDispatcher (const CommandDispatcher &)=delete
 
CommandDispatcheroperator= (const CommandDispatcher &)=delete
 
void printLineError (const char *line, uint8_t statusCode) const
 Print the input line that caused an error along with its status code.
 
void helpCommandHandler (Print &printer, int argc, const char *const *argv) const
 Handle the 'help' command.
 
void helpAll (Print &printer) const
 Print help on all commands.
 
bool helpSpecific (Print &printer, const char *cmd) const
 Print helpString of specific cmd. More...
 
void runCommand (char *line) const
 Tokenize the given line and run the command handler.
 
void findAndRunCommand (const char *cmd, int argc, const char *const *argv) const
 Find and run the given command.
 

Static Protected Member Functions

static void printHelp (Print &printer, const CommandHandler *command)
 Print help string for the given command.
 

Protected Attributes

ace_routine::Channel< InputLine > & mChannel
 
Print & mPrinter
 
const CommandHandler *const *const mCommands
 
const uint8_t mNumCommands
 
const char **const mArgv
 
const uint8_t mArgvSize
 
const char *const mPrompt
 

Static Protected Attributes

static const uint8_t STATUS_SUCCESS = 0
 
static const uint8_t STATUS_BUFFER_OVERFLOW = 1
 
static const uint8_t STATUS_FLUSH_TO_EOL = 2
 
static const char DELIMS [] = " \f\r\n\t\v"
 

Detailed Description

A coroutine that reads lines from the Serial port, tokenizes the line on whitespace boundaries, and calls the appropriate command handler to handle the command.

Command have the form "command arg1 arg2 ...", where the 'arg*' can be any string.

The calling code is expected to provide a mapping of the command string (e.g. "list") to its command handler (CommandHandler). The CommandHandler is called with the number of arguments (argc) and the array of tokens (argv), just like the arguments of the C-language main() function.

The template parameters can be either a 'char' for C-strings or '__FlashStringHelper' for F() flash strings.

Definition at line 51 of file CommandDispatcher.h.

Constructor & Destructor Documentation

◆ CommandDispatcher()

cli::CommandDispatcher::CommandDispatcher ( ace_routine::Channel< InputLine > &  channel,
Print &  printer,
const CommandHandler *const *  commands,
uint8_t  numCommands,
const char **  argv,
uint8_t  argvSize,
const char *  prompt 
)
inline

Constructor.

Parameters
channelA channel from the StringLineReader to this coroutine.
printerThe output object, normally the global Serial object.
commandsArray of CommandHandler pointers.
numCommandsnumber of commands.
argvArray of (const char*) that will be used to hold the word tokens of a command line string.
argvSizeThe size of the argv array. Tokens which are beyond this limit will be silently dropped.
promptIf not null, print a prompt and echo the command entered by the user. If null, don't print prompt and don't echo.

Definition at line 67 of file CommandDispatcher.h.

◆ ~CommandDispatcher()

virtual cli::CommandDispatcher::~CommandDispatcher ( )
inlinevirtual

Destructor.

Used only in unit tests.

Definition at line 84 of file CommandDispatcher.h.

Member Function Documentation

◆ findCommand()

const CommandHandler* cli::CommandDispatcher::findCommand ( const char *  cmd) const
inline

Find the CommandHandler of the given command name.

VisibleForTesting.

NOTE: this is currently a linear O(N) scan which is good enough for small number of commands. If we sorted the handlers, we could do a binary search for O(log(N)) and handle larger number of commands.

Definition at line 134 of file CommandDispatcher.h.

◆ helpSpecific()

bool cli::CommandDispatcher::helpSpecific ( Print &  printer,
const char *  cmd 
) const
protected

Print helpString of specific cmd.

Returns true if cmd was found.

Definition at line 84 of file CommandDispatcher.cpp.

◆ tokenize()

static uint8_t cli::CommandDispatcher::tokenize ( char *  line,
const char **  argv,
uint8_t  argvSize 
)
inlinestatic

Tokenize the line, separating tokens delimited by whitespace (space, formfeed, carriage return, newline, tab, and vertical tab) and fill argv with each token until argvSize is reached.

Return the number of tokens filled in.

VisibleForTesting.

Definition at line 94 of file CommandDispatcher.h.


The documentation for this class was generated from the following files: