More documentation

- also allow --degree to take a Callable

Changes

@@ -12,6 +12,7 @@ Revision history for App-Rak
        more in line with the concept of producers producing items
      - Make dependency on Edit::Files optional
      - Fix issue with --modify-files losing line-endings
+     - Allow a Callable to be specified with --degree
 
 0.0.99  2022-09-27T22:12:15+02:00
      - Add support for --unicode

doc/App-Rak.rakudoc

@@ -1219,7 +1219,7 @@ Save all options with the given name in the configuration file
 been saved with the given name.
 
 This feature can used to both create shortcuts for specific (long) options,
-or just as a convenient way to combine often used options.
+or just as a convenient way to combine often used options, or both.
 
 =begin code :lang<bash>
 
@@ -1229,8 +1229,8 @@ Saved option '--im' as: --ignorecase --ignoremark
 # same as --ignorecase --ignoremark
 $ rak foo --im
 
-$ rak --follow-symlinks --save=fs
-Saved option '--fs' as: --follow-symlinks
+$ rak --recurse-symlinked-dir --save=rsd
+Saved option '--rsd' as: --recurse-symlinked-dir
 
 $ rak --break='[---]' --save=B
 Saved option '--B' as: --break='[---]'

lib/App/Rak.rakumod

@@ -441,10 +441,10 @@ my sub convert-to-Callable(Str:D $code) {
 }
 
 # Convert a string to non-Regex code, fail if not possible
-my sub convert-to-simple-Callable(Str:D $code) {
+my sub convert-to-simple-Callable(Str:D $code, str $name) {
     my $callable := codify($code);
     Regex.ACCEPTS($callable)
-      ?? meh "Cannot use a regular expression in this context: '$code'"
+      ?? meh "Cannot use a regular expression for --$name: '$code'"
       !! $callable
 }
 
@@ -902,7 +902,7 @@ my sub set-filesystem-Instant(str $name, $value --> Nil) {
         $init-epoch - seconds(.substr(1, *-5))
     });
 
-    my $compiled := convert-to-simple-Callable($code);
+    my $compiled := convert-to-simple-Callable($code, $name);
     Callable.ACCEPTS($compiled)
       ?? (%filesystem{$name} := $compiled)
       !! meh "Problem compiling expression for '--$name': $value";
