Pre release of 0.1.5

Changes

@@ -1,6 +1,14 @@
 Revision history for App-Rak
 
 {{$NEXT}}
+     - Bump dependency on as-cli-arguments for better quoting rules
+     - Fix issue with message when removing a custom option
+     - Show single letter custom options with a single dash
+     - Allow for saving default options to be activated on each run
+     - Introduce RAK_CONFIG environment variable for location of custom
+       options
+     - Added documentation section "On the interpretation of options"
+     - Expanded documentation section "Creating your own options"
 
 0.1.4  2022-10-12T14:55:51+02:00
      - Add support for --output-dir

META6.json

@@ -6,7 +6,7 @@
   "build-depends": [
   ],
   "depends": [
-    "as-cli-arguments:ver<0.0.6>:auth<zef:lizmat>",
+    "as-cli-arguments:ver<0.0.7>:auth<zef:lizmat>",
     "CLI::Help:ver<0.0.5>:auth<zef:lizmat>",
     "CLI::Version:ver<0.0.8>:auth<zef:lizmat>",
     "has-word:ver<0.0.3>:auth<zef:lizmat>",
@@ -58,5 +58,5 @@
   ],
   "test-depends": [
   ],
-  "version": "0.1.4"
+  "version": "0.1.5"
 }

README.md

@@ -123,21 +123,103 @@ Note that the use of the `LAST` phaser will make the search run eagerly, meaning
 
 Any other phasers that do not require special attention by `App::Rak` are also supported in any code specified (such as `BEGIN` and `END`).
 
+ON THE INTERPRETATION OF OPTIONS
+================================
+
+All options when using App::Rak, start with either one dash `-` or two dashes `--`.
+
+If an option starts with two dashes, it is a so-called "long option". Any characters after the dashes are considered to be the single name of the option.
+
+If an option starts with a single dash, then it is considered to be a collection of "short options", each of 1 letter. If the number of short options is 1, then it can be followed by a numerical value (without equal sign).
+
+If the specification of the option does **not** contain an equal sign `=`, then the option is interpreted as a boolean option. By default, such a flag is considered to represent `True`. The value can be negated in two ways:
+
+  * a slash before the name
+
+  * the string "no-" before the name
+
+Some examples:
+
+  * -i option "i" is True
+
+  * -j5 option "j" has the value 5
+
+  * -im options "i" and "m" are True
+
+  * -/i option "i" is False
+
+  * -/im options "i" and "m" are False
+
+  * -no-i option "i" is False
+
+  * --foo option "foo" is True
+
+  * --/foo option "foo" is False
+
+  * --no-foo option "foo" is False
+
+If the specification of an option contains an equal sign after the name, then whatever follows that, is considered the value of that option. Whether or not that value needs to be quoted, and how they are to be quoted, really depends on the shell that you use to access `rak`. Generally, if the value consists of alphanumeric characters only, no quoting is necessary. Otherwise it's better to quote your values.
+
+Some examples:
+
+  * -s=foo option "s" has the value "foo"
+
+  * -t='foo bar' option "t" has the value "foo bar"
+
+  * --frobnicate=yes option "frobnicate" has the value "yes"
+
 CREATING YOUR OWN OPTIONS
 =========================
 
 App::Rak provides **many** options. If you are happy with a set of options for a certain workflow, You can use the `--save` option to save that set of options and than later access them with the given name:
 
 ```bash
-# create --im shortcut for ignoring case and accents
-$ rak --ignorecase --ignoremark --save=im
-Saved option '--im' as: --ignorecase --ignoremark
+# create -i shortcut for ignoring case
+$ rak --ignorecase --save=i
+Saved option '-i' as: --ignorecase
+
+# create -m shortcut for ignoring accents
+$ rak --ignoremark --save=m
+Saved option '-m' as: --ignoremark
 
 # same as --ignorecase --ignoremark
-$ rak foo --im
+$ rak foo -im
+```
+
+Generally speaking, the most used boolean options can be saved as single letter options: this allows multiple options to be specified in a single, short manner (as shown above).
+
+To better document / remember what a particular custom option is meant to do, you can add a description with the `--description` option.
+
+```bash
+# add a description to the -i custom option
+$ rak --description='Search without caring for uppercase' --save=i
+Saved '--description='Search without caring for uppercase'' as: -i
+
+# add an option -g for searching only git files
+$ rak --description='Committed files only' --under-version-control --save=g
+Saved '--description='Committed files only' --under-version-control' as: -g
 ```
 
