HyperCard Find and Replace (ABC97.06)

Gareth Jones

This article is the second in a series that show how to use HyperCard (for the Mac or IIGS) to load, change, and save text files, much like a word processor. This installment shows how to create a HyperCard button to "Find and Replace" text in a background field automatically, just as you do in a word processor. You don't need to have read the previous article to use this one.


Following the instructions in the previous article produces a HyperCard stack with a single button to import a text file and a single background field to display the imported text. If you have that stack handy, then enhance it with this article. If you haven't, then create a new stack ("New Stack..." from the File menu), go to the background layer of the stack ("Background" from the Edit menu) and create a text field ("New Field" from the Objects menu). Select "Background" a second time to return to the card layer.

Now, you'll need some text in the background field. If you have the stack from the last article, import a text file before you start. If you don't, then select the browser (hand-shaped) tool from the Tools menu, click inside the field, and type your favourite sonnet or haiku. (Confine yourself to less than 30,000 letters, which is the limit for a field).

The Button Script - Part 1

Create a new button by selecting "New Button" from the Objects menu. Drag it to a convenient spot on the card and double-click it to open up a dialogue box. The selected text at the top of the box says "New Button" - change that to something more descriptive, such as "Find & Replace" (or "Search & Destroy"). Now click on the "Script" button to start entering the script that controls what happens when the button is clicked.

Type the following text into the Script Editor window (which is a mini word processor just for editing scripts):

on mouseUp
  ask "What do you want replaced: " with "Old"
  if it is empty then
    exit mouseUp
    put it into findThis
  end if
  ask "Type in the replacement:" with "New"
  if it is empty then
    exit mouseUp
    put it into changeTo
  end if
  put "Changing" && findThis &&"to"&& changeTo
  if findThis is not in background field 1 then
    answer findThis && "is not there." with "OK"
    exit mouseUp
  end if

The portion of the script above asks for the information needed for the search and replace command to work:

  1. It asks for the text that will be searched for and places it into a variable called "findThis".
  2. It asks for the text that will replace findThis and places it into a variable called "changeTo".
  3. It shows a message informing the the user of what the script is doing.

Discussion of "Find"

A very useful command in HyperTalk (HyperCard's programming language) is "Find". You can use it manually - as opposed to in a script - by summoning up the message box (Command-M) and typing a line such as:

Find "worms"

On pressing Return, HyperCard will look through all the fields of all the cards and backgrounds of the stack for the word "worms". It will take you to the first card that has the text and draw a temporary box around the text so that you will notice its location. Pressing Return a second time will take you to the next occurance of worms in your stack, and so on.

That's the simplest use of Find. You can also use it to find only the cards which have both "worms" and "beetles" in them by typing into the message box:

Find "worms beetles"

However, for this search and replace function to work properly, you need to confine a search to only the contents of a single field. HyperCard allows you to do so - but only for a background field.

In other words, this command works:

find "worms" in background field 1

but this command causes an error message:

find "worms" in card field 1

Find has a number of variations, depending on what you want to find (a phrase, a set of letters that may not be complete words, complete words but not necessarily in order, and so on). The next snippet of script uses the "find string" variation, which finds the desired text even if it is not complete words.

There's a lot more to the Find command, which you can find out about if you select "Help" from the Go menu and root around.

Discussion of Replace

Now that we know how to find a set of characters in a background field, how do we replace it? Modern Mac HyperCard texts say that you should do it with a line like:

put changeTo into the foundChunk

This does indeed work with recent versions of Mac HyperCard. With earlier versions, and with the GS version, it fails. The second edition of Danny Goodman's "The Complete HyperCard Handbook" suggests using:

do "put changeTo into" && the foundChunk

This works with any version of HyperCard.

Discussion of "Lock Screen"

HyperCard normally shows you what it is doing. For example, if you issue a Find Command, HyperCard will obligingly scroll your text field to show you the text it has found. Doing this takes time, however. If you issue a "lock screen" command, the screen display will not change as the script operates, and the script will consequently finish in about half the time. Make sure that you unlock the screen when the script has finished changing the text.

The Script - Part 2

You're about ready to type in the rest of the script for your Find & Replace button:

lock screen
 repeat while findThis is in background field 1
   find string findThis in background field 1
 do "put changeTo into" &&the foundChunk
   end repeat
 unlock screen
 put "All Done!"
 play simpleBeep
end mouseUp

Close up the script editor now.

Using the Button, and Beyond

Click on the new Find & Replace button. Type in text at the prompts. Without ado, your commands will be carried out on the text in your field.

Similar scripts to this one are the heart of many useful stacks. For example, one turns the text in a text field into a Web Page ("HTML.Edit"). I've written one which goes the other direction, turning web pages into formatted WordPerfect documents ("HTML.to.WP"), and another one which turns certain pairs of letters into ligature characters (e.g. fi into ) in preparation for desktop publishing. You will find other uses for Find and Replace as you continue to use HyperCard.

The next article in this series will be on saving text from a field to disk, so that it can be loaded into other programs. After that, I'll discuss how to get around the 30,000 character limit of text field to let you load, change, and save files of virtually unlimited size. Past that, I am open to suggestions. What are you using HyperCard for? What problems are you having? Let me know.

Gareth Jones is the former Editor of Apples B.C. News and a Contributing Editor of Hyper Quarterly, a new magazine-on-disk devoted to HyperCard IIGS stacks.

HyperCard IIGS Article Index | HyperCard FAQ | Hyper Quarterly Home