Add support for --accept and --deny

After discussing a use case on #raku-rak .  Allows one to specify Raku
code that will accept a file or deny a file from being further inspected.

Also add some answers to some questions in the FAQ.

Add default --file setting always, unless it is explicitely set, or
set implicitely by another explicit option (such as --extensions).

Changes

@@ -1,7 +1,8 @@
 Revision history for App-Rak
 
 {{$NEXT}}
-     - Bump dependency on rak to get URL fetching support
+     - Bump dependency on rak to get URL support as file specification, and
+       support for --accept and --deny
      - Allow for multiple ecosystem specs with --ecosystem
      - Add support for --description
 

META6.json

@@ -13,7 +13,7 @@
     "highlighter:ver<0.0.15>:auth<zef:lizmat>",
     "JSON::Fast::Hyper:ver<0.0.3>:auth<zef:lizmat>",
     "META::constants:ver<0.0.3>:auth<zef:lizmat>",
-    "rak:ver<0.0.32>:auth<zef:lizmat>",
+    "rak:ver<0.0.33>:auth<zef:lizmat>",
     "String::Utils:ver<0.0.12>:auth<zef:lizmat>"
   ],
   "description": "21st century grep / find / ack / ag / rg on steroids",

README.md

@@ -144,6 +144,16 @@ SUPPORTED OPTIONS
 
 All options are optional. Any unexpected options, will cause an exception to be thrown with the unexpected options listed and possible alternatives mentioned. Unless specifically indicated otherwise, using the negation of a flag has the same effect as **not** specifying it.
 
+--accept=code
+-------------
+
+Specifies the code that should be executed that should return `True` if the path is acceptable, given an `IO::Path` object of the path. See also `--deny`.
+
+```bash
+# Include files that have "use Test" in them
+$ rak --accept='*.slurp.contains("use Test")'
+```
+
 --accessed=condition
 --------------------
 
@@ -275,6 +285,16 @@ 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>.
 
+--deny=code
+-----------
+
+Specifies the code that should be executed that should return `True` if the path is **NOT** acceptable, given an `IO::Path` object of the path. See also `--accept`.
+
+```bash
+# Include files that **NOT** have "use Test" in them
+$ rak --deny='*.slurp.contains("use Test")'
+```
+
 --description=text
 ------------------
 

doc/App-Rak.rakudoc

@@ -178,6 +178,19 @@ to be thrown with the unexpected options listed and possible alternatives
 mentioned.  Unless specifically indicated otherwise, using the negation of
 a flag has the same effect as B<not> specifying it.
 
+=head2 --accept=code
+
+Specifies the code that should be executed that should return C<True> if
+the path is acceptable, given an C<IO::Path> object of the path.  See also
+C<--deny>.
+
+=begin code :lang<bash>
+
+# Include files that have "use Test" in them
+$ rak --accept='*.slurp.contains("use Test")'
+
+=end code
+
 =head2 --accessed=condition
 
 If specified, indicates the C<Callable> that should return True to include a
@@ -356,6 +369,19 @@ 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 --deny=code
+
+Specifies the code that should be executed that should return C<True> if
+the path is B<NOT> acceptable, given an C<IO::Path> object of the path.
+See also C<--accept>.
+
+=begin code :lang<bash>
+
+# Include files that **NOT** have "use Test" in them
+$ rak --deny='*.slurp.contains("use Test")'
+
+=end code
+
 =head2 --description=text
 
 Specify a description to be saved with the custom option.  This will be

lib/App/Rak.rakumod

@@ -3,7 +3,7 @@ use as-cli-arguments:ver<0.0.6>:auth<zef:lizmat>;  # as-cli-arguments
 use has-word:ver<0.0.3>:auth<zef:lizmat>;          # has-word
 use highlighter:ver<0.0.15>:auth<zef:lizmat>;      # columns highlighter matches
 use JSON::Fast::Hyper:ver<0.0.3>:auth<zef:lizmat>; # from-json to-json
-use rak:ver<0.0.32>:auth<zef:lizmat>;              # rak
+use rak:ver<0.0.33>:auth<zef:lizmat>;              # rak
 use String::Utils:ver<0.0.12>:auth<zef:lizmat> <after before between is-sha1>;
 
 # The epoch value when process started
