Copyright: Copyright 1996, Ziff-Davis Publishing Company


WSEARCH

Introduction

Files

Text

Options

Results Display

Regular Expressions

Escape Character

The WSearch Command Line

Error Messages

WSearch and its documentation and source code are Copyright © 1996, Ziff-Davis Publishing Company, All Rights Reserved.  First Published in PC Magazine, US Edition, March 26, 1996.

Programmed by Tom Rawson.

1.00  2/96


Introduction

WSearch is a fast file and text search utility for Windows 3.x, Windows NT, Windows 95, and OS/2.  This help file explains how to use WSearch under Windows; for OS/2 use see the separate text file WSOS2.DOC.

Installing WSearch is easy -- just copy it to a directory on your hard disk and create a desktop object for it.  When you first launch WSearch, you'll see a simple dialog box. The two edit boxes at the top of the screen let you enter the files to search for and the text, if any, to search for within the files. Below the edit boxes are six checkbox options that control how WSearch performs the search and displays the results.

WSearch includes two Windows executables, and an OS/2 command-line version.  Be sure you set up the correct executable for your system:

WSWIN.EXE	16-bit Windows for Win 3.x

WSWIN32.EXE	32-bit Windows for Win NT / Win 95

WSOS2.EXE	32-bit OS/2 command line version

After entering the search information in the dialog box, press Enter or click the Search button, and the search will start. The Searching line at the top of the window displays the search status, and results are displayed in the Results box. You can use the scrollbars or standard navigation keys to scroll through the Results listbox.

While a search is running the Search button changes to a Stop button, and the Exit and Help buttons become unavailable. Clicking Stop or pressing Enter during a search will halt the search. If you restart the search, the listbox clears and the search starts over.

You can also initialize or execute a search from the WSearch command line if you wish.

If you use WSearch to search standard PC (ASCII) text files with typical line lengths, it will match text and count line numbers just as you expect.  However if you are using WSearch to search non-ASCII files (e.g. word processor documents, or binary files such as .EXE or .DLL files), files with very long lines (over 2048 characters), or files transferred from other systems (e.g. Apple Macintosh), you may want to look over some of the technical details under the heading Line Breaks and Line Numbers in the section on the Results Display.


Files

Use this box to enter the name(s) of files you want to search, or search for.

You can enter paths, file names, or both in the File(s) edit box.  If you use only a path, WSearch will search all files in the specified directory.

You can specify multiple file names or paths by separating them with spaces or semi-colons.  When searching multiple file specs, WSearch starts by looking through the first one (including subdirectories, if this option is checked), and then moves on to the next one.  You can list up to 32 separate file specifications for WSearch to search.

If you don't enter any paths or file names, the search starts from the current directory, which is displayed at the top of the dialog box.

The 32-bit version of WSearch supports long filenames, and requires double quotes around any filename which includes spaces or semicolons (e.g. Goulash Recipe).  Short file names, and long names without spaces or semicolons (e.g. GoulashRecipe) don't require quotes, but you can use them if you wish.

The Browse button allows you to select a filename or wildcard file specification in any directory.  The selected file name or specification is added to the end of any list already present in the File(s) box.  If you want to start a new file list with the Browse button, clear the File(s) box first.    The current directory, shown at the top of the dialog, does not change when you use the Browse button to select a directory or file.  Instead, the correct path is included in the name added to the File(s) box.

You can use a regular expression to specify multiple files.  Regular expressions include the wildcard characters * and ?, but also allow much more powerful tools for selecting filenames.  See the section on regular expressions for complete details.

The remainder of this topic explains how regular expressions work when they are used in the File(s) box.

When you use a regular expression in the File(s) box, WSearch retrieves the name of each file in the directory and tests it to see if it matches the pattern you've specified. For example, the filename [abc]*y.* will find all files whose names begin with a, b, or c and end in y, and have any extension.

You can only use a regular expression for the file name and extension. Regular expression characters in the path portion of the file name (the part before the final backslash) will be ignored as meta-characters and treated as though they are part of the path. If the path (or filename) is invalid, you will get an error message from the operating system.

