search.pl

UNIX下perl实现代码

.TP
.BI -dpath " GLOB"
This option exists, but is probably not very useful. It probably wants to
be like the '-below' or something I mention in the "TODO" section.
.TP
.BI -idpath " GLOB"
Case-insensitive version of
.BR -dpath .
.TP
.BI -idskip " GLOB"
Case-insensitive version of
.BR -dskip .
.TP
.BI -idregex " REGEX"
Case-insensitive version of
.BR -dregex .
.TP
.B -all
Ignore any 'magic' or 'option' lines in the startup file.
The effect is that all files that would otherwise be automatically
excluded are considered.
.TP
.BI -x SPECIAL
Arguments starting with
.B -x
(except
.BR -xdev ,
explained elsewhere) do special interaction with the
.I ~/.search
startup file. Something like
.nf
	-xflag1 -xflag2
.fi
will turn on "flag1" and "flag2" in the startup file (and is
the same as "-xflag1,flag2"). You can use this to write your own
rules for what kinds of files are to be considered.

For example, the internal-default startup file contains the line
.nf
	<!~> option: -skip '~ #'
.fi
This means that if the
.B -x~
flag is
.I not
seen, the option
.nf
    -skip '~ #'
.fi
should be done.
The effect is that emacs temp and backup files are not normally
considered, but you can included them with the -x~ flag.

You can write your own rules to customize
.I search
in powerful ways. See the STARTUP FILE section below.
.TP
.B -why
Print a message (to stderr) when and why a file is not considered.

.SH "OPTIONS TELLING WHAT TO DO WITH FILES THAT WILL BE CONSIDERED"
.TP
.B -find
(you can use
.B -f
as well).
This option changes the basic action of
.IR search .

Normally, if a file is considered, it is searched
for the regular expressions as described earlier. However, if this option
is given, the filename is printed and no searching takes place. This turns
.I search
into a 'find' of some sorts.

In this case, no regular expressions are needed on the command line
(any that are there are silently ignored).

This is not intended to be a replacement for the 'find' program,
but to aid
you in understanding just what files are getting past the exclusion checks.
If you really want to use it as a sort of replacement for the 'find' program,
you might want to use
.B -all
so that it doesn't waste time checking to see if the file is binary, etc
(unless you really want that, of course).

If you use
.BR -find ,
none of the "GREP-LIKE OPTIONS" (below) matter.

As a replacement for 'find',
.I search
is probably a bit slower (or in the case of GNU find, a lot slower --
GNU find is
.I unbelievably
fast).
However, "search -ffind"
might be more useful than 'find' when options such as
.B -skip
are used (at least until 'find' gets such functionality).
.TP
.B -ffind
(or
.BR -ff )
A faster more 'find'-like find. Does
.nf
    -find  -all -dorep
.fi
.SH "GREP-LIKE OPTIONS"
These options control how a searched file is accessed,
and how things are printed.
.TP
.B -i
Ignore letter case when matching.
.TP
.B -w
Consider only whole-word matches ("whole word" as defined by perl's "\\b"
regex).
.TP
.B -u
If the regex(es) is/are simple, try to modify them so that they'll work
in manpage-like underlined text (i.e. like _^Ht_^Hh_^Hi_^Hs).
This is very rudimentary at the moment.
.TP
.B -list
(you can use
.B -l
too).
Don't print matching lines, but the names of files that contain matching
lines. This will likely be *much* faster, as special optimizations are
made -- particularly with large files.
.TP
.B -n
Pepfix each line by its line number.
.TP
.B -nice
Not a grep-like option, but similar to
.BR -list ,
so included here.
.B -nice
will have the output be a bit more human-readable, with matching lines printed
slightly indented after the filename, a'la
.nf

   % search foo
   somedir/somefile: line with foo in it
   somedir/somefile: some food for thought
   anotherdir/x: don't be a buffoon!
   %

.fi
will become
.nf

   % search -nice foo
   somedir/somefile:
     line with foo in it
     some food for thought
   anotherdir/x:
     don't be a buffoon!
   %

.fi
This option due to Lionel Cons.
.TP
.B -nnice
Be a bit nicer than
.BR -nice .
Prefix each file's output by a rule line, and follow with an extra blank line.
.TP
.B -h
Don't prepend each output line with the name of the file
(meaningless when
.B -find
or
.B -l
are given).

