<type>documentation</type>
<domain>intro</domain>
<id>tutorial-search-tool</id>
<title>Tutorial: Search Tool</title>
<date>$Date$</date>
<product>all</product>

The `Search <script:show-panel-interactive-search>`__ tool provides simple search and
replace operations on the current editor or documentation page. Key bindings for
operations on this tool are given in the ``Search and Replace`` group in the ``Edit``
menu.

.. image:: search.png
  :width: 501
  :height: 118
  
Searches may span the whole file or be constrained to the current selection, can be case
sensitive or insensitive, and may optionally be constrained to matching only whole words.

By default, searching is incremental while you type your search string. To disable this,
uncheck ``Incremental`` in the ``Options`` menu.

**Replacing**

When the tool is displayed with ``Replace``, or when the ``Show Replace`` item in the
``Options`` menu is activated, Wing will show an area for entering a replace string and
add ``Replace`` and ``Replace All`` buttons to the Search tool:

.. image:: search-replace.png
  :width: 577
  :height: 136

Try replacing ``example1.py`` with search string ``PrintAs`` and replace string
``OutputAs``.

Select the first result match and then ``Replace`` repeatedly. One search match will be
replaced at a time. Search will occur again after each replace automatically unless you
turn off the ``Find After Replace`` option. Changes can be undone in the editor, one at a
time. Do this now to avoid saving this replace operation.

Next, try ``Replace All`` instead. Wing will simply replace all occurrences in the file at
the same time. When this is done, a single undo in the editor will cancel the entire
replace operation.

~~~if not WING101:
**Wildcard Searching**

By default, Wing searches for straight text matches on the strings you type. In Wing Pro
and Wing Personal, wildcard and regular expression searching are also available in the
``Search`` tool's ``Options`` menu.

Wildcard searching allows you to specify a search string that contains ``*`` to match
anything, ``?`` to match a single character, or ranges of characters specified within
``[`` and ``]`` to match any of the specified characters. This is the same syntax
supported by the Python ``glob`` module and is described in more detail in `Wildcard
Search Syntax <ref:edit/search-wildcard>`__.

Try a wildcard search now by selecting ``Wild Card`` from the ``Options`` menu while
``example1.py`` is your current editor. Set the search string to ``PrintAs*(``. This
should display all occurrences of the string ``PrintAs``, followed by zero or more
characters, followed by ``(``:

.. image:: search-wildcard.png
  :width: 579
  :height: 118

Also try searching on ``PrintAs*[A-Z](`` with the ``Case Sensitive`` search option turned
on. This matches all strings starting with ``PrintAs`` followed by zero or more
characters, followed by any capital letter from ``A`` to ``Z``, followed by ``(``.

Finally, try ``PrintAsT???``, which will match any string starting with ``PrintAsT``
followed by any three characters.

**Regular Expression Search**

Regular expressions are most useful for complex search tasks, such as finding all
calls to a particular function that occur as part of an assignment statement.

For example, ``open\(newscache( )?,.*\)`` matches only calls to the function ``open``
where the first argument is named ``newscache`` and there are at least two parameters. If
you try this with ``example1.py`` after selecting ``Regex search`` from the ``Options``
menu then you should get exactly one search match:

.. image:: search-regex.png
  :width: 782
  :height: 596

In this mode, the replace string can reference regex match groups with ``\1``, ``\2``,
etc, as in the Python ``re.sub()`` call.

The details of regular expression syntax and usage see `Regular Expression Syntax
<https://docs.python.org/library/re.html>`__ in the Python manual. 
~~~

See also `Search Tool <ref:edit/search-tool>`__ for more information.