@@ -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-07T16:08:12+02:00 by tools/makeOPTIONS.raku
+#- Generated on 2022-10-07T22:50:16+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 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>;
+my str @options = <absolute accept 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 deny 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 ----------------------------------------------------
 
@@ -68,6 +68,7 @@ my constant %falsies =
   TYPE             => 'extensions',
   v                => 'invert-match',
   x                => 'files-from',
+  1                => 'only-first',
 
 # from ag
   a                => 'find-all',
@@ -999,6 +1000,13 @@ my sub set-filesystem-name(str $name, $value, $name-getter, $id-getter --> Nil)
     }
 }
 
+# handle file attributes that need a callable
+my sub set-filesystem-callable(str $name, $value --> Nil) {
+    Bool.ACCEPTS($value)
+      ?? meh "--$name cannot be specified as a flag"
+      !! (%filesystem{$name} := convert-to-simple-Callable($value, $name));
+}
+
 # handle external execution
 my sub external-execution(str $name, $value --> Nil) {
     Bool.ACCEPTS($value)
@@ -1129,6 +1137,10 @@ my sub option-absolute($value --> Nil) {
     set-listing-flag('absolute', $value)
 }
 
+my sub option-accept($value --> Nil) {
+    set-filesystem-callable('accept', $value)
+}
+
 my sub option-accessed($value --> Nil) {
     set-filesystem-Instant('accessed', $value)
 }
@@ -1228,6 +1240,10 @@ my sub option-degree($value --> Nil) {
       !! meh "'--degree' must be an integer, or a Callable, not '$value'";
 }
 
+my sub option-deny($value --> Nil) {
+    set-filesystem-callable('deny', $value)
+}
+
 my sub option-description($value --> Nil) {
     Bool.ACCEPTS($value)
       ?? meh "'--description' can only be specified as a string"
@@ -1869,9 +1885,8 @@ my sub move-filesystem-options-to-rak(--> Nil) {
         %rak ,= %filesystem;
         %filesystem = ();
     }
-    else {
-        %rak<file> := codify-extensions @known-extensions;
-    }
+
+    %rak<file> := codify-extensions @known-extensions unless %rak<file>:exists;
 }
 
 my sub move-result-options-to-rak(--> Nil) {

resources/help.txt

@@ -46,8 +46,10 @@ Haystack specification:
 
 Filesystem filters:
  --accessed=condition    Check on epoch when file was last accessed
+ --accept=code           Given an IO of a file, return if file acceptable
  --blocks=condition      Number of filesystem blocks used by file
  --created=condition     Check on epoch when file was created
+ --deny=code             Given an IO of a file, return if **NOT** acceptable
  --device-number         Number of device on which file is located
  --dir=expression        Directory basename filter, default: not ^.
  --exec=program          Run program, include if successful

resources/help/faq.txt

@@ -1,4 +1,11 @@
 Frequently Asked Questions:
 ‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒
 
-There are no frequently asked questions yet.
+Q: How can I limit to files with a certain extension?
+A: Use "--extensions=name" where "name" is the actual extension.  Note that
+   a period will be added for the actual comparisons.
+
+Q: How can I limit to files without extension?
+A: Use "--extensions=,".  This works because the comma is used to indicate
+   multiple extensions to accept.  In this case, since there are no letters
+   between the "=" and the ",", it specifies a zero character extension.

resources/help/filesystem.txt

@@ -51,6 +51,26 @@ Flag.  If specified with a True value, will only accept files of which
 the extension is an extension of any of the predefined extension groups.
 Conflicts with --file, --find-all or --extensions.
 
+Refining by content:
+
+--accept=code
+
+Specifies the code that should be executed that should return True if
+the path is acceptable, given an IO::Path object of the path.
+
+Example:
+# Include files that have "use Test" in them
+$ rak --accept='*.slurp.contains("use Test")'
+
+--deny=code
+
+Specifies the code that should be executed that should return True if
+the path is **NOT** acceptable, given an IO::Path object of the path.
+
+Example:
+# Include files that **NOT** have "use Test" in them
+$ rak --deny='*.slurp.contains("use Test")'
+
 Refining by epoch:
 
 These arguments expect a Callable that will be given the associated