LOCATE - search files for lines matching given patterns.

Syntax:

LOCATE [filename]* [Pattern=]"pattern" [option]*
Escape=c            +Filenames
Report={Lines|Any|Complete|Summary} (Lines)
-Match              +lineNumbers
+Respectcase        -Verbose
Normal=str <>@+     Special=str $^.*[{(|
indeX=file          Window=n[,n]

Examples:

locate p=job expl/comm
locate p=apl|ftn|fortran expl/inde expl/comm +ln
locate +Respectcase expl/fred/o w=6 p=OT
locate expl/mail/comm expl/mail/over p=memo w=1,2
locate "^a string|an ending string$" expl/news w=-8
     Find set of files that use a variable name
locate report=any index=filelist p=<variable> sp=<>
     Find files that don't reference a variable
locate r=complete -match index=filelist p=\o<variable\o>

Options:

Escape=c
specifies an escape character "c" to be used in patterns. For example, "e=%" says that you will use the "%" character as an escape character. The default is the backslash (\).
+Filenames
displays the name of the file in which the match occurred. This option is turned on by default if you specify more than one filename or if you use the indeX= option.
-Match
selects lines that do NOT match the given pattern.
+lineNumbers
outputs line numbers for the lines printed.
+Respectcase
differentiates between upper and lowercase. By default, if you search for a pattern like "abc", LOCATE matches it with "abc", "ABC", "Abc", etc.
Normal=string
specifies a string of characters whose special meanings should not be used in the given pattern. For example,
Normal="$."

turns off the special meanings of "$" and ".". Putting the letter "D" in "string" is equivalent to specifying +Respectcase.

Report=keyword
controls what output LOCATE produces. Possible values of "keyword" are:
Lines
displays the selected lines. This is the default.
Any
if +Filenames is in effect, displays just the names of files in which at least one line was selected. If -Filenames is in effect, Report=Any displays a summary of the number of files in which at least one line was selected.
Complete
if +Filenames is in effect, displays just the name of files in which every line was selected. If -Filenames is in effect, Report=Complete displays a summary of the number of files in which every line was selected.
Summary
displays a summary of the number of lines selected. With +Filenames, there's a summary for each file; with -Filenames, LOCATE only prints out a summary at the end, giving the total of lines selected from all files.
Special=string
specifies a string of characters whose special meanings should be used in the given pattern. For example,
Special="<>"

turns on the special meanings of "<" and ">".

-Verbose
stops the printing of any "Can't locate" messages.
[Pattern=]"pattern"
states what pattern you are searching for. Patterns are described below.
indeX=file
gives the name of an "index" file. This is a text file containing the names of other files, one per line. LOCATE scans all the files named in the index file for occurrences of the desired pattern.
Window=n
sets a window of plus and minus "n" lines if "n" is positive. It sets a backwards window of "n" lines if "n" is negative. For more information see the section on "Windows" below.
Window=n1,n2
sets a backwards window of "n1" and a forward window of "n2". The default window is "w=0,1". For more information see the section on "Windows" below.

Description:

LOCATE searches files for lines containing a given pattern. The default action is to display all lines where a match occurs.

All options of LOCATE can be placed in any location on the command line. Unquoted strings are used as file names; the files are searched in the order they are given on the command line.

If LOCATE does not find any matches for the pattern, it normally displays a "Can't locate" message on the terminal. The -Verbose option tells LOCATE not to display such a message; in this case, LOCATE simply doesn't display anything if it can't find a match.

LOCATE normally ignores case distinctions in comparisons. +Respectcase tells LOCATE to pay attention to these distinctions.

The -Match option reverses the usual operation of LOCATE. LOCATE only displays lines (or windows around lines) that do NOT match the given pattern.

Patterns:

The simplest pattern is just a string of normal characters.

locate "abc" file

displays all lines in "file" that contain the character sequence "abc". The sequence may appear anywhere in the line and the characters may be in either upper or lowercase.

Patterns can also contain special characters. The special characters that can be used with LOCATE are the same as the special characters recognized by the FRED text editor, with one exception: LOCATE does not recognize the "fence" pattern character (#). Below, we summarize the special pattern characters that LOCATE recognizes.

.          -- any single character (except new-line)
^          -- start of line
$          -- end of line
P*         -- zero or more of pattern P
P+         -- one or more of pattern P
P|Q        -- pattern P or Q
(P)        -- same as pattern P
[XYZ...]   -- any character inside brackets
[^XYZ...]  -- any character not inside brackets
{P}T       -- pattern P with tag T
<          -- beginning of word
>          -- end of word
@(N)       -- null string before column N
@(-N)      -- null string after Nth last column

Complete explanations of these are given in "expl fred pattern" and in the FRED Reference Manual.

By default, the special meanings of

$^.*[]{}|()

are turned on, while the special meanings of

<>@+

are turned off. Special characters can also be turned on with the Special= option and turned off with the Normal= option. Putting "\c" in front of a character turns off its special meaning, and putting "\o" in front of a character turns on its special meaning. For example,

locate "\c[" file

matches any line that contains an opening square bracket. Without the "\c", you would receive an error for an incorrectly formed pattern (every opening "[" requires a closing "]").

You can represent non-printable or "hard to type" characters as "\ddd" where "ddd" are octal digits giving the ASCII representation of the character you wish to locate. For example,

locate "\007" file

matches any line that contains the BELL character (octal 007).

In constructs like "\c" or "\007", the first character is called the "escape character". By default, LOCATE's escape character is "\". You can change this with the Escape= option.

Windows:

The Window= option lets you look at lines surrounding a line where a pattern was found. For example,

window=3,4

tells LOCATE to display seven lines for each match located: the three lines before the matching line, the matching line itself, and the three lines after. The option

window=N

is equivalent to

window=N,N

A negative value of N, as in

window=-M

is equivalent to

window=M,1

The default window is "window=0,1".

Notes:

If you use LOCATE inside a command file (EXEC, CRUN, or DRUN), LOCATE does not set a T.ERROR flag if it fails to locate any appropriate lines. It only issues a T.ERROR if the command line is invalid (e.g. a pattern is badly formed) or if it cannot find a particular file that has been named on the command line or in the indeX= file. Even if LOCATE fails to find a particular file, it scans all the other files that have been named.

If LOCATE does not find any lines that meet the request (i.e. no lines match, or you specified -Match and every line matched), LOCATE sets switch bit 26. If one or more lines match, LOCATE clears bit 26 if no other errors occur.

See Also:

expl fred pattern
for a more detailed explanation of patterns.

Copyright © 1996, Thinkage Ltd.