AceRoutine  0.2
A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.
Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
ace_routine::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 ace_routine::cli::CommandDispatcher:
Inheritance graph
[legend]
Collaboration diagram for ace_routine::cli::CommandDispatcher:
Collaboration graph
[legend]

Public Member Functions

 CommandDispatcher (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...
 
virtual int runCoroutine () override
 The body of the coroutine. More...
 
const CommandHandlerfindCommand (const char *cmd) const
 Find the CommandHandler of the given command name. More...
 
- Public Member Functions inherited from ace_routine::Coroutine
Coroutine ** getNext ()
 Return the next pointer as a pointer to the pointer, similar to getRoot(). More...
 
const FCStringgetName () const
 Human-readable name of the coroutine. More...
 
virtual unsigned long millis () const
 Returns the current millisecond clock. More...
 
void suspend ()
 Suspend the coroutine at the next scheduler iteration. More...
 
void resume ()
 Add a Suspended coroutine into the head of the scheduler linked list, and change the state to Yielding. More...
 
bool isDelayExpired ()
 Check if delay time is over. More...
 
bool isSuspended () const
 The coroutine was suspended with a call to suspend(). More...
 
bool isYielding () const
 The coroutine returned using COROUTINE_YIELD(). More...
 
bool isDelaying () const
 The coroutine returned using COROUTINE_DELAY(). More...
 
bool isRunning () const
 The coroutine is currently running. More...
 
bool isEnding () const
 The coroutine returned using COROUTINE_END(). More...
 
bool isTerminated () const
 The coroutine was terminated by the scheduler with a call to setTerminated(). More...
 
bool isDone () const
 The coroutine is either Ending or Terminated. More...
 
void setupCoroutine (const char *name)
 Initialize the coroutine for the CoroutineScheduler, set it to Yielding state, and add it to the linked list of coroutines. More...
 
void setupCoroutine (const __FlashStringHelper *name)
 Same as setupCoroutine(const char*) except using flash string type. 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...
 
- Static Public Member Functions inherited from ace_routine::Coroutine
static Coroutine ** getRoot ()
 Get the pointer to the root pointer. 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. More...
 
void helpCommandHandler (Print &printer, int argc, const char **argv) const
 Handle the 'help' command. More...
 
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. More...
 
void findAndRunCommand (const char *cmd, int argc, const char **argv) const
 Find and run the given command. More...
 
- Protected Member Functions inherited from ace_routine::Coroutine
 Coroutine ()
 Constructor. More...
 
Status getStatus () const
 Return the status of the coroutine. More...
 
void statusPrintTo (Print &printer)
 Print the human-readable string of the Status. More...
 
void setJump (void *jumpPoint)
 Pointer to label where execute will start on the next call to runCoroutine().
 
void * getJump () const
 Pointer to label where execute will start on the next call to runCoroutine().
 
void setRunning ()
 Set the kStatusRunning state. More...
 
void setYielding ()
 Set the kStatusDelaying state. More...
 
void setDelaying ()
 Set the kStatusDelaying state. More...
 
void setDelay (uint16_t delayMillisDuration)
 Configure the delay timer. More...
 
void setEnding ()
 Set the kStatusEnding state. More...
 
void setTerminated ()
 Set status to indicate that the Coroutine has been removed from the Scheduler queue. More...
 

Static Protected Member Functions

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

Protected Attributes

Channel< InputLine > & mChannel
 
Print & mPrinter
 
const CommandHandler *const *const mCommands
 
uint8_t const mNumCommands
 
const char **const mArgv
 
uint8_t const 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"
 
- Static Protected Attributes inherited from ace_routine::Coroutine
static const Status kStatusSuspended = 0
 Coroutine has been suspended using suspend() and the scheduler should remove it from the queue upon the next iteration. More...
 
static const Status kStatusYielding = 1
 Coroutine returned using the COROUTINE_YIELD() statement. More...
 
static const Status kStatusDelaying = 2
 Coroutine returned using the COROUTINE_DELAY() statement. More...
 
static const Status kStatusRunning = 3
 Coroutine is currenly running. More...
 
static const Status kStatusEnding = 4
 Coroutine executed the COROUTINE_END() statement. More...
 
static const Status kStatusTerminated = 5
 Coroutine has ended and no longer in the scheduler queue. More...
 

Additional Inherited Members

- Protected Types inherited from ace_routine::Coroutine
typedef uint8_t Status
 The execution status of the coroutine, corresponding to the COROUTINE_YIELD(), COROUTINE_DELAY(), COROUTINE_AWAIT() and COROUTINE_END() macros. More...
 

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 52 of file CommandDispatcher.h.

Constructor & Destructor Documentation

◆ CommandDispatcher()

ace_routine::cli::CommandDispatcher::CommandDispatcher ( 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 68 of file CommandDispatcher.h.

◆ ~CommandDispatcher()

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

Destructor.

Used only in unit tests.

Definition at line 85 of file CommandDispatcher.h.

Member Function Documentation

◆ findAndRunCommand()

void ace_routine::cli::CommandDispatcher::findAndRunCommand ( const char *  cmd,
int  argc,
const char **  argv 
) const
protected

Find and run the given command.

Definition at line 122 of file CommandDispatcher.cpp.

◆ findCommand()

const CommandHandler* ace_routine::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 135 of file CommandDispatcher.h.

◆ helpCommandHandler()

void ace_routine::cli::CommandDispatcher::helpCommandHandler ( Print &  printer,
int  argc,
const char **  argv 
) const
protected

Handle the 'help' command.

Definition at line 55 of file CommandDispatcher.cpp.

◆ helpSpecific()

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

Print helpString of specific cmd.

Returns true if cmd was found.

Definition at line 85 of file CommandDispatcher.cpp.

◆ printHelp()

void ace_routine::cli::CommandDispatcher::printHelp ( Print &  printer,
const CommandHandler command 
)
staticprotected

Print help string for the given command.

Definition at line 95 of file CommandDispatcher.cpp.

◆ printLineError()

void ace_routine::cli::CommandDispatcher::printLineError ( const char *  line,
uint8_t  statusCode 
) const
protected

Print the input line that caused an error along with its status code.

Definition at line 39 of file CommandDispatcher.cpp.

◆ runCommand()

void ace_routine::cli::CommandDispatcher::runCommand ( char *  line) const
protected

Tokenize the given line and run the command handler.

Definition at line 107 of file CommandDispatcher.cpp.

◆ runCoroutine()

virtual int ace_routine::cli::CommandDispatcher::runCoroutine ( )
inlineoverridevirtual

The body of the coroutine.

The COROUTINE macro creates a subclass of this class and puts the body of the coroutine into this method.

Returns
The return value is always ignored. This method is declared to return an int to prevent the user from accidentally returning from this method using an explicit 'return' statement instead of through one of the macros (e.g. COROUTINE_YIELD(), COROUTINE_DELAY(), COROUTINE_AWAIT() or COROUTINE_END()).

Implements ace_routine::Coroutine.

Definition at line 106 of file CommandDispatcher.h.

◆ tokenize()

static uint8_t ace_routine::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 95 of file CommandDispatcher.h.


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