From 6c9fdfa34b13b1800247437fdd6e8ac87510c9f5 Mon Sep 17 00:00:00 2001
From: Elizabeth Mattijsen <liz@raku.rocks>
Date: Fri, 7 Oct 2022 16:29:31 +0200
Subject: [PATCH] Add support for --description

Allowing users to add a description to a custom option
---
 Changes                   |  1 +
 README.md                 |  5 +++
 doc/App-Rak.rakudoc       |  7 ++++
 lib/App/Rak.rakumod       | 75 ++++++++++++++++++++++++++++++++-------
 resources/help.txt        |  1 +
 resources/help/option.txt | 16 ++++++++-
 6 files changed, 91 insertions(+), 14 deletions(-)

diff --git a/Changes b/Changes
index 4a2edcb..7ed63d7 100644
--- a/Changes
+++ b/Changes
@@ -3,6 +3,7 @@ Revision history for App-Rak
 {{$NEXT}}
      - Bump dependency on rak to get URL fetching support
      - Allow for multiple ecosystem specs with --ecosystem
+     - Add support for --description
 
 0.1.1  2022-10-06T14:35:22+02:00
      - Add support for --sourcery
diff --git a/README.md b/README.md
index 42b0476..0782bbd 100644
--- a/README.md
+++ b/README.md
@@ -275,6 +275,11 @@ More documentation can be found with the [Text::CSV](https://raku.land/github:Tu
 
 Indicate the number of worker threads that should be maximally. Defaults to the number of cores minus 1 if not specified. Assumes `1` if specified as a flag. Can also take a `Callable` specification, in which case the number of CPU cores will be presented to that Callable as the only argument. See also <--batch>.
 
+--description=text
+------------------
+
+Specify a description to be saved with the custom option. This will be shown prominently with --list-custom-options. If it is the only argument apart from --save, then the discription will be added (if there was no description yet) or replace the current description of the option.
+
 --device-number=condition
 -------------------------
 
diff --git a/doc/App-Rak.rakudoc b/doc/App-Rak.rakudoc
index 6c787a3..006314d 100644
--- a/doc/App-Rak.rakudoc
+++ b/doc/App-Rak.rakudoc
@@ -356,6 +356,13 @@ as a flag.  Can also take a C<Callable> specification, in which case the
 number of CPU cores will be presented to that Callable as the only argument.
 See also <--batch>.
 
+=head2 --description=text
+
+Specify a description to be saved with the custom option.  This will be
+shown prominently with --list-custom-options.  If it is the only argument
+apart from --save, then the discription will be added (if there was no
+description yet) or replace the current description of the option.
+
 =head2 --device-number=condition
 
 If specified, indicates the C<Callable> that should return True to include a
diff --git a/lib/App/Rak.rakumod b/lib/App/Rak.rakumod
index d066922..3039a9b 100644
--- a/lib/App/Rak.rakumod
+++ b/lib/App/Rak.rakumod
@@ -14,9 +14,9 @@ my constant BON  = "\e[1m";   # BOLD ON
 my constant BOFF = "\e[22m";  # BOLD OFF
 
 #- start of available options --------------------------------------------------
-#- Generated on 2022-10-07T12:37:23+02:00 by tools/makeOPTIONS.raku
+#- Generated on 2022-10-07T16:08:12+02:00 by tools/makeOPTIONS.raku
 #- PLEASE DON'T CHANGE ANYTHING BELOW THIS LINE
-my str @options = <absolute accessed after-context allow-loose-escapes allow-loose-quotes allow-whitespace auto-diag backup batch before-context blame-per-file blame-per-line blocks break checkout context count-only created csv-per-line degree device-number dir dont-catch dryrun ecosystem edit encoding eol escape exec extensions file file-separator-null files-from files-with-matches files-without-matches filesize find find-all formula frequencies gid group group-matches hard-links has-setgid has-setuid help highlight highlight-after highlight-before human ignorecase ignoremark inode invert-match is-empty is-executable is-group-executable is-group-readable is-group-writable is-owned-by-group is-owned-by-user is-owner-executable is-owner-readable is-owner-writable is-readable is-sticky is-symbolic-link is-world-executable is-world-readable is-world-writable is-writable json-per-elem json-per-file json-per-line keep-meta known-extensions list-custom-options list-expanded-options list-known-extensions matches-only max-matches-per-file meta-modified mode modified modify-files module only-first output-file pager paragraph-context passthru passthru-context paths paths-from pattern per-file per-line proximate rename-files quietly quote rak recurse-symlinked-dir recurse-unmatched-dir repository save sayer sep shell show-blame show-filename show-item-number silently smartcase sourcery stats stats-only strict summary-if-larger-than trim type uid under-version-control unicode unique user verbose version vimgrep with-line-endings>;
+my str @options = <absolute accessed after-context allow-loose-escapes allow-loose-quotes allow-whitespace auto-diag backup batch before-context blame-per-file blame-per-line blocks break checkout context count-only created csv-per-line degree description device-number dir dont-catch dryrun ecosystem edit encoding eol escape exec extensions file file-separator-null files-from files-with-matches files-without-matches filesize find find-all formula frequencies gid group group-matches hard-links has-setgid has-setuid help highlight highlight-after highlight-before human ignorecase ignoremark inode invert-match is-empty is-executable is-group-executable is-group-readable is-group-writable is-owned-by-group is-owned-by-user is-owner-executable is-owner-readable is-owner-writable is-readable is-sticky is-symbolic-link is-world-executable is-world-readable is-world-writable is-writable json-per-elem json-per-file json-per-line keep-meta known-extensions list-custom-options list-expanded-options list-known-extensions matches-only max-matches-per-file meta-modified mode modified modify-files module only-first output-file pager paragraph-context passthru passthru-context paths paths-from pattern per-file per-line proximate rename-files quietly quote rak recurse-symlinked-dir recurse-unmatched-dir repository save sayer sep shell show-blame show-filename show-item-number silently smartcase sourcery stats stats-only strict summary-if-larger-than trim type uid under-version-control unicode unique user verbose version vimgrep with-line-endings>;
 #- PLEASE DON'T CHANGE ANYTHING ABOVE THIS LINE
 #- end of available options ----------------------------------------------------
 
@@ -297,22 +297,30 @@ my sub main(@ARGS) is export {
     $pattern := @positionals.shift if !$pattern.defined && @positionals;
 
     # Save current setting
-    if %global<save>:delete -> $save {
-        my @options := as-options;
+    if %global<save>:delete -> $name {
+        my @opts := as-options;
 
-        @options
-          ?? (%config{$save} := @options)
-          !! (%config{$save}:delete);
+        if @opts {
+            %config{$name} := @opts == 1 && @opts.head.key eq 'description'
+              ?? (|%config{$name}, @opts.head)
+              !! @opts;
+        }
+        else {
+            %config{$name}:delete;
+        }
 
         $config-file.spurt: to-json %config, :!pretty, :sorted-keys;
 
         say @options
-          ?? "Saved '&as-cli-arguments(@options)' as: -$save"
-          !! "Removed custom option '--$save'";
+          ?? "Saved '&as-cli-arguments(@opts)' as: -$name"
+          !! "Removed custom option '--$name'";
         exit;
     }
 
-    elsif %global<list-expanded-options>:delete {
+    # from here on out, description is a noop
+    %global<description>:delete;
+
+    if %global<list-expanded-options>:delete {
         if $verbose {
             for as-options() {
                 if description(.key) -> $description {
@@ -1220,6 +1228,12 @@ my sub option-degree($value --> Nil) {
       !! meh "'--degree' must be an integer, or a Callable, not '$value'";
 }
 
+my sub option-description($value --> Nil) {
+    Bool.ACCEPTS($value)
+      ?? meh "'--description' can only be specified as a string"
+      !! (%global<description> := $value);
+}
+
 my sub option-device-number($value --> Nil) {
     set-filesystem-Int('device-number', $value)
 }
@@ -2270,9 +2284,44 @@ my sub action-list-custom-options(--> Nil) {
     meh-for 'list-custom-options', <filesystem listing modify csv>;
 
     activate-output-options;
-    my $format := '%' ~ %config.keys>>.chars.max ~ "s: %s\n";
-    for %config.sort(*.key.fc) -> (:$key, :value(@args)) {
-        printf $format, $key, as-cli-arguments(@args);
+    if %config {
+        my @with;
+        my @without;
+
+        # find the ones with and without description
+        for %config.sort(*.key.fc) -> (:$key, :value(@args)) {
+            my $description;
+            my @nodesc = @args.map: {
+                if .key eq 'description' {
+                    $description := .value;
+                    Empty
+                }
+                else {
+                    $_
+                }
+            }
+            $description
+              ?? (@with.push: Pair.new: $key, Pair.new: $description, @nodesc)
+              !! (@without.push: Pair.new: $key, @args)
+        }
+
+        if @with {
+            for @with -> (:key($option), :value($_)) {
+                say "--$option: $_.key()";
+                say "  &as-cli-arguments(.value)";
+            }
+        }
+        if @without {
+            say "\nOther options without description:" if @with;
+            my $format := '%' ~ (@without.map(*.key.chars).max + 2) ~ "s: %s\n";
+            for @without -> (:key($option), :value(@valid)) {
+                printf $format, "--$option", as-cli-arguments(@valid);
+            }
+        }
+    }
+
+    else {
+        say "No custom options where found in '$config-file'";
     }
 }
 
diff --git a/resources/help.txt b/resources/help.txt
index 84585ab..a50d390 100644
--- a/resources/help.txt
+++ b/resources/help.txt
@@ -140,6 +140,7 @@ Special options:
 Option management:
  --save=name            Translate --name to all other options specified,
                         remove if --save was the only option specified
+ --description=text     Add description to custom option
  --list-custom-options  List all previously saved options
 
 General options:
diff --git a/resources/help/option.txt b/resources/help/option.txt
index e6305c3..6ad78ca 100644
--- a/resources/help/option.txt
+++ b/resources/help/option.txt
@@ -53,10 +53,24 @@ $ rak -x=dat foo
 To remove a custom option, just specify the --save argument with
 the name of the custom option you would like to remove.
 
-# Example:
+Example:
 # Remove the '--ex' custom option
 $ rak --save=ex
 
+--description=text
+
+Specify a description to be saved with the custom option.  This will be
+shown prominently with --list-custom-options.  If it is the only argument
+apart from --save, then the discription will be added (if there was no
+description yet) or replace the current description of the option.
+
+Examples:
+# Add description to --i custom option
+$ rak --description="Perform search without regards to case" --save=i
+
+# Add custom option --y with description
+$ rak --description='Yep, there is a codepoint for it' --unicode --save=y
+
 --list-custom-options
 
 List all currently known custom options.  Must be the only argument.