glark 1.9.0 → 1.10.0

data/lib/glark/util/option.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/ruby -w
+#!ruby -w
+# vim: set filetype=ruby : set sw=2
+
+module Glark
+  class Option
+    include Loggable
+    
+    def initialize optee
+      @optee = optee
+    end
+
+    def tags
+      [ '--' + rcfield ]
+    end  
+    
+    def match_rc name, values
+      if name == rcfield
+        values.each do |val|
+          set val
+        end
+        true
+      end
+    end
+
+    def add_to_option_data optdata
+      optdata << {
+        :tags => tags,
+        :arg  => [ argtype ],
+        :set  => Proc.new { |pat| set pat }
+      }
+    end
+  end
+end

data/lib/glark/util/options.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/ruby -w
+#!ruby -w
+# vim: set filetype=ruby : set sw=2
+
+require 'glark/util/optutil'
+require 'riel/log/loggable'
+
+module Glark
+  class Options
+    include Loggable, Glark::OptionUtil
+  end
+end

data/lib/glark/util/optutil.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/ruby -w
+# -*- ruby -*-
+
+require 'riel/text/ansi/color'
+
+module Glark
+  module OptionUtil
+    # returns whether the value matches a true value, such as "yes", "true", or "on".
+    def to_boolean value
+      [ "yes", "true", "on" ].include? value.downcase
+    end
+
+    NONE = Object.new
+
+    def set_var name, val
+      instance_variable_set '@' + name.to_s, val
+    end
+
+    def set name, sval = NONE
+      Proc.new { |optval| set_var name, sval == NONE ? optval : sval }
+    end
+
+    def add_opt optdata, varname, tags, val = NONE
+      optdata << {
+        :tags => tags,
+        :set  => set(varname, val)
+      }
+    end
+
+    def add_opt_arg optdata, varname, argtype, tags, val = NONE
+      optdata << {
+        :tags => tags,
+        :arg  => [ argtype ],
+        :set  => set(varname, val)
+      }
+    end
+
+    def add_opt_true optdata, varname, tags
+      add_opt optdata, varname, tags, true
+    end
+
+    def add_opt_false optdata, varname, tags
+      add_opt optdata, varname, tags, false
+    end
+
+    def add_opt_str optdata, varname, tags, val = NONE
+      add_opt_arg optdata, varname, :string, tags, val
+    end
+
+    def add_opt_int optdata, varname, tags, val = NONE
+      add_opt_arg optdata, varname, :integer, tags, val
+    end
+
+    def add_opt_blk optdata, tags, &blk
+      optdata << {
+        :tags => tags,
+        :set  => blk
+      }
+    end
+
+    def colorize field, str
+      if field
+        field + str + Text::Color::RESET
+      else
+        str
+      end
+    end
+  end
+end

data/lib/glark/util/timestamper.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/ruby -w
+# -*- ruby -*-
+
+module TimeStamper
+  def stamp msg = self
+    @start ||= Time.new
+    duration = Time.new - @start
+    printf "%10.6f %-20s %s\n", duration, self.class.to_s, msg.to_s
+  end
+
+  def interval msg = self
+    @last ||= @start
+    last = @last || Time.new
+    @last = Time.new
+    duration = @last - last
+    printf "%10.6f %-20s %s\n", duration, self.class.to_s, msg.to_s
+  end
+end

data/man/glark.1