When a regular expression is used to match a file name, WSearch assumes the first character in the expression must match at the start of the name, and the last character must match at the end of the name. For example, the pattern [abc]*t will match the file ADMIT, but will not match MARY.DAT (because the name does not begin with a, b, or c), or ARMPITS (because it does not end with t). To match the specified string anywhere within a filename, add a * at the beginning and end (e.g. *[abc]*t*).

Note that this is different from how text expressions are handled. In text expressions, the angle brackets, < and >, are used to anchor searches to the first or last character of a line. This difference is necessary to make WSearch's behavior consistent with the way file names are usually handled.  If file name patterns were not anchored to the beginning and end of the name, a pattern like xy? would match, for example, a file named ABXYZ, which is not what the user would expect.

When WSearch tests file names, the entire name  including the "." and any extension  is treated as a string and matched against the expression you specify. This is slightly different from the typical wildcard matching you may be used to, where the name and extension are treated separately. For example, in WSearch, the file name pattern a?y matches names which begin with the letter a followed by any character, followed by the letter y. This would match a file named ANY, or one named A.Y; the "." between the extension and the file name is simply treated as another character.


Text

Enter the text you want to search for in the Text box.

When you specify text for WSearch to match, most characters are treated literally  that is, an "a" in the Text box just means the letter "a", and a "(" means a left parenthesis.  For example, to search for the name "Mabel," just enter the word Mabel.

You can also use a regular expression to specify the text.  Regular expressions provide a much more powerful matching tool than plain text, because they allow you to describe "patterns" of characters, not just literal text.

Unlike the File(s) edit box, the Text edit box can contain only one search pattern. Any spaces in what you type are assumed to be part of the pattern. You can use quotes around the search pattern if you wish, but they are not required.

If you don't specify a Text search pattern, WSearch will list all the files that match the File(s) pattern, and will ignore the text within the files.


Options

There are six WSearch options selectable with check boxes in the dialog.  You can also set any option from the command line.

Search subdirectories:  Tells WSearch to search the current directory (or any directories you name in the Files box) and all of its subdirectories.  If this box is not checked, only the current and/or specifically named directories will be searched.  If you enter a root directory in the File(s) box, checking Search subdirectories will search an entire drive.

Case sensitive:  This option makes pattern matches case-sensitive  that is, the case of the search text will have to match the case of text in the file exactly for it to be considered a match.  Otherwise, case variations are ignored during the search.  Note that this applies only to text searches; file name searches are always case-insensitive.

Show files that don't match:  By default, WSearch will only list files in the results box that contain a match to the search text.  If you check this option, files with no match will be displayed as well, with the message ** No match **.

Show all matches:  Sometimes a file will contain more than one match to the search pattern.  Normally WSearch lists the first matching line only.  If you check this option, WSearch will list all the lines that match in each file.

Line numbers:  By default, WSearch does not display line numbers in the results list.  These are optional because the search goes a little faster when WSearch doesn't have to count lines.  However, you can tell WSearch to display line numbers by checking the Line numbers option.

Fast response:  Checking this option improves response to the Stop button, at a slight cost in search speed.  Under Windows 3.1 checking this box also gives more chances for other applications to run while a search is in progress.


Results Display

If you specify a text pattern, WSearch displays each file name, followed, on the same line in the Results box, by the line number of the first match (if line numbers were requested), and the text of the matching line.  If you ask for all matches, the file name is displayed on a line by itself in the Results box, with matching text lines below it.

If the matching text crosses a line boundary (i.e. if there is a \n in the search pattern), the first matching line is shown.  If the pattern starts with \n the line before the first matching \n is the one displayed.

If you don't specify a text pattern, WSearch will display filenames only.

When a search is completed (or terminated with the Stop button) WSearch displays the number of files found on the Searching: line at the top of the dialog.  If a text pattern was specified, the count shows how many files contained at least one match.  If no text pattern was given, the count simply shows the number of files found.

