Check command order in README matches the order in picotool help

README.md

@@ -10,50 +10,50 @@ PICOTOOL:
     Tool for interacting with RP-series device(s) in BOOTSEL mode, or with an RP-series binary
 
 SYNOPSIS:
+    picotool help [<cmd>]
+    picotool version [-s] [<version>]
     picotool info [-b] [-m] [-p] [-d] [--debug] [-l] [-a] [device-selection]
     picotool info [-b] [-m] [-p] [-d] [--debug] [-l] [-a] <filename> [-t <type>]
     picotool config [-s <key> <value>] [-g <group>] [device-selection]
     picotool config [-s <key> <value>] [-g <group>] <filename> [-t <type>]
     picotool load [--ignore-partitions] [--family <family_id>] [-p <partition>] [-n] [-N] [-u] [-v] [-x] <filename> [-t <type>] [-o
                 <offset>] [device-selection]
-    picotool encrypt [--quiet] [--verbose] [--embed] [--fast-rosc] [--use-mbedtls] [--otp-key-page <page>] [--hash] [--sign] [--no-clear]
-                [--pin-xip-sram] <infile> [-t <type>] [-o <offset>] <outfile> [-t <type>] <aes_key> <iv_salt> <signing_key> <otp>
-    picotool seal [--quiet] [--verbose] [--hash] [--sign] [--clear] [--pin-xip-sram] <infile> [-t <type>] [-o <offset>] <outfile> [-t
-                <type>] <key> <otp> [--major <major>] [--minor <minor>] [--rollback <rollback> [<rows>..]]
-    picotool link [--quiet] [--verbose] <outfile> [-t <type>] <infile1> [-t <type>] <infile2> [-t <type>] [<infile3>] [-t <type>] [-p <pad>]
     picotool save [-p] [-v] [--family <family_id>] <filename> [-t <type>] [device-selection]
     picotool save -a [-v] [--family <family_id>] <filename> [-t <type>] [device-selection]
     picotool save -r <from> <to> [-v] [--family <family_id>] <filename> [-t <type>] [device-selection]
+    picotool verify <filename> [-t <type>] [device-selection] [-r <from> <to>] [-o <offset>] [device-selection]
     picotool erase [-a] [device-selection]
     picotool erase -p <partition> [device-selection]
     picotool erase -r <from> <to> [device-selection]
-    picotool verify <filename> [-t <type>] [device-selection] [-r <from> <to>] [-o <offset>] [device-selection]
     picotool reboot [-a] [-u] [-g <partition>] [-c <cpu>] [device-selection]
-    picotool otp list|get|set|load|dump|permissions|white-label
+    picotool seal [--quiet] [--verbose] [--hash] [--sign] [--clear] [--pin-xip-sram] <infile> [-t <type>] [-o <offset>] <outfile> [-t
+                <type>] <key> <otp> [--major <major>] [--minor <minor>] [--rollback <rollback> [<rows>..]]
+    picotool encrypt [--quiet] [--verbose] [--embed] [--fast-rosc] [--use-mbedtls] [--otp-key-page <page>] [--hash] [--sign] [--no-clear]
+                [--pin-xip-sram] <infile> [-t <type>] [-o <offset>] <outfile> [-t <type>] <aes_key> <iv_salt> <signing_key> <otp>
     picotool partition info|create
-    picotool uf2 info|convert|combine
-    picotool version [-s] [<version>]
+    picotool uf2 convert|combine|info
+    picotool otp get|set|load|white-label|permissions|dump|list
     picotool coprodis [--quiet] [--verbose] <infile> <outfile>
-    picotool help [<cmd>]
+    picotool link [--quiet] [--verbose] <outfile> [-t <type>] <infile1> [-t <type>] <infile2> [-t <type>] [<infile3>] [-t <type>] [-p <pad>]
 
 COMMANDS:
+    help        Show general help or help for a specific command
+    version     Display picotool version
     info        Display information from the target device(s) or file.
                 Without any arguments, this will display basic information for all connected RP-series devices in BOOTSEL mode
     config      Display or change program configuration settings from the target device(s) or file.
     load        Load the program / memory range stored in a file onto the device.
-    encrypt     Encrypt the program.
-    seal        Add final metadata to a binary, optionally including a hash and/or signature.
-    link        Link multiple binaries into one block loop.
     save        Save the program / memory stored in flash on the device to a file.
-    erase       Erase the program / memory stored in flash on the device.
     verify      Check that the device contents match those in the file.
+    erase       Erase the program / memory stored in flash on the device.
     reboot      Reboot the device
-    otp         Commands related to the RP2350 OTP (One-Time-Programmable) Memory
+    seal        Add final metadata to a binary, optionally including a hash and/or signature.
+    encrypt     Encrypt the program.
     partition   Commands related to RP2350 Partition Tables
     uf2         Commands related to UF2 creation and status
