NAME
App::Rak - 21st century grep / find / ack / ag / rg on steroids
SYNOPSIS
$ 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
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 project is now in beta-development phase. Comments, suggestions and bug reports continue to be more than welcome!
POSITIONAL ARGUMENTS
pattern
The pattern to search for. This can either be a string, or a Raku regular expression (indicated by a string starting and ending with /
), a Callable
(indicated by a string starting with {
and ending with }
), or a a result of Whatever
currying (indicated by a string starting with *.
).
Can also be specified with the --pattern
option, in which case all the positional arguments are considered to be a path specification.
If the pattern is a Callable
, then the dynamic variable $*SOURCE
will contain the IO::Path
object of the file being processed. Note that pattern Callable
s will be called in a thread unsafe manner.
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 --dir
option).
By default, all files will be searched in the directories. This can be changed with the --file
option.
Paths can also be specified with the --paths
option, in which case there should only be a positional argument for the pattern, or none if --pattern
option was used for the pattern specification.
ON CALLABLES AS PATTERN
Callables
can be specfied by a string starting with *.
(so-called Whatever currying, 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 (pieces of code that will be executed automatically when a certain condition has been met.
App::Rak
currently supports all of Raku's loop phasers:
FIRST - code to run when searching starts
NEXT - code to run when searching a file is done
LAST - code to run when searching is done
These phasers will be called in a thread-safe manner.
$ rak '{ FIRST state $seen = 0; NEXT $seen++; LAST say "$seen files"; .contains("pattern")}'
Any other phasers that do not require special attention by App::Rak
are also supported in any code specified.
CREATING YOUR OWN OPTIONS
App::Rak provides many options. If you are happy with a set of options for a certain workflow, You can use the --save
option to save that set of options and than later access them with the given name:
$ rak --ignorecase --ignoremark --save=im
Saved option '--im' as: --ignorecase --ignoremark
# same as --ignorecase --ignoremark
$ rak foo --im
You can use the --list-custom-options
to see what options you have saved before.
SUPPORTED OPTIONS
All options are optional. Any unexpected options, will cause an exception to be thrown with the unexpected options listed.
--accessed=condition
If specified, indicates the 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 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 Callable
.
--absolute
Flag. If specified with a trueish value indicates that whenever paths are shown, they will be shown as absolute paths. Defaults to False
, which will cause paths to be shown as paths relative to the current directory.
--after-context=N
Indicate the number of lines that should be shown after any line that matches. Defaults to 0. Will be overridden by a --context
argument.
--allow-loose-escapes
Only applicable if --csv-per-line
has been specified. Flag. If specified, indicates that any character may be escaped.
--allow-loose-quotes
Only applicable if --csv-per-line
has been specified. Flag. If specified, indicates that fields do not need to be quoted to be acceptable.
--allow-whitespace
Only applicable if --csv-per-line
has been specified. Flag. If specified, indicates that whitespace is allowed around separators.
--auto-diag
Only applicable if --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 True
.
--backup[=extension]
Indicate whether backups should be made of files that are being modified. If specified without extension, the extension .bak
will be used.
--batch=N
Indicate the number of files that should be checked per thread. Defaults to 64
if not specified. See also <--degree>.
--before-context=N
Indicate the number of lines that should be shown before any line that matches. Defaults to 0. Will be overridden by a --context
argument.
--blame-per-file
Flag. Only makes sense if the pattern is a Callable
. If specified with a True
value, indicates that each of the selected files will be provided as Git::Blame::File
objects if git blame
can be performed on the a selected file. If that is not possible, then the selected file will be ignored.
If information can be obtained, then the associated Git::Blame::File
object will be presented to the pattern 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.
# show files with more than 10 commits
$ rak '*.commits > 10' --blame-per-file --files-with-matches
Requires that the Git::Blame::File
module is installed.
--blame-per-line
Flag. Only makes sense if the pattern is a Callable
. If specified with a True
value, indicates that each line from the selected files will be provided as Git::Blame::Line
objects if git blame
can be performed on the a selected file. If that is not possible, then the selected file will be ignored.
If information can be obtained, then the associated Git::Blame::Line
object will be presented to the pattern Callable
. If the Callable returns a true value, then the short representation of the git blame
information will be shown. If the returned value is a string, then that string will be shown.
# show git blame on lines of which the author is "Scooby Doo"
$ rak '{ .author eq "Scooby Doo" }' --blame-per-line
Requires that the Git::Blame::File
module is installed.
--blocks=condition
If specified, indicates the 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.
# show files that consist of at least 3 blocks
$ rak --find --blocks='* >= 3'
--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 True
(using an empty line as a divider) if --group-matches
is (implicitly) set to True
, else defaults to False
.
--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.
--context=N
Indicate the number of lines that should be shown around any line that matches. Defaults to 0. Overrides any a --after-context
or --before-context
arguments.
--count-only
Flag. Indicate whether just the number of lines with matches should be calculated. When specified with a True
value, will show a "N matches in M files" by default, and if the :files-with-matches
(or files-without matches
) option is also specified with a True
value, will just show total counts. See also stats-only
.
--created=condition
If specified, indicates the 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 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 Callable
.
--csv-per-line
Flag. Only makes sense if the pattern is a Callable
. If specified with a 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 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 #csv
group will be tried, unless overridden by any explicit extension specification.
More documentation can be found with the Text::CSV module itself.
--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>.
--device-number=condition
If specified, indicates the 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.
--dir=condition
If specified, indicates the 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 all directories for recursion.
--dont-catch
Flag. If specified with a trueish value, will not catch any error during processing, but will throw any error again. Defaults to False
, making sure that errors will be caught. Mainly intended for debugging and error reporting.
--dryrun
Flag. Indicate to not actually make any changes to any content modification if specified with a True
value. Only makes sense together with the --modify-files
and the --rename-files
option.
--edit[=editor]
Indicate whether the patterns found should be fed into an editor for inspection and/or changes. Defaults to False
. Optionally takes the name of the editor to be used.
--eol=[lf|cr|crlf]
Only applicable if --csv-per-line
has been specified. Indicate a line ending different from the standard line ending assumed by the system. Can be specified as lf
for a single LineFeed character, cr
for a single CarriageReturn character, or crlf
for a combination of a CarriageReturn and a LineFeed character.
--escape=["]
Only applicable if --csv-per-line
has been specified. Indicates the escape character to be used to escape characters in a field. Defaults to double quote.
--exec=invocation
If specified, indicates the name of a program and its arguments to be executed. Any $_
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.
--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 #name
), or a single extension.
# 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=
Predefined groups are #raku
, #perl
, #cro
, #text
#c
, #c++
, #yaml
, #ruby
, #python
, #html
, #markdown
, #json
, #jsonl
, #csv
, #config
and #text
.
The --list-known-extensions
argument can be used to see which predefined groups of extensions are supported, and which extensions they cover.
--file=condition
If specified, indicates the 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 True
, indicating that all files should be included.
--file-separator-null
Flag. Indicate to separate filenames by null bytes rather than newlines if the --files-with-matches
option is specified with a True
value.
--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.
--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 False
.
--files-without-matches
Flag. If specified with a true value, will only produce the filenames of the files in which the pattern was not found. Defaults to False
.
--filesize=condition
If specified, indicates the 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.
# show files that consist of at 30 bytes
$ rak --find --filesize='* >= 30'
--find
Flag. If specified with a true value, will not look at the contents of the selected paths, but instead consider the selected paths as lines in a virtual file.
--find-all
Flag. If specified with a true value, will override any file or directory filter settings and include all possible files for inspection.
--only-first[=N]
Indicate the overall number of matches to show. If specified without a value, will default to 1. Defaults to 1000 if a human is watching, otherwise defaults to returning all possible matches.
Only applicable if --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:
none - take not action, just pass on
die - throw an exception
diag - report line and position where formula was found
empty - replace the formula by an empty string
--frequencies
Flag. If specified, will produce a frequency table of the matches with the most frequent match first. Default is False
. See also --unique
;
--gid=condition
If specified, indicates the Callable
that should return True to include a file in the selection of files to be checked. The numeric gid
of the file will be passed as the only argument. Can also be specified as a single numeric argument. See also --group
.
# 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
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--group=condition
If specified, indicates the 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 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 except the listed named, prefix with a !
.
See also --gid
. Requires the P5getgrnam module to be installed.
# 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'
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--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 True
.
--hard-links=condition
If specified, indicates the 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.
--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 --/has-setgid
to only select files that do not have the SETGID bit set.
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--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 --/has-setuid
to only select files that do not have the SETUID bit set.
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--help [area-of-interest]
Show argument documentation, possibly extended by giving the area of interest, which are:
pattern
string
code
input
haystack
filesystem
result
listing
resource
special
option
general
philosophy
examples
--highlight
Flag. Indicate whether the pattern should be highlighted in the line in which it was found. Defaults to True
if a human is watching (aka STDOUT connected to a terminal), or --highlight-before
or highlight-after
are explicitely specified, or False
otherwise.
--highlight--after[=string]
Indicate the string that should be used at the end of the pattern found in a line. Specifying implies --highlight
ing implicitely. If --highlight
or --highlight-before
are explicitely specified, will default to whatever is specified with --highlight-before
, or to the ANSI code to end bold.
--highlight--before[=string]
Indicate the string that should be used at the end of the pattern found in a line. Specifying implies --highlight
ing implicitly. If highlight
is explicitely specified with a trueish value, will default to the terminal code to start bold.
--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 True
if STDOUT
is a TTY (aka, someone is actually watching the search results), otherwise defaults to False
.
--ignorecase
Flag. If specified with a trueish value, indicates that any matching should be done case insensitively. Default is False
.
Flag. If specified with a trueish value, indicates that any matching should be done without consideration of any accents. Default is False
.
--inode=condition
If specified, indicates the 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.
--invert-match
Flag. If specified with a trueish value, will negate the result of any match if it has a logical meaning:
--is-empty
Flag. If specified with a trueish value, will only select files that do not contain any data. Use negation --/is-empty
to only select files that do contain data.
--is-executable
Flag. If specified with a trueish value, will only select files that can be executed by the current user. Use negation --/is-executable
to only select files that are not executable by the current user.
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--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 --/is-group-executable
to only select files that are 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.
--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 --/is-group-readable
to only select files that are 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.
--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 --/is-group-writable
to only select files that are 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.
--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 --/is-owned-by-group
to only select files that are 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.
--is-owned-by-user
Flag. If specified with a trueish value, will only select files that are owned by current user. Use negation --/is-owned-by-user
to only select files that are not owned by the current user.
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--is-owner-executable
Flag. If specified with a trueish value, will only select files that can be executed by the owner. Use negation --/is-owner-executable
to only select files that are not executable by the owner.
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--is-owner-readable
Flag. If specified with a trueish value, will only select files that can be read by the owner. Use negation --/is-owner-readable
to only select files that are not readable by the owner.
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--is-owner-writable
Flag. If specified with a trueish value, will only select files that can be written to by the owner. Use negation --/is-owner-writable
to only select files that are not writable by the owner.
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--is-readable
Flag. If specified with a trueish value, will only select files that can be read by the the current user. Use negation --/is-readable
to only select files that are not readable by the current user.
--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 --/is-sticky
to only select files that do not have the STICKY bit set.
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--is-symbolic-link
Flag. If specified with a trueish value, will only select files that are symbolic links. Use negation --/is-symbolic-link
to only select files that are not symbolic links.
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--is-world-executable
Flag. If specified with a trueish value, will only select files that can be executed by anybody. Use negation --/is-group-executable
to only select files that are not executable by anybody.
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--is-world-readable
Flag. If specified with a trueish value, will only select files that can be read by anybody. Use negation --/is-world-readable
to only select files that are not readable by anybody.
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--is-world-writable
Flag. If specified with a trueish value, will only select files that can be written to by anybody. Use negation --/is-world-writable
to only select files that can not be written to by anybody.
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--is-writable
Flag. If specified with a trueish value, will only select files that can be written to by the current user. Use negation --/is-writable
to only select files that can not be written to by the current user.
--json-per-elem
Flag. Only makes sense if the pattern is a Callable
. If specified with a 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 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):
$ rak '{ $_ with .<auth> }' META.json --json-per-elem
--json-per-file
Flag. Only makes sense if the pattern is a Callable
. If specified with a 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:
$ rak '{ $_ with .<auth> }' --json-per-file
--json-per-line
Flag. Only makes sense if the pattern is a Callable
. If specified with a 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:
$ rak '{ $_ with .<auth> }' --json-per-line
Only applicable if --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 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 CSV::Field
object are:
is-quoted - field was quoted
is-binary - field contains undecodable data
is-utf8 - field contains decodable data beyond ASCII
is-formula = field looks like it contains a spreadsheet formula
--known-extensions
Flag. Indicate that only files with known extensions (occuring in any of the #groups
) should be searched. Defaults to True
if a human is watching (aka STDOUT is connected to a terminal).
--list-custom-options
$ rak --list-custom-options
fs: --'follow-symlinks'
im: --ignorecase --ignoremark
Flag. If specified with a true value and as the only option, will list all additional options previously saved with --save
.
--list-expanded-options
$ rak --im --list-expanded-options
--ignorecase --ignoremark
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.
--list-known-extensions
$ 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
Flag. If specified with a true value, will show all known extension groups and the extensions they represent. Intended as an informational aid.
--matches-only
Flag. Indicate whether only the matched pattern should be produced, rather than the line in which the pattern was found. Defaults to False
. Frequently used in conjunction with --per-file
. Will show separated by space if multiple matches are found on the same line.
--max-matches-per-file[=N]
Indicate the maximum number of matches that should be produced per file. If specified as a flag, will assume 1 for its value. By default, will produce all possible matches in a file.
If specified, indicates the 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 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 Callable
.
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--mode=condition
If specified, indicates the 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.
# list files with sticky bit set
$ rak --find --mode='{ $_ +& 0o1000 }'
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--modified=condition
If specified, indicates the 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 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 Callable
.
--modify-files
Flag. Only makes sense if the specified pattern is a Callable
. Indicates whether the output of the pattern should be applied to the file in which it was found. Defaults to False
.
The Callable
will be called for each line, giving the line (including its line ending). It is then up to the Callable
to return:
False
Remove this line from the file. NOTE: this means the exact False
value.
True
Keep this line unchanged the file. NOTE: this means the exact True
value.
Nil
Keep this line unchanged the file. NOTE: this means the exact Nil
value.
Empty
Keep this line unchanged the file. NOTE: this means the exact 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 "#":
$ rak '{ .subst("foo","bar") if .starts-with("#") }' --modify-files
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.
--module=Foo
Indicate the Raku module that should be loaded. Only makes sense if the pattern is executable code.
--output-file=filename
Indicate the path of the file in which the result of the search should be placed. Defaults to STDOUT
.
Indicate the name (and arguments) of a pager program to be used to page through the generated output. Defaults to the RAK_PAGER
environment variable. If that isn't specified either, then no pager program will be run.
$ RAK_PAGER='more -r' rak foo
$ rak foo --pager='less -r'
--paragraph-context
Flag. Indicate all lines that are part of the same paragraph around any line that matches. Defaults to False
.
--passthru
Flag. Indicate whether all lines from source should be shown always. Highlighting will still be performed, if so (implicitely) specified.
# Watch a log file, and highlight a certain IP address.
$ tail -f ~/access.log | rak --passthru 123.45.67.89
--passthru-context
Flag. Indicate whether all lines from source should be shown if at least one line matches. Highlighting will still be performed, if so (implicitely) specified.
--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.
--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.
--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 --save
.
--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 --encoding
and present that to the matcher. Optionally takes a Callable
specification: this will be given an IO::Path
object of the file: whatever it produces will be presented to the matcher. Usually used in conjunction with --matches-only
and/or count-only
.
# look for foo in only the first 10 lines of each file
$ rak foo --per-file='*.lines(:!chomp).head(10).join'
--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 1. Defaults to 0, indication no proximation.
--quietly
Flag. Only makes sense if the pattern is a Callable
. If specified with a true value, will catch all warnings that are emitted when executing the pattern's Callable
. Defaults to False.
--quote=["]
Only applicable if --csv-per-line
has been specified. Indicates the character that should be used for quoting fields. Defaults to double quote.
--rak
Flag. Intended for debugging purposes only. When specified with a trueish value, will show the named arguments sent to the rak
subroutine just before it is being called.
--recurse-unmatched-dir
Flag. Indicate whether directories that didn't match the --dir
specification, should be recursed into anyway. Will not produce files from such directories, but may recurse further if directories are encountered. Defaults to False
.
--recurse-symlinked-dir
Flag. Indicate whether directories that are actually symbolic links, should be recursed into. Defaults to False
.
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--rename-files
Flag. Only makes sense if the specified pattern is a Callable
. Feeds all selected files as IO::Path
to the pattern, and uses the result (if different from the original) as the new name of the file.
The --dryrun
argument can be used to run through the whole process except doing actually any renaming.
The --verbose
argument can be used to get more verbose feedback on the operation.
The Callable
will be called for each line, giving the file as an IO::Path
object. It is then up to the Callable
to return:
False
Don't change the name of the file NOTE: this means the exact False
value.
True
Don't change the name of the file. NOTE: this means the exact True
value.
Nil
Don't change the name of the file. NOTE: this means the exact Nil
value.
Empty
Don't change the name of the file. NOTE: this means the exact Empty
value. This is typically returned as the result of a failed condition.
any other value
Use this value as the new name of the file. It can either be a string or an 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 Str
returned, will be automatically converted to an IO::Path
object before being compared using eqv
.
Example: rename all files with the .t
extension to the .rakutest
extension.
$ rak '*.subst(/ \.t $/,".rakutest")' --rename-files
Note that files that are under git revision control will be renamed using git mv
: if that fails for any reason, a normal rename will be performed.
--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 --repository
option:
$ rak --repository=. --save=I.
Saved option '--I.' as: --repository='.'
$ rak --repository=lib --save=Ilib
Saved option '--Ilib' as: --repository=lib
--save=shortcut-name
Save all options with the given name in the configuration file (~/.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.
$ rak --ignorecase --ignoremark --save=im
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 --break='[---]' --save=B
Saved option '--B' as: --break='[---]'
$ rak --pattern=! --save=P
Saved option '--P' as: --pattern='!'
$ rak --save=foo
Removed configuration for 'foo'
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 --save
=foo as the only option to remove the "foo" set of options.
--sep=[,]
Only applicable if --csv-per-line
has been specified. Indicates the character to indicate the field separator. Defaults to the comma.
--show-blame
Flag. Indicate whether to show git blame
information for matching lines if possible, instead of just the line. Defaults to False
.
Requires that the Git::Blame::File
module is installed.
--show-filename
Flag. Indicate whether filenames should be shown. Defaults to True
.
--show-line-number
Flag. Indicate whether line numbers should be shown. Defaults to True
.
--shell=invocation
If specified, indicates the command(s) to be executed in a shell. Any $_
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.
--silently[=out,err]
Flag and option. Only applicable if the pattern is a Callable
. Indicates whether any output from the Callable
pattern should be caught. Defaults to 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:
out - only capture STDOUT
err - only capture STDERR
out,err - capture both STDIN as well as STDERR
err,out - capture both STDIN as well as STDERR
--smartcase
Flag. An intelligent version of --ignorecase
. If the pattern does not contain any uppercase characters, it will act as if --ignorecase
was specified. Otherwise it is ignored.
--stats
Flag. Also show statistics about the search operation after having shown the full search result.
--stats-only
Flag. Only show statistics about the search operation. See also --count-only
.
--strict
Only applicable if --csv-per-line
has been specified. Flag. If specified with a trueish value, then each line in the CSV file must have the same number of fields. Default is to allow different numbers of fields.
--summary-if-larger-than=N
Indicate the maximum size a line may have before it will be summarized. Defaults to 160
if STDOUT
is a TTY (aka, someone is actually watching the search results), otherwise defaults to Inf
effectively (indicating no summarization will ever occur).
- --type=words|starts-with|ends-with|contains
Only makes sense if the pattern is a string. With words
specified, will look for pattern as a word in a line, with starts-with
will look for the pattern at the beginning of a line, with ends-with
will look for the pattern at the end of a line, with contains
will look for the pattern at any position in a line.
--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 True
if no context for lines was specified, else defaults to False
.
--uid=condition
If specified, indicates the Callable
that should return True to include a file in the selection of files to be checked. The numeric uid
of the file will be passed as the only argument. Can also be specified as a single numeric argument. See also --user
.
# 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
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--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 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
Flag. If specified with a true value, will only produce unique lines of output. Default is False
. See also --frequencies
.
--user=condition
If specified, indicates the Callable
that should return True to include a file in the selection of files to be checked. The user name associated with the 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 except the listed named, prefix with a !
.
See also --uid
. Requires the P5getpwnam module to be installed.
# 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'
NOTE: support of this feature depends on Raku supporting that feature on the current operating system.
--version
Flag. If the only argument, shows the name and version of the script, and the system it is running on. Additionally specify --verbose
to see more information.
--vimgrep
Flag. If specified with a true value, will output search results in the format "filename:linenumber:column:line". This allows integration with the :grep
action in vim-like editors.
CHECKING TIMES ON FILES
The --accessed
, --created
, --modified
and --meta-modified
options expect Callable
to perform the check to include a file in the search process. It is passed the epoch (number of seconds since 1 January 1970 UTC) value of the file being checked for the indicated option, and it should return True
to include that file in any search.
To facilitate checks, some extra features are activated for these Callable
s, allowing you to more easily craft your conditions.
Automatic conversion to epoch
In Raku, the .accessed
, .created
, .changed
and .modified
methods on the IO::Path
object return Instant
objects, which are atomic time rather than epoch. Within these special Callables
, these values are automatically converted to epoch values, to ease comparisons.
Specifying some time ago
Within these special Callable
s, one can also indicate an epoch value in the past by using the .ago
method in a specially formatted string. This string is formatted similarly to time specifications of the Unix 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.
On method naming
For rak
it was decided to name the option for checking the meta information of a file as --meta-modified
. In Raku, the associated method on the IO::Path
object is (probably for historical reasons) called .changed
. To facilitate the creation of the Callable
s for these options, one can use both .meta-modified
as well as .changed
as methods.
Examples
# 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'
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 small sponsorship would mean a great deal to me!
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.