update examples and README

Author: naszly

README.md

@@ -1,9 +1,15 @@
 # StaticSerialCommands
-
-An Arduino library for parsing commands received over a serial port. Optimized for low dynamic memory usage, commands are stored in program memory. Typed arguments with strict input validation and friendly error messages. Commands can have subcommands.
+An Arduino library for parsing commands received over a serial port. Optimized for low dynamic memory usage, commands are stored in program memory.
+* Commands and arguments are separated by space.
+* A command must end with a new line or carriage return character.
+* Whitespaces are ignored when parsing a command.
+* Double quotation marks can be used to pass string argument with spaces.
+* Typed arguments with strict input validation.
+* Friendly error messages for invalid input.
+* Commands can have subcommands.
+* Methods to print out commands with syntax and description.
 
 ## Quickstart
-
 ```cpp
 #include "StaticSerialCommands.h"
 
@@ -25,18 +31,17 @@ void loop() {
   serialCommands.readSerial();
 }
 ```
-
 ## Commands
-
-COMMAND macro syntax:
+COMMAND macro is used to create Command object with data stored in program memory.
 ```cpp
 COMMAND(function, command)
 COMMAND(function, command, subcommands)
 COMMAND(function, command, subcommands, description)
 COMMAND(function, command, arguments..., subcommands, description)
 ```
 ### Simple arguments
-Valid argument types: Int, Float, String
+Valid argument types: Int, Float, String \
+Maximum number of arguments is limited to 16.
 ```cpp
 void cmd_hello(SerialCommands& sender, Args& args) {
   sender.getSerial().print(F("Hello "));
@@ -53,19 +58,17 @@ Command commands[] {
   // if string argument contains space it should be inside quotation marks
   // for example: name "Firstname Lastname"
   COMMAND(cmd_hello, "name", ArgType::String, nullptr, ""),
-  COMMAND(cmd_multiply, "mul", ArgType::Int, ArgType::Int, nullptr, "multiplies two number"),
+  COMMAND(cmd_multiply, "mul", ArgType::Int, ArgType::Int, nullptr, "multiply two numbers"),
 };
 ```
-
 ### Custom arguments
-ARG macro syntax:
+ARG macro is used to specify command argument type, range (if type is numeric) and name.
 ```cpp
 ARG(type)
 ARG(type, name)
 ARG(type, min, max)
 ARG(type, min, max, name)
 ```
-
 ```cpp
 void cmd_led_on(SerialCommands& sender, Args& args) {
   auto pin = args[0].getInt();
@@ -90,15 +93,19 @@ Command commands[] {
   COMMAND(cmd_led_off, "off", ARG(ArgType::Int, 2, 13, "pin"), nullptr, "turn off the led on the given pin"),
 };
 ```
+If you want to declare argument constraint into a variable, mark it as `constexpr`:
+```cpp 
+constexpr auto argConstraint = ARG(ArgType::Int, 2, 13, "pin");
 
-### Subcommands
-```
-help - list commands
-calc <int> - calculator
-calc <int> + <int> - add numbers
-calc <int> * <int> - multiply numbers
+Command commands[] {
+  COMMAND(cmd_led_on, "on", argConstraint, nullptr, "turn on the led on the given pin"),
+  COMMAND(cmd_led_off, "off", argConstraint, nullptr, "turn off the led on the given pin"),
+};
 ```
-
+### Subcommands
+An array of subcommands can only be passed to one command. \
+The sum of command arguments and subcommand arguments must be less than or equal to 16. \
+If the parent of subcommands has N arguments, the first N arguments of the subcommands will be the parent's arguments.
 ```cpp
 void cmd_help(SerialCommands& sender, Args& args);
 void cmd_calc(SerialCommands& sender, Args& args);
