AceRoutine  0.1
A low-memory, fast-switching, cooperative multitasking library using stackless coroutines on Arduino platforms.
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
ace_routine::cli::CommandDispatcher Class Referenceabstract

Base-class of 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 (StreamReader &streamReader, Print &printer, uint8_t numCommands, const char **argv, uint8_t argvSize)
 Constructor. 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 isAwaiting () const
 The coroutine returned using COROUTINE_AWAIT(). 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...
 

Static Public Member Functions

static uint8_t tokenize (char *line, const char **argv, uint8_t argvSize)
 Tokenize the line, 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)
 Print the error caused by the given line. More...
 
void helpCommandHandler (Print &printer, int argc, const char **argv)
 Handle the 'help' command. More...
 
virtual void helpGeneric (Print &printer)=0
 Print generic help. More...
 
virtual bool helpSpecific (Print &printer, const char *cmd)=0
 Print helpString of specific cmd. More...
 
void runCommand (char *line)
 Tokenize the given line and run the command handler. More...
 
virtual void findAndRunCommand (const char *cmd, int argc, const char **argv)=0
 Find and run the given command. More...
 
virtual int run () override
 The body of the coroutine. More...
 
- Protected Member Functions inherited from ace_routine::Coroutine
 Coroutine ()
 Constructor. More...
 
void init (const char *name)
 Initialize the coroutine, set it to Yielding state, and add it to the linked list of coroutines. More...
 
void init (const __FlashStringHelper *name)
 Same as init(const char*) except using flash string type. More...
 
Status getStatus () const
 Return the status of the coroutine. More...
 
void setJump (void *jumpPoint)
 Pointer to label where execute will start on the next call to run(). More...
 
void * getJump () const
 Pointer to label where execute will start on the next call to run(). More...
 
void setRunning ()
 Set the kStatusRunning state. More...
 
void setYielding ()
 Set the kStatusDelaying state. More...
 
void setAwaiting ()
 Set the kStatusAwaiting 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...
 

Protected Attributes

StreamReadermStreamReader
 
Print & mPrinter
 
const uint8_t mNumCommands
 
const char **const mArgv
 
const uint8_t mArgvSize
 

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 [] = " \t\n"
 
- 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 kStatusAwaiting = 2
 Coroutine returned using the COROUTINE_AWAIT() statement. More...
 
static const Status kStatusDelaying = 3
 Coroutine returned using the COROUTINE_DELAY() statement. More...
 
static const Status kStatusRunning = 4
 Coroutine is currenly running. More...
 
static const Status kStatusEnding = 5
 Coroutine executed the COROUTINE_END() statement. More...
 
static const Status kStatusTerminated = 6
 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

Base-class of 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.

Use the CommandDispatcherC subclass if the DispatchRecordC class with C-strings is used.

Use the CommandDispatcherF subclass if the DispatchRecordF class with FlashStrings are used.

Definition at line 77 of file CommandDispatcher.h.

Constructor & Destructor Documentation

◆ CommandDispatcher()

ace_routine::cli::CommandDispatcher::CommandDispatcher ( StreamReader streamReader,
Print &  printer,
uint8_t  numCommands,
const char **  argv,
uint8_t  argvSize 
)
inline

Constructor.

Parameters
streamReaderAn instance of StreamReader.
printerThe output object, normally the global Serial object.
numCommandsNumber of entries in the dispatchTable.
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.

Definition at line 90 of file CommandDispatcher.h.

Member Function Documentation

◆ findAndRunCommand()

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

Find and run the given command.

◆ helpCommandHandler()

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

Handle the 'help' command.

Definition at line 49 of file CommandDispatcher.cpp.

◆ helpGeneric()

virtual void ace_routine::cli::CommandDispatcher::helpGeneric ( Print &  printer)
protectedpure virtual

Print generic help.

◆ helpSpecific()

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

Print helpString of specific cmd.

Returns true if cmd was found.

◆ printLineError()

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

Print the error caused by the given line.

Definition at line 33 of file CommandDispatcher.cpp.

◆ run()

int ace_routine::cli::CommandDispatcher::run ( )
overrideprotectedvirtual

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 97 of file CommandDispatcher.cpp.

◆ runCommand()

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

Tokenize the given line and run the command handler.

Definition at line 70 of file CommandDispatcher.cpp.

◆ tokenize()

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

Tokenize the line, and fill argv with each token until argvSize is reached.

Return the number of tokens. VisibleForTesting.

Definition at line 85 of file CommandDispatcher.cpp.


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