@@ -0,0 +1,1134 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "GLARK" "1" "December 2012" "" ""
+.
+.SH "NAME"
+\fBglark\fR \- Search text files for complex regular expressions
+.
+.SH "SYNOPSIS"
+\fBglark\fR \fIoptions\fR expression \fIfiles\fR
+.
+.SH "DESCRIPTION"
+\fBGlark\fR searches files for regular expressions\.
+.
+.P
+Similar to \fBgrep\fR, \fBglark\fR supports Perl\-compatible regular expressions, color highlighting of matches, and context around matches\.
+.
+.P
+\fBGlark\fR extends \fBgrep\fR by matching complex expressions, such as "and", "or", and "xor"\.
+.
+.P
+\fBGlark\fR handles file, directory, and path arguments, optionally recursing directories to a certain depth, and processing path arguments as a set of files and directories\. \.svn and \.git subdirectories are automatically excluded\. Binary files are excluded (by default), but can, in the case of compressed or archived files, have their extracted contents be searched\.
+.
+.P
+\fBGlark\fR can use a per\-project configuration file, so different projects can have their own \fBGlark\fR parameters, such as different files to include and exclude for searching, and different colors for pattern highlighting\.
+.
+.SH "OPTIONS"
+For each option of the type \fB\-\-option=ARG\fR, the equivalent \fB\-\-option ARG\fR can be used instead\. Options can also be specified with their unambiguous leading substrings, such as \fB\-\-rec\fR for \fB\-\-recurse\fR\.
+.
+.SS "INPUT"
+.
+.TP
+\fB\-0[nnn]\fR
+Use \ennn (octal) as the input record separator\. If nnn is omitted, use \'\en\en\' as the record separator, which treats paragraphs as lines\.
+.
+.TP
+\fB\-d\fR ACTION, \fB\-\-directories\fR=ACTION
+Directories are processed according to the given \fBACTION\fR, which by default is \fBlist\fR, meaning that each file in the directory will be searched\. If \fBACTION\fR is \fBrecurse\fR (or \fBfind\fR), each file in the given directory and its subdirectories will be searched (equivalent to the \fB\-r\fR option)\. If \fBACTION\fR is \fBskip\fR, directories are not read, and no message is produced\.
+.
+.TP
+\fB\-\-binary\-files\fR=TYPE
+Specify how to handle binary files\. \fBTYPE\fR may be one of:
+.
+.IP
+\fBbinary\fR: only the name of matching files is printed\.
+.
+.IP
+\fBlist\fR: binary files that contain lists of files (such as tar, tar\.gz, zip and jar files) are searched such that the \fIfile names\fR are searched against\.
+.
+.IP
+\fBread\fR: the decompressed full contents of binary files will be searched\. This supports tar, jar, zip, tar\.gz, tgz and gz files\. Only one level of compression/archiving is handled; thus compressed files within other compressed files are not searched\.
+.
+.IP
+\fBskip\fR or \fBwithout\-match\fR: binary files are skipped\. This is the default\.
+.
+.IP
+\fBtext\fR: binary file are treated as text\. This option may have negative side effects with the terminal, attempting to print non\-printable characters\.
+.
+.TP
+\fB\-\-match\-name\fR=REGEXP
+Search only files with names that match the given regular expression\. As in find(1), this works on the basename of the file\. The expression can be negated and modified with \fB!\fR and \fBi\fR, such as \fB!/io\e\.[hc]$/i\fR\. This option, and all \fB\-\-match\-\fR and \fB\-\-skip\-\fR options, can be specified multiple times, in which case only files matching \fIany\fR of the given expressions will be searched\.
+.
+.TP
+\fB\-\-skip\-name\fR=REGEXP
+Do not search files with base names matching the given regular expression\. If this option is specified multiple times, only files matching \fInone\fR of the given expressions will be searched\.
+.
+.TP
+\fB\-\-match\-path\fR=REGEXP
+Search only files with full names that match the given regular expression\. As in find(1), this works on the path of the file\.
+.
+.TP
+\fB\-\-skip\-path\fR=REGEXP
+Skip files with full names matching the given regular expression\.
+.
+.TP
+\fB\-\-match\-dirname\fR=REGEXP
+Search only directories with basenames matching the given expression\.
+.
+.TP
+\fB\-\-skip\-dirname\fR=REGEXP
+Skip directories with basenames not matching the given expression\. Subdirectories of skipped directories will not be recursed\.
+.
+.TP
+\fB\-\-match\-dirpath\fR=REGEXP
+Search in and under directories with paths matching the given expression\.
+.
+.TP
+\fB\-\-skip\-dirpath\fR=REGEXP
+Skip directories with paths matching the given expression\.
+.
+.TP
+\fB\-\-match\-ext\fR=REGEXP
+Search only files with extensions that match the given regular expression, which should not include the leading dot\.
+.
+.TP
+\fB\-\-skip\-ext\fR=REGEXP
+Skip files with extensions that match the given regular expression\.
+.
+.TP
+\fB\-M\fR, \fB\-\-exclude\-matching\fR
+Do not search files whose names match the primary expression\. This can be useful for finding external references to a file, or to a class, assuming that class names match file names\.
+.
+.TP
+\fB\-r\fR, \fB\-\-recurse\fR
+Recurse through directories\. Equivalent to \fB\-\-directories=recurse\fR\.
+.
+.TP
+\fB\-\-split\-as\-path\fR
+If a command line argument includes the path separator (such as ":"), the argument will be split by the path separator\. This functionality is useful for using environment variables as input, such as \fB$PATH\fR and \fB$CLASSPATH\fR\. which are automatically split and processed as a list of files and directories\. This option is enabled by default\.
+.
+.TP
+\fB\-\-no\-split\-as\-path\fR
+Disables splitting arguments as paths\.
+.
+.TP
+\fB\-\-size\-limit\fR=SIZE
+Limit searches to files no larger than \fBSIZE\fR bytes\. This is useful when running the \fB\-\-recurse\fR option on directories that may contain large files\.
+.
+.SS "MATCHING"
+.
+.TP
+\fB\-a\fR NUM expr1 expr2, \fB\-\-and\fR NUM expr1 expr2, \fB\-\-and\fR=NUM expr1 expr2
+Match both expressions, within \fBNUM\fR lines of each other\. See the \fBEXPRESSIONS\fR section for more information\.
+.
+.TP
+\fB( expr1 \-\-and=NUM expr2 )\fR
+Same as the above, using infix notation instead of prefix\. Note that depending on your shell, you may have to escape the parentheses\.
+.
+.TP
+\fB\-\-after\fR=NUM[%]
+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 be skipped\. \fB\-\-after=25%\fR means to search the "lower" 25% of each file\. \fB\-\-after=10\fR means to skip the first ten lines of each file\.
+.
+.TP
+\fB\-b\fR NUM[%], \fB\-\-before\fR=NUM[%]
+Restrict the search to before the given location, which is either the number of the last line within the valid range, or the percentage of lines to be searched\.
+.
+.TP
+\fB\-f\fR FILE, \fB\-\-file\fR=FILE
+Use the lines in the given file as expressions\. Each line consists of a regular expression\. Complex expressions are supported\.
+.
+.TP
+\fB\-i\fR, \fB\-\-ignore\-case\fR
+Match regular expressions without regard to case\. The default is case sensitive\.
+.
+.TP
+\fB\-m\fR NUM, \fB\-\-match\-limit\fR=NUM
+Output only the first \fBNUM\fR matches in each file\.
+.
+.TP
+\fB\-a\fR NUM expr1 expr2, \fB\-\-or\fR NUM expr1 expr2, \fB\-\-or\fR=NUM expr1 expr2
+Match either expressions\. See the \fBEXPRESSIONS\fR section for more information\.
+.
+.TP
+\fB( expr1 \-\-or=NUM expr2 )\fR
+Same as the above, using infix notation instead of prefix\.
+.
+.TP
+\fB\-R\fR, \fB\-\-range\fR NUM[%],NUM[%]
+Restrict the search to the given range of lines, as either line numbers or a percentage of the length of the file\.
+.
+.TP
+\fB\-v\fR, \fB\-\-invert\-match\fR
+Show lines that do not match the expression\.
+.
+.TP
+\fB\-w\fR, \fB\-\-word\fR, \fB\-\-word\-regexp\fR
+Put word boundaries around each pattern, thus matching only where the full word(s) occur in the text\. Thus, \fBglark \-w Foo\fR is the same as \fBglark \'/\ebFoo\eb/\'\fR\.
+.
+.TP
+\fB\-x\fR, \fB\-\-line\-regexp\fR
+Select only where the entire line matches the pattern(s)\.
+.
+.TP
+\fB\-\-xor\fR expr1 expr2
+Match either of the two expressions, but not both\. See the EXPRESSIONS section for more information\.
+.
+.TP
+\fB( expr1 \-\-xor expr2 )\fR
+Same as the above, using infix notation instead of prefix\.
+.
+.SS "OUTPUT"
+.
+.TP
+\fB\-A\fR NUM, \fB\-\-after\-context\fR=NUM
+Print \fBNUM\fR lines after a matched expression\.
+.
+.TP
+\fB\-B\fR NUM, \fB\-\-before\-context\fR=NUM
+Print \fBNUM\fR lines before a matched expression\.
+.
+.TP
+\fB\-C\fR [NUM], \fB\-NUM\fR, \fB\-\-context[=NUM]\fR
+Output \fBNUM\fR lines of context around a matched expression\. The default is no context\. If no \fBNUM\fR is given for this option, the number of lines of context is 2\.
+.
+.TP
+\fB\-c\fR, \fB\-\-count\fR
+Instead of normal output, display only the number of matches in each file\.
+.
+.TP
+\fB\-F\fR, \fB\-\-file\-color\fR=COLOR
+Specify the highlight color for file names\. See the HIGHLIGHTING section for the values that can be used\.
+.
+.TP
+\fB\-\-no\-filter\fR
+Display all lines, after highlighting matching expressions\. This is useful to see highlighted matches as well as non\-matching lines, essentially a \fB\-\-context\fR of the entire file\.
+.
+.TP
+\fB\-g\fR, \fB\-\-grep\fR
+Produce output like the (legacy) 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\.
+.
+.TP
+\fB\-h\fR, \fB\-\-no\-filename\fR
+Do not display the names of the files that matched\.
+.
+.TP
+\fB\-H\fR, \fB\-\-with\-filename\fR
+Display the names of the files that matched\. This is the default behavior\.
+.
+.TP
+\fB\-l\fR, \fB\-\-files\-with\-matches\fR
+Print only the names of the file that matched the expression\.
+.
+.TP
+\fB\-L\fR, \fB\-\-files\-without\-match\fR
+Print only the names of the file that did \fBnot\fR match the expression\.
+.
+.TP
+\fB\-\-label\fR=NAME
+Use \fBNAME\fR as the output file name\. This is useful when reading from standard input, such as glark being piped from an archive listing (tar tvf or jar tvf)\.
+.
+.TP
+\fB\-n\fR, \fB\-\-line\-number\fR
+Display the line numbers\. This is the default behavior\.
+.
+.TP
+\fB\-N\fR, \fB\-\-no\-line\-number\fR
+Do not display the line numbers\.
+.
+.TP
+\fB\-\-line\-number\-color\fR=COLOR
+Specify the highlight color for line numbers\. This defaults to none (no highlighting)\. See the HIGHLIGHTING section for more information\.
+.
+.TP
+\fB\-T\fR, \fB\-\-text\-color\fR=COLOR
+Specify the highlight color for text\. See the HIGHLIGHTING section for more information\.
+.
+.TP
+\fB\-u\fR, \fB\-\-highlight\fR=FORMAT
+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\.
+.
+.TP
+\fB\-U\fR, \fB\-\-no\-highlight\fR
+Disable highlighting\.
+.
+.TP
+\fB\-y\fR, \fB\-\-extract\-matches\fR
+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 \fB\-g\fR, which eliminates the default highlighting and display of file names\.
+.
+.TP
+\fB\-Z\fR, \fB\-\-null\fR
+When in \fB\-l\fR mode, write file names followed by the ASCII NUL character (\'><\') instead of \'\en\'\. This is like \fBfind \.\.\. \-print0\fR, for piping into another command\.
+.
+.SS "INFORMATION"
+.
+.TP
+\fB\-?\fR, \fB\-\-help\fR
+Display the help message\.
+.
+.TP
+\fB\-\-config\fR
+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 configuration parameters\.
+.
+.TP
+\fB\-\-explain\fR
+Write the expression in a more legible format, useful for debugging complex expressions\.
+.
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR, \fB\-\-no\-messages\fR
+Suppress warnings\. By default, warnings are enabled\.
+.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Display version information\.
+.
+.TP
+\fB\-\-verbose\fR
+Display normally suppressed output, for debugging purposes\.
+.
+.SH "FILES"
+File arguments follow options and the expression to be matched\. Files can be one or more of any of the following:
+.
+.TP
+\fBfile\fR
+Name of files\.
+.
+.TP
+\fBdirectory\fR
+Directories under which files are searched\. See the \fB\-\-directories\fR option for controlling whether to match all files \fIin\fR the given directory (the \fBlist\fR value), or to match all files \fIunder\fR the given directory, recursively\.
+.
+.IP
+Files within and subdirectories of a directory are listed in sorted order\.
+.
+.IP
+Directories can also be of the form \fB/usr/lib/\.\.\.\fR, which means to recurse under the given directory\. This can also be \fB\.\.\.\fR, meaning to recurse under the current directory\.
+.
+.IP
+The form \fB/usr/lib/\.\.\.N\fR, where N is a number, restrains recursive searching to the given depth\. A value of 0 means to search only the files in the given directory; a value of 1 means to search the files in the given directory and the immediate subdirectories\. What happens with a value of 2 is left as an exercise for the reader\.
+.
+.TP
+\fB\-\fR
+Read from standard input\. If no file arguments are specified this is the default\.
+.
+.TP
+\fBpath\fR
+This is a path, using the path separator for the current OS (\':\' for Linux, \';\' for Windows)\. Each element of the path will be processed as a file or directory\.
+.
+.SH "EXPRESSIONS"
+Regular expressions are expected to be in the Perl/Ruby format\. \fBperldoc perlre\fR has more general information\. The expression may be of either form:
+.
+.IP "" 4
+.
+.nf
+
+something
+/something/
+.
+.fi
+.
+.IP "" 0
+.
+.P
+There is no difference between the two forms, except that with the latter, one can provide the "ignore case" modifier, thus matching "someThing" and "SoMeThInG":
+.
+.IP "" 4
+.
+.nf
+
+% glark /something/i
+.
+.fi
+.
+.IP "" 0
+.
+.P
+This is redundant with the \fB\-i\fR (\fB\-\-ignore\-case\fR) option\.
+.
+.P
+All regular expression characters and sequences are available, such as "\ew" and "\.*?"\. For example:
+.
+.IP "" 4
+.
+.nf
+
+% glark \'\eb[a\-z][^\ed]\ed{1,3}\.*\es*>>\es*\ed+\es*\.*& +\ed{3}\'
+.
+.fi
+.
+.IP "" 0
+.
+.P
+If the \fB\-\-and\fR and \fB\-\-or\fR 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 expression\. Note that in non\-quiet mode, a warning will result if the expression exists as a file, to show when the expression may have been erroneously omitted\.
+.
+.IP "" 4
+.
+.nf
+
+% glark \-w printf *\.c
+.
+.fi
+.
+.IP "" 0
+.
+.P
+POSIX character classes (e\.g\., [[:alpha:]]) are also supported\.
+.
+.SS "COMPLEX EXPRESSIONS"
+Complex expressions combine regular expressions (and complex expressions themselves) with logical AND, OR, and XOR operators\. Both prefix and infix notations are supported\.
+.
+.TP
+\fB\-a\fR NUM expr1 expr2, \fB\-\-and=NUM\fR expr1 expr2, \fB\-\-end\-of\-and\fR, \fB( expr1 \-\-and NUM expr2 )\fR
+Match both of the two expressions, within \fBNUM\fR lines of each other\. The forms \fB\-aNUM\fR and \fB\-\-and=NUM\fR are also supported\. In the prefix syntax, \fB\-\-end\-of\-and\fR is optional\.
+.
+.IP
+If \fBNUM\fR is \-1 (negative one), the distance is considered "infinite", so the condition is satisfied if both expressions match within the same file\.
+.
+.IP
+If \fBNUM\fR is 0 (zero), the condition is satisfied if both expressions match on the same line\.
+.
+.IP
+If the \fB\-\-and\fR option is used and the follow argument is not numeric, then the value defaults to zero\.
+.
+.IP
+A warning will result if the value given in the number position does not appear to be numeric\.
+.
+.TP
+\fB\-o\fR expr1 expr2, \fB\-\-or\fR expr1 expr2 \fB\-\-end\-of\-or\fR, \fB( expr1 \-\-or expr2 )\fR
+Match either of the two expressions\. As with the \fB\-\-and\fR option, the two forms are equivalent, and \fB\-\-end\-of\-or\fR is optional\.
+.
+.TP
+\fB\-\-xor\fR expr1 expr2 \fB\-\-end\-of\-xor\fR, \fB( expr1 \-\-xor expr2 )\fR
+Match either of the two expressions, but not both\. \fB\-\-end\-of\-xor\fR is optional\.
+.
+.SS "NEGATED EXPRESSIONS"
+Regular expressions can be negated, by being prefixed with \'!\', and using the \'/\' quote characters around the expression, such as:
+.
+.IP "" 4
+.
+.nf
+
+!/this/
+.
+.fi
+.
+.IP "" 0
+.
+.P
+This has the effect of "match anything other than \'this\'"\. For a single expression, this is no different than the \fB\-v\fR (\fB\-\-invert\-match\fR) option, but it can be useful in complex expressions, such as:
+.
+.IP "" 4
+.
+.nf
+
+\-\-and 0 this \'!/that/\'
+.
+.fi
+.
+.IP "" 0
+.
+.P
+which means "match a line that has "this", but not "that"\.
+.
+.SH "HIGHLIGHTING"
+On terminals that support ANSI escape sequences, matching patterns and file names can be highlighted for the foreground and/or background\. Colors are denoted by name, from the following list, or by RGB value, in the form RRGGBB\.
+.
+.IP "" 4
+.
+.nf
+
+black
+blue
+cyan
+green
+magenta
+red
+white
+yellow
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The foreground may have any number of the following modifiers applied:
+.
+.IP "" 4
+.
+.nf
+
+blink
+bold
+concealed
+negative
+underline
+underscore
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The format is "MODIFIERS FOREGROUND on BACKGROUND"\. For example:
+.
+.IP "" 4
+.
+.nf
+
+red
+black on yellow                    (the default for patterns)
+bold                               (the default for file names)
+green on white
+AE22D9
+f2331a on 2a3f44
+bold underline red on 88a72d
+.
+.fi
+.
+.IP "" 0
+.
+.P
+By default text is highlighted as black on yellow\. File names are written in bold\.
+.
+.SH "EXAMPLES"
+.
+.SS "BASIC USAGE"
+.
+.TP
+\fBglark format *\.h\fR
+Searches for "format" in the local \.h files\.
+.
+.TP
+\fBglark \-\-ignore\-case format *\.h\fR
+Searches for "format" without regard to case\. Short form:
+.
+.IP
+\fBglark \-i format *\.h\fR
+.
+.TP
+\fBglark \-\-context=6 format *\.h\fR
+Produces 6 lines of context around any match for "format"\. Short forms:
+.
+.IP
+\fBglark \-C 6 format *\.h\fR \fBglark \-6 format *\.h\fR
+.
+.TP
+\fBglark \-\-exclude\-matching Object *\.java\fR
+Find references to "Object", excluding the files whose names match "Object"\. Thus, SessionBean\.java would be searched; EJBObject\.java would not\. Short form:
+.
+.IP
+\fBglark \-M Object *\.java\fR
+.
+.TP
+\fBglark \-N \-h \-\-context=0 \-\-extract\-matches \'(\ew+)\e\.printStackTrace\e(\.*\e)\' *\.java\fR
+Show only the variable name of exceptions that are dumped\. Short form:
+.
+.IP
+\fBglark \-gy \'(\ew+)\e\.printStackTrace\e\e(\.\e*\e\e)\' *\.java\fR
+.
+.TP
+\fB% who| glark \-gy \'^(\eS+)\es+\eS+\es*May 15\'\fR
+Display only the names of users who logged in today\.
+.
+.TP
+\fBglark \-l \'\eb\ew{25,}\eb\' *\.txt\fR
+Display (only) the names of the text files that contain "words" at least 25 characters long\.
+.
+.TP
+\fBglark \-\-files\-without\-match \'"\ew+"\'\fR
+Display (only) the names of the files that do not contain strings consisting of a single word\. Short form:
+.
+.IP
+\fBglark \-L \'"\ew+"\'\fR
+.
+.TP
+\fBglark \-\-text\-color "red on white" \'\eb[[:digit:]]{5}\eb\' *\.c\fR
+Display (in red text on a white background) occurrences of exactly 5 digits\.
+.
+.IP
+See the HIGHLIGHTING section for valid colors and modifiers\.
+.
+.SS "COMPLEX EXPRESSIONS"
+.
+.TP
+\fBglark \-\-or format print *\.h"\fR
+Searches for either "printf" or "format"\. Short form:
+.
+.IP
+\fBglark \-o format print *\.h\fR
+.
+.TP
+\fBglark \-\-and 4 printf format *\.c *\.h\fR
+Searches for both "printf" or "format" within 4 lines of each other\. Short form:
+.
+.IP
+\fBglark \-a 4 printf format *\.c *\.h\fR
+.
+.TP
+\fBglark \-\-context=3 \-\-and 0 printf format *\.c"\fR
+Searches for both "printf" or "format" on the same line ("within 0 lines of each other")\. Three lines of context are displayed around any matches\. Short form:
+.
+.IP
+\fBglark \-3 \-a 0 printf format *\.c\fR
+.
+.TP
+\fBglark \-8 \-i \-a 15 \-a 2 pthx \'\e\.\e\.\e\.\' \-o \'va_\ew+t\' die *\.c\fR
+In order of the options: produces 8 lines of context around case insensitive matches of ("phtx" within 2 lines of \'\.\.\.\' (literal)) within 15 lines of (either "va_\ew+t" or "die")\.
+.
+.TP
+\fBglark \-\-and \-1 \'#define\es+YIELD\' \'#define\es+dTHR\' *\.h\fR
+Looks for "#define\es+YIELD" within the same file (\-1 == "infinite distance") of "#define\es+dTHR"\. Short form:
+.
+.IP
+\fBglark \-a \-1 \'#define\es+YIELD\' \'#define\es+dTHR\' *\.h\fR
+.
+.SS "RANGE LIMITING"
+.
+.TP
+\fBglark \-\-before 50% cout *\.cpp\fR
+Find references to "cout", within the first half of the file\. Short form:
+.
+.IP
+\fBglark \-b 50% cout *\.cpp\fR
+.
+.TP
+\fBglark \-\-after 20 cout *\.cpp\fR
+Find references to "cout", starting at the 20th line in the file\. Short form:
+.
+.IP
+\fBglark \-b 50% cout *\.cpp\fR
+.
+.TP
+\fBglark \-\-range 20,50% cout *\.cpp\fR
+Find references to "cout", in the first half of the file, after the 20th line\. Short form:
+.
+.IP
+\fBglark \-R 20,50% cout *\.cpp\fR
+.
+.SS "FILE PROCESSING"
+.
+.TP
+\fBglark \-r print \.\fR
+Search for "print" in all files at and below the current directory\. Equivalently, this can be:
+.
+.IP
+\fBglark print \.\.\.\fR
+.
+.TP
+\fBglark \-\-match\-path=\'/\e\.java$/\' \-r println org\fR
+Search for "println" in all Java files at and below the "org" directory\.
+.
+.TP
+\fBglark \-\-match\-name=\'!/CVS/\' \-r \'\eb\ed\ed:\ed\ed:\ed\ed\eb\' \.\fR
+Search for a time pattern in all files without "CVS" in their basenames\.
+.
+.TP
+\fBglark \-\-size\-limit=1024 \-r main \-r \.\fR
+Search for "main" in files no larger than 1024 bytes\.
+.
+.TP
+\fBglark Regexp /usr/lib/ruby/1\.9\.1/\.\.\.\fR
+Search for "Regexp" in all files \fIin\fR and \fIunder\fR /usr/lib/ruby/1\.9\.1, with no depth limit\.
+.
+.TP
+\fBglark Regexp /usr/lib/ruby/1\.9\.1/\.\.\.0\fR
+Search for "Regexp" in all files \fIin\fR /usr/lib/ruby/1\.9\.1\. This is equivalent to:
+.
+.IP
+\fBglark Regexp /usr/lib/ruby/1\.9\.1\fR
+.
+.TP
+\fBglark Regexp /usr/lib/ruby/1\.9\.1/\.\.\.2\fR
+Search for "Regexp" in all files \fIin\fR /usr/lib/ruby/1\.9\.1 and two levels of subdirectories underneath\.
+.
+.TP
+\fBglark \-\-match\-name \'http\.*\' Regexp /usr/lib/ruby/1\.9\.1/\.\.\.\fR
+Search for "Regexp" in all files \fIunder\fR /usr/lib/ruby/1\.9\.1 with a name starting with \'http\'\.
+.
+.TP
+\fBglark connect \-\fR
+Search standard input for "connect"\.
+.
+.TP
+\fBfor i in *\.jar; do jar tf $i | glark \-\-label=$i Exception; done\fR
+Search the files for \'Exception\', displaying the jar file name instead of the standard input marker (\'\-\')\. An equivalent is:
+.
+.IP
+\fBglark \-\-binary\-files=list Exception *\.jar\fR
+.
+.SS "ADVANCED USAGE"
+.
+.TP
+\fBglark \-\-explain \-\-match\-name \'c\.*\e\.rb$\' \-\-and=5 Regexp \-\-xor parse \-\-and=3 boundary quote /usr/lib/ruby/1\.9\.1/\.\.\.2\fR:
+.
+.IP
+As shown by the \fB\-\-explain\fR options:
+.
+.IP "" 4
+.
+.nf
+
+within 5 lines of each other:
+    /Regexp/
+and
+    only one of:
+        /parse/
+    xor
+        within 3 lines of each other:
+            /boundary/
+        and
+            /quote/
+.
+.fi
+.
+.IP "" 0
+.
+.IP
+Search for the given expression under the Ruby 1\.9\.1 tree, for \.rb files starting with \'c\'\.
+.
+.SH "ENVIRONMENT"
+.
+.TP
+\fBGLARKOPTS\fR
+A string of whitespace\-delimited options\. Because of parsing constraints, should probably not contain complex regular expressions\.
+.
+.TP
+\fB$HOME/\.glarkrc\fR
+A resource file, containing name/value pairs, separated by either \':\' or \'=\'\. The valid fields of a \.glarkrc file are as follows, with example values:
+.
+.IP "" 4
+.
+.nf
+
+after\-context:      1
+before\-context:     6
+context:            5
+file\-color:         blue on yellow
+grep:               true
+highlight:          off
+ignore\-case:        false
+line\-number\-color:  red
+local\-config\-files: true
+quiet:              yes
+text\-color\-0:       f2331a on 2a3f44
+text\-color\-1:       bold underline red on 88a72d
+text\-color\-2:       a85387 on e4d3d2
+verbose:            false
+.
+.fi
+.
+.IP "" 0
+.
+.IP
+"yes" and "on" are synonymnous with "true"\. "no" and "off" signify "false"\.
+.
+.IP
+My ~/\.glarkrc file contains:
+.
+.IP "" 4
+.
+.nf
+
+context: 3
+quiet: true
+local\-config\-files: true
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+\fB/path/\.\.\./\.glarkrc\fR
+See the \fBlocal\-config\-files\fR field below\.
+.
+.SS "FIELDS"
+.
+.TP
+\fBafter\-context\fR
+See the \fB\-\-after\-context\fR option\. For example, for 3 lines of context after the match:
+.
+.IP "" 4
+.
+.nf
+
+after\-context: 3
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+\fBbasename\fR
+See the \fB\-\-basename\fR option\. For example, to omit Subversion directories:
+.
+.IP "" 4
+.
+.nf
+
+basename: !/\e\.svn/
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+\fBbefore\-context\fR
+See the \fB\-\-before\-context\fR option\. For example, for 7 lines of context before the match:
+.
+.IP "" 4
+.
+.nf
+
+before\-context: 7
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+\fBbinary\-files\fR
+See the \fB\-\-binary\-files\fR option\. For example, to always search binary files, instead of the default behavior of skipping them:
+.
+.IP "" 4
+.
+.nf
+
+binary\-files: binary
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+\fBcontext\fR
+See the \fB\-\-context\fR option\. For example, for 2 lines before and after matches:
+.
+.IP "" 4
+.
+.nf
+
+context: 2
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+\fBexpression\fR
+See the \fBEXPRESSION\fR section\. Example:
+.
+.IP "" 4
+.
+.nf
+
+expression: \-\-or \'^\es*public\es+class\es+\ew+\' \'^\es*\ew+\e(
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+\fBfile\-color\fR
+See the \fB\-\-file\-color\fR option\. For example, for white on black:
+.
+.IP "" 4
+.
+.nf
+
+file\-color: white on black
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+\fBgrep\fR
+See the \fB\-\-grep\fR option\. For example, to always run in grep mode:
+.
+.IP "" 4
+.
+.nf
+
+grep: true
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+\fBhighlight\fR
+See the \fB\-\-highlight\fR option\. To turn off highlighting:
+.
+.IP "" 4
+.
+.nf
+
+highlight: false
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+\fBignore\-case\fR
+See the \fB\-\-ignore\-case\fR option\. To make matching case\-insensitive:
+.
+.IP "" 4
+.
+.nf
+
+ignore\-case: true
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+\fBknown\-nontext\-files\fR
+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:
+.
+.IP "" 4
+.
+.nf
+
+known\-nontext\-files: class exe dll com
+.
+.fi
+.
+.IP "" 0
+.
+.IP
+See the \fBExclusion of Non\-Text Files\fR section in \fBNOTES\fR for the default settings\.
+.
+.TP
+\fBknown\-text\-files\fR
+The extensions of files that should be considered to always be text\. See above for more\. Example:
+.
+.IP "" 4
+.
+.nf
+
+known\-text\-files: ini bat xsl xml
+.
+.fi
+.
+.IP "" 0
+.
+.IP
+See the \fBExclusion of Non\-Text Files\fR section in \fBNOTES\fR for the default settings\.
+.
+.TP
+\fBlocal\-config\-files\fR
+By default, glark uses only the configuration file ~/\.glarkrc\. Enabling this makes glark search upward from the current directory for the first \.glarkrc file\.
+.
+.IP
+This can be used, for example, in a Java project, where \.class files are binary, versus a PHP project, where \.class files are text:
+.
+.IP "" 4
+.
+.nf
+
+~/\.glarkrc
+
+    local\-config\-files: true
+
+/projects/javaproj/\.glarkrc
+
+    known\-nontext\-files: class
+
+/projects/phpproj/\.glarkrc
+
+    known\-text\-files: class
+.
+.fi
+.
+.IP "" 0
+.
+.IP
+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 up searches\.
+.
+.IP
+The configuration file ~/\.glarkrc is read first, so the definitions in the local configuration file will override those settings\.
+.
+.TP
+\fBmatch\-name\fR, \fBskip\-name\fR, \fBmatch\-path\fR, \fBskip\-path\fR, \fBmatch\-ext\fR, \fBskip\-ext\fR, \fBmatch\-dirname\fR, \fBskip\-dirname\fR, \fBmatch\-dirpath\fR, \fBskip\-dirpath\fR
+See the equivalent options\. For example, to omit files under CVS directories:
+.
+.IP "" 4
+.
+.nf
+
+skip\-dirname: CVS
+.
+.fi
+.
+.IP "" 0
+.
+.IP
+These fields can be specified multiple times\.
+.
+.TP
+\fBquiet\fR
+See the \fB\-\-quiet\fR option\.
+.
+.TP
+\fBtext\-color\fR
+See the \fB\-\-text\-color\fR option\. All matching regexps will be highlighted with the given color\. Example:
+.
+.IP "" 4
+.
+.nf
+
+text\-color: bold blue on white
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+\fBtext\-color\-NUM\fR
+Sets the color with which the NUMth regexp will be highlighted, for matching with multiple regular expressions, such as with the \fB\-\-or\fR or \fB\-\-file\fR option\. Example:
+.
+.IP "" 4
+.
+.nf
+
+text\-color\-2: white on green
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+\fBverbose\fR
+See the \fB\-\-verbose\fR option\. Example:
+.
+.IP "" 4
+.
+.nf
+
+verbose: true
+.
+.fi
+.
+.IP "" 0
+
+.
+.SH "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\. This test is skipped for files with suffixes associated with text files:
+.
+.IP "" 4
+.
+.nf
+
+c
+cpp
+css
+f
+for
+fpp
+h
+hpp
+html
+java
+mk
+php
+pl
+pm
+rb
+rbw
+txt
+.
+.fi
+.
+.IP "" 0
+.
+.P
+This test is also skipped for files with suffixes associated with non\-text (binary) files:
+.
+.IP "" 4
+.
+.nf
+
+Z
+a
+bz2
+elc
+gif
+gz
+jar
+jpeg
+jpg
+o
+obj
+pdf
+png
+ps
+tar
+zip
+.
+.fi
+.
+.IP "" 0
+.
+.P
+See the \fBknown\-text\-files\fR and \fBknown\-nontext\-files\fR fields for denoting file name suffixes to associate as text or nontext\.
+.
+.SH "EXCLUSION OF DIRECTORIES"
+The \.svn and \.git directories are always excluded from recursive searching of a file hierarchy\.
+.
+.SH "EXIT STATUS"
+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\.
+.
+.SH "SEE ALSO"
+For regular expressions, the \fBperlre\fR man page\.
+.
+.P
+Mastering Regular Expressions, by Jeffrey Friedl, published by O\'Reilly\.
+.
+.SH "CAVEATS"
+"Unbalanced" leading and trailing slashes will result in those slashes being included as characters in the regular expression\. Thus, the following pairs are equivalent:
+.
+.IP "" 4
+.
+.nf
+
+/foo        "/foo"
+/foo\e/      "/foo/"
+/foo\e/i     "/foo/i"
+foo/        "foo/"
+foo/        "foo/"
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The code to detect nontext files assumes ASCII, not Unicode\.
+.
+.SH "AUTHOR"
+Jeff Pace (jeugenepace at gmail dot com)
+.
+.P
+http://www\.incava\.org/projects/glark
+.
+.P
+http://www\.github\.com/jeugenepace/glark
+.
+.SH "COPYRIGHT"
+Copyright (c) 2006, Jeff Pace\.
+.
+.P
+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\.