.SH "OTHER OPTIONS"
.TP
.B -help
Print the usage information.
.TP
.B -version
Print the version information and quit.
.TP
.B -v
Set the level of message verbosity.
.B -v
will print a note whenever a new directory is entered.
.B -vv
will also print a note "every so often". This can be useful to see
what's happening when searching huge directories.
.B -vvv
will print a new with every file.
.B -vvvv
is
-vvv
plus
.BR -why .
.TP
.B -e
This ends the options, and can be useful if the regex begins with '-'.
.TP
.B -showrc
Shows what is being considered in the startup file, then exits.
.TP
.B -dorep
Normally, an identical file won't be checked twice (even with multiple
hard or symbolic links). If you're just trying to do a fast
.BR -find ,
the bookkeeping to remember which files have been seen is not desirable,
so you can eliminate the bookkeeping with this flag.

.SH "STARTUP FILE"
When
.I search
starts up, it processes the directives in
.IR ~/.search .
If no such file exists, a default
internal version is used.

The internal version looks like:
.nf

   magic: 32 : $H =~ m/[\ex00-\ex06\ex10-\ex1a\ex1c-\ex1f\ex80\exff]{2}/
   option: -skip '.a .COM .elc .EXE .gz .o .pbm .xbm .dvi'
   option: -iskip '.tarz .zip .z .lzh .jpg .jpeg .gif .uu'
   <!~> option: -skip '~ #'

.fi
If you wish to create your own "~/.search",
you might consider copying the above, and then working from there.

There are two kinds of directives in a startup file: "magic" and "option".
.RS 0n
.TP
OPTION
Option lines will automatically do the command-line options given.
For example, the line
.nf
	option: -v
.fi
in you startup file will turn on -v every time, without needing to type it
on the command line.

The text on the line after the "option:" directive is processed
like the Bourne shell, so make sure to pay attention to quoting.
.nf
	option: -skip .exe .com