WSearch does its best to make the display in the Results listbox useful.  Long filenames and text lines are truncated before they are displayed (to help avoid running out of memory before the search is finished).  Filenames are truncated at 80 characters by replacing a center portion of the name with "...." (e.g. d:\dira\....\dirx\filename.ext).  Text is truncated by discarding the beginning or end of the line, as required, and replacing them with "....", to limit the output to a maximum of 128 text characters.  The text truncation algorithm shows the portion of the line containing the text that matched, and includes additional text before and after the match if there is room.

NUL (ASCII code 0) characters would normally terminate the displayed line where the 0 character occurs.  To prevent this problem, binary 0s are converted to binary 1s before displaying the line.  The binary 1 character displays as a small "block" in most Windows fonts.

Line Breaks and Line Numbers

If you use WSearch to search standard PC (ASCII) text files with typical line lengths, it will match text and count line numbers just as you expect, and you can probably skip the remainder of this section.  However if you are using WSearch to search non-ASCII files (e.g. word processor documents, or binary files such as .EXE or .DLL files), files with very long lines (over 2048 characters), or files transferred from other systems (e.g. Apple Macintosh), you may find some of the technical details below useful.

WSearch finds and counts lines by looking for LF (line feed, or ASCII 10) characters.  As a result, WSearch's line numbering feature will only be useful in standard text files with an LF at the end of each actual line.  In addition, matching may not proceed as you expect in a file with non-standard line breaks, because a pattern you think of as occurring on a single line may be on multiple lines in the file.

Most binary files (e.g. .EXE files) contain essentially random line breaks, and line numbers usually will not provide useful information in these files.

Non-ASCII word processor documents (e.g. Word for Windows .DOC files) usually do contain LF characters, but they may not occur where you expect, and "soft" line breaks (within a paragraph), "soft" hyphens, and other formatting codes may break up text that you think of as separated only by spaces or other standard characters.  To work around this you may need to search for short text strings or use the "*" character to find the text you want.  For example, if you are searching a Wordperfect document for the string the quick brown fox and you suspect there may be special formatting characters inserted within the text, you might be more likely to find what you want by searching for an uncommon word like fox, or for the*quick*brown*fox.

In a file without any LF characters at all, WSearch will count each 32K-byte buffer it reads as a line.  When viewing such files any line numbers shown simply reflect which 32K portion of the file the text was in.  For this reason, WSearch will not count lines correctly in files which use only CR (carriage return, ASCII 13) characters as line terminators (many text files created on the Apple Macintosh use only CR as a line terminator).  WSearch only detects a line break when it finds an LF, or a CRLF pair; the CR alone will be ignored.

If you ask to see all matches in a file with non-standard line breaks, WSearch will display at most one match for each LF character found.  In a file with no line breaks at all (including Macintosh and other similar text files), WSearch will display at most one match per buffer.

Due to performance and memory usage issues in the internal design of the search process, WSearch may also  very rarely  fail to count lines correctly, or fail to find certain matches, in files where the line breaks are more than 2K (2048) characters apart.  In particular, when a line longer than 2K characters crosses a 32K buffer boundary, with at least the first 2048 characters in one 32K portion of the file, and the remainder of the line in the next 32K portion, WSearch will count the line as two lines, not one, and will fail to match text which happens to cross this artificial "line break".  For example, if you search for the string hello in a file with lines over 2K in length, and hel is at the end of one 32K section of the file and lo is at the start of the next 32K section, the match may not be found.  As long as you use WSearch on files with lines shorter than 2048 characters, this problem will not affect you.


Regular Expressions

Certain characters, such as the wildcard characters * and ?, have a special meaning to WSearch. These special characters allow you to specify a "pattern" for WSearch to locate in the file(s) listed in the File(s) box.  They are called "meta-characters" because they have a higher-level meaning than a plain text character. The meta-characters used by WSearch are:

?	Matches any single character except the end-of-line character. For example, a?c matches abc, axc, or a#c.

*	Matches any character or string except the end-of-line character; it also matches no character. For example, a*c matches alphabetic, all plastic, or AC.

[abc...]	Matches any character listed within the brackets (called a character class). In case-insensitive searches, letters in a class include their upper or lower case  equivalent. For example, [aBc] will match a, b, c, A, B, or C for case-insensitive searches, but only a, B, or c for case-sensitive searches.