-You can use the `--list-custom-options` to see what options you have saved before.
+There is also a special named option that indicates the options that will be automatically activated on any invocation: `(default)`.
+
+```bash
+# enable --smartcase by default on every run
+$ rak --smartcase --save='(default)'
+Saved '--smartcase' as: (default)
+
+=end
+
+You can use the C<--list-custom-options> to see what options you have saved
+before.
+
+Custom options are saved in C<~/.rak-config.json>.  You can override this
+by specifying the C<RAK_CONFIG> environment variable.
+
+=begin code :lang<bash>
+
+# read custom options from ".custom.json" (in the current directory)
+$ RAK_CONFIG=.custom.json rak foo
+```
 
 SUPPORTED OPTIONS
 =================

bin/rak

@@ -1,5 +1,5 @@
 use App::Rak;
 
-main(@*ARGS);
+main();
 
 # vim: expandtab shiftwidth=4

doc/App-Rak.rakudoc

@@ -151,6 +151,52 @@ meaning that no results will be shown until the search has been completed.
 Any other phasers that do not require special attention by C<App::Rak>
 are also supported in any code specified (such as C<BEGIN> and C<END>).
 
+=head1 ON THE INTERPRETATION OF OPTIONS
+
+All options when using App::Rak, start with either one dash C<-> or two
+dashes C<-->.
+
+If an option starts with two dashes, it is a so-called "long option".
+Any characters after the dashes are considered to be the single name of
+the option.
+
+If an option starts with a single dash, then it is considered to be a
+collection of "short options", each of 1 letter.  If the number of short
+options is 1, then it can be followed by a numerical value (without equal
+sign).
+
+If the specification of the option does B<not> contain an equal sign C<=>,
+then the option is interpreted as a boolean option.  By default, such a flag
+is considered to represent C<True>.  The value can be negated in two ways:
+
+=item a slash before the name
+=item the string "no-" before the name
+
+Some examples:
+
+=item -i  option "i" is True
+=item -j5  option "j" has the value 5
+=item -im  options "i" and "m" are True
+=item -/i  option "i" is False
+=item -/im  options "i" and "m" are False
+=item -no-i  option "i" is False
+=item --foo  option "foo" is True
+=item --/foo  option "foo" is False
+=item --no-foo  option "foo" is False
+
+If the specification of an option contains an equal sign after the name,
+then whatever follows that, is considered the value of that option.  Whether
+or not that value needs to be quoted, and how they are to be quoted, really
+depends on the shell that you use to access `rak`.  Generally, if the value
+consists of alphanumeric characters only, no quoting is necessary.  Otherwise
+it's better to quote your values.
+
+Some examples:
+
+=item -s=foo  option "s" has the value "foo"
+=item -t='foo bar'  option "t" has the value "foo bar"
+=item --frobnicate=yes  option "frobnicate" has the value "yes"
+
 =head1 CREATING YOUR OWN OPTIONS
 
 App::Rak provides B<many> options.  If you are happy with a set of options
@@ -159,18 +205,62 @@ of options and than later access them with the given name:
 
 =begin code :lang<bash>
 
-# create --im shortcut for ignoring case and accents
-$ rak --ignorecase --ignoremark --save=im
-Saved option '--im' as: --ignorecase --ignoremark
+# create -i shortcut for ignoring case
+$ rak --ignorecase --save=i
+Saved option '-i' as: --ignorecase
+
+# create -m shortcut for ignoring accents
+$ rak --ignoremark --save=m
+Saved option '-m' as: --ignoremark
 
 # same as --ignorecase --ignoremark
-$ rak foo --im
+$ rak foo -im
+
+=end code
+
+Generally speaking, the most used boolean options can be saved as single
+letter options: this allows multiple options to be specified in a single,
+short manner (as shown above).
+
+To better document / remember what a particular custom option is meant to
+do, you can add a description with the C<--description> option.
+
+=begin code :lang<bash>
+
+# add a description to the -i custom option
+$ rak --description='Search without caring for uppercase' --save=i
+Saved '--description='Search without caring for uppercase'' as: -i
+
+# add an option -g for searching only git files
+$ rak --description='Committed files only' --under-version-control --save=g
+Saved '--description='Committed files only' --under-version-control' as: -g
 
 =end code
 
+There is also a special named option that indicates the options that will
+be automatically activated on any invocation: C<(default)>.
+
+=begin code :lang<bash>
+
+# enable --smartcase by default on every run
+$ rak --smartcase --save='(default)'
+Saved '--smartcase' as: (default)
+
+=end
+
 You can use the C<--list-custom-options> to see what options you have saved
 before.
 
+Custom options are saved in C<~/.rak-config.json>.  You can override this
+by specifying the C<RAK_CONFIG> environment variable.
+
+=begin code :lang<bash>
+
+# read custom options from ".custom.json" (in the current directory)
+$ RAK_CONFIG=.custom.json rak foo
+
+=end code
+
 =head1 SUPPORTED OPTIONS
 
 All options are optional.  Any unexpected options, will cause an exception