16.2 Performing searches

You can use the Search Files tool in two different ways.

You can enter details of where to search and what to search for directly into the tool and click the button. This is described in more detail in 16.2.1 Entering Search Specifications directly.
You can use an Editor command or menu command that starts a context-dependent search. This is described in more detail in 16.2.2 Using context-dependent searches.

All kinds of search other than Grep use a LispWorks regular expression (regexp). For details of the syntax of LispWorks regular expressions see "Regular expression searching" in the Editor User Guide.

All kinds of search other than Grep actually operate on editor buffers (see 12.3 Displaying and swapping between buffers) rather than files. The Search Files tool creates buffers when needed, which involves some overhead. Therefore if you are searching a large number of files (or a number of large files) which are not already opened in the Editor, a Grep search is best because it operates directly on the files.

While the tool is searching, you can examine the results but you cannot change the search specifications. To stop a search, click the button in the toolbar.

16.2.1 Entering Search Specifications directly

To enter the search specifications directly, decide which kind of search to perform from the dropdown list in the toolbar and then fill in the boxes in the Search Specifications area. The different search kinds are described below. You can also hide the search specifications by choosing Hide Search Area from the dropdown list in the toolbar.

16.2.1.1 Plain Directory searches

A Plain Directory search is used to search for a particular regexp in all files whose names match a particular pattern. Enter the regexp in the Regexp Search String box and enter a set of filename patterns in the Filenames pattern box. You can press Up or Down in the Filenames pattern box to complete physical directory components, as described in 3.14 Completion.

The filename pattern should be a complete filename and can use the following syntax to make it match more than one file:

Use * within the pattern to match any sequence of characters in a directory or file name.
Use ** within the directory part of the pattern to match any number of subdirectories.

Here are some examples of filename patterns:

`.`	Matches all files in the root directory.
`subdir/*.txt`	Matches all `txt` files in `root/subdir`.
`examples/*/.lisp`	Matches all `lisp` files in `root/examples` and its subdirectories. This is similar to the pattern shown in The Search Files tool.
`*/zork/.bmp`	Matches all `bmp` files in any directory under the root directory that contains `zork` in its name.

See also the Match flat file-namestring option in 16.5.1 Search Parameters for additional information.

If a filename pattern is a directory then all files in that directory are searched.

Check Case sensitive to make the search match only the case of letters exactly as entered.

Check All files to ignore any list of File Types in the Preferences.

16.2.1.2 Root and Patterns searches

A Root and Patterns search is used to search for a particular regexp in all files whose names match one or more patterns within a directory. Enter the regexp in the Regexp Search String box, the starting directory in the Root Directory box, and a set of filename patterns in the Pattern List box.

You can press Up or Down in the Root Directory box to complete physical directory components, as described in 3.14 Completion.

A Roots and Patterns search

You can search subdirectories by including directory components (including wild components) in the Pattern List box.

Multiple filename patterns can be entered, separated by semicolons. Spaces before and after each pattern are ignored. Each filename pattern should be a complete filename and can use the following syntax to make it match multiple files:

Use * within the pattern to match any sequence of characters in a directory or file name.
Use ** within the directory part of the pattern to match any number of subdirectories.
Use {name1,name2,...} to match any one of name1, name2 and so on. Spaces before and after each name are ignored.

Here are some examples of pattern lists:

images/*.*  ; icons/*.*

{images,icons}/*.*

Both of these patterns match all files in the root/images and the root/icons directories.

**/{images,icons}/sunrise.{bmp,jpg,jpeg}

**/images/sunrise.{bmp,jpg,jpeg} ; **/icons/sunrise.{bmp,jpg,jpeg}

Both of these patterns match all files with the name sunrise.bmp, sunrise.jpg or sunrise.jpeg in a directory named icons or images, anywhere in the root directory.

