commands: A discussion of the syntax of IRAF commands

Package: language

Syntax

In command mode (normal interactive commands):

taskname arg1 ... argN par=val ... par=val redir

In compute mode (algebraic mode, for expressions and procedures)

taskname (arg1, ... argN, par=val, ... par=val, redir)

Elements

taskname

The name of the task to be executed.

argN

The positional arguments to the task. An argument may be any expression; in command mode, a parameter name must be enclosed in parenthesis to avoid interpretation as a string constant (e.g., filename).

param=value

Keyword equals value assignment. The value of the parameter named on the left is set equal to the value of the expression on the right. Keyword equals value assignments must follow any positional arguments. To save typing, boolean (yes/no) parameters may be set with a trailing + or -, e.g., "verbose+" is the same as "verbose=yes".

redir

A file redirection argument, e.g.:

> file          spool output in a file
< file          read input from a file (rather than the terminal)
>> file         append the output to a file
>& file         spool both error and regular output in a file
>>& file        append both error and regular output to a file
>[GIP]          redirect graphics output to a file, e.g, >G file
>>[GIP]         append graphics output to a file, e.g, >>G file

Description

A CL command is an invocation of a predefined CL task. A task may be one of the numerous builtin functions (e.g. time, lparam, ehistory), a task defined in a package supplied to the user automatically, (e.g., the directory task in the system package), or a task the user has defined himself, using the task directive.

The entire argument list of a command, including file redirection arguments may be enclosed in parentheses. This forces all arguments to be evaluated in compute mode. In command mode arguments are delimited by spaces and most characters may be included in strings without need to quote the strings. In compute mode arguments are delimited by commas, all strings must be quoted, and all CL arithmetic and other operators are recognized. Command mode is the default everywhere, except within parenthesis, on the right hand side of a "= expr" (inspect statement), or within procedures. The sequence #{ <statements> #} may be used to force interpretation of a series of statements in compute mode.

1. Arguments

The task name may be followed by any number of positional arguments and/or keyword=value type arguments, switches, or i/o redirection arguments. The positional arguments must come first. Arguments are most commonly simple numeric or string constants, but general expressions are allowed. Some examples of arguments follow.

"quoted string"
(cos(.5)**2 + sin(.5)**2)
"work" // 02
k + 2                   # valid only in compute mode
i+3                     # valid in both modes
(i+3)                   # same answer in both modes

Within an argument the treatment of unquoted strings depends upon the current mode. In command mode the string is assumed to be a string constant, while in compute mode it is taken to be the name of a parameter. For example, in command mode the expression

i+3

is equivalent to the string "i+3", while in compute mode this would evaluate to the sum of the value of the parameter "i" plus 3. To force evaluation of a string like i+3 as a arithmetic expression, enclose it in parenthesis.

Positional arguments are assigned to the parameters of the task to be executed. The position of each task parameter is determined by the order of the arguments in the procedure declaration of a procedure script task, or by the order of declaration of the parameters in a parameter file for other tasks.

Hidden parameters cannot be assigned values positionally (one must use keywork assignment). It is an error to have more positional arguments than there are corresponding parameters in the task, but omitting positional arguments is legal. In compute mode, arguments may be skipped using commas to mark the skipped arguments, e.g. a,,b.

Following the positional arguments the user may specify keyword arguments. All parameters of a task, including hidden parameters may be assigned to using keyword arguments. The form of a keyword argument is

param=expr

where param is the name of the task's parameter, and expr is any legal CL expression. If the parameter is boolean an alternative syntax called the "switch" syntax is available:

param+          # same as param=yes
param-          # same as param=no

A given parameter may only be assigned to once in a command line.

2. I/O Redirection

Following the argument list the user may specify one or more file redirection parameters. This permits the altering of standard i/o streams for this command only. Note that the file name specified is interpreted according to the current mode, i.e.

> file

sends output to a file with the name "file" in command mode, but uses the value of the parameter "file" as the filename in compute mode.

The output from one command may also be directed to the input of another using pipes. The syntax is

    command1 | command2
or
    command1 |& command2

Here command1 and command2 are full commands, including the taskname and all arguments. In the first example the standard output of command1 becomes the standard input of command2, while in the second the both the standard and error output are sent to command2.

Once two commands have been joined by a pipe they function effectively as a single command, and the combined command may be joined by pipe to further commands. The resulting "command block" is executed as a unit, and may be submitted as a background job by following the command block with an "&".

Examples

1. Simple positional arguments only (command mode).

cl> copy file1 file2

2. Simple positional arguments only (compute mode).

cl> copy ("file1", "file2")

3. One positional argument, i.e., the string "file1,file", and one keyword=value type argument. Note that string need not be quoted even though it contains the comma, provided there are no spaces in the string.

cl> lprint file1,file2 device=versatec

4. Syntax for i/o redirection in compute mode, as in a script.

type ("*.x", > "spool")

5. The same command in command mode.

cl> type *.x > spool

6. Use of an arithmetic expression in command mode; the scalar value of the expression given as the third positional argument is added to the value of every pixel in image "pix1", writing a new image "pix2" as output.

cl> imarith pix1 + (log(4.2)+10) pix2

Many additional examples may be found in the EXAMPLES section of the manual pages throughout the system.

See also

procedure, parameters