App-Rak.rakudoc

=begin pod

=head1 NAME

App::Rak - 21st century grep / find / ack / ag / rg on steroids

=head1 SYNOPSIS

=begin code :lang<bash>

$ rak foo      # look for "foo" in current directory recursively

$ rak foo bar  # look for "foo" in directory "bar" recursively

$ rak '/ << foo >> /'    # look for "foo" as word in current directory

$ rak foo --files-with-matches  # look for "foo", only produce filenames

$ rak foo --before=2 --after=2  # also produce 2 lines before and after

$ rak '{.contains("foo") && .contains("bar")}'  # lines with foo AND bar

=end code

=head1 DESCRIPTION

App::Rak provides a CLI called C<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 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 project is now in beta-development phase.  Comments, suggestions
and bug reports continue to be more than welcome!

=head1 POSITIONAL ARGUMENTS

=head2 pattern

The pattern to search for.  This can either be a string, or a
L<Raku regular expression|https://docs.raku.org/language/regexes>
(indicated by a string starting and ending with C</>), a
C<Callable> (indicated by a string starting with C<{> and ending with C<}>),
or a a result of L<C<Whatever> currying|https://docs.raku.org/type/Whatever>
(indicated by a string starting with C<*.>).

Can also be specified with the C<--pattern> option, in which case B<all>
the positional arguments are considered to be a path specification.

If the pattern is a C<Callable>, then the dynamic variable C<$*SOURCE> will
contain the C<IO::Path> object of the file being processed.  Note that
pattern C<Callable>s will be called in a thread B<unsafe> manner.

=head2 path(s)

Optional.  Either indicates the path of the directory (and its
sub-directories), or the file that will be searched.  By default, all
directories that do not start with a period, will be recursed into (but
this can be changed with the C<--dir> option).

By default, all files will be searched in the directories.  This can be
changed with the C<--file> option.

Paths can also be specified with the C<--paths> option, in which case there
should only be a positional argument for the pattern, or none if C<--pattern>
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 all of Raku's
L<loop phasers|https://docs.raku.org/language/phasers#FIRST>:

=item FIRST - code to run when searching starts
=item NEXT - code to run when searching a file is done
=item LAST - code to run when searching is done

These phasers will be called in a thread-safe manner.

=begin code :lang<bash>

$ rak '{ FIRST state $seen = 0; NEXT $seen++; LAST say "$seen files"; .contains("pattern")}'

=end code

Any other phasers that do not require special attention by C<App::Rak>
are also supported in any code specified.

=head1 CREATING YOUR OWN OPTIONS

App::Rak provides B<many> options.  If you are happy with a set of options
for a certain workflow, You can use the C<--save> option to save that set
of options and than later access them with the given name:

=begin code :lang<bash>

$ rak --ignorecase --ignoremark --save=im
Saved option '--im' as: --ignorecase --ignoremark

# same as --ignorecase --ignoremark
$ rak foo --im

=end code

You can use the C<--list-custom-options> to see what options you have saved
before.

=head1 SUPPORTED OPTIONS

All options are optional.  Any unexpected options, will cause an exception
to be thrown with the unexpected options listed.

=head2 --accessed=condition

If specified, indicates the C<Callable> that should return True to include a
file in the selection of files to be checked.  The access time of the file
(number of seconds since epoch, as a C<Num> value) will be passed as the
only argument.  Note that many file systems do not actually support this
reliably.

See "CHECKING TIMES ON FILES" for more information about features that
can be used inside the C<Callable>.

=head2 --absolute

Flag.  If specified with a trueish value indicates that whenever paths
are shown, they will be shown as absolute paths.  Defaults to C<False>,
which will cause paths to be shown as paths relative to the current
directory.

=head2 --after-context=N

Indicate the number of lines that should be shown B<after> any line that
matches.  Defaults to B<0>.  Will be overridden by a C<--context> argument.

=head2 --allow-loose-escapes

Only applicable if C<--csv-per-line> has been specified.  Flag.  If specified,
indicates that B<any> character may be escaped.

=head2 --allow-loose-quotes

Only applicable if C<--csv-per-line> has been specified.  Flag.  If specified,
indicates that fields do not need to be quoted to be acceptable.

=head2 --allow-whitespace

Only applicable if C<--csv-per-line> has been specified.  Flag.  If specified,
indicates that whitespace is allowed around separators.

=head2 --auto-diag

Only applicable if C<--csv-per-line> has been specified.  Flag.  If
(implicitly) specified with a trueish value, will show diagnostic information
about problems that occurred during parsing of the CSV file.  The default is
C<True>.

=head2 --backup[=extension]

Indicate whether backups should be made of files that are being modified.
If specified without extension, the extension C<.bak> will be used.

=head2 --batch=N

Indicate the number of files that should be checked per thread.  Defaults
to C<64> if not specified.  See also <--degree>.

=head2 --before-context=N

Indicate the number of lines that should be shown B<before> any line that
matches.  Defaults to B<0>.  Will be overridden by a C<--context> argument.

=head2 --blame-per-file

