SYNTAX

MatchIt [window] [[-a[sm]] | [-c] | [-p[ascal]]] [-h] [-l] [-n] [-v]

DESCRIPTION

The MatchIt tool matches the currently selected left delimiter with its mate. When found, the right delimiter is highlighted as the current selection, but when not found, the left delimiter remains the current selection. Note that MatchIt ignores leading and trailing blanks in the delimiter selection and that it does not support right-to-left matching.

Matching is performed on the basis of the programming language used in the specified window. This allows MatchIt to perform sophisticated matches based on the language's syntax, such as matching the Pascal CASE with its mate, END.

Normally MatchIt determines the language by looking at the suffix of the window name (for example, ".p" for Pascal) but you can explicitly specify either assembly language, C, or Pascal by using -a[sm], -c, or -p[ascal]. If the window name does not have a suffix and you do not specify the language explicitly, MatchIt tries to determine it on the basis of the left delimiter. Note that in ambiguous cases, C is assumed.

You may recall that the MPW Shell editor also allows you to find the mates to left delimiters by double-clicking on the character. Although it performs the same function, MatchIt is much more sophisticated and powerful. As mentioned before, this tool takes the programming language into account when searching for a delimiter. This includes consideration for commenting, string, and nesting conventions. In addition, MatchIt supports more delimiters than the MPW Shell editor.

The table below summarizes the delimiters supported by MatchIt, specifying the associated languages for each.

INPUT

None

OUTPUT

None

ALIAS RESOLUTION

Resolves Finder aliases that are part of a partial or complete pathname substituted for the window name. The resolved pathname must specify the name of an open window. Note that using a Shell variable to designate a window is usually faster than requiring MPW to resolve a Finder alias.

STATUS

MatchIt can return the following status codes:

PARAMETERS

window

Specifies the window in which the selected left delimiter can be found. If the window name contains a suffix, MatchIt determines the language accordingly: .a for assembly; .c, .h, or .r for C; and .p for Pascal.

The target window is the default window.

OPTIONS

-a[sm]

Specifies assembly language. Note that only left delimiters defined in the table for assembly-language are allowed as the selection.

-c

Specifies C language. Note that only left delimiters defined in the table for C are allowed as the selection.

-h

Selects all characters starting from the original selection up to the matching delimiter. If MatchIt cannot find the matching delimiter, the left delimiter remains selected.

-l

Selects the entire line containing the right delimiter when a match is found. If you specify both this option and -h , MatchIt uses -h.

-n

Generates an error message to diagnostic output and returns a nonzero status code if a matching delimiter cannot be found.

Normally MatchIt returns the status code 0 without generating an error message. This is usually sufficient because the current selection does not change if a match is not found. However, this option can be useful in MPW Shell scripts and AddMenu commands.

-p[ascal]

Specifies Pascal language. Note that only left delimiters defined in the table for Pascal are allowed as the selection.

-v

Writes version information to diagnostic output.

EXAMPLES

The following command line matches the currently selected delimiter in the MySource.c file. Note that MatchIt assumes the window contains C code because of the .c suffix.

Matchit MySource.c

The next command line matches the currently selected delimiter in the target window. If a match cannot be found, MatchIt generates an error message. Note that {Target} is enclosed in quotation marks in case the target window name contains spaces or special characters.

MatchIt "{Target}" -n

Although the previous example can be useful for scripts, MatchIt is more often used in the same manner as the MPW Shell editor's own delimiter-matching mechanism. The following example illustrates this purpose:

AddMenu Edit 'Match It/µ' 'MatchIt -n -h "{active}" ≥ "{MPW}"Errors ∂
|| Alert < "{MPW}"Errors'

This example produces a Match It menu item, with the keyboard equivalent Option-M (µ), in the Edit menu. When you make a selection in the currently active window, you can invoke the menu item to find the matching delimiter.

If MatchIt finds a match, it selects all characters from the initially selected delimiter to its mate (-h). If a match is not found, or if any other errors occur, an alert box appears containing an error message. The script uses an auxiliary file, "{MPW}"Errors, for this purpose.

If you do not want to display the alert box or create an error file, you can use the following command instead. It matches the delimiter in the same manner as in the previous example but ignores all errors.

AddMenu Edit 'Match It/µ' 'MatchIt -h "{active}" ≥ dev:null'

LIMITATIONS

MatchIt only finds a right delimiter to match the specified left delimiter. Right-to-left matching is not supported.

MatchIt does not process conditionals (that is, C #if, Pascal $ifc, and so on), C macros, or \ during its scan, except to find matching pairs.