[a-z]	Matches any character between the ends of the range, including the end characters themselves, using standard ASCII values. You may need an ASCII chart to understand unusual ranges. For example, the range [0-z] would also include many punctuation characters. You can enter the ends of a range in either order. For example, [z-a] is the same as [a-z].

[~abc...]	Matches any character except those listed within the brackets. If a range is used, WSearch will match characters which are not part of the range. For example, [~afw-z#] will match all characters except a, f, w, x, y, z, and #.

<	Matches only if the character or string occurs at the beginning of the line. For example, <app will match apple but not happy.

>	Matches only if the character or string occurs at the end of the line.  For example, and> will match hand but not handle.

If you want to find a file that contains the string noodles you can just enter that string in the Text box. But what if you want to find any string that starts with n, has a vowel plus two additional characters following, and then ends in les (for example, needles, nestles, nettles, nibbles, nickles, niggles, nipples, nobbles, nodules, noodles, nozzles, nubbles, and nuzzles)?  You can do it by putting this regular expression pattern in the Text box:

n[aeiou]??les

If you want to find all files that contains the words breach or broach, you would use this expression:

br[oe]ach

Here are a few more examples:

a*b	Matches a line which contains an a followed by a b somewhere later in the line.  For example the following lines would match:

The alphabet contains 26 letters.

Today is the day we go to the boat.

ABC

The following lines would not match:

The quick brown fox jumped over the lazy sleeping dog.

Boys will be boys.

1[0-9][0-9]	Matches a line which contains a number between 100 and 199.

<1[0-9][0-9]	Matches a line which begins with a number between 100 and 199.

<??1[0-9][0-9]	Matches a line which contains a number between 100 and 199 in the third, fourth, and fifth columns.

Mabel[~i]	Matches a line which contains the word Mabel, and where the next character after the word is not an I.

. [~ ^n]	Matches a line which contains a period, then a space, then any character that is not a space or end of line (see below for information on the escape character, ^).

Strings in square brackets are called "character classes". Whether a character is interpreted as a meta-character depends on whether it's in a class, and sometimes on its relative position.

Outside a class, the characters with special meanings are <, >, ?, *, [, and ]. The special characters used within classes, ~ and -, are interpreted as normal characters when they occur outside a class.  For example, outside a class, the pattern ab~c would be interpreted literally, with no special meaning for the ~.

The ~ character only carries a special meaning when it is the first character in the class; otherwise it is taken literally. Characters which have a special meaning outside a class such as ? and * are interpreted as plain text characters when they occur within a class. For example, the pattern [xyz*~] would match the characters x, y, z, *, or ~.

If you need to include one of the WSearch meta-characters in your text you must precede the meta-character with the escape character, a caret (^).  For example, to search for the string Are you there?, you must use this in the Text box:

Are you there^?

For more details, and information on using the escape character to represent non-printing characters like Tab or Line Feed, see the Escape Character section.


Escape Character

The escape character, a caret (^), is used to change the meaning of the following character or characters.  You can use it to include meta-characters (see regular expressions) or non-printing characters (see below) in your search pattern or file name.

If an Escape character precedes a meta-character, the meta-character is treated literally, as plain text.  For example, you would use ^? to search for a question mark. To put a caret in the text, use two carets (^^). (Note that the WSearch escape character is not the same as the ASCII ESC character.)

The Escape character also lets you specify characters that normally can't be used within a search pattern because they are non-printing  for example, the carriage return or line feed characters. WSearch recognizes five escape sequences of this type:

^t	Tab (ASCII 9) character.

^r	Carriage return (ASCII 13) character.

^n	Line feed (ASCII 10) character; during searches this also matches a carriage return/line feed pair.

^ddd	Numeric ASCII character ddd (decimal). The next three characters after the ^ are considered to be the number, but a one- or two-digit number can be used if the character that follows is not a valid decimal digit.

^xdd	Numeric ASCII character ddd (hex). The next two characters after the ^x are considered to be the number, but a one-digit number can be used if the following character is not a valid hex digit.

If the Escape character is followed by a character other than the ones listed above, the Escape is ignored and the character after it is used literally, even if it is a meta-character.  Here are some more examples:

^[Boot^]	Searches for [Boot].

abc^ndef	Searches for abc at the end of one line followed by def at the start of the next line.

3 ^^ 6	Searches for 3 ^ 6.


Command Line Options
The WSearch Command Line

The WSearch command line goes in the Command Line box when you create the icon for the program under Windows 3.1. The Windows 95 equivalent is the Target line on the Shortcut page of the Properties dialog box.

You can specify a filename, a text string, and any of the six WSearch options using switches on the command line. Command line switches can be preceded with either a dash (-) or a slash (/).

Note that the command to launch WSearch will be different, depending on whether you are running the 16-bit or 32-bit version.

The command line syntax is:

WSearch-command   [options]   [-t] text-expression   -[f] file-specification ... [-g]

For 16-bit Windows, the WSearch command is WSWIN; for 32-bit Windows it is WSWIN32.

The search option switches are:

-a	Show all matches

-c	Case sensitive

-m	Show files that dont match

-n	Show line numbers

-s	Search subdirectories

-r	Fast response

The -t and -f switches are not necessary if a text expression precedes the file specifications. If you want to omit the text expression, or if you want to put the file specification before the text expression, the -t and -f switches let you do so. Their meanings are:

-t	text expression follows

-f	filespec follows

Switches used on the command line will initialize the values in the WSearch dialog box. You can then change or add information and start the search manually. If you prefer, however, you can tell WSearch to run immediately by using the -g (go) switch. If you use -g, the dialog box will be filled with the information you specify on the command line, and then the search will be initiated automatically.

For example, to initialize the 32-bit version of WSearch so that it starts out assuming you want to search subdirectories, you could start it with the command:

d:\path\wswin32.exe -s

(where d:\path is the path where WSearch is stored on your system).  To start the 16-bit version search all files on drive D for the text expression n[aeiou]??les using a case-sensitive match, and display the results, you could use this command:

d:\path\wswin.exe -s -c n[aeiou]??les d:\*.* -g


Error Messages

The messages listed below are displayed by WSearch when it finds a problem.  Those beginning with "**" are displayed within the WSearch dialog; all others are displayed in popup dialogs.

** No match **:  The text was not found in the file.

** Not found **:  The file was not found.

** Terminated **:  You terminated the search before it was finished.

Cannot load dialog box:  WSearch could not load its dialog box.  Either your executable file is damaged, or you are VERY low on Windows memory or other resources.

Cannot open file:  The file could not be opened, probably because it is in use by another program or because you do not have the correct rights to view the file.

Cannot retrieve current directory:  WSearch could not determine the current directory.  This error should not occur unless Windows is not working properly.

Expression too long:  Your text or filename regular expression was too long for WSearch's internal buffers.

File search failed:  WSearch could not search the directory for the file(s).  You may not have the correct rights to access the directory, the directory structure may be damaged, or the operating system may be having some other problem accessing the directory..

Invalid class:  A class in a regular expression was invalid.  For example, you forgot to include the closing ], or you failed to terminate a range (as in the pattern [a-]).

Invalid hex value:  The value after a ^x did not contain a valid hexadecimal digit.

Invalid switch:  You used an invalid switch character on the WSearch command line.

More than one expression specified:  You used the -e switch to put more than one expression on the command line.

No class open:  WSearch found a closing ] in a text or filename pattern but there was no opening [ before it.

Out of memory:  WSearch could not allocate memory for one of its internal buffers or storage areas.

Read error:  WSearch encountered a data error while reading the file.

Search in process -- press OK to close anyway, or Cancel to continue :  You are trying to close WSearch while a search is still in process.

Seek error:  WSearch encountered a data error or directory error while accessing the file.

String too long:  A string within your expression is too long.  The limit is 1024 characters.

There is not enough memory to display any more results:  WSearch ran out of memory while trying to add more results to the results box.

Too many file specifications:  You used too many file specifications.  The limit is 32 file specifications at any one time.