@@ -124,14 +131,61 @@ void cmd_calc(SerialCommands& sender, Args& args) {
 }
 
 void cmd_calc_add(SerialCommands& sender, Args& args) {
-  float number1 = args[0].getInt();
-  float number2 = args[1].getInt();
+  auto number1 = args[0].getInt();
+  auto number2 = args[1].getInt();
   sender.getSerial().println(number1 + number2);
 }
 
 void cmd_calc_mul(SerialCommands& sender, Args& args) {
-  float number1 = args[0].getInt();
-  float number2 = args[1].getInt();
+  auto number1 = args[0].getInt();
+  auto number2 = args[1].getInt();
   sender.getSerial().println(number1 * number2);
 }
 ```
+Result:
+```
+help - list commands
+calc <int> - calculator
+calc <int> + <int> - add numbers
+calc <int> * <int> - multiply numbers
+```
+## SerialCommands methods
+public methods of SerialCommands class:
+```cpp
+// read serial port and parse command when new line is received
+// if parsing is successful, command function will be called
+// if parsing is unsuccessful, error message will be printed
+void readSerial();
+
+// get Serial object
+Stream& getSerial();
+
+// print the command syntax
+void printCommand(const Command& command);
+
+// print command description
+void printCommandDescription(const Command& command);
+
+// list all commands but not their subcommands
+void listCommands();
+void listCommands(const Command* commands, uint16_t commandsCount);
+
+// list all commands and their subcommands
+void listAllCommands();
+void listAllCommands(const Command* commands, uint16_t commandsCount);
+```
+## Custom buffer size
+Default buffer size is 64 bytes. \
+This buffer is used to store characters received over the serial port,
+and to read strings from program memory (command name, description and argument name). \
+The buffer must be large enough to:
+* receive the longest command
+* store the longest command name and the longest description.
+```cpp
+char buffer[128];
+SerialCommands serialCommands(
+  Serial,
+  commands, sizeof(commands) / sizeof(Command),
+  buffer, sizeof(buffer)
+);
+```

examples/CommandsWithArguments/CommandsWithArguments.ino

@@ -19,8 +19,8 @@ void cmd_hello(SerialCommands& sender, Args& args) {
 }
 
 void cmd_multiply(SerialCommands& sender, Args& args) {
-  float number1 = args[0].getFloat();
-  float number2 = args[1].getFloat();
+  auto number1 = args[0].getFloat();
+  auto number2 = args[1].getFloat();
   sender.getSerial().println(number1 * number2);
 }
 
@@ -40,21 +40,41 @@ void cmd_led_off(SerialCommands& sender, Args& args) {
   sender.getSerial().println(F(" is off "));
 }
 
+/*
+COMMAND macro is used to create Command object.
+It takes the following arguments:
+    COMMAND(function, command)
+    COMMAND(function, command, subcommands)
+    COMMAND(function, command, subcommands, description)
+    COMMAND(function, command, arguments..., subcommands, description)
+
+ARG macro is used to specify argument type, range (if type is numeric) and name.
+It takes the following arguments:
+    ARG(type)
+    ARG(type, name)
+    ARG(type, min, max)
+    ARG(type, min, max, name)
+*/
+
 Command commands[] {
   COMMAND(cmd_help, "help", NULL, "list commands"),
 
   // if string argument contains space it should be inside quotation marks
-  // for example: myname "Firstname Lastname"
-  COMMAND(cmd_hello, "myname", ArgType::String, NULL, ""),
-  COMMAND(cmd_multiply, "mul", ArgType::Float, ArgType::Float, NULL, "multiplies two number"),
+  // for example: name "Firstname Lastname"
+  COMMAND(cmd_hello, "name", ArgType::String, NULL, ""),
+  COMMAND(cmd_multiply, "mul", ArgType::Float, ArgType::Float, NULL, "multiply two numbers"),
 
-  // set min and max value of argument
-  // if the argument is out of range command does not run
+  // argument should be an integer between 2 and 13
+  // otherwise error message will be printed and command won't be executed
   COMMAND(cmd_led_on, "on", ARG(ArgType::Int, START_PIN, END_PIN, "pin"), NULL, "turn on the led on the given pin"),
   COMMAND(cmd_led_off, "off", ARG(ArgType::Int, START_PIN, END_PIN, "pin"), NULL, "turn off the led on the given pin"),
 };
 
-SerialCommands serialCommands = SERIAL_COMMANDS(Serial, commands);
+SerialCommands serialCommands(Serial, commands, sizeof(commands) / sizeof(Command));
+
+// if default buffer size (64) is too small pass a buffer through constructor
+// char buffer[128];
+// SerialCommands serialCommands(Serial, commands, sizeof(commands) / sizeof(Command), buffer, sizeof(buffer));
 
 void setup() {
   Serial.begin(9600);

examples/SimpleCommands/SimpleCommands.ino

@@ -8,6 +8,10 @@ Repository     : https://github.com/naszly/Arduino-StaticSerialCommands
 
 #define LED_PIN 13
 
+void cmd_help(SerialCommands& sender, Args& args) {
+    sender.listCommands();
+}
+
 void cmd_led_on(SerialCommands& sender, Args& args) {
   digitalWrite(LED_PIN, HIGH);
   sender.getSerial().println(F("Led is on"));
@@ -19,16 +23,23 @@ void cmd_led_off(SerialCommands& sender, Args& args) {
 }
 
 Command commands[] {
+  COMMAND(cmd_help, "help"),
   COMMAND(cmd_led_on, "on"),
   COMMAND(cmd_led_off, "off"),
 };
 
-SerialCommands serialCommands = SERIAL_COMMANDS(Serial, commands);
+SerialCommands serialCommands(Serial, commands, sizeof(commands) / sizeof(Command));
+
+// if default buffer size (64) is too small pass a buffer through constructor
+// char buffer[128];
+// SerialCommands serialCommands(Serial, commands, sizeof(commands) / sizeof(Command), buffer, sizeof(buffer));
 
 void setup() {
   Serial.begin(9600);
 
   pinMode(LED_PIN, OUTPUT);
+
+  serialCommands.listCommands();
 }
 
 void loop() {

examples/Subcommands/Subcommands.ino

@@ -0,0 +1,67 @@
+/*---------------------------------------------------------------------
+Author         : naszly
+License        : BSD
+Repository     : https://github.com/naszly/Arduino-StaticSerialCommands
+-----------------------------------------------------------------------*/
+
+#include <StaticSerialCommands.h>
+
+void cmd_help(SerialCommands& sender, Args& args);
+void cmd_calc(SerialCommands& sender, Args& args);
+void cmd_calc_add(SerialCommands& sender, Args& args);
+void cmd_calc_mul(SerialCommands& sender, Args& args);
+
+/*
+COMMAND macro is used to create Command object.
+It takes the following arguments:
+    COMMAND(function, command)
+    COMMAND(function, command, subcommands)
+    COMMAND(function, command, subcommands, description)
+    COMMAND(function, command, arguments..., subcommands, description)
+*/
+
+Command subCommands[] {
+        COMMAND(cmd_calc_add, "+", ArgType::Int, nullptr, "add numbers"),
+        COMMAND(cmd_calc_mul, "*", ArgType::Int, nullptr, "multiply numbers"),
+};
+
+Command commands[] {
+        COMMAND(cmd_help, "help", nullptr, "list commands"),
+        COMMAND(cmd_calc, "calc", ArgType::Int, subCommands, "calculator"),
+};
+
+SerialCommands serialCommands(Serial, commands, sizeof(commands) / sizeof(Command));
+
+// if default buffer size (64) is too small pass a buffer through constructor
+// char buffer[128];
+// SerialCommands serialCommands(Serial, commands, sizeof(commands) / sizeof(Command), buffer, sizeof(buffer));
+
+void setup() {
+    Serial.begin(9600);
+
+    serialCommands.listAllCommands();
+}
+
+void loop() {
+    serialCommands.readSerial();
+}
+
+void cmd_help(SerialCommands& sender, Args& args) {
+    sender.listAllCommands();
+}
+
+void cmd_calc(SerialCommands& sender, Args& args) {
+    sender.listAllCommands(subCommands, sizeof(subCommands) / sizeof(Command));
+}
+
+void cmd_calc_add(SerialCommands& sender, Args& args) {
+    auto number1 = args[0].getInt();
+    auto number2 = args[1].getInt();
+    sender.getSerial().println(number1 + number2);
+}
+
+void cmd_calc_mul(SerialCommands& sender, Args& args) {
+    auto number1 = args[0].getInt();
+    auto number2 = args[1].getInt();
+    sender.getSerial().println(number1 * number2);
+}