<type>documentation</type>
<domain>edit</domain>
<id>search-tool</id>
<title>Search Tool</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>all</product>

The `Search <script:show_panel#panel_type="interactive-search">`__ tool in
the ``Tools`` menu can be used to search and replace within the current editor. 

Searches may be initiated from the ``Search and Replace`` sub-menu of the ``Edit`` menu,
using ``Search``, ``Replace``, ``Search for Selection Forward``, and ``Search for
Selection Backward``. The ``Replace`` field will be hidden unless a replace operation was
started. 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.

To search only part of a file, select the desired range in the editor and check ``In
Selection``.

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:

**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.

For each of these, the checkboxes in the tool provide some additional options:

**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).

Search Options
--------------

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

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

**Wrap Search** allows wrapping when the search reaches the top or bottom of a file.

**Incremental** immediately starts or restarts searching as you type or alter 
search options.  When unchecked, use the ``Previous`` and ``Next`` search buttons to 
initiate searching.

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

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.

