diff --git a/doc/user/COMMANDS.md b/doc/user/COMMANDS.md index 99dcd47191..8974ae3788 100644 --- a/doc/user/COMMANDS.md +++ b/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\` diff --git a/doc/user/CONFIGURATION_FILE.md b/doc/user/CONFIGURATION_FILE.md index e8c564d4e3..a533bd3190 100644 --- a/doc/user/CONFIGURATION_FILE.md +++ b/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. diff --git a/library/public/utils.h b/library/public/utils.h index 48fa7033c1..fba7ebfc0c 100644 --- a/library/public/utils.h +++ b/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 tokenize(std::string_view str); // clang-format on diff --git a/library/src/interactor_impl.cxx b/library/src/interactor_impl.cxx index 7cb69256d9..6ff99f6e93 100644 --- a/library/src/interactor_impl.cxx +++ b/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 { diff --git a/library/src/utils.cxx b/library/src/utils.cxx index afddbe3fc4..72222e6766 100644 --- a/library/src/utils.cxx +++ b/library/src/utils.cxx @@ -26,6 +26,7 @@ std::vector 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 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) { diff --git a/library/testing/TestSDKUtils.cxx b/library/testing/TestSDKUtils.cxx index d1701dfa40..93ae0a204c 100644 --- a/library/testing/TestSDKUtils.cxx +++ b/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{ "set", "render.hdri.file", "file path escape" }); + test("tokenize comments", + f3d::utils::tokenize(R"(set render.hdri.file file # A comment)") == + std::vector{ "set", "render.hdri.file", "file" }); + + test("tokenize escaped comments", + f3d::utils::tokenize(R"(set render.hdri.file fi\#le)") == + std::vector{ "set", "render.hdri.file", "fi#le" }); + test("tokenize backslashes", f3d::utils::tokenize(R"(set render.hdri.file file\\pa\\th\\backsl\\ashes)") == std::vector{ "set", "render.hdri.file", R"(file\pa\th\backsl\ashes)" }); diff --git a/testing/scripts/TestCommandScriptBasic.txt b/testing/scripts/TestCommandScriptBasic.txt index b2148d44fb..a7f4d7a5ab 100644 --- a/testing/scripts/TestCommandScriptBasic.txt +++ b/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 \ No newline at end of file +increase_light_intensity diff --git a/testing/scripts/TestCommandScriptInvalid.txt b/testing/scripts/TestCommandScriptInvalid.txt index 6d50c388e7..cf4ae73dbb 100644 --- a/testing/scripts/TestCommandScriptInvalid.txt +++ b/testing/scripts/TestCommandScriptInvalid.txt @@ -1 +1 @@ -INVALID_COMMAND_1 \ No newline at end of file +INVALID_COMMAND_1