MPW Command Reference is a command dictionary that describes each of the scripts, tools, and built-in commands available for use with the Macintosh Programmer's Workshop (MPW). Following the command dictionary are appendixes describing the special characters and operators.

Sections of the Reference

For each entry, the reference begins with a heading line that includes the command name and a label indicating whether the command is a script, tool, or built-in command.

For each command, the reference provides the following information:

• Syntax -- a concise listing of the syntax for invoking the command

• Description -- an explanation of the command's function

• Input -- information on the command's input

• Output -- information on the command's output

• Status -- a list of possible status codes and their meanings

• Parameters -- a description of each of the command's parameters

• Options -- a description of each of the command's options

For some commands, the reference also includes these sections:

• Alias Resolution -- information about the command's ability to resolve Finder aliases

• Examples -- examples of how to use the command

• Limitations -- a list of limitations, special cases, or warnings

• See Also -- references to related commands or information

Syntax

This section lists the complete syntax for the command, in the general form

Command [parameter…] [option…]

where Command is the name of the script, tool, or built-in command; parameter… is a list of one or more parameters; and option… is a list of one or more options.

The syntax used in MPW is relatively flexible. None of the syntax elements are case sensitive. The syntax conventions shown in the table below are used in this manual as well as in the syntax information displayed online by the MPW Help command.

MPW syntax conventions

Note
You cannot place spaces and special characters within a parameter unless you place quotation marks around the entire parameter. •

Description

This section takes a task-oriented approach to describing the function of the script, tool, or built-in command. In general, the section describes the default behavior and then discusses notable options that modify the default behavior. These options often appear in a bulleted list of alternative or additional ways to use the command that allow you to customize its function to fit your needs.

Note
All commands can be executed in the MPW Shell running under any runtime environment. However, the function or output of certain commands is applicable only to specific environments. For example, the Asm command generates code only for the classic 68K runtime environment. For commands that target specific runtime environments, the supported environments are indicated in this section. •

Input

This section states the allowable input for the command and any relevant information concerning it. In most cases, input is either one or more files or standard input.

In the case of standard input, the command waits for input upon execution. The exact text that MPW uses as input depends on which of the following you do:

• Press Enter after placing the cursor on the line to be used as input. In this case, MPW processes only the current line as input.

• Select the text to be used as input and press Enter. In this case, MPW uses the selected text as input.

Note
You can terminate standard input at any time by pressing Command-Enter or Command-Shift-Return. This is true for all commands that accept standard input. •

Output

This section describes the output of the command. Output can include none (no output), one or more files, or standard output. Text processors usually write their output to standard output. For example, the Sort tool is a text processor that writes sorted text lines to standard output.

Any important information about diagnostic output appears in the "Output" section. You need only remember that, unless otherwise noted, errors and warnings are always written to diagnostic output. Many scripts, tools, and built-in commands also include a progress option (-p), which writes progress and summary information to diagnostic output.

Status

This section lists the status codes that the command returns and their meanings. Note that these status codes are returned in the {Status} variable and can be retrieved by using the command line

Echo {Status}

A value of 0 indicates that no errors occurred; anything else indicates an error.

Typical values are:

In general, a positive status code indicates an error in the usage of a particular MPW script, tool, or built-in command, while a negative status code indicates MPW Shell errors. An exception to this rule is -9, which indicates a user abort. This status code can be returned by any script, tool, or built-in command, any of which can be aborted by typing Command-period.

Parameters

This section describes all the parameters that can be used with a particular script, tool, or built-in command. If multiple parameters are position dependent, they appear in the order in which they must appear on the command line.

Although parameters precede options on the syntax line throughout the manual, MPW itself is indifferent to this ordering. Unless otherwise noted in the text, you can place options in any order with respect to the parameters.

There are some cases when the order of parameters themselves is significant. For scripts, tools, and commands that have more than one type of parameter on their syntax line, the order in which you place the different types of parameters with respect to each other is significant. For example, in cases in which you can specify a selection expression and a window, such as

Cut selectionExpression [window] [-c count]

the selection expression must precede the window name.

Be careful not to confuse a parameter type with a specific instance of that parameter. A parameter such as file1 [file2]…, which indicates that you can specify more than one file, is considered to be a single parameter type; myFile and yourFile are specific instances of that parameter. The syntax line for CreateMake

CreateMake programName sourceFile… [options]

indicates that you must specify the program name before listing the source files to be combined into that program. The files, however, can be specified in any order. In other words, these two command lines are equivalent:

CreateMake MyProgram myFile yourFile
CreateMake MyProgram yourFile myFile

Options

This section describes all the command line options that can be used with a particular script, tool, or built-in command. You use them to tailor a command to your needs. Options are listed in alphabetical order except in cases where a functional grouping is more helpful.

You can distinguish options to the commands from parameters (which are most frequently filenames) by the hyphen (-) that immediately precedes an option. This hyphen is part of the option and must always be included.

Options can have their own parameters, which are also described in this section. In general, if you specify an option that has parameters, you must also specify at least one of its parameters.

Alias Resolution

MPW allows Finder aliases to be used as part or all of a pathname or filename. A Finder alias is an object that represents another file, folder, volume, or server volume. The object that a Finder alias represents is called the target of the alias. A Finder alias should not be confused with aliases to commands that you create using the MPW Alias command; these are called command aliases.

Finder aliases can occur at any point in a path. Embedded aliases, which occur embedded in or at the beginning of (rather than at the end of) a pathname, are always resolved. A leaf alias is a Finder alias whose name appears at the end of a pathname. Not all commands resolve leaf aliases.

Most MPW commands that deal with files resolve Finder aliases on those files. For example, current_project is the Finder alias in each of the following valid command lines:

SC :current_project:current_file.c -o :current_project:obj:current_file.o

DumpObj :current_project:obj:current_file.o

You may substitute a pathname containing a Finder alias for a window name in commands that accept or require window names. However, be aware that window names are different from filenames in MPW. A window name is equivalent to the full pathname of the file that is associated with the window.

There are a number of special-case commands that do not resolve all Finder aliases in a pathname. Usually these commands resolve embedded aliases but not leaf aliases. For instance, Projector commands, because they must be able to check in Finder alias files, generally do not resolve leaf aliases. Another example is the Duplicate command which now has special options that let you control whether the Finder alias file itself or the target of the Finder alias file is duplicated. Commands that have special alias resolution characteristics or options have these features called out in the "Alias Resolution" section. See Introduction to MPW for more details about Finder alias resolution in the MPW Shell.

Examples

Using one or more examples, this section illustrates the uses of a script, tool, or built-in command, either alone or within enclosing scripts. Examples proceed from relatively easy tasks (often the default behavior) to more complicated ones (using multiple options) that are custom designed for a specific purpose.

Limitations

This section is included for some commands to point out certain limitations, warnings, or special cases of which you should be aware.

See Also

This section provides references to other relevant information, usually related commands or topics discussed in Inside Macintosh.

Appendixes

Appendix A lists the operators used in MPW expressions and their order of precedence.

Appendix B lists selection expressions and regular expressions as they are used in selection expressions.

Appendix C is a dictionary of special characters and operators.