.fi
will give an error (".com" by itself isn't a valid option), while
.nf
	option: -skip ".exe .com"
.fi
will properly include it as part of -skip's argument.

.TP
MAGIC
Magic lines are used to determine if a file should be considered a binary
or not (the term "magic" refers to checking a file's magic number).  These
are described in more detail below.
.RE

Blank lines and comments (lines beginning with '#') are allowed.

If a line begins with  <...>, then it's a check to see if the
directive on the line should be done or not. The stuff inside the <...>
can contain perl's && (and), || (or), ! (not), and parens for grouping,
along with "flags" that might be indicated by the user with
.BI -x flag
options.

For example, using "-xfoo" will cause "foo" to be true inside the <...>
blocks. Therefore, a line beginning with "<foo>" would be done only when
"-xfoo" had been specified, while a line beginning with "<!foo>" would be
done only when "-xfoo" is not specified (of course, a line without any <...>
is done in either case).

A realistic example might be
.nf
	<!v> -vv
.fi
This will cause -vv messages to be the default, but allow "-xv" to override.

There are a few flags that are set automatically:
.RS
.TP
.B TTY
true if the output is to the screen (as opposed to being redirected to a file).
You can force this (as with all the other automatic flags) with -xTTY.
.TP
.B -v
True if -v was specified. If -vv was specified, both 
.B -v
and
.B -vv
flags are true (and so on).
.TP
.B -nice
True if -nice was specified. Same thing about -nnice as for -vv.
.PP
.TP
.B -list
true if -list (or -l) was given.
.TP
.B -dir
true if -dir was given.
.RE

Using this info, you might change the last example to
.nf

    <!v && !-v> option: -vv

.fi
The added "&& !-v" means "and if the '-v' option not given".
This will allow you to use "-v" alone on the command line, and not
have this directive add the more verbose "-vv" automatically.

.RS 0
Some other examples:
.TP
<!-dir && !here> option: -dir ~/
Effectively make the default directory your home directory (instead of the
current directory). Using -dir or -xhere will undo this.
.TP
<tex> option: -name .tex -dir ~/pub
Create '-xtex' to search only "*.tex" files in your ~/pub directory tree.
Actually, this could be made a bit better. If you combine '-xtex' and '-dir'
on the command line, this directive will add ~/pub to the list, when you
probably want to use the -dir directory only. You could do
.nf

   <tex> option: -name .tex
   <tex && !-dir> option: -dir ~/pub
.fi

to will allow '-xtex' to work as before, but allow a command-line "-dir"
to take precedence with respect to ~/pub.
.TP
<fluff> option: -nnice -sort -i -vvv
Combine a few user-friendly options into one '-xfluff' option.
.TP
<man> option: -ddir /usr/man -v -w
When the '-xman' option is given, search "/usr/man" for whole-words
(of whatever regex or regexes are given on the command line), with -v.
.RE

The lines in the startup file are executed from top to bottom, so something
like
.nf

   <both> option: -xflag1 -xflag2
   <flag1> option: ...whatever...
   <flag2> option: ...whatever...

.fi
will allow '-xboth' to be the same as '-xflag1 -xflag2' (or '-xflag1,flag2'
for that matter). However, if you put the "<both>" line below the others,
they will not be true when encountered, so the result would be different
(and probably undesired).

The "magic" directives are used to determine if a file looks to be binary
or not. The form of a magic line is
.nf
    magic: \fISIZE\fP : \fIPERLCODE\fP
.fi
where
.I SIZE
is the number of bytes of the file you need to check, and
.I PERLCODE
is the code to do the check. Within
.IR PERLCODE ,
the variable $H will hold at least the first
.I SIZE
bytes of the file (unless the file is shorter than that, of course).
It might hold more bytes. The perl should evaluate to true if the file
should be considered a binary.

An example might be
.nf
    magic: 6 : substr($H, 0, 6) eq 'GIF87a'
.fi
to test for a GIF ("-iskip .gif" is better, but this might be useful
if you have images in files without the ".gif" extension).

Since the startup file is checked from top to bottom, you can be a bit
efficient:
.nf
    magic: 6 : ($x6 = substr($H, 0, 6)) eq 'GIF87a'
    magic: 6 :  $x6                     eq 'GIF89a'
.fi
You could also write the same thing as
.nf
  magic: 6 : (($x6 = substr($H, 0, 6)) eq 'GIF87a') || ## an old gif, or.. \e
	       $x6                     eq 'GIF89a'     ## .. a new one.
.fi
since newlines may be escaped.

The default internal startup file includes
.nf
   magic: 32 : $H =~ m/[\ex00-\ex06\ex10-\ex1a\ex1c-\ex1f\ex80\exff]{2}/
.fi
which checks for certain non-printable characters, and catches a large
number of binary files, including most system's executables, linkable
objects, compressed, tarred, and otherwise folded, spindled, and mutilated
files.

Another example might be
.nf
    ## an archive library
    magic: 17 : substr($H, 0, 17) eq "!<arch>\en__.SYMDEF"
.fi

.SH "RETURN VALUE"
.I Search
returns zero if lines (or files, if appropriate) were found,
or if no work was requested (such as with
.BR -help ).
Returns 1 if no lines (or files) were found.
Returns 2 on error.

.SH TODO
Things I'd like to add some day:
.nf
  + show surrounding lines (context).
  + highlight matched portions of lines.
  + add '-and', which can go between regexes to override
    the default logical or of the regexes.
  + add something like
      -below GLOB
    which will examine a tree and only consider files that
    lie in a directory deeper than one named by the pattern.
  + add 'warning' and 'error' directives.
  + add 'help' directive.
.fi
.SH BUGS
If -xdev and multiple -dir arguments are given, any file in any of the
target filesystems are allowed. It would be better to allow each filesystem
for each separate tree.

Multiple -dir args might also cause some confusing effects. Doing
.nf
   -dir some/dir -dir other
.fi
will search "some/dir" completely, then search "other" completely. This
is good. However, something like
.nf
   -dir some/dir -dir some/dir/more/specific
.fi
will search "some/dir" completely *except for* "some/dir/more/specific",
after which it will return and be searched. Not really a bug, but just sort
of odd.

File times (for -newer, etc.) of symbolic links are for the file, not the
link. This could cause some misunderstandings.

Probably more. Please let me know.
.SH AUTHOR
Jeffrey Friedl, Omron Corp ([e-mail])
.br
http://www.wg.omron.co.jp/cgi-bin/j-e/jfriedl.html

.SH "LATEST SOURCE"
See http://www.wg.omron.co.jp/~jfriedl/perl/index.html