{maj,min}or-events/{*-name,date}/*.txt

major-events/{*-name,date}/.txt ; minor-events/{*-name,date}/.txt

{maj,min}or-events/date/*.txt ; {maj,min}or-events/*-name/*.txt

Each of these three patterns matches all .txt files which are in a directory date or a directory that ends with -name in the major-events or minor-events directories.

See also the Match flat file-namestring option in 16.5.1 Search Parameters for additional information.

If a filename pattern is a directory then all files in that directory are searched.

Check Case sensitive to make the search match only the case of letters exactly as entered, as illustrated above.

Check All files to ignore any list of File Types in the Preferences.

16.2.1.3 System Search

A System Search is used to search for a particular regexp in all the files referenced by a LispWorks defsystem definition. Enter the regexp in the Regexp Search String box and the system names in the System Names box. Multiple system names can be entered, separated by semicolons.

Check Case sensitive to make the search match only the case of letters exactly as entered.

You can also do a System Search in a "system" defined by another source code manager such as ASDF, if you have configured LispWorks appropriately. See 26.9 ASDF Integration for the details.

16.2.1.4 Known Definitions searches

You can use the Search Files tool to search in all files known to contain definitions. To do this, select Known Definitions in the dropdown list in the toolbar. Then complete your other search specifications and click the button.

A Known Definitions search

A file is known to contain definitions in one of two ways:

A file was loaded and executed a defining form which was recorded by the source location system. The associated source files are searched when the list value of the variable dspec:*active-finders* contains the keyword :internal.
The file is recorded as a location in a tags database. Such files are searched when the list value of the variable dspec:*active-finders* contains the path of the tags database.

See "Dspecs: Tools for Handling Definitions" in the LispWorks® User Guide and Reference Manual for more information about definition recording and tags databases.

16.2.1.5 Searching editor buffers

You can use the Search Files tool to search in all currently open editor buffers. To do this, select Opened Buffers in the dropdown list in the toolbar. Then complete your other search specifications and click the button.

16.2.1.6 Grep searches

A Grep search is used to run an external program to search files and show the results in the tool. Enter the working directory for the external program in the Root Directory box and the complete command line of the external program in the Grep Command box.

A Grep search

The external program is typically grep, but other programs can be used as long as they print the matched lines in this format:

filename:line-number line-text

When using grep you generally need to pass the -n option and the filename argument /dev/null to force it to print the file and line number in all cases. This is done automatically when you invoke the Search Files tool by the Editor command Grep.

16.2.2 Using context-dependent searches

Context dependent searches take some information from the current window and invoke the Search Files tool to perform the search. There are various Editor commands and menu commands that start a context-dependent search, as described below.

16.2.2.1 Context-dependent searches using Editor commands

Search Files	Prompts for a search string and directory pattern and then performs a Plain Directory or Root and Patterns search. If an existing Search Files tool is reused by this command and was last doing a Root and Patterns search, then the directory pattern is split to fill the boxes. Otherwise, a Plain Directory search is performed using the directory pattern. If the directory pattern ends in a slash, then the default pattern is added to the end (see 16.5.1 Search Parameters).
Search Files Matching Patterns
	Prompts for a search string, root directory and set of filename patterns and then performs a Root and Patterns search.
Search System	Prompts for a search string and system name and then performs a System Search.
Grep	Prompts for command line arguments to pass to grep and then performs a Grep search. The grep command is created from these arguments, with a `-n` option and the filename argument `/dev/null` as mentioned in 16.2.1.6 Grep searches.

16.2.2.2 Context-dependent searches using menu commands

Edit > Search Files...
	Opens a Search Files tool in for a Plain Directory or Root and Patterns search, using the directory associated with the current tool (in particular, the directory of the buffer displayed in an Editor tool). If an existing Search Files tool is reused by this command and was last doing a Root and Patterns search, then the directory is placed in the Root Directory box. Otherwise, the directory is placed in the Filename Patterns box for a Plain Directory search with the default pattern added to the end (see 16.5.1 Search Parameters).
Systems > Search Files...
	Prompts for a regexp and performs a System Search in the currently selected system.

16.2.2.3 Search History

The Search Files tool keeps a history of previous searches and their results. You can revisit these searches using the and buttons as described in 3.5 The history list.