<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=US-ASCII">
<meta name="author" content="mailto:webmaster@zap.tartarus.org">
<meta name="description" content="Zap is a configurable programmers' editor for Acorn RISC OS">
<title>Searching</title>
</head>
<body background='/img/background.png' text="#000000" bgcolor="#DCDCDC" link="#20209F" vlink="#008000" alink="#FF2020">
<p align='center'><a href="Chapter7">Previous</a> | <a href="Contents">Contents</a> | <a href="IndexPage">Index</a> | <a href="Chapter9">Next</a></p>

<ul>
<li><a href="#C8">Chapter 8: Searching</a>
<ul>
<li><a href="#S8.1">8.1 Search options</a>
<ul>
<li><a href="#S8.1.1">8.1.1 Raw search</a></li>
<li><a href="#S8.1.2">8.1.2 Case sensitivity</a></li>
<li><a href="#S8.1.3">8.1.3 Macros</a></li>
<li><a href="#S8.1.4">8.1.4 To window searching</a></li>
</ul></li>
<li><a href="#S8.2">8.2 \-commands</a></li>
<li><a href="#S8.3">8.3 Replace</a>
<ul>
<li><a href="#S8.3.1">8.3.1 Global replace</a></li>
<li><a href="#S8.3.2">8.3.2 The replace expression</a></li>
</ul></li>
<li><a href="#S8.4">8.4 Incremental search</a></li>
</ul></li>
</ul>
<h1><a name="C8"></a>Chapter 8: Searching</h1>
<p>
Zap's <a name="i0"></a>search system is quite powerful, and is based loosely on <em>UNIX</em> regular expression searching (as used, for instance, in <a name="i1"></a><em>Emacs</em>. There are a variety of ways in which you can use it; the main ones are <a name="i2"></a>search to cursor, <a name="i3"></a>search to window, <a name="i4"></a>replace, and <a name="i5"></a>incremental (or keyboard) search. These are started by the <code>F4</code> and <code>F7</code> keys, by <code>sF4</code>, and by <code>cS</code>/<code>cR</code> (for forward/backward incremental search), respectively. The first three use similar dialogue boxes. The first two are essentially the same, with one important difference: search to cursor will jump the cursor to the search match, while search to window creates a <em>throwback buffer</em> containing all the matches (search to window is also sometimes called search to buffer). See <a href="Chapter10#S10.7">section 10.7</a> for more information about throwback buffers.
</p>
<p>
The Zap search window is split into several sections. In the first column is a set of search options; the second column gives the direction (forward, backward, forward from the start of the file, or all files starting from the start of the first one); and the final column gives some more options. Below these columns are the search expression (and, for the replace dialogue box, the replace expression) and a button labelled <code>Edit macros</code> which we'll cover later. In addition there are the expected <code>Cancel</code> and <code>Find</code> buttons, and a button marked <code>couNt</code> with a field below it - clicking this (or pressing <code>cN</code>, which is why the label is capitalised the way it is) will fill the field with the number of matches of the current search string.
</p>
<p>
<code>cP</code> inserts the current selection in Zap into whichever search/replace field has the caret. <code>cK</code> clears the history; <code>Page up</code> and <code>Page down</code> and the cursor keys navigate the history (cursor keys will move from field to field in the replace dialogue), and <code>cTab</code> replaces the entry with the one used in the last search.
</p>
<h2><a name="S8.1"></a>8.1 Search options</h2>
<p>
A number of options control how Zap's search system works. These are: raw search, case sensitivity, macros, \-commands and to window.
</p>
<h3><a name="S8.1.1"></a>8.1.1 <a name="i6"></a>Raw search</h3>
<p>
If this option is turned on, then the whole file will be treated as a single line of text and searched accordingly. Thus <code>\&lt;</code> will match the start of the file, and <code>\&gt;</code> the end of the file (see <a href="#S8.2">section 8.2</a> below). The reason it's called 'raw search' is that in this mode, Zap won't 'detokenise' first - so you're searching the raw data of the file. With this option turned off, the search is done line by line, but BASIC mode will detokenise the lines (so you are searching against what you see when Zap displays the file, rather than against what is stored); Code mode disassembles, and so on.
</p>
<h3><a name="S8.1.2"></a>8.1.2 <a name="i7"></a>Case sensitivity</h3>
<p>
If this option is turned on, strings of letters will only match if their case agrees; if off, matching ignores case. Case matching is currently only done for letters in ASCII - ie the letters A-Z. Accented characters in <a name="i8"></a>ISO Latin 1 are <em>not</em> understood for case insensitive matching.
</p>
<h3><a name="S8.1.3"></a>8.1.3 <a name="i9"></a>Macros</h3>
<p>
To make your life easier, you can define up to sixteen macros. These are substituted in the search string before the search is actually performed. Macros may expand to anything - most usefully, they may contain \-commands, as defined below.
</p>
<p>
There are three default macros:
</p>
<ul><li>
<code>*</code> expands to <code>\.\*</code> (matches anything).
</li>
<li>
<code>#</code> expands to <code>\ #</code> (matches any character).
</li>
<li>
<code>\d</code> expands to <code>\[0-9]</code> (matches any digit).
</li>
</ul>
<p>
The 'Edit macros' button in the search windows allows you to view and edit these macros; note, however, that to change them permanently you'll have to edit Zap's textual settings file. See <a href="Chapter12#S12.3.1">section 12.3.1</a> for more information.
</p>
<h3><a name="S8.1.4"></a>8.1.4 <a name="i10"></a>To window searching</h3>
<p>
This option is automatically turned off when you press <code>F4</code>, and turned on when you press <code>F7</code>. When it is turned off, the cursor will be moved to the first match, and subsequent matches may be got by pressing <code>sF7</code> (next match) and <code>scF7</code> (previous match). A beep will sound if there are no more matches, and the cursor will not move.
</p>
<p>
If it is turned on, all matches are placed in a new throwback file. Double clicking entries in this file will cause the cursor to jump to the corresponding match - see <a href="Chapter10#S10.7">section 10.7</a> for more information.
</p>
<h2><a name="S8.2"></a>8.2 <a name="i11"></a>\-commands</h2>
<p>
The search dialogues have a switch to turn off \-commands. If you don't, then the character '\' introduces a <em>wildcard</em>. The wildcards are documented below, and are also summarised in the search windows (although they are initially hidden - click the toggle size icon to reveal the wildcard descriptions).
</p>
<p>
In this list, <code>x</code> stands for any ASCII character unless otherwise mentioned:
</p>
<ul><li>
<code>\x</code> - Matches <code>x</code> case sensitively (irrespective of the case sensitivity option), unless \x is mentioned below.
</li>
<li>
<code>`x</code> - Matches <code>x</code> only (without any replacement of macros).
</li>
<li>
<code>\(, \)</code> - Act as brackets for nesting expressions.
</li>
<li>
<code>\{, \}</code> - Act as brackets, but may be referred to in the replace string (see <a href="#S8.3">section 8.3</a> below).
</li>
<li>
<code>\#</code> - Matches any character. eg: <code>a\#d</code> matches <code>and</code>, <code>aid</code> and <code>aad</code>, but not <code>ad</code>.
</li>
<li>
<code>\.</code> - Matches any character except the return character.
</li>
<li>
<code>\*</code> - Matches any number (including zero) of the previous expression. eg: <code>fo\*</code> matches <code>f</code>, <code>fo</code>, <code>foo</code> etc., and <code>\(and\)\*</code> matches the empty string, <code>and</code>, <code>andand</code>, etc.
</li>
<li>
<code>\%</code> - Matches as many as possible of the previous expression. Thus <code>\[0-9]\%</code> matches <code>1</code> in <code>1pt</code>, and the <code>395</code> in <code>ab395rty</code>.
</li>
<li>
<code>\|</code> - Matches either one expression or another. eg: <code>hello\|goodbye\|fred</code> matches <code>hello</code>, <code>goodbye</code> or <code>fred</code>. <code>\(a\|b\)\*</code> matches <code>abababa</code>, <code>abbba</code>, etc.
</li>
<li>
<code>\[...]</code> - Matches a range of characters. eg <code>\[a-zA-Z%]</code> matches any letter or a <code>%</code>. If a <code>^</code> if given immediately after the opening bracket, then the range given is the characters that the expression <em>won't</em> match, so <code>\[^abc]</code> matches any character except <code>a</code>, <code>b</code> or <code>c</code>. A <code>]</code> may be included in the range by placing it first in the list (after the <code>[</code> opening the list, or after the <code>^</code> if present).
</li>
<li>
<code>\&lt;</code> - Matches the null string at the start of a line.
</li>
<li>
<code>\&gt;</code> - Matches the null string at the end of a line. Note that this doesn't work properly; <code>phip\&gt;</code> won't match <code>phip</code> at the end of a line. Assuming your return character is the normal one, <code>phip\n\&gt;</code> will do the trick (this will be fixed at some point).
</li>
<li>
<code>\+</code> - Turns on case sensitivity for the following letters. Its effect stops at the next wildcard, bracket or command. It doesn't affect nested or bracketed statements. eg: <code>\+Fred\|Bill</code> will match <code>Fred</code> case sensitively, but not <code>Bill</code>.
</li>
<li>
<code>\-</code> - As above, but turns off case sensitivity.
</li>
<li>
<code>\\</code> - Matches a <code>\</code>.
</li>
<li>
<code>\ddd</code> - Where d is any decimal digit, matches a byte of that value, eg: <code>\0alf</code> matches the byte 0 followed by <code>alf</code>, and <code>\233</code> matches the byte 233. Please note that <code>\999</code> matches byte 99 followed by <code>9</code>, since 999 &gt; 255 (the greatest possible value of a byte).
</li>
<li>
<code>\&amp;hh</code> - As above, but matches the hex byte hh when h are valid hex characters.
</li>
<li>
<code>\A</code> - <code>\Z</code> - Matches control A to control Z.
</li>
<li>
<code>\a</code> - Matches alert (ASCII 7).
</li>
<li>
<code>\b</code> - Matches backspace (ASCII 8).
</li>
<li>
<code>\f</code> - Matches a form feed (ASCII 12).
</li>
<li>
<code>\hdd..</code> - Where d's are hex digits, match the given word (32 bit number).
</li>
<li>
<code>\n</code> - Matches a newline (ASCII 10).
</li>
<li>
<code>\o</code> - Matches any character except a <code>.</code> (useful for matching filenames).
</li>
<li>
<code>\r</code> - Matches a return (ASCII 13).
</li>
<li>
<code>\t</code> - Matches a tab (ASCII 9).
</li>
<li>
<code>\v</code> - Matches a vertical tab (ASCII 11).
</li>
<li>
<code>\?</code> - Matches a delete (ASCII 127).
</li>
<li>
<code>\wdd</code> - Where d's are decimal digits, match the given word (32 bit number).
</li>
<li>
<code>\xhh</code> - Matches hex numbers as above (where <code>x</code> is the letter <code>x</code>, eg: <code>\x2D</code>).
</li>
</ul>
<p>
Examples:
</p>
<ul><li>
<code>cat\|mat</code> matches cat or mat.
</li>
<li>
<code>re*ment</code> matches any occurrence of <code>re</code> then <code>ment</code> on a line.
</li>
<li>
<code>SWI</code> matches any SWI (in code mode).
</li>
<li>
<code>LDR\|STR</code> matches any load or store instruction.
</li>
<li>
<code>R6</code> matches any instruction using <code>R6</code>.
</li>
<li>
<code>BL*&amp;0000A95C</code> matches any call to <code>&amp;0000A95C</code>.
</li>
<li>
<code>\&amp;0A</code> matches the byte &amp;0A.
</li>
<li>
<code>\&lt;fred</code> matches fred, but only at the start of a line.
</li>
<li>
<code>main`(</code> matches <code>main(</code>.
</li>
<li>
<code>\d\%</code> matches any decimal number (where <code>\d</code> is a macro which expands to <code>\[0-9]</code>).
</li>
</ul>
<p>
The search will be <em>much</em> faster if you give a definite first character to start with. eg: <code>a\(nd\|pple\)</code> will be a lot faster than <code>and\|apple</code>. If the search takes longer than a third of a second, then an hourglass will come up displaying the position in the file as a percentage underneath. You may stop the search by pressing <code>Escape</code>, and the partial results will be displayed if you are using <code>Search to window</code>.
</p>
<h2><a name="S8.3"></a>8.3 <a name="i12"></a>Replace</h2>
<p>
Pressing <code>sF4</code> brings up the search and replace dialogue box. The first two columns of this are the same as for the search dialogue; the last one has a <code>global</code> option instead of <code>to window</code>. <code>couNt</code> works the same way as for searching (it does <em>not</em> perform any replaces), as does <code>Edit macros</code>.
</p>
<h3><a name="S8.3.1"></a>8.3.1 <a name="i13"></a>Global replace</h3>
<p>
With the global option turned on, replace will replace all occurrences of the search expression with the replace expression, in the direction of the search. (So if you're searching forwards, only matches forwards of the cursor will be replaced; if the search direction is <code>all files</code> then all matches in all files will be replaced.)
</p>
<p>
With global turned off, each match will be highlighted in turn, and a <code>Replace ?</code> window will appear with a series of options. As usual, you can press control and the first capitalised letter of each button to get the desired action; in this case you can also do the same without holding down control. The options are:
</p>
<ul><li>
<code>Replace</code> - Replaces that match and moves to the next.
</li>
<li>
<code>Skip</code> - <em>Doesn't</em> replace this match, and moves to the next.
</li>
<li>
<code>Last</code> - Replaces this match and aborts the operation.
</li>
<li>
<code>Undo</code> - Undoes the last replace operation.
</li>
<li>
<code>reDo</code> - Redoes the last replace operation.
</li>
<li>
<code>All</code> - Replaces all matches from the current match onwards.
</li>
<li>
<code>Front</code> - Brings the window containing the match to the front; particularly useful when you are replacing across all files.
</li>
<li>
<code>In sel</code> - Replaces all matches in the selection (since the replace system selects the word it's considering, you'll have to make your own selection while the operation is in progress for this to be useful).
</li>
<li>
<code>Cancel</code> - Closes the window and aborts the search/replace operation.
</li>
</ul>
<h3><a name="S8.3.2"></a>8.3.2 The replace expression</h3>
<p>
The format of the replace expression is as for the search string, with the following additions:
</p>
<ul><li>
<code>&amp;n</code> - Replace with the n'th <code>\{ ... \}</code> expression in the search string. n starts at 1 and must be less than 10.
</li>
<li>
<code>&amp;&amp;</code> - Replace with an <code>&amp;</code>.
</li>
</ul>
<p>
Examples:
</p>
<ul><li>
S:<code>cat</code>, R: (the empty string) removes all occurrences of <code>cat</code>.
</li>
<li>
S:<code>\{cat\}</code>, R:<code>&amp;1s</code> replaces <code>cat</code> with <code>cats</code>, preserving case.
</li>
<li>
S:<code>time=\{\#\*\}</code>, R:<code>time is &amp;1</code> replaces <code>time=58</code> with <code>time is 58</code> etc.
</li>
</ul>
<p>
To convert spaces between columns of figures in a table into tab characters, use <code>\{\d\} \*</code> as the search string, and <code>&amp;1\9</code> as the replace string. Alternatively, replace <code>\{\d\} \%</code> with <code>&amp;1\9</code>.
</p>
<h2><a name="S8.4"></a>8.4 Incremental search</h2>
<p>
(This is also sometimes called keyboard or interactive search, or <a name="i14"></a>i-search.)
</p>
<p>
Incremental search is activated by pressing <code>cS</code> (to search forward) or <code>cR</code> (to search backwards - reverse incremental search). When you do this, a <a name="i15"></a>minibuffer will be opened for you to type the search string into. As you type the string, Zap will search though the text placing the cursor at the end of the next match. If there is no match, Zap will beep and display <code>(fail)</code>. Pressing <code>Delete</code> removes characters from the search string; doing so will move you back to the first successful match of whatever is left in the search string.
</p>
<p>
To halt the search at the current position, press <code>Escape</code> or <code>Return</code>. If you press an arrow or function key, then the search will be halted and the keypress acted upon. Alternatively, <code>cG</code> (<code>CANCEL</code>) will cause the search to be cancelled and the search returned to its initial position before the search.
</p>
<p>
Pressing <code>cS</code> or <code>cR</code> whilst in search mode will move you to the next/previous match; if the search string was empty then the previous search string will be placed in the buffer.
</p>
<p>
<a name="i16"></a>Macros are turned off during the search; however <code>\(</code> and all other <a name="i17"></a>\-commands will still work. The current settings of the options in the search window will be used (so you if you have disabled slash-commands in searches, they won't work in incremental search either).
</p>
<hr>
<p>
The next section in the manual is <a href="Chapter9#C9">chapter 9</a>, which covers various advanced features of Zap, as well as Zap's internal help system.
</p>
<p>
Alternatively, you could move on to <a href="Chapter10#C10">chapter 10</a>, which explains Zap's different editing/displaying modes, and looks at some of the most useful ones. Modes form the key to many of Zap's most useful features, and since they've been occasionally mentioned in the manual up till now you probably want to learn more about them.
</p>

<hr><address><a href='/copyright'>&copy; Copyright Zap Developers 1992-2004</a>. All Rights Reserved.
</address></body>
</html>
