CLI help text refactoring to better match http://docopt.org/ standard

Author: akopachov

services/cli/cli.c

@@ -2,48 +2,43 @@
 
 #include "cli.h"
 #include <lib/toolbox/args.h>
-#include "cli_common_helpers.h"
+#include "cli_helpers.h"
 #include "commands/list/list.h"
 #include "commands/add/add.h"
 #include "commands/delete/delete.h"
 #include "commands/timezone/timezone.h"
-
-#define TOTP_CLI_COMMAND_NAME "totp"
-#define TOTP_CLI_COMMAND_HELP "help"
+#include "commands/help/help.h"
 
 static void totp_cli_print_unknown_command(FuriString* unknown_command) {
     TOTP_CLI_PRINTF(
-        "Command \"%s\" is unknown. Use \"help\" command to get list of available commands.",
+        "Command \"%s\" is unknown. Use \"" TOTP_CLI_COMMAND_HELP "\" command to get list of available commands.",
         furi_string_get_cstr(unknown_command));
 }
 
-static void totp_cli_print_help() {
-    TOTP_CLI_PRINTF("Usage:\r\n");
-    TOTP_CLI_PRINTF(TOTP_CLI_COMMAND_NAME " <command> <arguments>\r\n");
-    TOTP_CLI_PRINTF("Command list:\r\n");
-    TOTP_CLI_PRINTF("\t" TOTP_CLI_COMMAND_HELP " - print command usage help\r\n\r\n");
-    totp_cli_command_list_print_help();
-    totp_cli_command_delete_print_help();
-    totp_cli_command_add_print_help();
-    totp_cli_command_timezone_print_help();
-}
-
 static void totp_cli_handler(Cli* cli, FuriString* args, void* context) {
     PluginState* plugin_state = (PluginState*)context;
 
     FuriString* cmd = furi_string_alloc();
 
     args_read_string_and_trim(args, cmd);
 
-    if(furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_HELP) == 0 || furi_string_empty(cmd)) {
-        totp_cli_print_help();
-    } else if(furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_ADD) == 0) {
+    if(furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_HELP) == 0 || 
+        furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_HELP_ALT) == 0 || 
+        furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_HELP_ALT2) == 0 || 
+        furi_string_empty(cmd)) {
+        totp_cli_command_help_handle();
+    } else if(furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_ADD) == 0 || 
+        furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_ADD_ALT) == 0 ||
+        furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_ADD_ALT2) == 0) {
         totp_cli_command_add_handle(plugin_state, args, cli);
-    } else if(furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_LIST) == 0) {
+    } else if(furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_LIST) == 0 ||
+        furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_LIST_ALT) == 0) {
         totp_cli_command_list_handle(plugin_state, cli);
-    } else if(furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_DELETE) == 0) {
+    } else if(furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_DELETE) == 0 ||
+        furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_DELETE_ALT) == 0) {
         totp_cli_command_delete_handle(plugin_state, args, cli);
-    } else if(furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_TIMEZONE) == 0) {
+    } else if(furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_TIMEZONE) == 0 ||
+        furi_string_cmp_str(cmd, TOTP_CLI_COMMAND_TIMEZONE_ALT) == 0) {
         totp_cli_command_timezone_handle(plugin_state, args, cli);
     } else {
         totp_cli_print_unknown_command(cmd);

services/cli/cli_common_helpers.h

@@ -1,21 +1,16 @@
-#include "cli_common_helpers.h"
+#include "cli_helpers.h"
 #include <cli/cli.h>
 
-void totp_cli_print_invalid_arguments() {
-    TOTP_CLI_PRINTF(
-        "Invalid command arguments. use \"help\" command to get list of available commands");
-}
-
 bool totp_cli_ensure_authenticated(PluginState* plugin_state, Cli* cli) {
     if(plugin_state->current_scene == TotpSceneAuthentication) {
         TOTP_CLI_PRINTF("Pleases enter PIN on your flipper device\r\n");
 
         while(plugin_state->current_scene == TotpSceneAuthentication &&
               !cli_cmd_interrupt_received(cli)) {
-            furi_delay_tick(0);
+            furi_delay_ms(100);
         }
 
-        TOTP_CLI_PRINTF("\033[A\33[2K\r");
+        TOTP_CLI_DELETE_LAST_LINE();
         fflush(stdout);
 
         if(plugin_state->current_scene == TotpSceneAuthentication) {

services/cli/cli_common_helpers.c renamed to services/cli/cli_helpers.c

@@ -0,0 +1,26 @@
+#pragma once
+
+#include <cli/cli.h>
+#include "../../types/plugin_state.h"
+
+#define TOTP_CLI_COMMAND_NAME "totp"
+
+#define DOCOPT_ARGUMENT(arg) "<" arg ">"
+#define DOCOPT_OPTIONAL(param) "[" param "]"
+#define DOCOPT_REQUIRED(param) "(" param ")"
+#define DOCOPT_OPTION(option, value) option " " value
+#define DOCOPT_SWITCH(option) option
+#define DOCOPT_OPTIONS "[options]"
+#define DOCOPT_DEFAULT(val) "[default: " val "]"
+
+#define TOTP_CLI_PRINTF(format, ...)                                 \
+    _Pragma(STRINGIFY(GCC diagnostic push));                         \
+    _Pragma(STRINGIFY(GCC diagnostic ignored "-Wdouble-promotion")); \
+    printf(format, ##__VA_ARGS__);                                   \
+    _Pragma(STRINGIFY(GCC diagnostic pop));
+
+#define TOTP_CLI_DELETE_LAST_LINE() TOTP_CLI_PRINTF("\033[A\33[2K\r")
+#define TOTP_CLI_DELETE_CURRENT_LINE() TOTP_CLI_PRINTF("\33[2K\r")
+#define TOTP_CLI_PRINT_INVALID_ARGUMENTS() TOTP_CLI_PRINTF("Invalid command arguments. use \"help\" command to get list of available commands")
+
+bool totp_cli_ensure_authenticated(PluginState* plugin_state, Cli* cli);

services/cli/cli_helpers.h

@@ -4,13 +4,13 @@
 #include "../../../list/list.h"
 #include "../../../../types/token_info.h"
 #include "../../../config/config.h"
-#include "../../cli_common_helpers.h"
+#include "../../cli_helpers.h"
 #include "../../../../scenes/scene_director.h"
 
-#define TOTP_CLI_COMMAND_ADD_ARG_NAME "NAME"
-#define TOTP_CLI_COMMAND_ADD_ARG_ALGO "ALGO"
+#define TOTP_CLI_COMMAND_ADD_ARG_NAME "name"
+#define TOTP_CLI_COMMAND_ADD_ARG_ALGO "algo"
 #define TOTP_CLI_COMMAND_ADD_ARG_ALGO_PREFIX "-a"
-#define TOTP_CLI_COMMAND_ADD_ARG_DIGITS "DIGITS"
+#define TOTP_CLI_COMMAND_ADD_ARG_DIGITS "digits"
 #define TOTP_CLI_COMMAND_ADD_ARG_DIGITS_PREFIX "-d"
 #define TOTP_CLI_COMMAND_ADD_ARG_UNSECURE_PREFIX "-u"
 
@@ -46,22 +46,26 @@ static bool token_info_set_algo_from_str(TokenInfo* token_info, FuriString* str)
     return false;
 }
 
-void totp_cli_command_add_print_help() {
-    TOTP_CLI_PRINTF("\t" TOTP_CLI_COMMAND_ADD " " TOTP_CLI_ARG(TOTP_CLI_COMMAND_ADD_ARG_NAME) " " TOTP_CLI_OPTIONAL_PARAM(
-        TOTP_CLI_COMMAND_ADD_ARG_ALGO_PREFIX " " TOTP_CLI_ARG(
-            TOTP_CLI_COMMAND_ADD_ARG_ALGO)) " " TOTP_CLI_OPTIONAL_PARAM(TOTP_CLI_COMMAND_ADD_ARG_DIGITS_PREFIX
-                                                                        " " TOTP_CLI_ARG(
-                                                                            TOTP_CLI_COMMAND_ADD_ARG_DIGITS)) " " TOTP_CLI_OPTIONAL_PARAM(TOTP_CLI_COMMAND_ADD_ARG_UNSECURE_PREFIX) " - add new token\r\n");
-    TOTP_CLI_PRINTF("\t\t" TOTP_CLI_ARG(TOTP_CLI_COMMAND_ADD_ARG_NAME) "   - token name\r\n");
-    TOTP_CLI_PRINTF("\t\t" TOTP_CLI_ARG(
-        TOTP_CLI_COMMAND_ADD_ARG_ALGO) "   - " TOTP_CLI_OPTIONAL_PARAM_MARK
-                                       " token hashing algorithm, could be one of: sha1, sha256, sha512; default: sha1\r\n");
-    TOTP_CLI_PRINTF("\t\t" TOTP_CLI_ARG(
-        TOTP_CLI_COMMAND_ADD_ARG_DIGITS) " - " TOTP_CLI_OPTIONAL_PARAM_MARK
-                                         " number of digits to generate, one of: 6, 8; default: 6\r\n");
-    TOTP_CLI_PRINTF(
-        "\t\t" TOTP_CLI_COMMAND_ADD_ARG_UNSECURE_PREFIX "       - " TOTP_CLI_OPTIONAL_PARAM_MARK
-        " to show console user input as-is without masking; default: show masked\r\n\r\n");
+void totp_cli_command_add_docopt_commands() {
+    TOTP_CLI_PRINTF("  " TOTP_CLI_COMMAND_ADD ", " TOTP_CLI_COMMAND_ADD_ALT ", " TOTP_CLI_COMMAND_ADD_ALT2 "     Add new token\r\n");
+}
+
+void totp_cli_command_add_docopt_usage() {
+    TOTP_CLI_PRINTF("  " TOTP_CLI_COMMAND_NAME " " DOCOPT_REQUIRED(TOTP_CLI_COMMAND_ADD " | " TOTP_CLI_COMMAND_ADD_ALT " | " TOTP_CLI_COMMAND_ADD_ALT2) " " DOCOPT_ARGUMENT(TOTP_CLI_COMMAND_ADD_ARG_NAME) " " 
+        DOCOPT_OPTIONAL(DOCOPT_OPTION(TOTP_CLI_COMMAND_ADD_ARG_ALGO_PREFIX, DOCOPT_ARGUMENT(TOTP_CLI_COMMAND_ADD_ARG_ALGO))) " " 
+        DOCOPT_OPTIONAL(DOCOPT_OPTION(TOTP_CLI_COMMAND_ADD_ARG_DIGITS_PREFIX, DOCOPT_ARGUMENT(TOTP_CLI_COMMAND_ADD_ARG_DIGITS))) " " 
+        DOCOPT_OPTIONAL(DOCOPT_SWITCH(TOTP_CLI_COMMAND_ADD_ARG_UNSECURE_PREFIX))"\r\n");
+}
+
+void totp_cli_command_add_docopt_arguments() {
+    TOTP_CLI_PRINTF("  " TOTP_CLI_COMMAND_ADD_ARG_NAME "        Token name\r\n");
+}
+
+void totp_cli_command_add_docopt_options() {
+    TOTP_CLI_PRINTF("  " DOCOPT_OPTION(TOTP_CLI_COMMAND_ADD_ARG_ALGO_PREFIX, DOCOPT_ARGUMENT(TOTP_CLI_COMMAND_ADD_ARG_ALGO)) "      Token hashing algorithm.\r\n");
+    TOTP_CLI_PRINTF("                 Could be one of: sha1, sha256, sha512 " DOCOPT_DEFAULT("sha1") "\r\n");
+    TOTP_CLI_PRINTF("  " DOCOPT_OPTION(TOTP_CLI_COMMAND_ADD_ARG_DIGITS_PREFIX, DOCOPT_ARGUMENT(TOTP_CLI_COMMAND_ADD_ARG_DIGITS))"    Number of digits to generate, one of: 6, 8 " DOCOPT_DEFAULT("6") "\r\n");
+    TOTP_CLI_PRINTF("  " DOCOPT_SWITCH(TOTP_CLI_COMMAND_ADD_ARG_UNSECURE_PREFIX) "             Show console user input as-is without masking\r\n");
 }
 
 void totp_cli_command_add_handle(PluginState* plugin_state, FuriString* args, Cli* cli) {
@@ -72,7 +76,7 @@ void totp_cli_command_add_handle(PluginState* plugin_state, FuriString* args, Cl
 
     // Reading token name
     if(!args_read_probably_quoted_string_and_trim(args, temp_str)) {
-        totp_cli_print_invalid_arguments();
+        TOTP_CLI_PRINT_INVALID_ARGUMENTS();
         furi_string_free(temp_str);
         token_info_free(token_info);
         return;
@@ -117,7 +121,7 @@ void totp_cli_command_add_handle(PluginState* plugin_state, FuriString* args, Cl
         }
 
         if(!parsed) {
-            totp_cli_print_invalid_arguments();
+            TOTP_CLI_PRINT_INVALID_ARGUMENTS();
             furi_string_free(temp_str);
             token_info_free(token_info);
             return;
@@ -126,7 +130,7 @@ void totp_cli_command_add_handle(PluginState* plugin_state, FuriString* args, Cl
 
     // Reading token secret
     furi_string_reset(temp_str);
-    TOTP_CLI_PRINTF("Enter token secret and confirm with [ENTER]:\r\n");
+    TOTP_CLI_PRINTF("Enter token secret and confirm with [ENTER]\r\n");
 
     uint8_t c;
     while(cli_read(cli, &c, 1) == 1) {
@@ -135,6 +139,7 @@ void totp_cli_command_add_handle(PluginState* plugin_state, FuriString* args, Cl
             cli_read_timeout(cli, &c2, 1, 0);
             cli_read_timeout(cli, &c2, 1, 0);
         } else if(c == CliSymbolAsciiETX) {
+            TOTP_CLI_DELETE_CURRENT_LINE();
             TOTP_CLI_PRINTF("Cancelled by user");
             furi_string_free(temp_str);
             token_info_free(token_info);
@@ -162,6 +167,8 @@ void totp_cli_command_add_handle(PluginState* plugin_state, FuriString* args, Cl
 
     temp_cstr = furi_string_get_cstr(temp_str);
 
+    TOTP_CLI_DELETE_LAST_LINE();
+
     if(!totp_cli_ensure_authenticated(plugin_state, cli)) {
         furi_string_free(temp_str);
         token_info_free(token_info);

services/cli/commands/add/add.c

@@ -4,6 +4,11 @@
 #include "../../../../types/plugin_state.h"
 
 #define TOTP_CLI_COMMAND_ADD "add"
+#define TOTP_CLI_COMMAND_ADD_ALT "mk"
+#define TOTP_CLI_COMMAND_ADD_ALT2 "new"
 
 void totp_cli_command_add_handle(PluginState* plugin_state, FuriString* args, Cli* cli);
-void totp_cli_command_add_print_help();
+void totp_cli_command_add_docopt_commands();
+void totp_cli_command_add_docopt_usage();
+void totp_cli_command_add_docopt_arguments();
+void totp_cli_command_add_docopt_options();

services/cli/commands/add/add.h

@@ -5,29 +5,34 @@
 #include <lib/toolbox/args.h>
 #include "../../../list/list.h"
 #include "../../../config/config.h"
-#include "../../cli_common_helpers.h"
+#include "../../cli_helpers.h"
 #include "../../../../scenes/scene_director.h"
 
-#define TOTP_CLI_COMMAND_DELETE_ARG_INDEX "INDEX"
+#define TOTP_CLI_COMMAND_DELETE_ARG_INDEX "index"
 #define TOTP_CLI_COMMAND_DELETE_ARG_FORCE_SUFFIX "-f"
 
-void totp_cli_command_delete_print_help() {
-    TOTP_CLI_PRINTF(
-        "\t" TOTP_CLI_COMMAND_DELETE
-        " " TOTP_CLI_ARG(TOTP_CLI_COMMAND_DELETE_ARG_INDEX) " " TOTP_CLI_OPTIONAL_PARAM(
-            TOTP_CLI_COMMAND_DELETE_ARG_FORCE_SUFFIX) " - delete token\r\n");
-    TOTP_CLI_PRINTF(
-        "\t\t" TOTP_CLI_ARG(TOTP_CLI_COMMAND_DELETE_ARG_INDEX) " - token index in the list\r\n");
-    TOTP_CLI_PRINTF("\t\t" TOTP_CLI_COMMAND_DELETE_ARG_FORCE_SUFFIX
-                    "      - " TOTP_CLI_OPTIONAL_PARAM_MARK
-                    " force command to do not ask user for interactive confirmation\r\n\r\n");
+void totp_cli_command_delete_docopt_commands() {
+    TOTP_CLI_PRINTF("  " TOTP_CLI_COMMAND_DELETE ", " TOTP_CLI_COMMAND_DELETE_ALT "       Delete existing token\r\n");
+}
+
+void totp_cli_command_delete_docopt_usage() {
+    TOTP_CLI_PRINTF("  " TOTP_CLI_COMMAND_NAME " " DOCOPT_REQUIRED(TOTP_CLI_COMMAND_DELETE " | " TOTP_CLI_COMMAND_DELETE_ALT) " " DOCOPT_ARGUMENT(TOTP_CLI_COMMAND_DELETE_ARG_INDEX) " "
+        DOCOPT_OPTIONAL(DOCOPT_SWITCH(TOTP_CLI_COMMAND_DELETE_ARG_FORCE_SUFFIX)) "\r\n");
+}
+
+void totp_cli_command_delete_docopt_arguments() {
+    TOTP_CLI_PRINTF("  " TOTP_CLI_COMMAND_DELETE_ARG_INDEX "       Token index in the list\r\n");
+}
+
+void totp_cli_command_delete_docopt_options() {
+    TOTP_CLI_PRINTF("  " DOCOPT_SWITCH(TOTP_CLI_COMMAND_DELETE_ARG_FORCE_SUFFIX) "             Force command to do not ask user for interactive confirmation\r\n");
 }
 
 void totp_cli_command_delete_handle(PluginState* plugin_state, FuriString* args, Cli* cli) {
     int token_number;
     if(!args_read_int_and_trim(args, &token_number) || token_number <= 0 ||
        token_number > plugin_state->tokens_count) {
-        totp_cli_print_invalid_arguments();
+        TOTP_CLI_PRINT_INVALID_ARGUMENTS();
         return;
     }
 
@@ -38,7 +43,7 @@ void totp_cli_command_delete_handle(PluginState* plugin_state, FuriString* args,
             confirm_needed = false;
         } else {
             TOTP_CLI_PRINTF("Unknown argument \"%s\"\r\n", furi_string_get_cstr(temp_str));
-            totp_cli_print_invalid_arguments();
+            TOTP_CLI_PRINT_INVALID_ARGUMENTS();
             furi_string_free(temp_str);
             return;
         }

services/cli/commands/delete/delete.c

@@ -4,6 +4,10 @@
 #include "../../../../types/plugin_state.h"
 
 #define TOTP_CLI_COMMAND_DELETE "delete"
+#define TOTP_CLI_COMMAND_DELETE_ALT "rm"
 
 void totp_cli_command_delete_handle(PluginState* plugin_state, FuriString* args, Cli* cli);
-void totp_cli_command_delete_print_help();
+void totp_cli_command_delete_docopt_commands();
+void totp_cli_command_delete_docopt_usage();
+void totp_cli_command_delete_docopt_arguments();
+void totp_cli_command_delete_docopt_options();

services/cli/commands/delete/delete.h

@@ -0,0 +1,39 @@
+#include "help.h"
+#include "../../cli_helpers.h"
+#include "../add/add.h"
+#include "../delete/delete.h"
+#include "../list/list.h"
+#include "../timezone/timezone.h"
+
+void totp_cli_command_help_docopt_commands() {
+    TOTP_CLI_PRINTF("  " TOTP_CLI_COMMAND_HELP ", " TOTP_CLI_COMMAND_HELP_ALT ", " TOTP_CLI_COMMAND_HELP_ALT2 "       Show command usage help\r\n");
+}
+
+void totp_cli_command_help_docopt_usage() {
+    TOTP_CLI_PRINTF("  " TOTP_CLI_COMMAND_NAME " " DOCOPT_REQUIRED(TOTP_CLI_COMMAND_HELP " | " TOTP_CLI_COMMAND_HELP_ALT " | " TOTP_CLI_COMMAND_HELP_ALT2) "\r\n");
+}
+
+void totp_cli_command_help_handle() {
+    TOTP_CLI_PRINTF("Usage:\r\n");
+    totp_cli_command_help_docopt_usage();
+    totp_cli_command_list_docopt_usage();
+    totp_cli_command_add_docopt_usage();
+    totp_cli_command_delete_docopt_usage();
+    totp_cli_command_timezone_docopt_usage();
+    cli_nl();
+    TOTP_CLI_PRINTF("Commands:\r\n");
+    totp_cli_command_help_docopt_commands();
+    totp_cli_command_list_docopt_commands();
+    totp_cli_command_add_docopt_commands();
+    totp_cli_command_delete_docopt_commands();
+    totp_cli_command_timezone_docopt_commands();
+    cli_nl();
+    TOTP_CLI_PRINTF("Arguments:\r\n");
+    totp_cli_command_add_docopt_arguments();
+    totp_cli_command_delete_docopt_arguments();
+    totp_cli_command_timezone_docopt_arguments();
+    cli_nl();
+    TOTP_CLI_PRINTF("Options:\r\n");
+    totp_cli_command_add_docopt_options();
+    totp_cli_command_delete_docopt_options();
+}

services/cli/commands/help/help.c

@@ -0,0 +1,11 @@
+#pragma once
+
+#include <cli/cli.h>
+
+#define TOTP_CLI_COMMAND_HELP "help"
+#define TOTP_CLI_COMMAND_HELP_ALT "h"
+#define TOTP_CLI_COMMAND_HELP_ALT2 "?"
+
+void totp_cli_command_help_handle();
+void totp_cli_command_help_docopt_commands();
+void totp_cli_command_help_docopt_usage();