Flag.  Only makes sense if the pattern is a C<Callable>.  If specified with a
C<True> value, indicates that each of the selected files will be provided as
L<C<Git::Blame::File>|https://raku.land/zef:lizmat/Git::Blame::File#methods-on-gitblamefile>
objects if C<git blame> can be performed on the a selected file.  If that
is not possible, then the selected file will be ignored.

If <git blame> information can be obtained, then the associated
C<Git::Blame::File> object will be presented to the pattern C<Callable>.
If the Callable returns a true value, then filename will be shown.  If the
returned value is a string, then that string will be shown.

=begin code :lang<bash>

# show files with more than 10 commits
$ rak '*.commits > 10' --blame-per-file --files-with-matches

=end code

Requires that the L<C<Git::Blame::File>|https://raku.land/zef:lizmat/Git::Blame::File> module is installed.

=head2 --blame-per-line

Flag.  Only makes sense if the pattern is a C<Callable>.  If specified with a
C<True> value, indicates that each line from the selected files will be
provided as L<C<Git::Blame::Line>|https://raku.land/zef:lizmat/Git::Blame::File#accessors-on-gitblameline>
objects if C<git blame> can be performed on the a selected file.  If that
is not possible, then the selected file will be ignored.

If <git blame> information can be obtained, then the associated
C<Git::Blame::Line> object will be presented to the pattern C<Callable>.
If the Callable returns a true value, then the short representation of
the C<git blame> information will be shown.  If the returned value is a
string, then that string will be shown.

=begin code :lang<bash>

# show git blame on lines of which the author is "Scooby Doo"
$ rak '{ .author eq "Scooby Doo" }' --blame-per-line

=end code

Requires that the L<C<Git::Blame::File>|https://raku.land/zef:lizmat/Git::Blame::File> module is installed.

=head2 --blocks=condition

If specified, indicates the C<Callable> that should return True to include a
file in the selection of files to be checked.  The number of logical blocks
that a file takes up in the filesystem, will be passed as the only argument.

=begin code :lang<bash>

# show files that consist of at least 3 blocks
$ rak --find --blocks='* >= 3'

=end code

=head2 --break[=string]

Indicate whether there should be a visible division between matches of
different files.  Can also be specified as a string to be used as the
divider.  Defaults to C<True> (using an empty line as a divider) if
C<--group-matches> is (implicitly) set to C<True>, else defaults to C<False>.

=head2 --checkout=branch

Only valid if the current directory is under git version control.  Indicate
the branch to checkout by the general matching logic of App::Rak.  Will
produce listing of matching branches if more than one, or say that there
is no match.  Branches need not have been checked out locally yet.

=head2 --context=N

Indicate the number of lines that should be shown B<around> any line that
matches.  Defaults to B<0>.  Overrides any a C<--after-context> or
C<--before-context> arguments.

=head2 --count-only

Flag.  Indicate whether just the number of lines with matches should be
calculated.  When specified with a C<True> value, will show a "N matches
in M files" by default, and if the C<:files-with-matches> (or
C<files-without matches>) option is also specified with a C<True> value,
will just show total counts.  See also C<stats-only>.

=head2 --created=condition

If specified, indicates the C<Callable> that should return True to include a
file in the selection of files to be checked.  The creation time of the file
(number of seconds since epoch, as a C<Num> value) will be passed as the
only argument.

See "CHECKING TIMES ON FILES" for more information about features that
can be used inside the C<Callable>.

=head2 --csv-per-line

Flag.  Only makes sense if the pattern is a C<Callable>.  If specified with a
C<True> value, indicates that selected files should be interpreted as
comma separated values (CSV).  Each row from the selected files will be
provided as a list of strings (or of C<CSV::Field> objects).

Attempt to interpret file as a CSV file, and pass each row as a List to
to the pattern Callable.  Only files with extensions from the C<#csv> group
will be tried, unless overridden by any explicit extension specification.

More documentation can be found with the
L<Text::CSV|https://raku.land/github:Tux/Text::CSV> module itself.

=head2 --degree=N

Indicate the number of worker threads that should be maximally.  Defaults
to the number of cores minus 1 if not specified.  See also <--batch>.

=head2 --device-number=condition

If specified, indicates the C<Callable> that should return True to include a
file in the selection of files to be checked.  The device number of the
filesystem on which the file is located, will be passed as the only argument.

=head2 --dir=condition

If specified, indicates the C<Callable> that should return True to have a
directory be included for further recursions in file selection.  The basename
of the directory will be passed as the only argument.  Defaults to all
directories that do not start with a period.  Can specify as a flag to
include B<all> directories for recursion.

=head2 --dont-catch

Flag.  If specified with a trueish value, will B<not> catch any error
during processing, but will throw any error again.  Defaults to C<False>,
making sure that errors B<will> be caught.  Mainly intended for debugging
and error reporting.

=head2 --dryrun

Flag.  Indicate to B<not> actually make any changes to any content
modification if specified with a C<True> value.  Only makes sense together
with the C<--modify-files> and the C<--rename-files> option.

=head2 --edit[=editor]

Indicate whether the patterns found should be fed into an editor for
inspection and/or changes.  Defaults to C<False>.  Optionally takes the
name of the editor to be used.

