User's Manual

Expanding the edit fields

The Regular Expression, Replacement Pattern, and Search Text fields all have an Expand Field button to the right of the edit field.  Clicking on this button opens up a larger window so you can more easily edit longer strings or search texts if you need to. When you close the expanded edit window, entire the text is automatically copied back into the appropriate edit field, even if there's not enough room to display it all. When you run the search by clicking on the Match button, the entire text will be used.

Contextual menus

The Regular Expression, Replacement Pattern, and Search Text fields all support contextual menus (right-click or Option-click to bring up a menu of common editting commands).

Loading the Search Text field

You can load any plain text file into the Search Text field by selecting "Open Search Text..." from the File Menu.

Options

The Options checkboxes across the top of the window correspond to the options available in the RegExOptions class in REALbasic and control how pattern matching responds to certain special conditions.  They are as follows.

• Greedy -- if checked, wildcard patterns like "+" and "*" will try to match as many characters as possible unless you qualify them with "?". If unchecked, the reverse is true (i.e. it will match as few characters as possible unless qualified with a "?" character). Normally you'll want to leave this checked; the REALbasic RegEx class sets the Greedy option to True by default.
• Dot = All -- if checked, the dot character "." will match any character including newline and carriage return. If unchecked, the dot character will match any character except newline and carriage return. Normally unchecked; the REALbasic RegEx class sets the DotMatchAll option to False by default.
• Match Empty -- if checked, a pattern like "(.*)" will count as matching if it matches an empty string. If unchecked, the matching string cannot be empty. Normally checked; the REALbasic RegEx class sets the MatchEmpty option to True by default.
• Case Sensitive -- if checked, pattern matching is case sensitive; if not, pattern matching is case insensitive. Normally unchecked; the REALbasic RegEx class sets the CaseSensitive option to False by default.
• 1 Line -- if checked, pattern matching considers the entire Search Text as a single line as far as matching the "^" and "$" operators are concerned. If unchecked, the "^" and "$" will match the beginning and ending of lines based any newlines and/or carriage returns embedded in the Search Text. Normally unchecked; the REALbasic RegEx class sets the TreatTargetAsOneLine option to False by default.

Regular Expression field

The Regular expression field lets you type in any regular expression you would like to try out. If you need help with regular expression syntax, you can use the Match menu and the Patterns menu to insert the correct wildcards, repetition symbols, or other operators. If you need more room to edit your regular expression, you can click on the Expand Field button to edit your regular expression in a larger window. Whenever you test out a regular expression (by clicking on the Match button), it is stored in your History, and can be retrieved via the History menu, so you can easily revert to an earlier version of your regex if you try something that doesn't work out.

Match menu and information windows

The Match menu has menu items for all the common wildcard operators (digit, whitespace, word boundary, etc) of regular expressions, plus a number of items that take more information, such as "match any character in a set" and so on. Menu items that require additional input from the user will open up a special Information Window asking for additional information to be entered.  When the window first opens, there is a prompt explaining what kind of text is needed, and an input field. Additional help is available in the window itself however. Under the left end of the input field is a small triangle which, when clicked on, opens up a short help screen with examples of the kind of text that can be entered. 

Patterns menu

The Patterns menu has menu entries for grouping, the "|" operator, the "?" greedy qualifier, the occurrences operators, and the zero-width lookahead and look-behind assertions. If you have text selected in the Regular Expression field, and select "Group" from the Patterns menu, it will put parentheses around the selected text.  The "Or" and "Greedy" menu items will insert "|" and "?", respectively.

The zero-width lookahead and look-behind assertions bring up an information window, as above. To use a zero-width lookahead, enter any regular expression in the input field. It will be correctly formatted as a zero-width lookahead and inserted into your regular expression. The zero-width lookahead and look-behind assertions appear in the Patterns menu as "Followed by...", "Not followed by...", "Preceded by..." and "Not preceded by..."

The "occurrences" menu items are fairly self-explanatory, and simply insert the appropriate character (+, *, or ?, depending which item you select). The Number of Occurrences menu option is somewhat different, and has its own dialog box for entering the minimum and maximum number of occurrences. According to proper regular expression syntax, you can specify an exact number of occurrences, a minimum number of occurrences, or a range of occurrences. Click the radio button for the version you want, or just type into the appropriate input fields and the radio buttons will set themselves automatically. 

Replacement Pattern field

The Replacement Pattern field is deactivated by default to make it easier to tab between the Regular Expression field and the Search Text field. To activate the Replacement Pattern field, just click in the checkbox beside the field. The replacement pattern can be anything you like including backreferences (i.e. \1 to match the first matching subexpression, and so on). The special symbol "$&" will be replaced with the entire matched string.

History menu

Any time  you click the Match button, the contents of the Regular Expression field (and the Replacement Pattern field, if active) are saved in the History. When you are editting the Regular Expression field, you can replace the current regular expression with any previous regular expression by selecting it from the History menu. Likewise, whenever you are editting the Replacement Pattern, you can replace the current replacement pattern with any previous replacement pattern by selecting it from the History menu.

Saving and loading the History menu items (registered version only)

In the registered version of RegExplorer, the History menu contents can be saved to a text file and loaded back in for future sessions, using the "Save History," "Save History As..." and "Load History" menu items under the File menu. The history file is a plain text file that can be editted using any text editor, however you can easily corrupt the file if you change the number of lines, so edit the history file at your own risk. Simply copying regular expressions out of the history file, however, should be perfectly safe.

Search Text field

The Search Text field is where you enter the text you will be running your regular expression on. You can type text into this field by hand, or you can use the Edit menu or the Contextual menu to paste text here, or you can use the "Open Search Text..." menu item under the File menu to open any available text file and load it into the Search Text field.

One-shot versus batch

You can run your regular expressions in either one-shot mode or batch mode. In one-shot mode, the regular expression is passed to a RegEx class, the options are set up, and the Search method is called one time, with the results displayed in the list at the bottom of the window. In batch mode, the Search Text is searched until no more matches are found, with each new search starting with the first character following the end of the last match. All the matches are then displayed in the list at the bottom of the window. The one-shot/batch radio buttons are to the left of the Search Text field, and batch mode is the default.

Results list

The results list is displayed as a hierarchical list, with each match displayed on a separate line. Clicking on the disclosure triangle for a match opens it up to display the subexpression matches for that particular match, so you can see a list view of all your matches (if you have a lot of matches), and can zero in on individual subexpressions (if you happen to have a lot of subexpressions). Each match line displays not only the part that matched, but also the part that came before the match. If you had a replacement pattern, the replaced version is also displayed. Double-click on any cell to open up a larger inspection window so you can see the full text of any matched (or unmatched) text that may be too big to fit in a single cell.

New version notification

If you have an Internet connection, RegExplorer now has the option of notifying you whenever a new version of the application is released. (This can be turned off in the Preferences if you wish.) When a new version is available, the dialog at the right will be displayed. The new version number is displayed at the top, and release notes are displayed in the read-only edit field in the middle.

If you check the "Don't show this version again" checkbox, then you will not be notified again about this particular version, but you will be notified whenever the next version is released.  For example, if version 1.0.2 comes out, and you check "Don't show this version again," then the New Version dialog won't notify you again about the 1.0.2 version, but if 1.0.3 or 1.1.0 is released, you will get a New Version notification. If you don't want to get any New Version notifications, use the Preferences menu and uncheck the checkbox that says "Check for new versions of RegExplorer."

Author

RegExplorer and this manual are both © 2005 by Mark Nutter.
All Rights Reserved.