<type>documentation</type>
<domain>edit</domain>
<id>search-replace-tool</id>
<title>Search in Files Tool</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

The `Search in Files <script:show_panel#panel_type="batch-search">`__ tool in the
``Tools`` menu searches within sets of files and displays a list of all matches
found. 

The files to search are selected with ``Look in`` and ``Filter``. ``Look in`` specifies
the set of files to search, which may be the current editor, a single selected file, all
open files, all project files, a named `File Set <ref:edit/file-sets>`__, a selected
directory on disk, or all of Wing's documentation. ``Filter`` can be used to select a
subset of the files specified by ``Look in``, using a `File Filter
<ref:custom/file-filters>`__ or by typing a wild card expression containing ``*`` 
and/or ``?``. For example, ``Look in`` set to ``Project Files`` and
``Filter`` set to ``Python Files`` will restrict searching to only Python files that
appear in the `Project <script:show-panel-project>`__ tool.  ``Look in`` set to
``*.mako`` would search only file sending in ``.mako``.  If the ``Filter`` is
neither a valid ``File Filter`` name nor a valid wild card expression then all
the files selected by ``Look in`` are searched.

Searches may be initiated using ``Search in Files`` in the ``Search and Replace`` sub-menu
of the ``Edit`` menu. The ``Replace`` field will be hidden unless ``Replace in Files`` was
used. It can also be shown from the ``Options`` menu at the top right of the tool.

The popups to the right of the ``Search`` and ``Replace`` fields contain a history of
previously used strings. Right-click on the fields to insert special characters.

Once a search is started, matches can be selected from the result list and shown in the
editor or documentation viewer, even before the entire search completes. The result list
is updated automatically as files are edited, added, or removed, in order to include any
new matches or remove any old ones.

When a match is visited in the editor, Wing highlights it briefly with a callout, as 
configured from the ``Editor > Callouts`` preferences group.

Search Type
-----------

The type of search is selected from the ``Options`` menu in the top right of the tool:

**Text Search** chooses plain text search, without wildcard or regex matching.

**Wildcard Search** uses wildcard style searching.  See `Wildcard Search 
Syntax <ref:edit/search-wildcard>`__ for details.

**Regex Search** uses regular expression style searching. See Python's `Regular Expression
Syntax <https://docs.python.org/library/re.html#regular-expression-syntax>`__
documentation for details. When ``Regex Search`` is selected, a popup menu ``Regex
Flags`` appears to the left of the ``Options`` menu.  These are the same flags passed
to Python's ``re.compile()``.  For regex searching, the replace string can
reference regex match groups with ``\1``, ``\2``, etc, as in the Python ``re.sub()`` call.

**Case Sensitive** shows only exact matches of upper and lower case letters in the
search string.

**Whole Words** requires that matches are surrounded by white space (spaces, tabs, or
line ends) or punctuation other than ``_`` (underscores).

Options
-------

The following additional options are available from the ``Options`` menu:

**Show Replace** controls whether the ``Replace`` field is visible in the tool.

**Show Search Type in Tool** moves the selection of search type out of the
``Options`` menu and to the surface of the tool.

**Find After Replace** automatically finds the next search match after each replace
operation.

**Replace Operates On Disk** replaces text in un-opened files directly on disk rather than
in an editor.  This should be used with caution since changes cannot be undone except
by reverting using a 
~~~if WINGPRO:
`version control <ref:versioncontrol/index>`__ system
~~~
~~~if not WINGPRO:
version control system
~~~
or restoring from a backup.

**Recursive Directory Search** also searches all sub-directories when searching a
directory on disk.

**Omit Binary Files** omits any file that appears to contain binary data.

**Auto-restart Searches** restarts searching immediately if it is interrupted because a
search option or the set of files being searched has changed.

**Open First Match** automatically opens the first batch search match found when searching
starts.

**Show Line Numbers** includes line numbers in the result area.

**Result File Name** selects the format of the file names shown in the batch result area.

**Copy Result to Clipboard** places a copy of all the search results on the clipboard.

**Name Result File Set** creates a `File Set <ref:edit/file-sets>`__ containing
all the files listed in the current result list.

Special Characters
------------------

The right-click context menu on the ``Search`` and ``Replace`` fields provide some options
for search and replace strings to include special characters:

**Insert Newline** inserts new line (``\r\n`` on Windows and ``\n`` on other OSes)

**Insert Line Feed** inserts a line feed character (``\n``)

**Insert Carriage Return** inserts a carriage return character (``\r``)

**Insert Tab** inserts a tab character (``\t``)

**Interpret Backslash Characters** toggles whether special characters like ``\n``, ``\r``,
``\t`` and others are interpreted as a backslash followed by a letter or as the character
that they represent (line feed, carriage return, tab, etc).  The supported characters are
all those that Python supports in its representation of strings.

