Haystack specification:
‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒

The "haystack" is the original selection of files that will be examined,
which will then be refined by the file system arguments, before being
in actual matching of the pattern.

Note that almost all (implicit) options in the haystack specification
will be in conflict with any of the other options.  So don't use them
at the same time!

path1 path2 ...  OR  --paths=path1,path2

The pattern to be used for matching is either specified with the
 --pattern argument, or by the first positional argument.  All (other)
positionals arguments are considered to be paths to be investigated
for files and subdirectories.  If only a pattern has been specified
then the current directory will be assumed.  Paths can also be
specified with the --paths argument, which expects a comma separated
list of paths to investigate.

--files-from=file

If specified, expects the name of file containing the names of the
*files* to be examined.  Relative filenames will be assumed to be
relative to the current directory.  Conflicts with --paths,
 --paths-from, --recurse-symlinked-dir, --recurse-unmatched-dir and
 --under-version-control.

--paths-from=file

If specified, expects the name of file containing the names of the
*path* to be recursed into to find files.  Relative pathnames will
be assumed to be relative to the current directory.  Conflicts
with --paths, --files-from and --under-version-control.

--recurse-symlinked-dir

If specified with a True value, will cause the file collection
process to recurse into symlinked directories.  Default is False,
so that no recursion into symlinked directories will occur.
Conflicts with --files-from and --under-version.control.

--recurse-unmatched-dir

If specified with a True value, will cause the file collection
process to recurse into directories that did **NOT** satisfy the
(implicit) --dir specification.  Default is False, so that
recursion will only occur into directories that satisfy the
 --dir specification.  Conflicts with --files-from and
 --under-version.control.

--under-version-control[=git]

If specified indicates which version control system should be
interrogated to find out which files are currently known to the
version control system.  If specified with a True value, assumes
"git" as the version control system.  Currently, this is the only
version control system supported.  Conflicts with --paths,
 --files-from, --paths-from, --recurse-symlinked-dir and
 --recurse-unmatched-dir.

--eco-code=[rea|fez]

Indicate that all the files that can contain Raku code in the local
ecosystem cache (as generated by Ecosystem::Cache) should be searched.
If specified as a flag, will assume "rea" (Raku Ecosystem Archive).

--eco-doc=[rea|fez]

Indicate that all the files that can documentation in the local
ecosystem cache (as generated by Ecosystem::Cache) should be searched.
If specified as a flag, will assume "rea" (Raku Ecosystem Archive).

--eco-meta[=name,name2]

Intended to be used by Raku ecosystem maintainers.  Indicates the
name of one or more Raku ecosystems (separated by commmas) of
which to inspect the META6.json information of all its modules.
Currently supported names are:

 - p6c  - the original git ecosystem (deprecated)
 - cpan - the ecosystem piggybacking on PAUSE / CPAN (deprecated)
 - fez  - the currently recommended ecosystem for new modules / updates
 - rea  - the Raku Ecosystem Archive

Defaults to "rea" if specified as a flag.  Implies --json-per-elem.

Examples:
# show all unique module names by an author from the REA
$ rak '{ .author eq "Scooby Doo" }' --eco-meta

# same, but now from the p6c and cpan ecosystems
$ rak '{ .author eq "Scooby Doo" }' --eco-meta=p6c,cpan

Assumes "zef" is installed and its meta information is available.

--eco-provides=[rea|fez]

Indicate that the module files (from the "provides" section of the
meta-information in a distribution) in the local ecosystem cache
(as generated by Ecosystem::Cache) should be searched. If specified
as a flag, will assume "rea" (Raku Ecosystem Archive).

--eco-scripts=[rea|fez]

Indicate that the scripts (from the "bin" directory of a distribution)
in the local ecosystem cache (as generated by Ecosystem::Cache) should
be searched. If specified as a flag, will assume "rea" (Raku Ecosystem
Archive).

--eco-tests=[rea|fez]

Indicate that the test files (from the "t" and "xt" directories of a
distribution) in the local ecosystem cache (as generated by
Ecosystem::Cache) should be searched. If specified as a flag, will
assume "rea" (Raku Ecosystem Archive).

--rakudo-all

Indicate that all the files recognized by the Rakudo cache (as generated
by Rakudo::Cache) should be searched.

--rakudo-c

Indicate that the files recognized as C programming language files by
the Rakudo cache (as generated by Rakudo::Cache) should be searched.

--rakudo-doc

Indicate that the files recognized as documentation files by the Rakudo
cache (as generated by Rakudo::Cache) should be searched.

--rakudo-java

Indicate that the files recognized as Java programming language files
by the Rakudo cache (as generated by Rakudo::Cache) should be searched.

--rakudo-js

Indicate that the files recognized as Javascript programming language
files by the Rakudo cache (as generated by Rakudo::Cache) should be searched.

--rakudo-nqp

Indicate that the files recognized as NQP related files by the Rakudo cache
(as generated by Rakudo::Cache) should be searched.

--rakudo-perl

Indicate that the files recognized as Perl programming language files
by the Rakudo cache (as generated by Rakudo::Cache) should be searched.

--rakudo-raku

Indicate that the files recognized as Raku Programming Language files
by the Rakudo cache (as generated by Rakudo::Cache) should be searched.

--rakudo-shell

Indicate that the files recognized as shell scripts / batch files by
the Rakudo cache (as generated by Rakudo::Cache) should be searched.

--rakudo-test

Indicate that the files recognized as test related files by the Rakudo
cache (as generated by Rakudo::Cache) should be searched.

--rakudo-yaml

Indicate that the files recognized as files containing YAML of some sort
by the Rakudo cache (as generated by Rakudo::Cache) should be searched.