@@ -912,7 +912,7 @@ my sub set-filesystem-Instant(str $name, $value --> Nil) {
 my sub set-filesystem-Int(str $name, $value --> Nil) {
     meh "Must specify a condition for '--$name'" if Bool.ACCEPTS($value);
 
-    my $compiled := convert-to-simple-Callable($value);
+    my $compiled := convert-to-simple-Callable($value, $name);
     Callable.ACCEPTS($compiled)
       ?? (%filesystem{$name} := $compiled)
       !! meh "Problem compiling condition for '--$name': $value";
@@ -922,7 +922,7 @@ my sub set-filesystem-Int(str $name, $value --> Nil) {
 my sub set-filesystem-id(str $name, $value --> Nil) {
     meh "Must specify a condition for '--$name'" if Bool.ACCEPTS($value);
 
-    my $compiled := convert-to-simple-Callable($value);
+    my $compiled := convert-to-simple-Callable($value, $name);
     %filesystem{$name} := do if Callable.ACCEPTS($compiled) {
         $compiled
     }
@@ -953,7 +953,7 @@ my sub set-filesystem-name(str $name, $value, $name-getter, $id-getter --> Nil)
     }
 
     # An actual condition
-    my $compiled := convert-to-simple-Callable($value);
+    my $compiled := convert-to-simple-Callable($value, $name);
     %filesystem{$name} := do if Callable.ACCEPTS($compiled) {
         -> $id { $compiled($_) with id-getter($id).head }
     }
@@ -1186,7 +1186,13 @@ my sub option-csv-per-line($value --> Nil) {
 }
 
 my sub option-degree($value --> Nil) {
-    set-rak-Int('degree', $value);
+    my $code := convert-to-simple-Callable($value, 'degree');
+    my $integer := Callable.ACCEPTS($code)
+      ?? $code(Kernel.cpu-cores).Int
+      !! $value.Int;
+    Int.ACCEPTS($integer)
+      ?? (%rak<degree> := $integer)
+      !! meh "'--degree' must be an integer, or a Callable, not '$value'";
 }
 
 my sub option-device-number($value --> Nil) {

resources/help.txt

@@ -143,9 +143,9 @@ Option management:
 General options:
  --help      Show this
  --help foo  Show additional help about:
-               pattern | string   | code    | haystack | result  | listing
-               content | resource | special | option   | general | philosophy
-               examples
+   argument   | code       | content  | debugging | examples | faq
+   filesystem | general    | haystack | item      | listing  | option
+   pattern    | philosophy | resource | result    | special  | string
  --version                Show version information
  --verbose                Be more verbose, if applicable
 
@@ -156,6 +156,7 @@ Debugging options:
  --rak                    Show arguments to "rak" plumbing before running
 
 Argument format:
+ foo        Positional argument
  --foo      Option "foo" is True
  --/foo     Option "foo" is False
  --no-foo   Option "foo" is False

resources/help/argument.txt

@@ -1,6 +1,7 @@
 Argument format:
 ‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒
 
+In short:
  foo        Positional argument
  --foo      Option "foo" is True
  --/foo     Option "foo" is False
@@ -9,3 +10,32 @@ Argument format:
  -fo        Single letter options "f" and "o" True
  -/ba       Single letter options "b" and "a" False
  -j2        Single letter option "j" with value 2
+
+More verbose:
+Command line arguments come in two types: positional and named.
+Named arguments start with a "-" and are usually referred to as
+"options" in the documentation.  And argument that does not start
+with a hyphen, is considered to be a positional argument.
+
+Named and positional arguments can be specified in any order.
+
+Note that the values of some arguments will need quoting in some
+form according to rules determined by the shell being used.
+
+If a named argument starts with single "-", then the name is
+considered to be a sequence of one letter named arguments
+with a boolean True value.  Except if all of the characters
+after the first letter are numeric, then these are considered
+a numerical value specified with that single letter named
+argument.
+
+If a named argument starts with two hyphens, then the characters
+after it (until an optional equal sign) are considered to be
+the name of a single named argument.  If such a named argument
+contains an equal sign, then the characters after the equal sign
+are considered the value of that named argument.
+
+If there is no equal sign, then the named argument is supposed
+to be a Boolean True value.  Except when there is a slash, or
+"no-" after the first hyphen(s), in which case the named argument
+is considered to have the boolean False value.

resources/help/general.txt

@@ -10,10 +10,12 @@ Show an overview of all options of the "rak" command line interface.
 Show additional information about the given subject.  Possible subjects
 are (in alphabetical order):
 
+- argument    Argument format
 - code        Code pattern helpers
 - content     Content modifiers
-- debug       Debugging options
+- debugging   Debugging options
 - examples    Usage examples
+- faq         Frequently asked questions
 - filesystem  File system filters
 - general     General options
 - haystack    Haystack specification

resources/help/listing.txt

@@ -46,12 +46,12 @@ Force defaults as if a human is watching.  Defaults to True if a human
 is watching (aka, a terminal is connected to STDOUT, aka $*OUT.t is true).
 The following defaults will be applied unless specifically overridden:
 
-- --break=""
-- --group-matches
-- --highlight
-- --trim
-- --only-first=1000
-- --proximate=1
+ --break=""
+ --group-matches
+ --highlight
+ --trim
+ --only-first=1000
+ --proximate=1
 
 --only-first[=N]
 

resources/help/option.txt

@@ -3,9 +3,60 @@ Option management:
 
 --save=name
 
-Translate --name to all other options specified, remove if --save
-was the only option specified
+Create a custom option with the name given, of all the other named
+arguments specified.  The other named arguments may themselves be
+shortcuts.
+
+Examples:
+# specify '--rsd' as a shortcut to '--recurse-symlinked-dir"
+$ rak --recurse-symlinked-dir --save=rsd
+
+# specify '--i' as shortcut to '--ignorecase'
+$ rak --ignorecase --save=i
+
+# specify '--m' as shortcut to '--ignoremark'
+$ rak --ignoremark --save=m
+
+# run a search with '--ignorecase' and '--ignoremark'
+$ rak -im foo
+
+# specify '--r' as shortcut to '-im' and '--extensions=#raku'
+$ rak -im --extensions=#raku --save=r
+
+# run a search with --im on files with raku extensions
+$ rak -r foo
+
+One of these other named arguments can be marked as needing to
+have a value specified with a single exclamation mark as its value.
+
+Examples:
+# specify '--ex' as a shortcut for '--extensions', requiring a value
+$ rak --extensions=! --save=ex
+
+# run a search on files with raku extensions only
+$ rak foo --ex=#raku
+
+It's also possible for one named argument to have a default value
+(that can be overridden) by specifying the default value between
+square brackets.
+
+Examples:
+# specify '--x' as a shortcut for --extensions=#raku with override
+$ rak --extensions=[#raku] --save=x
+
+# run a search on files with Raku extensions
+$ rak -x foo
+
+# run a search on files with ".dat" extensions
+$ 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:
+# Remove the '--ex' custom option
+$ rak --save=ex
 
 --list-custom-options
 
-List all previously saved options
+List all currently known custom options.  Must be the only argument.

resources/help/resource.txt

@@ -1,10 +1,39 @@
 Resource usage:
 ‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒
 
---batch=N
+By default, "rak" attempts to use all computer's resources as
+much as possible.  You can tune some of the parameters related
+to parallelism of execution.
 
-Max number of files to process in a thread (default: 64)
+--batch[=N]
 
---degree=N
+Indicate how many files should be processed within a single worker
+thread at a time.  Defaults to 64 if not specified.  When specified
+as a flag without any value, will assume the value 1.
 
-Max number of threads to use for processing (default: cores - 1)
+Examples:
+# run a search using batches of 1024 files per worker thread
+$ rak --batch=1024 foo
+
+# run a search with each file handled by a separate worker thread
+$ rak --batch foo
+
+--degree[=N | code]
+
+Indicate how many worker threads should be use maximally (which
+usually effectively means the number of CPU cores to be used).
+Defaults to the number of CPU cores minus one (with a minimum of
+one, obviously).  When specified as a flag without any value,
+will assume the value 1.  When specified with a Callable, will
+call that Callable with the total number of CPUs available,
+and will use the result as the value to apply.
+
+Examples:
+# run a search on only one worker thread
+$ rak --degree foo
+
+# run a search on maximally 2 worker threads
+$ rak --degree=2 foo
+
+# run a search on half of the CPUs maximally
+$ rak --degree='*/2' foo

resources/help/result.txt

@@ -1,62 +1,77 @@
 Result modifiers:
 ‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒
 
+These options alter the way a search result is processed and shown.
+Many combinations of these options may or may not make sense.
+
 --after-context=N
 
-List N lines after any line with a match
+Also produce N items after any item with a match.  Defaults to *no*
+items after any item with a match.
 
 --before-context=N
 
-List N lines before any line with a match
+Also produce N items before any item with a match.  Defaults to *no*
+items before any item with a match.
 
 --context=N
 
-List N lines around any line with a match
+Also produce N items before and after any item with a match.
+Defaults to *no* items before or after a match.
 
 --count-only
 
-Only return count of matches
+When specified with a true value, will **ONLY** produce result counts.
 
 --files-with-matches
 
-Only return filenames with matches
+Produce only the names of files *with* matches.  By default, will
+return full result information.
 
 --files-without-matches
 
-Only return filenames without matches
+Produce only the names of files *without* matches.  By default, will
+return full result information.
 
 --frequencies
 
-Only return lines and their frequencies
+Create a Bag of the search result and produce the contents of the Bag
+in decreasing frequency.  Usually used in conjunction with a Callable
+pattern that produces a string, or with --matches-only.
 
 --invert-match
 
-Select lines that do **not** match
+Invert the meaning of matching, producing items that did *not* match.
 
 --matches-only
 
-Only produce the actual matches
+Only produce the actual matches, instead of the items that matched.
+Usually used in conjunction with --unique or --frequencies.
 
 --max-matches-per-file=N
 
-Maximum number of matches per file, default: all
+Specify the maximum number of matches that should be produced per
+file.  If not specified, will produce all possible matches of a file.
 
 --paragraph-context
 
-List all lines in the same paragraph around a match
+Also produce all items before and after any matched item if they are
+in the same paragraph.  A paragraph being defined as the items between
+two items that stringify to the empty string.
 
 --passthru
 
-List all lines always
+Always produce all items.
 
 --passthru-context
 
-List all lines if there is at least one match
+Produce all items of a file if there was at least one match.
 
 --stats-only
 
-Only return statistics of the search
+When specified with a true value, will **ONLY** produce statistics.
+See also --stats.
 
 --unique
 
-Only return unique lines
+Only produce unique items (or whatever a Callable pattern produced).