=head2 --eol=[lf|cr|crlf]

Only applicable if C<--csv-per-line> has been specified.  Indicate a
line ending different from the standard line ending assumed by the system.
Can be specified as C<lf> for a single LineFeed character, C<cr> for a
single CarriageReturn character, or C<crlf> for a combination of a
CarriageReturn and a LineFeed character.

=head2 --escape=["]

Only applicable if C<--csv-per-line> has been specified.  Indicates the
escape character to be used to escape characters in a field.  Defaults to
B<double quote>.

=head2 --exec=invocation

If specified, indicates the name of a program and its arguments to be
executed. Any C<$_> in the invocation string will be replaced by the file
being checked. The file will be included if the program runs to a successful
conclusion.

=head2 --extensions=spec

Indicate the extensions of the filenames that should be inspected.
By default, no limitation on filename extensions will be done.

Extensions can be specified as a comma-separated list of either a
a predefined group of extensions (indicated by C<#name>), or a single
extension.

=begin code :lang<bash>

# inspect files with extensions used by Raku and Perl
$ rak foo --extensions=#raku,#perl

# inspect files with Markdown content
$ rak foo --extensions=md,markdown

# inspect files without extension
$ rak foo --extensions=

=end code

Predefined groups are C<#raku>, C<#perl>, C<#cro>, C<#text>, C<#c>, C<#c++>,
C<#yaml>, C<#ruby>, C<#python>, C<#html>, C<#markdown>, C<#json>, C<#jsonl>,
C<#csv>, C<#config> and C<#text>.

The C<--list-known-extensions> argument can be used to see which predefined
groups of extensions are supported, and which extensions they cover.

=head2 --file=condition

If specified, indicates the C<Callable> that should return True to have a
file be included in the file selection process.  The basename of the file
will be passed as the only argument.  Defaults to C<True>, indicating that
all files should be included.

=head2 --file-separator-null

Flag.  Indicate to separate filenames by null bytes rather than newlines
if the C<--files-with-matches> option is specified with a C<True> value.

=head2 --files-from=filename

Indicate the path of the file to read filenames from instead of the
expansion of paths from any positional arguments.  "-" can be specified
to read filenames from STDIN.

=head2 --files-with-matches

Flag.  If specified with a true value, will only produce the filenames of
the files in which the pattern was found.  Defaults to C<False>.

=head2 --files-without-matches

Flag.  If specified with a true value, will only produce the filenames of
the files in which the pattern was B<not> found.  Defaults to C<False>.

=head2 --filesize=condition

If specified, indicates the C<Callable> that should return True to include a
file in the selection of files to be checked.  The number of bytes of data
in the file, will be passed as the only argument.

=begin code :lang<bash>

# show files that consist of at 30 bytes
$ rak --find --filesize='* >= 30'

=end code

=head2 --find

Flag.  If specified with a true value, will B<not> look at the contents of
the selected paths, but instead consider the selected paths as lines in a
virtual file.

=head2 --find-all

Flag.  If specified with a true value, will override any file or directory
filter settings and include all possible files for inspection.

=head2 --only-first[=N]

Indicate the B<overall> number of matches to show.  If specified without a
value, will default to B<1>.  Defaults to B<1000> if a human is watching,
otherwise defaults to returning all possible matches.

=head2 --formula=[none]

Only applicable if C<--csv-per-line> has been specified.  If specified,
indicates the action to be taken when a field starts with an equal sign
(indicating a formula of some kind in many spreadsheets).  The following
values are recognized:

=item none - take not action, just pass on
=item die - throw an exception
=item diag - report line and position where formula was found
=item empty - replace the formula by an empty string

=head2 --frequencies

Flag.  If specified, will produce a frequency table of the matches with
the most frequent match first.  Default is C<False>.  See also C<--unique>;

=head2 --gid=condition

If specified, indicates the C<Callable> that should return True to include a
file in the selection of files to be checked.  The numeric C<gid> of the file
will be passed as the only argument.  Can also be specified as a single
numeric argument.  See also C<--group>.

=begin code :lang<bash>

# show files of which the numeric group id is greater than 20
$ rak --find --gid='* > 20'

# show files of which the numeric group id is 20
$ rak --find --gid=20

=end code

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --group=condition

If specified, indicates the C<Callable> that should return True to include a
file in the selection of files to be checked.  The name of the group
associated with the C<gid> of the file will be passed as the only argument.

Can also be specified as a list of comma separated names to (not) select on.
To select all names B<except> the listed named, prefix with a C<!>.

See also C<--gid>.  Requires the
L<P5getgrnam|https://raku.land/zef:lizmat/P5getgrnam> module to be installed.

=begin code :lang<bash>

# files of which the name associated with the user id starts with underscore
$ rak --find --group='*.starts-with("_")'

# show files of which the group is "staff"
$ rak --find --group=staff

# show files of which the group is NOT "staff"
$ rak --find --group='!staff'

=end code

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --group-matches

Flag.  Indicate whether matches of a file should be grouped together by
mentioning the filename only once (instead of on every line).  Defaults
to C<True>.

=head2 --hard-links=condition

If specified, indicates the C<Callable> that should return True to include a
file in the selection of files to be checked.  The number of hard-links to
the file on the filesystem, will be passed as the only argument.

=head2 --has-setgid

Flag. If specified with a trueish value, will only select files that do have
the SETGID bit set in their attributes.  Use negation C<--/has-setgid> to
only select files that do B<not> have the SETGID bit set.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --has-setuid

Flag. If specified with a trueish value, will only select files that do have
the SETUID bit set in their attributes.  Use negation C<--/has-setuid> to
only select files that do B<not> have the SETUID bit set.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --help [area-of-interest]

Show argument documentation, possibly extended by giving the area of
interest, which are:

=item pattern
=item string
=item code
=item input
=item haystack
=item filesystem
=item result
=item listing
=item resource
=item special
=item option
=item general
=item philosophy
=item examples

=head2 --highlight

Flag.  Indicate whether the pattern should be highlighted in the line in
which it was found.  Defaults to C<True> if a human is watching (aka STDOUT
connected to a terminal), or C<--highlight-before> or C<highlight-after>
are explicitely specified, or C<False> otherwise.

=head2 --highlight--after[=string]

Indicate the string that should be used at the end of the pattern found in
a line.  Specifying implies C<--highlight>ing implicitely.  If C<--highlight>
or C<--highlight-before> are explicitely specified, will default to whatever
is specified with C<--highlight-before>, or to the ANSI code to end B<bold>.

=head2 --highlight--before[=string]

Indicate the string that should be used at the end of the pattern found in
a line.  Specifying implies C<--highlight>ing implicitly.  If C<highlight>
is explicitely specified with a trueish value, will default to the terminal
code to start B<bold>.

=head2 --human

Flag.  Indicate that search results should be presented in a human readable
manner.  This means: filenames shown on a separate line, line numbers
shown, and highlighting performed.  Defaults to C<True> if C<STDOUT> is
a TTY (aka, someone is actually watching the search results), otherwise
defaults to C<False>.

=head2 --ignorecase

Flag.  If specified with a trueish value, indicates that any matching should
be done case insensitively.  Default is C<False>.

=head2 --ignoremark

Flag.  If specified with a trueish value, indicates that any matching should
be done without consideration of any accents.  Default is C<False>.

=head2 --inode=condition

If specified, indicates the C<Callable> that should return True to include a
file in the selection of files to be checked.  The inode number of the file
on the filesystem, will be passed as the only argument.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --invert-match

Flag.  If specified with a trueish value, will negate the result of any
match if it has a logical meaning:

=item True -> False
=item Nil -> True
=item Empty -> True
=item none of the above -> just that

=head2 --is-empty

Flag. If specified with a trueish value, will only select files that do not
contain any data.  Use negation C<--/is-empty> to only select files that B<do>
contain data.

=head2 --is-executable

Flag. If specified with a trueish value, will only select files that can be
executed by the current user.  Use negation C<--/is-executable> to only select
files that are B<not> executable by the current user.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --is-group-executable

Flag. If specified with a trueish value, will only select files that can be
executed by members of the group of the owner.  Use negation
C<--/is-group-executable> to only select files that are B<not> executable by
the members of the group of the owner.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --is-group-readable

Flag. If specified with a trueish value, will only select files that can be
read by members of the group of the owner.  Use negation
C<--/is-group-readable> to only select files that are B<not> readable by
the members of the group of the owner.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --is-group-writable

Flag. If specified with a trueish value, will only select files that can be
written to by members of the group of the owner.  Use negation
C<--/is-group-writable> to only select files that are B<not> writable by
the members of the group of the owner.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --is-owned-by-group

Flag. If specified with a trueish value, will only select files that are
owned by the group of the current user.  Use negation
C<--/is-owned-by-group> to only select files that are B<not> owned by
the group of the current user.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --is-owned-by-user

Flag. If specified with a trueish value, will only select files that are
owned by current user.  Use negation C<--/is-owned-by-user> to only select
files that are B<not> owned by the current user.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --is-owner-executable

Flag. If specified with a trueish value, will only select files that can be
executed by the owner.  Use negation C<--/is-owner-executable> to only select
files that are B<not> executable by the owner.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --is-owner-readable

Flag. If specified with a trueish value, will only select files that can be
read by the owner.  Use negation C<--/is-owner-readable> to only select files
that are B<not> readable by the owner.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --is-owner-writable

Flag. If specified with a trueish value, will only select files that can be
written to by the owner.  Use negation C<--/is-owner-writable> to only select
files that are B<not> writable by the owner.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --is-readable

Flag. If specified with a trueish value, will only select files that can be
read by the the current user.  Use negation C<--/is-readable> to only select
files that are B<not> readable by the current user.

=head2 --is-sticky

Flag. If specified with a trueish value, will only select files that do have
the STICKY bit set in their attributes.  Use negation C<--/is-sticky> to
only select files that do B<not> have the STICKY bit set.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --is-symbolic-link

Flag. If specified with a trueish value, will only select files that are
symbolic links.  Use negation C<--/is-symbolic-link> to only select files that
are B<not> symbolic links.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --is-world-executable

Flag. If specified with a trueish value, will only select files that can be
executed by anybody.  Use negation C<--/is-group-executable> to only select
files that are B<not> executable by anybody.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --is-world-readable

Flag. If specified with a trueish value, will only select files that can be
read by anybody.  Use negation C<--/is-world-readable> to only select files
that are B<not> readable by anybody.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --is-world-writable

Flag. If specified with a trueish value, will only select files that can be
written to by anybody.  Use negation C<--/is-world-writable> to only select
files that can B<not> be written to by anybody.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --is-writable

Flag. If specified with a trueish value, will only select files that can be
written to by the current user.  Use negation C<--/is-writable> to only select
files that can B<not> be written to by the current user.

=head2 --json-per-elem

Flag.  Only makes sense if the pattern is a C<Callable>.  If specified with
a C<True> value, indicates that each selected file will be interpreted
as JSON, and if valid, will then produce all elements of the outermost
data structure to the pattern for introspection.  If the data structure
is a hash, then key/value C<Pair>s will be produced.

If the Callable returns a true value, the element will be shown.  If
the returned value is a string, that string will be mentioned.  For example
when searching the list of modules in the zef ecosystem (which consists of
an array of hashes):

=begin code :lang<bash>

$ rak '{ $_ with .<auth> }' META.json --json-per-elem

=end code

=head2 --json-per-file

Flag.  Only makes sense if the pattern is a C<Callable>.  If specified with
a C<True> value, indicates that each selected file will be interpreted
as JSON, and if valid, will then be given to the pattern for introspection.
If the Callable returns a true value, the filename will be shown.  If
the returned value is a string, that string will also be mentioned.
For example:

=begin code :lang<bash>

$ rak '{ $_ with .<auth> }' --json-per-file

=end code

=head2 --json-per-line

Flag.  Only makes sense if the pattern is a C<Callable>.  If specified with
a C<True> value, indicates that each line from the selected files will be
interpreted as JSON, and if valid, will then be given to the pattern for
introspection.  If the Callable returns a true value, the filename and
line number will be shown.  If the returned value is a string, that
string will also be mentioned.  For example:

=begin code :lang<bash>

$ rak '{ $_ with .<auth> }' --json-per-line

=end code

=head2 --keep-meta

Only applicable if C<--csv-per-line> has been specified.  Flag.  If specified,
indicates that meta-information will be kept for each field, by presenting
each field as a C<CSV::Field|https://github.com/Tux/CSV/blob/master/doc/Text-CSV.md#csvfield>
object rather than as a string.  The most important methods that can be called
on a C<CSV::Field> object are:

=item is-quoted - field was quoted
=item is-binary - field contains undecodable data
=item is-utf8 - field contains decodable data beyond ASCII
=item is-formula = field looks like it contains a spreadsheet formula

=head2 --known-extensions

Flag.  Indicate that only files with known extensions (occuring in any of
the C<#groups>) should be searched.  Defaults to C<True> if a human is
watching (aka STDOUT is connected to a terminal).

=head2 --list-custom-options

=begin code :lang<bash>

$ rak --list-custom-options
fs: --'follow-symlinks'
im: --ignorecase --ignoremark

=end code

Flag.  If specified with a true value and as the only option, will list all
additional options previously saved with C<--save>.

=head2 --list-expanded-options

=begin code :lang<bash>

$ rak --im --list-expanded-options
--ignorecase --ignoremark

=end code

Flag.  If specified with a true value, will show all actual options being
activated after having been recursively expanded, and then exit.
Intended as a debugging aid if you have many custom options defined.

=head2 --list-known-extensions

=begin code :lang<bash>

$ rak --list-known-extensions
       #c: c h hdl
     #c++: cpp cxx hpp hxx
  #config: ini
#markdown: md markdown
    #perl: (none) pl pm t
  #python: py
    #raku: (none) raku rakumod rakutest rakudoc nqp t pm6 pl6 pod6 t6
    #ruby: rb
    #text: (none) txt
    #yaml: yaml yml

=end code

Flag.  If specified with a true value, will show all known extension
groups and the extensions they represent.  Intended as an informational
aid.

=head2 --matches-only

Flag.  Indicate whether only the matched pattern should be produced, rather
than the line in which the pattern was found.  Defaults to C<False>.
Frequently used in conjunction with C<--per-file>.  Will show separated by
space if multiple matches are found on the same line.

=head2 --max-matches-per-file[=N]

Indicate the maximum number of matches that should be produced per file.
If specified as a flag, will assume B<1> for its value.  By default, will
produce B<all> possible matches in a file.

=head2 ---meta-modified=condition

If specified, indicates the C<Callable> that should return True to include a
file in the selection of files to be checked.  The modification time of meta
information of the file (number of seconds since epoch, as a C<Num> value)
will be passed as the only argument.

See "CHECKING TIMES ON FILES" for more information about features that
can be used inside the C<Callable>.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --mode=condition

If specified, indicates the C<Callable> that should return True to include a
file in the selection of files to be checked.  The full numeric mode value
of the file on the filesystem, will be passed as the only argument.

=begin code :lang<bash>

# list files with sticky bit set
$ rak --find --mode='{ $_ +& 0o1000 }'

=end code

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --modified=condition

If specified, indicates the C<Callable> that should return True to include a
file in the selection of files to be checked.  The modification time of the
file (number of seconds since epoch, as a C<Num> value) will be passed as the
only argument.

See "CHECKING TIMES ON FILES" for more information about features that
can be used inside the C<Callable>.

=head2 --modify-files

Flag.  Only makes sense if the specified pattern is a C<Callable>.
Indicates whether the output of the pattern should be applied to the file
in which it was found.  Defaults to C<False>.

The C<Callable> will be called for each line, giving the line (B<including>
its line ending).  It is then up to the C<Callable> to return:

=head3 False

Remove this line from the file.  NOTE: this means the exact C<False> value.

=head3 True

Keep this line unchanged the file.  NOTE: this means the exact C<True> value.

=head3 Nil

Keep this line unchanged the file.  NOTE: this means the exact C<Nil> value.

=head3 Empty

Keep this line unchanged the file.  NOTE: this means the exact C<Empty> value.
This is typically returned as the result of a failed condition.  For example,
only change the string "foo" into "bar" if the line starts with "#":

=begin code :lang<bash>

$ rak '{ .subst("foo","bar") if .starts-with("#") }' --modify-files

=end code

=head3 any other value

Inserts this value in the file instead of the given line.  The value can
either be a string, or a list of strings.

=head2 --module=Foo

Indicate the Raku module that should be loaded.  Only makes sense if the
pattern is executable code.

=head2 --output-file=filename

Indicate the path of the file in which the result of the search should
be placed.  Defaults to C<STDOUT>.

=head2 --pager=name

Indicate the name (and arguments) of a pager program to be used to page
through the generated output.  Defaults to the C<RAK_PAGER> environment
variable.  If that isn't specified either, then no pager program will be
run.

=begin code :lang<bash>

$ RAK_PAGER='more -r' rak foo

$ rak foo --pager='less -r'

=end code

=head2 --paragraph-context

Flag.  Indicate all lines that are part of the same paragraph B<around>
any line that matches.  Defaults to C<False>.

=head2 --passthru

Flag.  Indicate whether B<all> lines from source should be shown always.
Highlighting will still be performed, if so (implicitely) specified.

=begin code :lang<bash>

# Watch a log file, and highlight a certain IP address.
$ tail -f ~/access.log | rak --passthru 123.45.67.89

=end code

=head2 --passthru-context

Flag.  Indicate whether B<all> lines from source should be shown if at
least one line matches.  Highlighting will still be performed, if so
(implicitely) specified.

=head2 --paths=path1,path2

Indicates the path specification to be used instead of from any positional
arguments.  "-" can be specified to read path specifications from STDIN.
Multiple path specifications should be separated by comma's.

=head2 --paths-from=filename

Indicate the path of the file to read path specifications from instead of
from any positional arguments.  "-" can be specified to read path
specifications from STDIN.

=head2 --pattern=foo

Alternative way to specify the pattern to search for.  If (implicitly)
specified, will assume the first positional parameter specified is
actually a path specification, rather than a pattern.  This allows
the pattern to be searched for to be saved with C<--save>.

=head2 --per-file[=code]

Indicate whether matching should be done per file, rather than per line.
If specified as a flag, will slurp a file with the indicated C<--encoding>
and present that to the matcher.  Optionally takes a C<Callable>
specification: this will be given an C<IO::Path> object of the file:
whatever it produces will be presented to the matcher.  Usually used in
conjunction with C<--matches-only> and/or C<count-only>.

=begin code :lang<bash>

# look for foo in only the first 10 lines of each file
$ rak foo --per-file='*.lines(:!chomp).head(10).join'

=end code

=head2 --per-line[=code]

Indicate whether matching should be done per line.  If specified as a flag,
will read lines with the indicated C<--encoding> and present each line to the
matcher (which is actually the default if no action was specified).i

Optionally takes a C<Callable> specification: this will be given an C<IO::Path>
object of the file: that is then expected to produce lines that will be
presented to the matcher.

=begin code :lang<bash>

# look for foo in only the last 10 lines of each file
$ rak foo --per-line='*.lines.tail(10)'

=end code

=head2 --proximate=[N]

Indicates whether matched lines should be grouped together that are within
N lines of each other. This is useful for visually picking out matches that
appear close to other matches.  If specified as a flag, indicates a
proximation of B<1>.  Defaults to B<0>, indication no proximation.

=head2 --quietly

Flag.  Only makes sense if the pattern is a C<Callable>.  If specified
with a true value, will catch all B<warnings> that are emitted when executing
the pattern's C<Callable>.  Defaults to False.

=head2 --quote=["]

Only applicable if C<--csv-per-line> has been specified.  Indicates the
character that should be used for quoting fields.  Defaults to B<double quote>.

=head2 --rak

Flag.  Intended for debugging purposes only.  When specified with a trueish
value, will show the named arguments sent to the C<rak> subroutine just
before it is being called.

=head2 --recurse-unmatched-dir

Flag.  Indicate whether directories that didn't match the C<--dir>
specification, should be recursed into anyway.  Will not produce files
from such directories, but may recurse further if directories are
encountered. Defaults to C<False>.

=head2 --recurse-symlinked-dir

Flag.  Indicate whether directories that are actually symbolic links,
should be recursed into.  Defaults to C<False>.

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --rename-files

Flag.  Only makes sense if the specified pattern is a C<Callable>.
Feeds all selected files as C<IO::Path> to the pattern, and uses the
result (if different from the original) as the new name of the file.

The C<--dryrun> argument can be used to run through the whole process
B<except> doing actually any renaming.

The C<--verbose> argument can be used to get more verbose feedback on
the operation.

The C<Callable> will be called for each line, giving the file as an
C<IO::Path> object.  It is then up to the C<Callable> to return:

=head3 False

Don't change the name of the file  NOTE: this means the exact C<False> value.

=head3 True

Don't change the name of the file.  NOTE: this means the exact C<True> value.

=head3 Nil

Don't change the name of the file.  NOTE: this means the exact C<Nil> value.

=head3 Empty

Don't change the name of  the file.  NOTE: this means the exact C<Empty> value.
This is typically returned as the result of a failed condition.

=head3 any other value

Use this value as the new name of the file.  It can either be a string
or an C<IO::Path> object.  Only when the returned value is different from
the given value, will a rename actually be attempted.  To make this easier
on the user, any C<Str> returned, will be automatically converted to an
C<IO::Path> object before being compared using C<eqv>.

Example: rename all files with the C<.t> extension to the C<.rakutest>
extension.

=begin code :lang<bash>

$ rak '*.subst(/ \.t $/,".rakutest")' --rename-files

=end code

Note that files that are under git revision control will be renamed using
C<git mv>: if that fails for any reason, a normal rename will be performed.

=head2 --repository=dir

Indicate the directory that should be searched for Raku module loading.
Only makes sense if the pattern is executable code.

Note that you can create a familiar shortcut for the most common arguments of
the C<--repository> option:

=begin code :lang<bash>

$ rak --repository=. --save=I.
Saved option '--I.' as: --repository='.'

$ rak --repository=lib --save=Ilib
Saved option '--Ilib' as: --repository=lib

=end code

=head2 --save=shortcut-name

Save all options with the given name in the configuration file
(C<~/.rak-config.json>), and exit with a message that these options have
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 both.

=begin code :lang<bash>

$ rak --ignorecase --ignoremark --save=im
Saved option '--im' as: --ignorecase --ignoremark

# same as --ignorecase --ignoremark
$ rak foo --im

$ rak --recurse-symlinked-dir --save=rsd
Saved option '--rsd' as: --recurse-symlinked-dir

$ rak --break='[---]' --save=B
Saved option '--B' as: --break='[---]'

$ rak --pattern=! --save=P
Saved option '--P' as: --pattern='!'

$ rak --save=foo
Removed configuration for 'foo'

=end code

Any options can be accessed as if it is a standard option.  Please note
that no validity checking on the options is being performed at the moment
of saving, as validity may depend on other options having been specified.

One option can be marked as requiring a value to be specified (with "!")
or have a default value (with "[default-value]").

To remove a saved set of options, use C<--save>=foo as the only option
to remove the "foo" set of options.

=head2 --sep=[,]

Only applicable if C<--csv-per-line> has been specified.  Indicates the
character to indicate the field separator.  Defaults to the B<comma>.

=head2 --show-blame

Flag.  Indicate whether to show C<git blame> information for matching lines
if possible, instead of just the line.  Defaults to C<False>.

Requires that the L<C<Git::Blame::File>|https://raku.land/zef:lizmat/Git::Blame::File> module is installed.

=head2 --show-item-number

Flag.  Indicate whether item numbers should be shown.  Defaults to C<True>.

=head2 --show-filename

Flag.  Indicate whether filenames should be shown.  Defaults to C<True>.

=head2 --shell=invocation

If specified, indicates the command(s) to be executed in a shell. Any C<$_>
in the invocation string will be replaced by the file being checked. The
file will be included if the shell command(s) run to a successful conclusion.

=head2 --silently[=out,err]

Flag and option.  Only applicable if the pattern is a C<Callable>.  Indicates
whether any output from the C<Callable> pattern should be caught.  Defaults
to C<False>.  If specified as a flag, will catch both STDOUT as well as
STDERR output from the pattern's execution.  When specified as an option,
will accept:

=item out - only capture STDOUT
=item err - only capture STDERR
=item out,err - capture both STDIN as well as STDERR
=item err,out - capture both STDIN as well as STDERR

=head2 --smartcase

Flag.  An intelligent version of C<--ignorecase>.  If the pattern does
B<not> contain any uppercase characters, it will act as if C<--ignorecase>
was specified.  Otherwise it is ignored.

=head2 --stats

Flag.  Also show statistics about the search operation after having shown
the full search result.

=head2 --stats-only

Flag.  B<Only> show statistics about the search operation.  See also
C<--count-only>.

=head2 --strict

Only applicable if C<--csv-per-line> has been specified.  Flag.  If
specified with a trueish value, then each line in the CSV file B<must> have
the same number of fields.  Default is to allow different numbers of fields.

=head2 --summary-if-larger-than=N

Indicate the maximum size a line may have before it will be summarized.
Defaults to C<160> if C<STDOUT> is a TTY (aka, someone is actually watching
the search results), otherwise defaults to C<Inf> effectively (indicating
no summarization will ever occur).

=item --type=words|starts-with|ends-with|contains

Only makes sense if the pattern is a string.  With C<words> specified,
will look for pattern as a word in a line, with C<starts-with> will
look for the pattern at the beginning of a line, with C<ends-with>
will look for the pattern at the end of a line, with C<contains> will
look for the pattern at any position in a line.

=head2 --trim

Flag.  Indicate whether lines that have the pattern, should have any
whitespace at the start and/or end of the line removed.  Defaults to
C<True> if no context for lines was specified, else defaults to C<False>.

=head2 --uid=condition

If specified, indicates the C<Callable> that should return True to include a
file in the selection of files to be checked.  The numeric C<uid> of the file
will be passed as the only argument.  Can also be specified as a single
numeric argument.  See also C<--user>.

=begin code :lang<bash>

# show files of which the numeric user id is greater than 500
$ rak --find --uid='* > 500'

# show files of which the numeric user id is 501
$ rak --find --uid=501

=end code

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --under-version-control[=git]

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 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
output.  Default is C<False>.  See also C<--frequencies>.

=head2 --user=condition

If specified, indicates the C<Callable> that should return True to include a
file in the selection of files to be checked.  The user name associated with
the C<uid> of the file will be passed as the only argument.

Can also be specified as a list of comma separated names to (not) select on.
To select all names B<except> the listed named, prefix with a C<!>.

See also C<--uid>.  Requires the
L<P5getpwnam|https://raku.land/zef:lizmat/P5getpwnam> module to be installed.

=begin code :lang<bash>

# files of which the name associated with the user id starts with underscore
$ rak --find --user='*.starts-with("_")'

# show files of which the owner is liz or wendy
$ rak --find --user=liz,wendy

# show files of which the owner is NOT liz or wendy
$ rak --find --user='!liz,wendy'

=end code

NOTE: support of this feature depends on Raku supporting that feature on
the current operating system.

=head2 --version

Flag.  If the only argument, shows the name and version of the script, and
the system it is running on.  Additionally specify C<--verbose> to see more
information.

=head2 --vimgrep

Flag.  If specified with a true value, will output search results in the
format "filename:linenumber:column:line".  This allows integration with
the C<:grep> action in vim-like editors.

=head1 CHECKING TIMES ON FILES

The C<--accessed>, C<--created>, C<--modified> and C<--meta-modified>
options expect C<Callable> to perform the check to include a file in the
search process.  It is passed the B<epoch> (number of seconds since
1 January 1970 UTC) value of the file being checked for the indicated
option, and it should return C<True> to include that file in any search.

To facilitate checks, some extra features are activated for these
C<Callable>s, allowing you to more easily craft your conditions.

=head2 Automatic conversion to epoch

In Raku, the C<.accessed>, C<.created>, C<.changed> and C<.modified>
methods on the C<IO::Path> object return
L<C<Instant>|https://docs.raku.org/type/Instant> objects, which are
atomic time rather than epoch.  Within these special C<Callables>,
these values are automatically converted to epoch values, to ease
comparisons.

=head2 Specifying some time ago

Within these special C<Callable>s, one can also indicate an epoch
value in the past by using the C<.ago> method in a specially formatted
string.  This string is formatted similarly to time specifications of
the Unix C<find> command: one of more digits followed by "s" for
seconds, "m" for minutes, "h" for hours, "d" for days and "w" for weeks.
"+" and "-" may also be used, but do not have any special meaning other
than negating the value they apply to.

=head2 On method naming

For C<rak> it was decided to name the option for checking the meta
information of a file as C<--meta-modified>.  In Raku, the associated
method on the C<IO::Path> object is (probably for historical reasons)
called C<.changed>.  To facilitate the creation of the C<Callable>s
for these options, one can use both C<.meta-modified> as well as
C<.changed> as methods.

=head2 Examples

=begin code :lang<bash>

# all files that were modified later than an hour ago
$ rak --find --modified='* > "1h".ago'

# all files that were created before 2.5 hours ago
$ rak --find --created='* < "2h30m".ago'

# all files that were modified after "Changes" was created
$ rak --find --modified='* > "Changes".IO.created'

=end code

=head1 AUTHOR

Elizabeth Mattijsen <liz@raku.rocks>

Source can be located at: https://github.com/lizmat/App-Rak .
Comments and Pull Requests are welcome.

If you like this module, or what I’m doing more generally, committing to a
L<small sponsorship|https://github.com/sponsors/lizmat/>  would mean a great
deal to me!

=head1 COPYRIGHT AND LICENSE

Copyright 2022 Elizabeth Mattijsen

This library is free software; you can redistribute it and/or modify it under
the Artistic License 2.0.

=end pod

# vim: expandtab shiftwidth=4