Commands: Add comment support and improve doc

doc/user/COMMANDS.md

@@ -79,25 +79,29 @@ eg: `add_files_or_set_hdri /path/to/dragon.vtu /path/to/file.hdr`.
 
 ## Command Script (`--command-script`)
 
-F3D provides a feature to execute commands from a script file using the `--command-script` [CLI option[(OPTIONS.md)]]. This allows users to automate a sequence of commands by listing them in a plain text file.
-eg: `f3d --command-script path/to/command_script.txt`.
-Example Command Script, commands are separated by new lines:
-```
+F3D provides a feature to execute commands from a script file using the `--command-script` [CLI option](OPTIONS.md). This allows users to automate a sequence of commands by listing them in a plain text file, eg: `f3d --command-script path/to/command_script.txt`.
+
+Example Command Script, commands are separated by new lines, comments are supported:
+
+```shell
+# A comment
 roll_camera 90
 toggle ui.scalar_bar
-print_scene_info
+print_scene_info # Another comment
 increase_light_intensity
 ```
 
 ## Command syntax
 
 Command syntax is similar to bash, as in they will be split by "token" to be processed.
-Tokens are spaces separated, eg: `set scene.up.direction +Z`.
-Tokens can also be quoted to support spaces inside, eg:  `set render.hdri.file "/path/to/file with spaces.png"`.
-Supported quotes are `` `'" ``, eg: `set render.hdri.file '/path/to/file with spaces.png'`.
-Quotes inside quotes are supported as well, eg: `set render.hdri.file "/path/to/file'with'quotes.png"`.
-Quotes and spaces can be escaped, eg: `set render.hdri.file /path/to/file\ with\ spaces\ and\ \'quotes\".png`.
-Escapes can be escaped too: eg: `set render.hdri.file C:\\path\\to\\windows\\file.png`.
-Other escaped character will be processed as if the escape was not present, eg: `set scene.up.direction +\Z`
-Unfinished quoted section is invalid, eg: `set scene.up.direction "+Z`
-A escape at the end is also invalid, eg: `set scene.up.direction +Z\`
+
+ - Tokens are spaces separated, eg: `set scene.up.direction +Z`.
+ - Tokens can also be quoted to support spaces inside, eg:  `set render.hdri.file "/path/to/file with spaces.png"`.
+ - Supported quotes are `` `'" ``, eg: `set render.hdri.file '/path/to/file with spaces.png'`.
+ - Quotes inside quotes are supported as well, eg: `set render.hdri.file "/path/to/file'with'quotes.png"`.
+ - Quotes and spaces can be escaped, eg: `set render.hdri.file /path/to/file\ with\ spaces\ and\ \'quotes\".png`.
+ - Comment are supported using `#`, Any character after will be ignored. Use `\#` to add it verbatim.
+ - Escapes can be escaped too: eg: `set render.hdri.file C:\\path\\to\\windows\\file.png`.
+ - Other escaped character will be processed as if the escape was not present, eg: `set scene.up.direction +\Z`
+ - Unfinished quoted section is invalid, eg: `set scene.up.direction "+Z`
+ - A escape at the end is also invalid, eg: `set scene.up.direction +Z\`

doc/user/CONFIGURATION_FILE.md

@@ -106,7 +106,7 @@ A typical config file with bindings may look like this:
 
 Here, the first block define new bindings for all and any files.
 It even replace an existing default [interaction](INTERACTIONS.md) on the `O` key with its own.
-Each bind is associated to the [command](COMMANDS.mnd) to execute when it is pressed.
+Each bind is associated to the [command](COMMANDS.md) to execute when it is pressed.
 
 In the second block, new bindings are defined for files ending in `.vtu`, and there bindings
 will only be available when loading such a file.

library/public/utils.h

@@ -32,20 +32,22 @@ class F3D_EXPORT utils
    *  - Split by quoted section and remove the quotes
    *  - Supported quotes are: '"`
    *  - Use escaped \ quotes, spaces and escape to add them verbatim
+   *  - Comments are supported with `#`, any characters after are ignored
+   *  - Use escaped \# to add it verbatim
    *  - Other escaped characters are also added verbatim
    * Throw a tokenize_exception if a quoted section is not closed or if finishing with an escape
    *
    * Examples:
    * `set scene.up.direction +Z` -> `set` `scene.up.direction` `+Z`
