-
Notifications
You must be signed in to change notification settings - Fork 7
Commander API Public methods.
Commander();
Commander(uint16_t reservedBuffer)
Constructors. An optional argument can be used to reserve memory for the buffer. The buffer is a String object so the reservedBuffer argument gets used in the String reserve() method.
void begin(Stream *sPort)
void begin(Stream *sPort, const commandList_t *commands, uint32_t size)
void begin(Stream *sPort, Stream *oPort, const commandList_t *commands, uint32_t size)
Initialise Commander with a Stream object for the input and output ports. Commander also needs a command list and a size variable before it can work. Optionally Commander can be initialised with a different output port (oPort). Any data printed using the print and write functions will use this port.
bool update()
Update the Commander object. Commander will copy any new bytes from the inPort to its buffer and try and handle a command if an end of line character is found.
If any data has been loaded into the buffer as a pending command, either by the user, or because of a chain command or autochain, Commander will process this data instead of looking in the stream object for new data.
Returns true if there are bytes available in the stream.
Commander can be locked and unlocked. If an optional passphrase is set then it must be used to unlock the command system.
There are two lock levels, soft or hard. A soft lock allows internal commands to be used and will print help data. A hard lock prevents all internal commands except the unlock command. HARD_LOCK and SOFT_LOCK are defined as macros for true and false.
void setPassPhrase(String& phrase)
Set a String containing the passphrase for the locking system. The passphrase String is passed as a reference and so it is not stored inside Commander so it can be changed at any time by the users code.
void printPassPhrase()
Prints the passphrase to the output port.
void lock()
Locks the command system.
void unlock()
Unlocks the command system.
void setLockType(bool hlState)
Set to ‘HARD_LOCK’ or ‘true’ to use hard locking, or ‘SOFT_LOCK’ or ‘false’ to use soft locking.
bool isLocked()
Returns true if Commander is locked
bool getLockType()
Returns ‘HARD_LOCK’ or ‘true’ if the hard locking is enabled, ‘SOFT_LOCK’ or ‘false’ if soft locking is enabled.
bool feed(Commander& Cmdr)
Feeds another commander object to this one. Commander will then extract any payload from the other Commander and try and process it as a command.
bool hasPayload()
Returns true if the buffer contains a payload - any characters except an end of line character that are found after a valid command is a payload.
String getPayload()
Returns a String containing the payload. The end of line character will be included in the String.
String getPayloadString()
Returns a String containing the payload but with any end of line character removed.
bool feedString(String newString)
Overwrites the buffer with newString before processing the buffer and handling any commands. An end of line character is appended to the string if it is not already there.
void loadString(String newString)
Overwrites the buffer with newString and sets the pending command bit to true. Unlike feedString, the buffer will not be processed immediately. The next call to update() will process the contents of the buffer. An end of line character is appended to the string if it is not already there.
bool endLine()
Appends a newline to the buffer and processes it. This is used when reading files to handle the final line of a file if it does not contain an end of line character.
void startStream()
Start streaming incoming data to a special handler function.
void stopStream()
End the file streaming and return to normal operation
`void setStream(bool streamState) Set the state of the streaming system – on or off.
bool isStreaming()
Returns true if the streaming system is on.
void attachSpecialHandler(cmdHandler handler)
Attach a handler function for streaming or number commands. The function must match the template for command handlers and accept a Commander object as an argument, and return a bool.
void transfer(Commander& Cmdr)
bool transferTo(const commandList_t *commands, uint32_t size, String newName)
void transferBack(const commandList_t *commands, uint32_t size, String newName)
void attachOutputPort(Stream *oPort)
`Stream* getOutputPort()
void attachAltPort(Stream *aPort)
`Stream* getAltPort()
void attachInputPort(Stream *iPort)
Stream* getInputPort()
void deleteAltPort()
void attachDefaultHandler(cmdHandler handler)
void setBuffer(uint16_t buffSize)
void attachCommands(const commandList_t *commands, uint32_t size)
void setStreamType(streamType_t newType)
streamType_t getStreamType()
void quickSetHelp()
bool quickSet(String cmd, int& var)
bool quickSet(String cmd, float& var)
bool quickSet(String cmd, double& var)
void quickGet(String cmd, int var)
void quickGet(String cmd, float var)
These replicate the print and write methods for Stream objects but also handle pre and postfix Strings, and copying to the alt port.
size_t println()
size_t print(printType printableVariable)
size_t print(printType printableVariable, int fmt)
size_t println(printType printableVariable)
size_t println(printType printableVariable, int fmt)
size_t write(printType printableVariable)
size_t write(printType printableVariable, int length)
void setPrefix(String prfx)
Sets the prefix String.
void startPrefix()
Starts applying prefix formatting to the current command (this expires when the command handler returns)
void setPostfix(String pofx)
Sets the postfix String.
void startPostfix()
Starts applying postfix formatting to the current command (this expires when the command handler returns)
void startFormatting()
Starts applying pre and postfix formatting to the current command (this expires when the command handler returns)
void setAutoFormat(bool state)
Sets the state of the autoformat system.
bool getAutoFormat()
Returns the autoformat state.
void printCommandPrompt()
Prints the command prompt to the outPort.
bool containsTrue()
Returns true if the payload contains ‘true’ or ‘TRUE’.
bool containsOn()
Returns true if the payload contains ‘on’ or ‘ON’.
void setCommentChar(char cmtChar)
Sets the character used to mark a like as a comment. Lines starting with this character are ignored. Default is #
void setReloadChar(char reloadChar)
Sets the ‘reload last command’ character. Default is /
void setEndOfLineChar(char eol)
Sets the end of line character that marks the end of a command line. Default is the newline character.
void setPromptChar(char eol)
Sets the command prompt character. Default is >
void setDelimChar(char eol)
Set the delimiter char for identifying the end of a command, and the separation of items in the payload. This char is used in addition to the default (space) character.
void echo(bool sState)
Enable or disable echoing of incoming chars back to the incoming port.
void printComments(bool cState)
Enables comment printing. When enabled and if a line in the buffer starts with a comment character, the buffer will be printed to the outport.
void echoToAlt(bool sState)
Enable or disable echoing incoming bytes to the alt port.
void copyRepyAlt(bool sState)
Enable or disable the copying of any data printed with print(), println() and write() to the alt port.
void commandProcessor(bool state)
Enable or disable the command processor
bool commandProcessor()
Returns the settings bit.
void stripCR(bool sState)
Enable or disable removal of carriage returns from the buffer.
bool stripCR()
Returns the settings bit.
void multiCommander(bool enable)
Enable or disable multi command mode
bool multiCommander()
Returns the settings bit.
void errorMessages(bool state)
Enable or disable internal and error messages
bool errorMessages()
Returns the settings bit.
void commandPrompt(bool state)
Enable or disable the command prompt.
bool commandPrompt()
Returns the settings bit.
void showHelp(bool state)}
Enable or disable the help system.
bool showHelp()
Returns the settings bit.
void internalCommands(bool state)
Enable or disable the internal commands
bool internalCommands()
Returns the settings bit.
void showInternalCommands(bool state)
Enable the printing of internal command in the help system.
bool showInternalCommands()
Returns the settings bit.
cmdSettings_t getSettings()
Returns the settings register – A 16 bit bitfield.
void setSettings(cmdSettings_t newSet)
Sets the configuration register.
portSettings_t getPortSettings()
Returns a struct containinge port settings – The three Stream pointers and the settings register.
void setPortSettings(portSettings_t newPorts)
Assign new port settings.
void printDiagnostics()
Print diagnostic date – used for development debugging.
bool getInt(iType &myIvar)
Attempts to parse the next item in the payload as an int and assign it to myIvar. Returns true if successful.
bool getFloat(float &myFloat)
Attempts to parse the next item in the payload as a float and assign it to myFloat. Returns true if successful.
bool getDouble(double &myDouble)
Attempts to parse the next item in the payload as a double and assign it to myDouble. Returns true if successful.
bool getString(String &myString)
Returns the next string in the payload.
#Help system
uint16_t getCommandListLength()
Returns the number of items in the command list
String getCommandItem(uint16_t commandItem)
Returns a String containing the help system text for the specified command item. The text consists of the command, and the help text.
The line is formatted with a tab at the start, a tab after the command string, the | character followed by another tab and the help text.
uint8_t getInternalCommandLength()
Returns the number of internal command items
String getInternalCommandItem(uint8_t internalItem)
Get the help text line for the specified internal item
void printCommandList()
Print a formatted command list - this method is used when the internal help command is used.
void printCommanderVersion()
Print the commander version and settings - used by the internal ? command.