glark - Search text files for complex regular expressions
glark [options] expression file ...
Similar to "grep", "glark" offers: Perl-compatible regular expressions, color
highlighting of matches, context around matches, complex expressions (``and'' and
``or''), grep output emulation, and automatic exclusion of non-text files. Its
regular expressions should be familiar to persons experienced in Perl, Python,
or Ruby. File may also be a list of files in the form of a path.
Use \nnn (octal) as the input record separator. If nnn is omitted, use '\n\n' as
the record separator, which treats paragraphs as lines.
-d ACTION, --directories=ACTION
Directories are processed according to the given ACTION, which by default is
"read". If ACTION is "recurse", each file in the directory is read and each
subdirectory is recursed into (equivalent to the "-r" option). If ACTION is
"skip", directories are not read, and no message is produced.
Specify how to handle binary files, thus overriding the default behavior, which
is to denote the binary files that match the expression, without displaying the
match. TYPE may be one of: "binary", the default; "without-match", which
results in binary files being skipped; and "text", which results in the binary
file being treated as text, the display of which may have bad side effects with
the terminal. Note that the default behavior has changed; this previously was to
skip binary files. The same effect may be achieved by setting binary-files to
"without-match" in the ~/.glarkrc file.
--[with-]basename EXPR, --[with-]name EXPR
Search only files whose names match the given regular expression. As in find(1),
this works on the basename of the file. This expression can be negated and
modified with "!" and "i", such as '!/io\.[hc]$/i'.
--[with-]fullname EXPR, --[with-]path EXPR
Search only files whose names, including path, match the given regular
expression. As in find(1), this works on the path of the file. This expression
can be negated and modified with "!" and "i", such as '!/Dialog.*\.java$/i'.
--without-basename EXPR, --without-name EXPR
Do not search files with base names matching the given regular expression.
--without-fullname EXPR, --without-path EXPR
Do not search files with full names matching the given regular expression.
Do not search files whose names match the given expression. This can be useful
for finding external references to a file, or to a class (assuming that class
names match file names).
Recurse through directories. Equivalent to --directories=read.
Sets whether, if a command line argument includes the path separator (such as
``:''), the argument should be split by the path separator. This functionality is
useful for using environment variables as input, such as $PATH and $CLASSPATH,
which are automatically split and processed as a list of files and directories.
The default value of this option is ``true''. "--no-split-as-path" is equivalent
If provided, files no larger than SIZEbytes will be searched. This is
useful when running the "--recurse" option on directories that may contain
-a NUM expr1 expr2
--and NUM expr1 expr2
--and=NUM expr1 expr2
( expr1 --and=NUM expr2 )
Match both of the two expressions, within NUM lines of each other. See the
EXPRESSIONS section for more information.
-b NUM[%], --before NUM[%]
Restrict the search to before the given location, which represents either the
number of the last line within the valid range, or the percentage of lines to be
Restrict the search to after the given section, which represents either the
number of the first line within the valid range, or the percentage of lines to
-f FILE, --file=FILE
Use the lines in the given file as expressions. Each line consists of a regular
Match regular expressions without regard to case. The default is
-m NUM, --match-limit NUM
Find only the first NUM matches in each file.
-o expr1 expr2
--or expr1 expr2
( expr1 --or expr2 )
Match either of the two expressions. See the EXPRESSIONS section for more
-R, --range NUM[%],NUM[%]
Restrict the search to the given range of lines, as either line numbers or a
percentage of the length of the file.
Show lines that do not match the expression.
-w, --word, --word-regexp
Put word boundaries around each pattern, thus matching only where
the full word(s) occur in the text. Thus, "glark -w Foo" is the same
as "glark '/\bFoo\b/'".
Select only where the entire line matches the pattern(s).
--xor expr1 expr2
( expr1 --xor expr2 )
Match either of the two expressions, but not both. See the EXPRESSIONS section
for more information.
-A NUM, --after-context=NUM
Print NUM lines after a matched expression.
-B NUM, --before-context=NUM
Print NUM lines before a matched expression.
-C [NUM], -NUM, --context[=NUM]
Output NUM lines of context around a matched expression. The default is no
context. If no NUM is given for this option, the number of lines of context
Instead of normal output, display only the number of matches in each file.
-F, --file-color COLOR
Specify the highlight color for file names. See the HIGHLIGHTING section for
the values that can be used.
Display the entire file(s), presumably with matches highlighted.
Produce output like the grep default: file names, no line numbers, and a single
line of the match, which will be the first line for matches that span multiple
lines. If the EMACS environment variable is set, this value is set to true.
Thus, running glark under Emacs results in the output format expected by Emacs.
Do not display the names of the files that matched.
Display the names of the files that matched. This is the default
Print only the names of the file that matched the expression.
Print only the names of the file that did not match the expression.
Use NAME as output file name. This is useful when reading from standard input.
Display the line numbers. This is the default behavior.
Do not display the line numbers.
Specify the highlight color for line numbers. This defaults to none (no
highlighting). See the HIGHLIGHTING section for more information.
-T, --text-color COLOR
Specify the highlight color for text. See the HIGHLIGHTING section for more
Specify the highlight color for the regular expression capture NUM. Colors are
used by regular expressions in the order they are created (that is, with the
"--and" and "--or" option), or with captures within a regular expression (such
as '/(this)|(that)/'). is See the HIGHLIGHTING section for more information.
Enable highlighting. This is the default behavior. Format is ``single'' (one
color) or ``multi'' (different color per regular expression). See the HIGHLIGHTING
section for more information.
Display only the region that matched, not the entire line. If the expression
contains ``backreferences'' (i.e., expressions bounded by ``( ... )''), then only
the portion captured will be displayed, not the entire line. This option is
useful with "-g", which eliminates the default highlighting and display of file
When in -l mode, write file names followed by the ASCII NUL character ('\0')
instead of '\n'.
Display the help message.
Display the settings glark is using, and exit. Since this is run after
configuration files are read, this may be useful for determining values of
Write the expression in a more legible format, useful for debugging.
-q, -s, --quiet, --no-messages
Enable warnings. This is the default.
Display version information.
Display normally suppressed output, for debugging purposes.
Regular expressions are expected to be in the Perl/Ruby format. "perldoc
perlre" has more general information. The expression may be of either form:
There is no difference between the two forms, except that with the latter, one
can provide the ``ignore case'' modifier, thus matching ``someThing'' and
% glark /something/i
Note that this is redundant with the "-i" ("--ignore-case") option.
All regular expression characters and options are available, such as ``\w'',
``.*?'' and ``[^9]''. For example:
If the and and or options are not used, the last non-option is considered
to be the expression to be matched. In the following, ``printf'' is used as the
% glark -w printf *.c
POSIX character classes (e.g., [[:alpha:]]) are also supported.
Complex expressions combine regular expressions (and complex expressions
themselves) with logical AND, OR, and XOR operators. Both prefix and infix
notation is supported.
-o expr1 expr2
--or expr1 expr2 --end-of-or
( expr1 --or expr2 )
Match either of the two expressions. The results of the two forms are
equivalent. In the latter syntax, the --end-of-or is optional.
-a number expr1 expr2
--and=number expr1 expr2 --end-of-and
( expr1 --and number expr2 )
Match both of the two expressions, within <number> lines of each other. As with
the "or" option, the results of the two forms are equivalent, and the
"--end-of-and" is optional. The forms "-aNUM" and "--and=NUM" are also
If the number provided is -1 (negative one), the distance is considered to be
``infinite'', and thus, the condition is satisfied if both expressions match
within the same file.
If the number provided is 0 (zero), the condition is satisfied if both
expressions match on the same line.
If the --and option is used, and the follow argument is not numeric, then the
value defaults to zero.
A warning will be issued if the value given in the number position does not
appear to be numeric.
--xor expr1 expr2 --end-of-xor
( expr1 --xor expr2 )
Match either of the two expressions, but not both. "--end-of-xor" is optional.
Negated Regular Expressions
Regular expressions can be negated, by being prefixed with '!', and using the
'/' quote characters around the expression, such as:
This has the effect of ``match anything other than this''. For a single
expression, this is no different than the -v/--invert-match option, but it can
be useful in complex expressions, such as:
--and 0 this '!/that/'
which means ``match and line that has ''this``, but not ''that".
Matching patterns and file names can be highlighted using ANSI escape sequences.
Both the foreground and the background colors may be specified, from the
The foreground may have any number of the following modifiers applied:
The format is ``MODIFIERS FOREGROUND on BACKGROUND''. For example:
black on yellow (the default for patterns)
reverse bold (the default for file names)
green on white
bold underline red on cyan
By default text is highlighted as black on yellow. File names are written in
reversed bold text.
% glark format *.h
Searches for ``format'' in the local .h files.
% glark --ignore-case format *.h
Searches for ``format'' without regard to case. Short form:
% glark -i format *.h
% glark --context=6 format *.h
Produces 6 lines of context around any match for ``format''. Short forms:
% glark -C 6 format *.h
% glark -6 format *.h
% glark --exclude-matching Object *.java
Find references to ``Object'', excluding the files whose names match ``Object''.
Thus, SessionBean.java would be searched; EJBObject.java would not. Short form:
% glark -M Object *.java
Show where exceptions are dumped. Note that the "--grep" option is used, thus
turning off highlighting and display of file names. If the "--no-filename"
option is used, the output will consist of only the matching portions. The short
form of this command is:
% glark -gy '\w+\.printStackTrace\(.*\)' *.java
See the "--file-color" option. For example, for white on black:
file-color: white on black
See the "--filter" option. For example, to show the entire file:
See the "--fullname" and "--basename" options. For example, to omit CVS files:
See the "--grep" option. For example, to always run in grep mode:
See the "--highlight" option. To turn off highlighting:
See the "--ignore-case" option. To make matching case-insensitive:
The extensions of files that should be considered to always be nontext (binary).
If a file extension is not known, the file contents are examined for nontext
characters. Thus, setting this field can result in faster searches. Example:
known-nontext-files: class exe dll com
See the Exclusion of Non-Text Files section in NOTES for the default
The extensions of files that should be considered to always be text. See above
for more. Example:
known-text-files: ini bat xsl xml
See the Exclusion of Non-Text Files section in NOTES for the default
By default, glark uses only the configuration file ~/.glarkrc. Enabling this
makes glark search upward from the current directory for the first .glarkrc
This can be used, for example, in a Java project, where .class files are binary,
versus a PHP project, where .class files are text:
With this configuration, .class files will automatically be treated as binary
file in Java projects, and .class files will be treated as text. This can speed
Note that the configuration file ~/.glarkrc is read first, so the local
configuration file can override those settings.
See the "--quiet" option.
Whether to display breaks between sections, when displaying context. Example:
By default, this is false.
See the "--text-color" option. Example:
text-color: bold blue on white
See the "--verbose" option. Example:
See the "--verbosity" option. Example:
Exclusion of Non-Text Files
Non-text files are automatically skipped, by taking a sample of the file and
checking for an excessive number of non-ASCII characters. For speed purposes,
this test is skipped for files whose suffixes are associated with text files:
Similarly, this test is also skipped for files whose suffixes are associated
with non-text (binary) files:
See the "known-text-files" and "known-nontext-files" fields for denoting file
name suffixes to associate as text or nontext.
The exit status is 0 if matches were found; 1 if no matches were found, and 2 if
there was an error. An inverted match (the -v/--invert-match option) will result
in 1 for matches found, 0 for none found.
For regular expressions, the "perlre" man page.
Mastering Regular Expressions, by Jeffrey Friedl, published by O'Reilly.
``Unbalanced'' leading and trailing slashes will result in those slashes being
included as characters in the regular expression. Thus, the following pairs are
The code to detect nontext files assumes ASCII, not Unicode.
Jeff Pace <jpace at incava dot org>
Copyright (c) 2006, Jeff Pace.
All Rights Reserved. This module is free software. It may be used, redistributed
and/or modified under the terms of the Lesser GNU Public License. See
http://www.gnu.org/licenses/lgpl.html for more information.