-    version     Display picotool version
+    otp         Commands related to the RP2350 OTP (One-Time-Programmable) Memory
     coprodis    Post-process coprocessor instructions in disassembly files.
-    help        Show general help or help for a specific command
+    link        Link multiple binaries into one block loop.
 
 Use "picotool help <cmd>" for more info
 ```
@@ -1125,24 +1125,24 @@ OTP:
     Commands related to the RP2350 OTP (One-Time-Programmable) Memory
 
 SYNOPSIS:
-    picotool otp list [-p] [-n] [-f] [-i <filename>] [<selector>..]
     picotool otp get [-c <copies>] [-r] [-e] [-n] [-i <filename>] [device-selection] [-z] [<selector>..]
     picotool otp set [-c <copies>] [-r] [-e] [-s] [-i <filename>] [-z] <selector> <value> [device-selection]
     picotool otp load [-r] [-e] [-s <row>] [-i <filename>] <filename> [-t <type>] [device-selection]
+    picotool otp white-label -s <row> <filename> [device-selection]
+    picotool otp permissions <filename> [--led <pin>] [--hash] [--sign] <key> [device-selection]
     picotool otp dump [-r] [-e] [-p] [--output <filename>] [device-selection]
     picotool otp dump [-r] [-e] [-p] [--output <filename>] <input> [-t <type>]
-    picotool otp permissions <filename> [--led <pin>] [--hash] [--sign] <key> [device-selection]
-    picotool otp white-label -s <row> <filename> [device-selection]
+    picotool otp list [-p] [-n] [-f] [-i <filename>] [<selector>..]
 
 SUB COMMANDS:
-    list          List matching known registers/fields
     get           Get the value of one or more OTP registers/fields (RP2350 only)
     set           Set the value of an OTP row/field (RP2350 only)
     load          Load the row range stored in a file into OTP and verify. Data is 2 bytes/row for ECC, 4 bytes/row for raw (MSB is
                   ignored). (RP2350 only)
-    dump          Dump entire OTP (RP2350 only)
-    permissions   Set the OTP access permissions (RP2350 only)
     white-label   Set the white labelling values in OTP (RP2350 only)
+    permissions   Set the OTP access permissions (RP2350 only)
+    dump          Dump entire OTP (RP2350 only)
+    list          List matching known registers/fields
 ```
 
 ### set/get

gen_help_txt.sh

@@ -100,10 +100,57 @@ fi
 mv tmp/README.md README.md
 rm -rf tmp
 
