Add support for --unicode

And many fixes and documentation improvements

Changes

@@ -1,6 +1,17 @@
 Revision history for App-Rak
 
 {{$NEXT}}
+     - Add support for --unicode
+     - Workaround Raku issue with coercion to Str with highlighting
+     - Fix issue with non-matching incomplete flags, such as --tri
+     - Make non-empty Slip return values from Callables DTRT
+     - Add documentation on possible return values of Callable patterns
+     - Bump dependency on rak for deadlock issues caused by Git::Files
+     - Fix issue with --blame-per-file not honoring e.g. --unique
+     - Fix issue with --blame-per-line not honoring e.g. --unique
+     - Fix issue with --json-per-file not honoring e.g. --unique
+     - Fix issue with --json-per-line not honoring e.g. --unique
+     - Fix issue with --json-per-elem not honoring e.g. --unique
 
 0.0.98  2022-09-26T19:49:26+02:00
      - Bump dependency on rak to get :old-new support

META6.json

@@ -14,7 +14,7 @@
     "highlighter:ver<0.0.14>: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.26>:auth<zef:lizmat>",
+    "rak:ver<0.0.28>:auth<zef:lizmat>",
     "String::Utils:ver<0.0.12>:auth<zef:lizmat>"
   ],
   "description": "21st century grep / find / ack / ag / rg on steroids",

README.md

@@ -27,7 +27,7 @@ DESCRIPTION
 
 App::Rak provides a CLI called `rak` that allows you to look for a pattern in (a selection of files) from one or more directories recursively. It has been modelled after utilities such as `grep`, `ack`, `ag` and `rg`, with a little bit of `find` mixed in, and `-n` and `-p` parameters of many programming languages.
 
-Note: this is still very much in alpha development phase. Comments, suggestions and bug reports are more than welcome!
+Note: this project is now in beta-development phase. Comments, suggestions and bug reports continue to be more than welcome!
 
 POSITIONAL ARGUMENTS
 ====================
@@ -53,9 +53,49 @@ Paths can also be specified with the `--paths` option, in which case there shoul
 ON CALLABLES AS PATTERN
 =======================
 
+`Callables` can be specfied by a string starting with `*.` (so-called [Whatever currying](https://docs.raku.org/type/Whatever), or as a string starting with `{` and ending with `}`.
+
+Note that if a `Callable` is specified as a pattern, then no highlighting can be performed as it cannot signal why or where a match occurred.
+
+The return value of the pattern `Callable` match is interpreted in the following way:
+
+True
+----
+
+If the `Bool`ean True value is returned, assume the pattern is found. Produce the item unless `--invert-match` was specified.
+
+False
+-----
+
+If the `Bool`ean False value is returned, assume the pattern is **not** found. Do **not** produce the item unless `--invert-match` was specified.
+
+Nil
+---
+
+If `Nil` is returned, assume the pattern is **not** found.
+
+This typically happens when a `try` is used in a pattern, and an execution error occurred. Do **not** produce the item unless `--invert-match` was specified.
+
+Empty
+-----
+
+If the empty `Slip` is returned, assume the pattern is **not** found. Do **not** produce the item unless `--invert-match` was specified. Shown in stats as a `passthru`.
+
+any other Slip
+--------------
+
+If a non-empty `Slip` is returned, produce the values of the `Slip` separately for the given item (each with the same item number).
+
+### any other value
+
+Produce that value.
+
+PHASERS IN CALLABLE PATTERNS
+============================
+
 The Raku Programming Language has a number of unique features that can be used with patterns that are so-called `Callable`s. One of them is the use of so-called [phasers](https://docs.raku.org/language/phasers) (pieces of code that will be executed automatically when a certain condition has been met.
 
-`App::Rak` currently supports the [loop phasers](https://docs.raku.org/language/phasers#FIRST):
+`App::Rak` currently supports all of Raku's [loop phasers](https://docs.raku.org/language/phasers#FIRST):
 
   * FIRST - code to run when searching starts
 
@@ -1044,6 +1084,11 @@ NOTE: support of this feature depends on Raku supporting that feature on the cur
 
 Indicate whether to only select files that are under some form of version control. If specified with a trueish value, will assume files that are under `git` version control. Can also specify the name of the version control system as the value: currently only **git** is supported.
 
+--unicode
+---------
+
+Flag. If specified with a true value, will search the unicode database for defined codepoints by name. Default is `False`.
+
 --unique
 --------
 

doc/App-Rak.rakudoc

@@ -30,8 +30,8 @@ been modelled after utilities such as C<grep>, C<ack>, C<ag> and C<rg>, with
 a little bit of C<find> mixed in, and C<-n> and C<-p> parameters of many
 programming languages.
 
-Note: this is still very much in alpha development phase.  Comments,
-suggestions and bug reports are more than welcome!
+Note: this project is now in beta-development phase.  Comments, suggestions
+and bug reports continue to be more than welcome!
 
 =head1 POSITIONAL ARGUMENTS
 
@@ -67,13 +67,58 @@ option was used for the pattern specification.
 
 =head1 ON CALLABLES AS PATTERN
 
+C<Callables> can be specfied by a string starting with C<*.> (so-called
+L<Whatever currying|https://docs.raku.org/type/Whatever>, or as a string
+starting with C<{> and ending with C<}>.
+
+Note that if a C<Callable> is specified as a pattern, then no highlighting
+can be performed as it cannot signal why or where a match occurred.
+
+The return value of the pattern C<Callable> match is interpreted in the
+following way:
+
+=head2 True
+
+If the C<Bool>ean True value is returned, assume the pattern is found.
+Produce the item unless C<--invert-match> was specified.
+
+=head2 False
+
+If the C<Bool>ean False value is returned, assume the pattern is B<not>
+found.  Do B<not> produce the item unless C<--invert-match> was specified.
+
+=head2 Nil
+
+If C<Nil> is returned, assume the pattern is B<not> found.
+
+This typically happens when a C<try> is used in a pattern, and an execution
+error occurred.  Do B<not> produce the item unless C<--invert-match> was
+specified.
+
+=head2 Empty
+
+If the empty C<Slip> is returned, assume the pattern is B<not> found.
+Do B<not> produce the item unless C<--invert-match> was specified.  Shown
+in stats as a C<passthru>.
+
+=head2 any other Slip
+
+If a non-empty C<Slip> is returned, produce the values of the C<Slip>
+separately for the given item (each with the same item number).
+
+=head3 any other value
+
+Produce that value.
+
+=head1 PHASERS IN CALLABLE PATTERNS
+
 The Raku Programming Language has a number of unique features that can
 be used with patterns that are so-called C<Callable>s.  One of them is
 the use of so-called L<phasers|https://docs.raku.org/language/phasers>
 (pieces of code that will be executed automatically when a certain
 condition has been met.
 
-C<App::Rak> currently supports the
+C<App::Rak> currently supports all of Raku's
 L<loop phasers|https://docs.raku.org/language/phasers#FIRST>:
 
 =item FIRST - code to run when searching starts
@@ -1300,6 +1345,11 @@ control.  If specified with a trueish value, will assume files that are
 under C<git> version control.  Can also specify the name of the version
 control system as the value: currently only B<git> is supported.
 
+=head2 --unicode
+
+Flag.  If specified with a true value, will search the unicode database
+for defined codepoints by name.  Default is C<False>.
+
 =head2 --unique
 
 Flag.  If specified with a true value, will only produce unique lines of