-   * `set render.hdri.file "/path/to/file with spaces.png"` -> `set`, `render.hdri.file`,
-   * `/path/to/file with spaces.png` `set render.hdri.file '/path/to/file with spaces.png'` ->
-   * `set`, `render.hdri.file`, `/path/to/file with spaces.png` `set render.hdri.file
-   * "/path/to/file'with'quotes.png"` -> `set`, `render.hdri.file`, `/path/to/file'with'quotes.png`
-   * `set render.hdri.file /path/to/file\ spaces\ \'quotes\".png` -> `set`, `render.hdri.file`,
-   * `/path/to/file spaces 'quotes".png` `set render.hdri.file C:\\path\\to\\windows\\file.png` ->
-   * `set`, `render.hdri.file`, `C:\path\to\windows\file.png` `set scene.up.direction +\Z` -> `set`,
-   * `scene.up.direction`, `+Z` `set scene.up.direction "+Z` -> tokenize_exception `set
-   * scene.up.direction +Z\` -> tokenize_exception
+   * `set render.hdri.file "/path/to/file with spaces.png"` -> `set`, `render.hdri.file`, `/path/to/file with spaces.png`
+   * `set render.hdri.file '/path/to/file with spaces.png'` -> `set`, `render.hdri.file`, `/path/to/file with spaces.png`
+   * `set render.hdri.file "/path/to/file'with'quotes.png"` -> `set`, `render.hdri.file`, `/path/to/file'with'quotes.png`
+   * `set render.hdri.file /path/to/file\ spaces\ \'quotes\".png` -> `set`, `render.hdri.file`, `/path/to/file spaces 'quotes".png`
+   * `set render.hdri.file C:\\path\\to\\windows\\file.png` -> `set`, `render.hdri.file`, `C:\path\to\windows\file.png`
+   * `set scene.up.direction +Z # A comment` -> `set`, `scene.up.direction`, `+Z`
+   * `set scene.up.direction +\Z` -> `set`, `scene.up.direction`, `+Z`
+   * `set scene.up.direction "+Z` -> tokenize_exception
+   * `set scene.up.direction +Z\` -> tokenize_exception
    */
   static std::vector<std::string> tokenize(std::string_view str);
   // clang-format on

library/src/interactor_impl.cxx

@@ -684,6 +684,11 @@ bool interactor_impl::triggerCommand(std::string_view command)
     return false;
   }
 
+  if (tokens.empty())
+  {
+    return true;
+  }
+
   const std::string& action = tokens[0];
   try
   {

library/src/utils.cxx

@@ -26,6 +26,7 @@ std::vector<std::string> utils::tokenize(std::string_view str)
   };
   bool escaped = false;
   char quoted = '\0';
+  bool commented = false;
   for (char c : str)
   {
     switch (c)
@@ -66,11 +67,27 @@ std::vector<std::string> utils::tokenize(std::string_view str)
         }
         escaped = false;
         break;
+      case '#':
+        if (!escaped && !quoted)
+        {
+          commented = true;
+        }
+        else
+        {
+          accumulate(c);
+        }
+        escaped = false;
+        break;
       default:
         accumulate(c);
         escaped = false;
         break;
     }
+
+    if (commented)
+    {
+      break;
+    }
   }
   if (quoted || escaped)
   {

library/testing/TestSDKUtils.cxx

@@ -50,6 +50,14 @@ int TestSDKUtils(int argc, char* argv[])
     f3d::utils::tokenize(R"(set render.hdri.file file\ pa\th\ esc\ape)") ==
       std::vector<std::string>{ "set", "render.hdri.file", "file path escape" });
 
+  test("tokenize comments",
+    f3d::utils::tokenize(R"(set render.hdri.file file # A comment)") ==
+      std::vector<std::string>{ "set", "render.hdri.file", "file" });
+
+  test("tokenize escaped comments",
+    f3d::utils::tokenize(R"(set render.hdri.file fi\#le)") ==
+      std::vector<std::string>{ "set", "render.hdri.file", "fi#le" });
+
   test("tokenize backslashes",
     f3d::utils::tokenize(R"(set render.hdri.file file\\pa\\th\\backsl\\ashes)") ==
       std::vector<std::string>{ "set", "render.hdri.file", R"(file\pa\th\backsl\ashes)" });

testing/scripts/TestCommandScriptBasic.txt

@@ -1,4 +1,6 @@
-roll_camera 90
+# A comment at the beginning of the script
+roll_camera 90 # A comment at the and of a command
 toggle ui.scalar_bar
+# A comment in the middle of the script
 print_scene_info
-increase_light_intensity
+increase_light_intensity

testing/scripts/TestCommandScriptInvalid.txt

@@ -1 +1 @@
-INVALID_COMMAND_1
+INVALID_COMMAND_1