+# Check that command order in README matches picotool help output
+echo "Checking command order..."
+
+order_mismatch=false
+
+check_cmd_order() {
+    local label="$1" tool_order="$2" readme_order="$3"
+    local fp="" fr=""
+    while IFS= read -r cmd; do
+        [ -z "$cmd" ] && continue
+        echo "$readme_order" | grep -qx "$cmd" && fp+="$cmd"$'\n'
+    done <<< "$tool_order"
+    while IFS= read -r cmd; do
+        [ -z "$cmd" ] && continue
+        echo "$tool_order" | grep -qx "$cmd" && fr+="$cmd"$'\n'
+    done <<< "$readme_order"
+    if [ "$fp" != "$fr" ]; then
+        echo "Order mismatch in $label!"
+        echo "  picotool: $(echo "$fp" | tr '\n' ' ')"
+        echo "  README:   $(echo "$fr" | tr '\n' ' ')"
+        order_mismatch=true
+    fi
+}
+
+# Check top-level command order
+tool_top_order=$(picotool help 2>/dev/null | \
+    awk '/^COMMANDS:/{f=1;next} f && /^[A-Z]/{exit} f && /^    [a-z]/{print $1}')
+readme_top_order=$(grep -n '^\$ picotool help [a-z][a-z-]*$' README.md | \
+    sed 's/^\([0-9]*\):.*\$ picotool help \([a-z][a-z-]*\)$/\1 \2/' | \
+    sort -n | awk '{print $2}' | awk '!seen[$0]++')
+check_cmd_order "top-level commands" "$tool_top_order" "$readme_top_order"
+
+# Check sub-command order for each parent command
+for array in $sub_command_arrays; do
+    prefix=${array%_sub_commands}
+    tool_sub_order=$(picotool help "$prefix" 2>/dev/null | \
+        awk '/^SUB COMMANDS:/{f=1;next} f && /^[A-Z]/{exit} f && /^    [a-z]/{print $1}')
+    readme_sub_order=$(grep -n "^\$ picotool help ${prefix} [a-z][a-z-]*$" README.md | \
+        sed "s/^\([0-9]*\):.*\$ picotool help ${prefix} \([a-z][a-z-]*\)$/\1 \2/" | \
+        sort -n | awk '{print $2}' | awk '!seen[$0]++')
+    check_cmd_order "${prefix} sub-commands" "$tool_sub_order" "$readme_sub_order"
+done
+
 echo "Help text sections have been updated in README.md"
 
 # Still fail if there are missing commands
 if [ ${#missing_commands[@]} -ne 0 ]; then
     echo "Failing job due to missing help text sections"
     exit 1
 fi
+if $order_mismatch; then
+    echo "Failing job due to command order mismatch in README"
+    exit 1
+fi

main.cpp

@@ -1360,15 +1360,15 @@ struct otp_white_label_command : public cmd {
 
 
 vector<std::shared_ptr<cmd>> otp_sub_commands {
-        std::shared_ptr<cmd>(new otp_list_command()),
     #if HAS_LIBUSB
         std::shared_ptr<cmd>(new otp_get_command()),
         std::shared_ptr<cmd>(new otp_set_command()),
         std::shared_ptr<cmd>(new otp_load_command()),
-        std::shared_ptr<cmd>(new otp_dump_command()),
-        std::shared_ptr<cmd>(new otp_permissions_command()),
         std::shared_ptr<cmd>(new otp_white_label_command()),
+        std::shared_ptr<cmd>(new otp_permissions_command()),
+        std::shared_ptr<cmd>(new otp_dump_command()),
     #endif
+        std::shared_ptr<cmd>(new otp_list_command()),
 };
 
 struct otp_command : public multi_cmd {
@@ -1415,7 +1415,7 @@ struct uf2_convert_command : public cmd {
                         family_id("family_id").set(settings.family_id) % "family ID for UF2"
                 ).force_expand_help(true) % "UF2 Family options" +
                 (
-                    option("--platform") % "Optional platform for memory-address validation" &
+                    option("--platform") % "Optional platform for memory-address validation" &
                         platform_model("platform").set(settings.model) % "platform to use (eg rp2040, rp2350)"
                 ).force_expand_help(true) % "Platform options"
             #if SUPPORT_RP2350_A2
@@ -1471,11 +1471,11 @@ struct uf2_combine_command : public cmd {
 };
 
 vector<std::shared_ptr<cmd>> uf2_sub_commands {
+        std::shared_ptr<cmd>(new uf2_convert_command()),
+        std::shared_ptr<cmd>(new uf2_combine_command()),
     #if HAS_LIBUSB
         std::shared_ptr<cmd>(new uf2_info_command()),
     #endif
-        std::shared_ptr<cmd>(new uf2_convert_command()),
-        std::shared_ptr<cmd>(new uf2_combine_command()),
 };
 
 struct uf2_command : public multi_cmd {
@@ -1603,28 +1603,26 @@ auto reboot_cmd = std::shared_ptr<reboot_command>(new reboot_command());
 auto help_cmd = std::shared_ptr<help_command>(new help_command());
 
 vector<std::shared_ptr<cmd>> commands {
+        help_cmd,
+        std::shared_ptr<cmd>(new version_command()),
         std::shared_ptr<cmd>(new info_command()),
         std::shared_ptr<cmd>(new config_command()),
     #if HAS_LIBUSB
         std::shared_ptr<cmd>(new load_command()),
-    #endif
-    #if HAS_MBEDTLS
-        std::shared_ptr<cmd>(new encrypt_command()),
-        std::shared_ptr<cmd>(new seal_command()),
-    #endif
-        std::shared_ptr<cmd>(new link_command()),
-    #if HAS_LIBUSB
         std::shared_ptr<cmd>(new save_command()),
-        std::shared_ptr<cmd>(new erase_command()),
         std::shared_ptr<cmd>(new verify_command()),
+        std::shared_ptr<cmd>(new erase_command()),
         reboot_cmd,
     #endif
-        std::shared_ptr<cmd>(new otp_command()),
+    #if HAS_MBEDTLS
+        std::shared_ptr<cmd>(new seal_command()),
+        std::shared_ptr<cmd>(new encrypt_command()),
+    #endif
         std::shared_ptr<cmd>(new partition_command()),
         std::shared_ptr<cmd>(new uf2_command()),
-        std::shared_ptr<cmd>(new version_command()),
+        std::shared_ptr<cmd>(new otp_command()),
         std::shared_ptr<cmd>(new coprodis_command()),
-        help_cmd
+        std::shared_ptr<cmd>(new link_command()),
 };
 
 template <typename T>
@@ -6916,7 +6914,7 @@ bool uf2_convert_command::execute(device_map &devices) {
 }
 
 bool uf2_combine_command::execute(device_map &devices) {
-    if (get_file_type_idx(0) != filetype::uf2 || get_file_type_idx(1) != filetype::uf2) {
+    if (get_file_type_idx(0) != filetype::uf2 || get_file_type_idx(1) != filetype::uf2) {
         fail(ERROR_ARGS, "All files must be UF2 files\n");
     }