diff options
Diffstat (limited to 'doc/clman.ms')
| -rw-r--r-- | doc/clman.ms | 1287 |
1 files changed, 1287 insertions, 0 deletions
diff --git a/doc/clman.ms b/doc/clman.ms new file mode 100644 index 00000000..62252841 --- /dev/null +++ b/doc/clman.ms @@ -0,0 +1,1287 @@ +.RP +.TL +CL Programmer's Manual +.AU +Elwood Downey +Douglas Tody +George H. Jacoby +.AI +.K2 "" "" "*" +December 1982 +(revised September 1983) +.AB +This document serves as a programmer's manual for the IRAF Command Language +version 1.0. +CL tasks, packages, parameter files, modes, expressions, statements, +abbreviations, environment variables, command logging, error handling and +directives are discussed. The special CL parameters are listed. +A example of a complete CL callable program is given. +.PP +This manual is a programmer's guide, not a user's guide or a technical +specification of the CL. Information about other programming tools +within the IRAF system, such as the SPP language and compiler and the +program interface, is given only to the extent required to introduce +the examples. +.AE + +.NH +Introduction +.PP +The Command Language, or \fBCL\fP, serves as a command and runtime supportive +interface between the user at his computer terminal and the application +programs he is executing. The user types his commands to the CL and it does +whatever task and file manipulations are necessary to carry out the commands. +.PP +The user and the applications task do not communicate directly; they +communicate only through the CL. +Once started, a task requests parameters by name from the CL and the CL responds +with the value of the parameter. +To get that value, the CL may have had to read a parameter +file, query the user, do range checking, extract a value from a command line or +perform other actions. +.PP +All CL/task communications take place via an interprocess communications +link between the CL process and the process containing the applications task. +Standard input, output, error, and plotting channels are multiplexed on this +link and managed by the CL. The CL process and the applications package +process execute concurrently. +.PP +This arrangement relieves each new application program from having +to provide user interface functions that are often rewritten +directly each time, such as command line parsing, command and parameter +abbreviations, and levels of interaction to accommodate both novice and +experienced users. +In addition, the CL provides a common environment for running all tasks +with services such as executing programs with their input and output +redirected to files or to other programs, managing parameters for each command, +handling lists of values in lieu of a simple parameter, logical device +and file name assignments, and help facilities. The CL is a simple programming +language in its own right, with conditional and repetitive command execution, +parameter expressions and a calculator. +.PP +While intended to support scientific reduction and analysis applications at +Kitt Peak and elsewhere, the CL can serve any project that involves running +programs as commands with arguments. Every effort has been made to make the CL +as portable as possible. The link between the CL and the task it +is running is character oriented and allows the task to to be run directly +without any support from the CL if desired. +This link may be simulated by any program that wants to run as a task +under the control of the CL. However, any task written in the SPP +language (which is Fortran based) will automatically include all the i/o +facilities required to interface to the CL. + +.NH +Terminology +.PP +This section defines most of the terminology associated with the CL. +Words in \fBboldface\fP are part of the actual terminology of the CL. +Those in \fIitalics\fP are more descriptive in nature and serve only to +name a representative item. + +.NH 2 +Physical and Logical Tasks, Scripts +.PP +A task runnable under the CL is a file +containing either the executable program itself, or a text file containing +a \fBscript\fP written in the CL language. Either of these is referred to as +a \fBphysical task\fP since they are true files on the host computer. +The executable form consists of one or more \fBlogical tasks\fP but +the script file is always considered exactly one logical task. +The general terms \fBcommand\fP and \fBprogram\fR refer to one of +these logical tasks. In order to know just how to go about running the command, +the CL has a "task" declaration that indicates in which +file the task resides, and whether it is in an executable or script form. +Once declared, the logical task commands are used the same way regardless of +whether they reside in an executable object file or a script. +.PP +In order to manage itself, there are a few commands that the CL does +itself, such as the "task" command mentioned above. These built-in commands +are referred to as CL \fBdirectives\fP, but only as a means of classifying +them as a group. They act and are used very much like regular commands. +In this way, they have the same syntax rules and their diagnostics work in the +same fashion. Since they are built into the CL program itself to achieve +intimate knowledge of its internal data structures or simply to increase +efficiency, the set of directives is not extensible by the user. +.PP +Thus, there are a variety of ways a command may get executed. +It is no accident that there is often no easy way to tell how a command is +implemented. + +.NH 2 +Packages +.PP +Ostensibly, tasks are grouped into packages. This provides a +logical framework to organize a large body of commands in a large system +and also serves to address the problem of redefinitions. +The CL directives and a few utility programs are located in the root +package, called \fBclpackage\fP, and is always present when the CL starts up. +Some of the commands in the root define more packages when run. They +are script tasks that define a package and some tasks in that package. +By convention, the name of the package defined by a script, the logical task +and the script physical task file name are all the same. +.PP +Any package defined to the CL may become the \fBcurrent package\fP. The prompt +issued by the CL includes the first two characters of the current package. +When a command is typed to the CL, it looks in the tasks +of the current package first, then through all tasks in lower packages towards +the root clpackage for the logical task with the given name. Tasks defined +in packages defined farther away from the root are searched last. This +\fBcircular search path\fR provides some measure of control over command +scope. +.PP +Wherever a task name is expected in the CL syntax, the package may be explicitly +specified in the form \fIpackage.task\fP so that only tasks defined +in that specific package will be considered in the search for the given +logical task name. This form allows package names farther away from the root +than the current package to be accessed. It also provides an unambiguous way to +reference a task when the task name appears in more than one loaded package. +If the name of a loaded package itself is given as a command, then it +simply becomes the current package (see the package directive in \(sc12). + +.NH +Parameter Files +.PP +A separate file, the \fBparameter file\fP, may exist for each logical task. +It contains a description of each of the parameters used by the task that +should be known and managed by the CL. (These are not the same as variables +declared in the source program for the task.) The parameter files are the +permanent record of task parameters. When a parameter value is permanently +changed, as with an assignment or when in learn mode, the CL makes a local copy +of the parameter file with the new value. Thus, running tasks imply CL reads +and writes to parameter files as well as execution of the task. +.PP +A logical task need not have a parameter file. If a task makes a request to the +CL for a parameter and the CL knows the task has no parameter file a fake query +for the the parameter will be issued by name (see \(sc4 for more on queries). +All of the range, prompt, learning and type checking advantages of real +parameters will be lost, however. Thus, a parameter reference by a task +that does not have a parameter file at all is not considered an error. This is +different than a reference to a nonexistent parameter by a task that does have a +parameter file, which is an error. + +.NH 2 +Location and Name of Parameter Files +.PP +The parameter file for a logical task may be in two places. The CL first +searches the \fBuparm\fP directory, then the directory containing the physical +task. All physical tasks for a package, including the script task that defines +it, are usually in one directory, often referred to as the \fBpackage +directory\fP. +.PP +Uparm is an environmental entry used by the CL when accessing parameter files. +If it does not exist, the current directory is used. +Uparm may either be another environmental reference to a directory or be in +host-dependent format (see environment, \(sc8). +.PP +The names of parameter files written out, either to uparm or to the current +directory, are formed by concatenating the first two and final characters +of the package name, an underscore, the name of the logical task, and the +extension ".par". +For example, when the parameter file for a task \fItxyz\fP in package +\fIpxyz\fP is written, it is named \fIpxz\(ultxyz.par\fP. +The package prefix is prepended to avoid file name +conflicts if two tasks in different packages happen to have the same name. +Since local copies have the package prefix, the CL looks for them before ones +without the package prefix. + +.NH 2 +Parameter File Format +.PP +The parameter file for a logical task consists of comments, blank lines, and +parameter declarations. These may appear in any desired order. +Comment lines are those that begin with the sharp character, #, +and signal that it and all remaining characters on that line should be +ignored. The maximum line length is 132 characters. +.PP +Parameter declarations within the parameter file take the form +.DS + name, type, mode, value, minimum, maximum, prompt +.DE +where all fields from value on are optional. The comma and the end of the line +itself both serve as a field delimiter and thus a comma is not necessary after +the last field, whatever it is. +.NH 3 +name +.PP +This is the name of the parameter. There is no length limit other than the +overall line length limit consideration. This is the name by which the +parameter will be known to the task and to the CL. It must begin with a +letter or a dollar sign, $, but the remaining characters may be any +combination of letters, numbers, underscore, \(ul, and dollar, $. Casual use +of $ is not recommended, however, as it is used to make environment references +(see \(sc8). +.NH 3 +type +.PP +The type field indicates how the parameter is to be stored. It also implies +some information about what values are acceptable and how they are entered, +as discussed below under value. +.DS +.TS +; +ci ci +l l. +code meaning +.sp +b boolean +i integer +r real +s string +f or f\fIxx\fR file name +struct structure +gcur graphics cursor +imcur image cursor +.TE +.DE +.PP +The codes \fBb\fP, \fBi\fP and \fBr\fP indicate the usual boolean, +integer and real types. They are discussed further in the value section, +below. +.PP +There are several types that manipulate character strings. +The characters themselves may be anything from the ASCII set. +The type \fBs\fP is the simplest and is an ordinary character string. It is +typically used for names, flags and messages. +.PP +The \fBf\fP type is like s except that it is limited to +legal file names on the host operating system, after possible environment +substitution. The f may optionally be followed by any reasonable combination +of the characters \fBe\fP, \fBn\fP, \fBr\fP, or \fBw\fP. +These indicate that checks should be made of the file name before it is +used that it exists, does not exist, that it exists and is readable and that +it exists and is writable, respectively. \fBStruct\fP is also like s but +its value is the entire next line of the parameter file. +.PP +\fBGcur\fP and \fBimcur\fP are +similar to struct but are expected to be of the form "x y char" to be usable +as cursor coordinates. +A gcur or imcur parameter will always read from the hardware +graphics or image display cursor if it is in query mode. +.PP +If the type is preceded by a star, *, the parameter is \fBlist-structured\fP. +When the parameter is referenced, the value will come from +a file, the name of which is the fourth field of the parameter declaration. +All of the basic types may be list-structured. +.NH 3 +mode +.PP +This field indicates what actions are performed when the parameter is +referenced or assigned. +The topic of modes is important to the CL and is covered more thoroughly +elsewhere (\(sc4) Briefly, query mode generally causes the user to be +queried each time the parameter is referenced. +Learn means that all changes to the parameter will be permanent. +Auto mode means that the effective mode of the parameter should be whatever +the mode is of the task that is using the parameter; auto mode defers +mode selection to the task, or CL level. +Hidden means that the existence of the parameter will not be +evident to the user unless its value is not acceptable. +.PP +The mode field may be any reasonable combination of query, learn, +auto and hidden. These may be spelled out and separated with plus signs, +, +or abbreviated to one character and run together. For example, +.DS + ...,auto+learn,... +and + ...,al,... +.DE +and equivalent. +.NH 3 +value +.PP +This field is optional. The value field is the initial or \fBdefault\fP value +of the parameter. It has various characteristics depending on the type of the +parameter. If it is absent, the parameter will be marked as undefined and will +cause an error if used in an expression. A special entry, \fBindef\fP, is +allowed that marks the parameter value as being indefinite, but not undefined. +It may be used with all types. Acceptable constants in the value field are +like those allowed by the CL in expressions (see \(sc5.1). +.PP +For boolean parameters, it should be either the three characters \fByes\fP or +the two characters \fBno\fP. +.PP +Integer and real parameters are as one would expect. Real constants need not +include a decimal point, ., if not required. +.PP +For string and file name parameters, the field +extends from the comma following the mode field to the next comma, or the end +of the line if none. It may be surrounded by single or double quotes, ' or ", +but these are not necessary unless the string is to include a comma. +The length of the storage allocated for the string will be the minimum of +30 characters and the length of the initial value, up to a maximum of 132. +Later changes to the value of the string will be silently truncated to the +amount thus established. +.PP +Structs and the cursor types use the value field to indicate the number of +characters of storage to allocate to hold the value of the parameter. The value +is a string consisting of the entire next line of the parameter file. +If no number is given in the value field, then just enough storage to hold the +next line will be allocated. If the number is larger, this allows +the value to grow longer than the length of the next line. Since dynamic +string storage is not used in the CL, the length of all strings is fixed +and using the value field in this way permits a short initial value but allows +for later growth. +The length of string storage is limited to 132 characters. +It is an error to explicitly specify a storage length shorter than the initial +value. +.PP +The value field for list-structured parameters is the name +of the file containing values for the parameter. This name is subject to the +same restrictions as a parameter of type fr and environmental references are +allowed. +.PP +Thus, the value field entry for a parameter in a parameter file has several +different uses, depending on the type of the parameter. +The term \fBvalue\fP refers to that which is used +when the parameter is used in an expression and \fBvalue field\fP refers +specifically to the fourth field of the parameter specification. +Because of this multiple usage, the CL recognizes this field with several +names, as described under parameter references (\(sc5.2). +.NH 3 +minimum \fRand\fP maximum +.PP +These two fields work together to specify a validity range for the value of +the parameter. They are ignored for all types except integer, real, and file +name parameters and follow the same rules as the value field for these type +parameters. Their application to filenames is to test for a simple lexical +ordering. If they are both set when the parameter is referenced, then a query +will be generated if the value of the parameter is not within range. No range +checking is done if either the minimum or maximum are undefined or if min > +max. If the parameter is list-structured, then the range checking is +applied to the entry read from the file. +.NH 3 +prompt +.PP +This field behaves like a string and extends from just after the sixth +comma in the parameter spec to the end of the line. It may be quoted. +As explained more thoroughly under query mode, its purpose is to provide a +meaningful prompt for the parameter during a query. If no prompt string is +given, then the query will just use the name of the parameter. As with strings, +the length of the prompt implies the amount of static storage to allocate; +later changes to the the prompt will be silently limited to this length. + +.NH +Modes +.PP +The CL supports three modes of operation, query, learn and auto. +.PP +\fBQuery\fP mode is the most interactive and is the standard mode when +the CL is being used interactively. +It causes each parameter referenced by a task, or script, to +produce a query on the terminal consisting of the prompt string for that +parameter, its current value and minimum and maximum values, if set. If there +is no prompt string, then the name of the parameter is used. When the user +sees this query, he may type a simple return to accept the current value or +type a new value. +New values that are entered in this way are checked for validity immediately +with regard to type and range, and the query repeats until a reasonable value +is entered. +.PP +A query will be generated regardless of the effective mode of the +parameter if it does not meet its range requirements. On the other hand, a +query will be prevented if the parameter was set on the command line, again +assuming it is not out of range. Thus, the CL relieves the +application program from some of the burden of verifying its parameters. +.PP +\fBLearn\fP mode retains the values of parameters across task runs +and even across CL sessions. The default values of parameters come from their +entries in the task's parameter file. If learn mode is not in effect, changes +to parameter values by way of command line arguments to the task or queries +do not cause the parameter file to be updated and so the values revert back +to their defaults as soon as the task ends. +Learn mode makes these changes permanent by updating the parameter file for +the task. +.PP +\fBHidden\fP mode applies only to parameters. It prevents queries from being +generated even if the effective mode for the parameter is query, unless its +value is out of range. Hidden mode also prevents +the default value from ever being "learned". The only way to change the default +value of a hidden parameter is by an assignment statement. +Hidden mode is useful for parameters that are rarely if ever changed to hide +their existence from all but experienced users. + +.NH 2 +Determining Modes +.PP +The modes exist independently in a three level hierarchy: the +parameter, the current task, and the CL itself. Whenever a parameter is +referenced, its \fBeffective mode\fP is calculated. To determine +the effective mode, the mode settings of the three levels are used starting +with the parameter level. If the +mode of the parameter is query or learn, that is the effective mode. +If the parameter's mode is \fBauto\fP, then the effective mode is that of the +current task unless it too is in auto mode in which case the effective mode is +that of the CL. If all levels are auto, the effective mode is auto and +neither query nor learn effects will occur. +.PP +Thus, each layer of the hierarchy, starting at the parameter level, defers +to a higher level until it finds either query or learn (or both). +Note that the presence of hidden mode at the parameter does not alter this +process but rather serves to override query mode, should it be found at any +given level. +As a practical example, all the auto-mode parameters in a task can +effectively be put into query mode at once by setting the mode once at the +task level to query. + +.NH 2 +Setting and Changing Modes +.PP +The modes themselves are set in different ways at the parameter and task +level. The mode for a particular parameter is accessed as a field of that +parameter called \fBp\(ulmode\fP. It may be abbreviated. The mode of a task +is in a parameter \fBmode\fP, of type string, that contains any reasonable +combination of the letters \fBq\fP, \fBl\fP, \fBa\fP and \fBh\fP. This +parameter may be declared +and initialized as desired in the parameter file for the task just like any +other parameter. If it does not appear in the parameter file for a task when +it runs, it will be manufactured and supplied with a default setting of 'ql'. +This is the only case of a parameter added by the CL to a parameter list for a +task. One of the parameters to the CL itself is also \fBmode\fP, and this +serves as the mode of the CL, the highest level in the mode hierarchy. +.PP +As a convenience for naming modes, four CL string parameters \fBquery\fP, +\fBlearn\fP, \fBauto\fP and \fBhidden\fP are defined to be the +single-character strings 'q', 'l', 'a' and 'h'. +Examples of setting modes at the CL, task, and parameter +levels: +.TS +center; +l l. +mode \(eq 'ql' # set CL mode to query, learn +package.task.mode \(eq 'a' # set given task mode to auto +package.task.param.p\(ulmode \(eq 'ql' # set given parameter's mode +mode \(eq query + learn # use pre-defined string params +mode +\(eq query # add query +.TE +.PP +The mode of a parameter may also be changed during a query for that +parameter. If the response to the query begins with a percent, %, then +the mode for the parameter may be set using the same format as that used +in the parameter file mode field (see \(sc 3.2). +This is useful during program development for making a parameter hidden once +its default value has been determined. + +.NH 2 +Recommended Mode Settings +.PP +The recommended default modes are auto and learn for the CL itself, query for +each task and auto or hidden for the parameters. Auto mode for all non-hidden +parameters in a task allows them all to be changed at once by changing the +mode of the task. +The user will rarely do more than change a task's mode to auto, +hide a parameter (by use of the %h response to a query, \(sc4.2), +or reset all parameters of a task to their original default by +deleting its parameter file from the uparm directory (see \(sc3.1). + +.NH +Expressions +.PP +The CL allows expressions wherever a simple variable might appear. This applies +only to the language, however, not, for example, in the parameter files. +Expressions are the usual kinds of combinations of constants, variables, +intrinsic functions, operators, parentheses and expressions (recursively). + +.NH 2 +Constants +.PP +Boolean constants are entered as the three characters "yes" or the two +characters "no". There are no true and false constants. +.PP +Integers are an uninterrupted sequence of digits; a trailing `b' denotes an +octal constant. +.PP +Floating point constants are as in most languages but a decimal point is not +necessary if not needed. 5, 5., 5e0, .5e1 and 5.e0 are all equivalent. +Sexagesimal notation may also be used to create a floating point value. +A negative value is indicated by a leading minus sign, -, leading zeros are +not necessary and the seconds field is optional. +1:23:4.56, -12:3:4.5, 1:2:3 and -12:34 are all acceptable. +.PP +Strings are zero or more characters surrounded by single or double +quotes, ' or ". The quotes are not needed in two cases. One is in response to +a query. In that case, everything up to the end of the typed line is taken to +be the string. If the quotes are used, however, they will be discarded. The +other case is when specifying the value of a parameter on the command line +when running a task. If the corresponding parameter is of type string, filename +or is list-structured and the string need not be used in an expression, then +the quotes are optional. +.PP +An additional constant, \fBindef\fP, is known to the CL. This is a +special setting that means indefinite, as opposed to being truly undefined. +The latter causes an abortive error if encounted during the evaluation of an +expression. A parameter that is merely indefinite does not result in an error +or a query and is useful for indicating the value should be ignored, but +propagated through an expression. +.PP +See the discussion of the intrinsic scan function (\(sc 5.3) for two +additional constants, EOF and stdin. + +.NH 2 +Parameter References +.PP +The "variables" in CL expressions are task parameters. To reference a +parameter, the most general form is \fIpackage.task.param.field\fP. +This form may be used anywhere a parameter is legal. +Only the parameter name portion is required. +If the package and task are not specified, the parameters for the current +task, then the current package and finally those of the CL itself are searched. +The parameter is not found if it does not exist in one of these three places. +.PP +If the field is not specified, then the meaningful value +of the parameter is used, as explained under the discussion for the value +field of a parameter (see \(sc3.2). The possible fields are p\(ulname, +p\(ultype, p\(ulmode, p\(ulvalue, p\(ulminimum, p\(ulmaximum and p\(ulprompt. +In addition, the value field may also be given as p\(ullength, p\(uldefault +or p\(ulfilename. These are intended for use with parameters of type struct or +cursor, integer or real, or filename (or list-structured). These aliases are +not strictly enforced but are provided to improve readability and reliability +in CL commands, particularly within script tasks. +Each portion of the parameter reference may be abbreviated separately (see +\(sc7). +.PP +The result of using a logical operator is either the +boolean true or false. These values are represented internally as 1 and 0, +respectively. Although it is bad programming practice to make use of that fact +in further arithmetic operations, it is not prohibited. + +.NH 2 +Intrinsic Functions +.PP +The CL provides a set of standard intrinsic functions that may be used +in expressions. They are much like those found in most math libraries and are +listed here only for reference. As with commands, they may be abbreviated but +unlike commands their arguments must be enclosed in parentheses. +Calling them with illegal arguments or producing underflow or overflow +generates an error. +Their argument(s) may be integer or real and they will try to return the same +type as their argument if no loss of precision would result. +.TS +center; +l c l. +Usage Number of Description +\^ Arguments \^ +\_ \_ \_ +abs(x) 1 absolute value +atan2(y,x) 2 arc tangent, with proper quadrant +cos(x) 1 cosine +exp(x) 1 natural exponentiation +frac(x) 1 fractional part +int(x) 1 integral part +log(x) 1 natural logarithm +log10(x) 1 common logarithm +max(x1,x2...) > 1 maximum +min(x1,x2...) > 1 minimum +mod(x,modulo) 2 first arg modulus the second +round(x) 1 nearest integer, rounded away from zero +scan(l,p...) > 1 free-format read; see below +sin(x) 1 sine +sqrt(x) 1 square root +tan(x) 1 tangent +.TE +.PP +The \fBscan\fP intrinsic function reads from its first argument as a string +and assigns the pieces, suitably type cast, into the remaining arguments. +If the first argument is a list-structured parameter, the next line of the file +is read and scanned, unless query mode is in effect in which case the user is +always prompted for the line. If the first argument is a string-type parameter, +including filename, struct, gcur or imcur, then the string is scanned. This +serves as an in-core read, much like a Fortran decode or a C sscanf function. +Spaces, tabs and commas are recognized delimiters. If the last +target parameter is a string, it will receive the remainder of the string being +scanned. +.PP +Scan returns as its function value the number of successful conversions. +Reading from a list and encountering eof will cause scan to return a count +of zero. There is a pre-defined constant in the CL, \fBEOF\fP, +which is simply zero; it may be used to make the test more explicit. +There is another CL constant, \fBstdin\fP, which may be used as the first +argument to cause scan to read from the standard input. Examples of scan are +.DS +.cs 1 22 +# Read gcur and print radii until end of list. +while (scan (gcur, x, y, remainder) >\(eq 2) + \(eq sqrt (x\(**\(**2 + y\(**\(**2) + +# Read until EOF is detected. +while (scan (file, line) !\(eq EOF) + \(eq line +.DE +.cs 1 + +.NH 2 +Operators +.PP +The following is a list of the arithmetic and logical operators available in +the CL. They are the same as in the SPP language. +.TS +center; +l l l. +Operator(s) Type of Result Function +\_ \_ \_ ++,\ \(mi,\ \(**,\ / numeric the usual, but see below for + with strings +\(**\(** numeric raise to power +% numeric first expression modulus the second; like mod() +<,\ > logical less than, greater than +<\(eq,\ >\(eq logical less than or equal, greater than or equal +\(eq\(eq,\ !\(eq logical equal, not equal +&& logical logical `and' +|| logical logical `or' +! logical logical `not' +.TE +For those familiar with C, note the absence of \(eq. It is not considered +an operator that produces an l-value but may only be used in an assignment +statement. +.PP +The + operator can be used to concatenate strings. If only one of its +operands are strings, the other will be converted first. If one operand is a +string, the other is an integer and the string operand contains an integer on +the same side as the integer operand, then an arithmetic addition will be +performed as well. For example, +.RS +.TS +; +l l l. +'stringa' + 'stringb' \(-> 'stringastringb' +'string1' + 'string2' \(-> 'string1string2' +'string1' + 2 \(-> 'string3' +2 + 'string1' \(-> '2string1' +2 + '9string' \(-> '11string' +'string' + boolean\(ulparam \(-> 'stringyes' (or 'stringno') +.TE +.RE +Points, ., in strings with digits are not recognized as floatings so trying to +add floatings to strings, while not prohibited, probably doesn't do anything +useful. + +.NH +Statements +.PP +Statements fall into the following categories: assignments, commands, +immediate and flow control. These will are discussed separately, below. +.PP +Statements may be delimited by newline or semicolon, ;, and may be grouped +with brackets, { and }. Nesting is supported. +Comments begin with the sharp character, #, which indicates +that all characters from it to the end of the line are to be ignored. +Statements that are too long to fit on a line may be continued by ending +the line with a backslash, \\\, or they are automatically continued if the +last character is a comma. +.PP +When used from a terminal, the CL issues a continuation prompt, >>>, when +the outermost statement has not been completed. This indicates input +is still being accepted and parsed. No work will actually be done until +the CL sees a complete input statement. + +.NH 2 +Assignment Statement +.PP +An \fBassignment\fP is a statement of the form \fIparameter \(eq expression\fP. +The parameter is always permanently changed by an assignment +statement, whether or not learn mode is in effect. +.PP +Two additional forms of assignments are provided that also perform arithmetic, +\fIparam +\(eq exp\fP and \fIparam \(mi\(eq exp\fP. These are equivalent to +\fIparam \(eq param + exp\fP and \fIparam \(eq param \(mi exp\fP. They are more +efficient as well as more convenient. These forms also permanently change the +parameter. +.PP +All forms of the assignment statements will cause an error if the result of +\fIexp\fP is undefined. Thus, the CL will never allow a parameter to be set +to an undefined state. The only way to get an undefined parameter is by not +setting it in a parameter file (see the value discussion in \(sc3.2). +Assignment statements are the only way a hidden parameter may be permanently +changed. + +.NH 2 +Commands +.PP +A \fBcommand\fP is the basic means of running logical tasks. It consists of +the name of the logical task, possibly with arguments, and pipes to more +commands or io redirections. The arguments to the command, if any, may +optionally be surrounded by parentheses. These are recommended in scripts. +Command lines may be continued on the next line automatically if they end +with a comma or a backslash. + +.NH 3 +Command Arguments +.PP +The arguments to a command are given as a comma-separated list and come in two +basic forms, positional and absolute. +The \fBpositional\fP form is any general expression. +The expressions will be evaluated and assigned one-to-one to the corresponding +parameters of the task, as defined by their order in the task's parameter file, +not counting hidden parameters. Only the value of the parameter may be set in +this manner. +A lone comma may be used as a placeholder and skips a parameter without +changing it. Parameters not reached in the matching are also not changed. +.PP +The \fBabsolute\fP form is an assignment, \fIparameter \(eq expression\fP, +where the parameter must be a parameter of the task being run. This is useful +when a parameter value is to be changed but its +position in the argument list is not known or it would be awkward to arrive +at its position by a large number of positional arguments. Since +the parameter is explicitly named, fields other than the default value +may be changed with the absolute form. +.PP +Another form of absolute argument is the \fBswitch\fP. It is +a shorthand way of specifying the truth value of a boolean parameter. A +switch consists of the parameter followed by a plus, +, to set it to yes, or a +minus, \(mi, to set it to no. Thus, these two forms are equivalent ways of +turning off the boolean parameter \fIoption\fP: +.DS + task option\(eqno + task option\(mi +.DE +.PP +While they may be used together, all positional arguments must precede +absolute arguments. Here are examples of using the positional and absolute +forms together: (note the parens in the second example are optional) +.DS + task1 x, task2.param, op+ + task3 (a, b, c, param2\(eqx+y, op3\(mi, param3\(eqtask4.x/zzz) + task4 x, y, z, op1+, op2\(eqyes +.DE +.PP +Parameters changed on the command line will have their new values as long as +the command is executing. If learn mode is not in effect for the parameters, +they will revert back to their original values when the task ends or if the +task aborts for some reason. + +.NH 3 +Pipes and Redirections +.PP +A \fBpipe\fP connects the standard output of one task to the standard input of +another task. A pipe is indicated by separating the tasks +with a vertical bar, |. As many pipes in a series may be used as necessary. +\fBRedirections\fP of the standard input and output of a task from or to files +are also supported. +.PP +The standard input may come from a file by indicating the filename after the +less-than symbol, <, and the standard output from the last task in a pipe +sequence may be sent to a file by giving its name after the greater-than +symbol, >. Two greater-thans, >>, cause the output to be concatenated to the +end of the file. If the output redirection symbol is preceded by an ampersand, +&, then the standard error will also be included, as in &|, &> and &>>. +Output redirections, but not pipes, are considered absolute arguments to the +task so they must follow any positional arguments and must be set off by +commas. For example, task1 reading from file t1input piped to task2 +writing to file t2output is done as +.DS + task1 x,y,z, < t1input | task2 x2, y2\(eqa+b, > t2output +.DE + +.NH 2 +Immediate Statement +.PP +This is the \fBcalculator\fP mode of the CL. It consists of the basic assignment +statement without the left-hand side parameter, as in "\fI\(eq exp\fP". +Instead of computing the expression and assigning it to a parameter, +the result is simply sent to the standard output. This may in turn be +redirected if the calculation is being done from a script. + +.NH 2 +Flow Control +.PP +The CL provides \fBif-then-else\fP and \fBwhile\fP program flow control +constructs. These look like +.DS +.cs 1 22 + \fBif\fR (expr) + statement + \fBelse\fR + statement +and + \fBwhile\fR (expr) + statement +.DE +.cs 1 +This is quite general since the "statement" may be a group of statements in +brackets. Also, since if-then-else is itself a statement, they may be +chained into if-then-else-if- and so on. The else clause is optional. + +.NH 2 +Abbreviations +.PP +If the boolean CL parameter \fBabbreviations\fP is yes, then packages, +commands, intrinsic functions and parameters may be abbreviated. +The scope of the abbreviation is limited by its context. For example, if +a parameter reference is \fItask.param\fP, the only candidates for the param +abbreviation are those parameters belonging to the given task; similarly for +parameter names given in the absolute form of a task's argument list. +Parameter fields, such as p\(ulname and so on, are always considered within +their own class so their briefest forms are always p\(uln, p\(ult, p\(ulmo, +p\(ulv, p\(ull, p\(uld, p\(ulf, p\(ulmi, p\(ulma and p\(ulp (see \(sc5.2). +The intrinsic functions are also in their own class. +.PP +Abbreviations are not allowed in scripts. They are intended +only to streamline interactive work with the CL. + +.NH +Environment +.PP +The \fBset\fP CL directive, as explained elsewhere (\(sc12), provides a simple +string substitution mechanism for filename translations. Most operating systems +allow a logical assignment to a physical device name for use in filenames. +The CL trys to merge this with its own environment table so that definitions +in the host system are available within the CL in addition to new +entries added by the CL. Typical uses for the translations are portable names +for system-dependent directories and io devices, such as tape. +.PP +The CL keeps its environment table in a last-in first-out fashion. New entries +hide but do not overwrite old entries. Substitutions take place in strings +being used as file names in commands and in parameter files. +This includes list-structured parameters and io redirection. Environment +references are indicated by following them with a dollar, $. For example, +if the following environment definition is made: +.DS + set mydir \(eq '/usr/myname/dir/' +.DE +then these uses +.DS + task x, y, z, > mydir$file1 + task2 filename \(eq mydir$file2 +.DE +become +.DS + task x, y, z, > /usr/myname/dir/file1 + task2 filename \(eq /usr/myname/dir/file2 +.DE +Note that the quotes around the value for mydir are necessary since the slashes +are not legal in identifiers. +.PP +The environment facility is strictly a string substitution mechanism. +Directory names and other uses must be complete enough so that a valid +filename is the direct result of the substitution; the environment facility +has no knowledge of file naming requirements on the host system whatsoever. + +.NH +Log File +.PP +If the boolean CL parameter \fBkeeplog\fP is yes, then each command typed +by an interactive CL will be entered into a log. Commands that come to the +CL from tasks or scripts are not kept. The name of the file is in the +filename CL parameter \fBlogfile\fP. This parameter is only used when logging +is started. To change the name of the logging file after logging has +already begun, set keeplog to no, change the value of logfile, then restart +logging by setting keeplog to yes. Each time logging starts, the current time +is entered in the log file as a CL comment. + +.NH +Error Handling +.PP +From the start, the single most important requirement of the CL was that it +properly handle error conditions. As one veteran put it, "the error case is +the normal case, and the case when the program runs perfectly is the abnormal +case".* +.FS +* \fIWriting Interactive Compilers and Interpreters\fP, P.J. Brown, page 55. +.FE +.PP +To most easily explain error recovery in the CL, the discussion diverges for a +moment to explain a bit of its internal structure. +Each new logical task that is run pushes a data structure onto a control stack. +This structure indicates, among other things, where the standard input and +output for the task are connected and process control information. +As each task dies, its control structure gets popped off and the +exposed task resumes as the active one. +.PP +When a task encounters an error, +it issues a diagnostic to its standard error and informs the CL. The CL then +repeatedly pops tasks, killing them as necessary, until it uncovers one +that had its input and output connected to the terminal. Thus, an error +condition forces a return to an interactive task, most likely an instance +of the cl directive. +.PP +As each task is popped, its name and the parameters that +were set on the command line when it was run are given as a kind of "stack +trace" to aid diagnosis. Parameter files of tasks that abort due to their +own errors or because they got killed on the way to restoring an interactive +state are not updated. The environment, package and task definitions, and +all other extensible data structures, are restored to their state at the time +the resumed task was pushed. +.PP +The diagnostics from the CL all begin with "ERROR:". This always +means that the full abortive procedure outlined above has occurred. +If an internal consistency check fails, this becomes "INTERNAL ERROR:". A few +diagnostics begin with "WARNING:". Warnings do not invoke the abortive +procedure but are merely informative messages generated during command +processing. +.PP +Perhaps the least helpful error messages are "syntax error" and "parser +gagged". These are generated by the parser when it has no idea of what it is +trying to crack or when it gets terribly confused. +The only advice, until the improved parser of CL2 is available, is to +carefully inspect the offending statement. If the error occurs during +the interpretation of a script, an approximate line number is also given. + +.NH +CL Initialization +.PP +When the CL starts up, it tries to read two CL script files. The first +is in an IRAF system-wide directory and is called \fBclpackage.cl\fP. +It defines the tasks in the root package clpackage, +makes useful environment entries and does other chores such +as printing news. The other is called \fBlogin.cl\fP and will be run if found +in the current directory from which the CL is started. This serves as a way +to personalize the CL on a per-user basis. Typical uses are to +set modes, options and uparm, define personal tasks and packages and make +environment entries for frequently used directories. +Note that login.cl is run as a genuine script and any changes it makes to the +dictionary after doing a "keep" will be lost. + +.NH +CL Directives +.PP +The following commands are handled directly by the CL. They are always +available in the root package, clpackage. They behave as all other commands +in that they may be abbreviated and may have their input and output redirected +as desired. Arguments in square brackets, [ and ], are optional. +.NH 2 +\fBbye\fR +.PP +Exit the current task and resume the previous one where it left off. If there +is no previous task, then the CL ends. Any task declarations, cached +parameter files and environment definitions not kept (see keep) will be +discarded from core. +The same effect may be achieved by typing EOF (control-z on DEC systems). +If used in a script task, it causes the script to abruptly end as though +the end of the script file had been encountered. +Since most packages are defined in scripts that do the cl directive, bye +often has the effect of exiting from an entire package (see cl). +.NH 2 +\fBcache \fIlt [, lt2, ...]\fR +.PP +Read the parameter file for each given logical task(s) into the dictionary. +They will remain in core until the current task exits (see bye). This is useful +before running a task repetitively to reduce the file i/o required to +bring in and possibly update the task's parameter file each time it runs. +.NH 2 +\fBcl\fR +.PP +Run the cl itself as a task. This is generally useful in script tasks to +stop the script midstream and allow terminal interaction again. The script +might start with a package declaration, make some set and task declarations +then do "cl()". This would cause the cl to run as a subtask to the script task +and allow user interaction, with the new package and tasks. When the cl +sees bye or EOF, the script task resumes, doing whatever cleanup it desires +and exits, taking the new package, tasks and other dictionary changes with it. +Other uses of the cl directive are to run script tasks. Since its input can +be redirected, as with any other task, "cl < file" is a way to run a script +file. Note: just where the cl gets its input when run without arguments is still +being discussed but the above description, as far as it goes, should not +change. +.NH 2 +\fBkeep\fR +.PP +Cause all currently defined tasks and packages and any cached parameter files +to remain in core when the current task ends. Normally, all dictionary space +used by a task is discarded when the task ends. +If any further dictionary changes are made, they will be discarded +as keep only retains what was defined at the instant it is used. +Keep only effects the current task. When the task from which the current task +was called ends, the kept dictionary space will be discarded unless keep +was called in the prior task as well. +.NH 2 +\fBlparam\fP \fIlt [, lt2, ...]\fR +.PP +List all parameters for the given logical task(s), if any. The name, current +value, and prompt string is given for each, one per line. The parameters are +given in the order in which they should be used as positional arguments in +commands. Hidden parameters are listed at the end, surrounded by parentheses. +.NH 2 +\fBpackage\fP \fIpackname\fR +.PP +Create a new package with the given name. The parameter file associated with +the current task, if any, is associated with the package and becomes the +package's parameter file. All later task declarations will go into this +package. A package declaration normally occurs in a script +task, which creates the package and defines are tasks therein. +If the package already exists, an error is indicated. +.PP +As an aside, if the name of an existing package is itself given as a command, +then it is pushed and run as a kind of task; nothing is changed in the +dictionary. Bye or EOF will pop this pseudotask and return the current package +setting to its previous state. This is useful for temporarily changing the +search path for commands when a few commands in a package are needed without +having to worry about tasks with the same name in other packages being found +instead (see \(sc2.2). +.NH 2 +\fBredefine\fP \fI[lt1, lt2, ...] lt \(eq pt\fR +.PP +Exactly like the task directive except that redefinitions are allowed. +A warning message is still issued, however, if a redefinition does occur. +.NH 2 +\fBset\fP \fI[name \(eq value]\fR +.PP +Make a new, or redefines an existing, environment entry. If given +without arguments, all current entries are simply listed, one per line. +Entries are made in the dictionary so are subject to the same rules as +other dictionary objects, that is, entries are discarded when the task +that does the set ends unless it uses keep. +New entries are always made at the top of the list. Since searching also +starts at the top, a second entry with the same name as an existing one will +make the first entry inaccessible. +An attempt is made to merge the environment facilities of the host +operating system with the entries managed by set. Examples are given in +the environment discussion. +.NH 2 +\fBtask\fP \fI[lt1, lt2, ...] lt \(eq pt\fR +.PP +Define the logical task(s) found in the given physical task. +All entries are made in the current package. +Pt is the name of the physical task file. It may be in terms of +environmental directories or, if quoted, may be given in host-dependent form. +If it ends in ".cl", the file is assumed to be a script written in the CL +language. +.PP +The logical tasks, lt1, lt2 and so on are the logical tasks that can be +run from the physical task. At least one must be given. If the logical task +name is prepended with a dollar, $, then no parameter file is to be associated +with that task. If a newly declared logical task redefines an existing one +in the current package, an error message is issued and the entry will not +be made. Other logical tasks that do not conflict will still be entered, +however. It is not an error to reference a physical task in more than one +task command. +.NH 2 +\fBupdate\fP \fIlt [, lt2, ...]\fR +.PP +Cause the in-core parameter file for the given task(s) to be written out. +This is used in conjunction with cache to force an update of a parameter +file before the current task ends. It may also be used to force an update +of a parameter file that would not otherwise be updated, that is, when learn +mode is not effect. +.NH 2 +\fBversion\fR +.PP +Give the current version number of the CL. The current implementation gives +the time at which the program was built. The "version" of the CL for the +near future is always considered to be 1.2. +.NH 2 +\fB?\fP and \fB??\fR +.PP +The "?" command gives the names of all the logical tasks defined in the current +package. The format is an indented, multicolumn block. Entries are read +left-to-right top-to-bottom in the order in which they are searched (opposite +of the order they were declared). +The "??" command is similar but includes all packages. +Packages and tasks that lie above the current package, +and are thus not immediately accessible, are given in parentheses. + +.NH +CL Parameters +.PP +Some of the parameters belonging to the CL logical task itself have special +significance. Many of them have been mentioned elsewhere. These parameters +behave according to all the usual rules but they are used internally by the CL +or by utility tasks to specify options. All the CL parameters may be viewed +with "lparam cl". CL parameters not included in the following list are provided +as handy scratch variables. Other parameters will be added as time goes on. +.sp +.RS +.TS +; +ci ci ci +l l l. +param type usage +.sp +abbreviations boolean enables abbreviations +keeplog boolean enables command logging +logfile filename name of logging file +menus boolean automatically do a "?" when changing packages +mode string sets mode of CL task +.TE +.RE + +.NH +An Example +.PP +This is a complete example of a package, \fBcoord\fP, written for the CL +environment. The package contains two logical tasks, \fBairmass\fP and +\fBprecession\fP. +Airmass accepts \fBelevation\fP and \fBscale\fP and computes airmass. +The result is printed and saved in a parameter \fBairmass\fP. +Precession computes the precession between any two years, \fByear1\fP and +\fByear2\fP. The ra and dec for year1 are read from the standard input and the +precessed coordinates to year2 are written to the standard output. +These two logical tasks are +written in the SPP language and are defined in the single physical +task, \fBcoord.x\fP. +.PP +The following are examples of actual running programs. The name of the +files in each case is given in boldface and is not part of the files. +Numerous other examples can be found in the source directories for the +IRAF system. +.PP +The login.cl file (see \(sc11) defines the logical task \fBcoord\fP +as the script task \fBcoord.cl\fP in its own directory. + +.sp +file \fBlogin.cl\fP: +.sp +.DS L +.cs 1 22 +# When the CL starts up, it looks for a "login.cl" file in the +# current directory. The login file should contain any commands +# or declarations which one wants executed upon startup. A KEEP +# or CL command must be executed after the declarations section +# or the new definitions will go away. + +# The logical directory uparm, if defined, is where the CL will +# save updated parameter files. Other IRAF system routines also +# use this directory to store user-specific database files. + +set uparm \(eq "/usr/jacoby/iraf/tasks/param/" +task $coord \(eq "/usr/jacoby/iraf/tasks/coord/coord.cl" + +keep # keep additions to dictionary when login.cl terminates +.DE +.cs 1 + + +file \fBcoord.cl\fP: + +.DS L +.cs 1 22 +# CL script task to define and run the "coord" coordinate tool +# package. When this script task runs, it defines the package +# "coord", the package directory "codir", and the two logical +# tasks comprising the package, AIRMASS and PRECESS. The task +# CL is called to process commands from the user. When CL +# terminates, COORD will also terminate (since there are no more +# commands in the file), causing the package and its contents to +# become undefined. + +package coord + +set codir \(eq "/usr/jacoby/iraf/tasks/coord/" +task airmass, precess \(eq codir$coord + +cl() +.DE +.cs 1 + +file \fBairmass.par\fP: + +.DS L +.cs 1 22 +# Parameters for logical task AIRMASS. + +elevation,r,a,1.5708,0.,1.5708,elevation angle in radians +scale,r,h,750.,,,scale height +airmass,r,h,1.,,,computed airmass +.DE +.cs 1 + +file \fBprecess.par\fP: + +.DS L +.cs 1 22 +# Parameters for logical task PRECESS. + +year1,r,h,1950,,,year from which coordinates are to be precessed +year2,r,a,1982.9,,,year to which coordinates are to be precessed +.DE +.cs 1 + + +.bp +file \fBcoord.x\fP: + +.DS L +.cs 1 22 +# This file is written in the SPP language, which implements a +# subset of the planned IRAF scientific programming language. + +# Define CL-callable tasks. +task airmass, precess \(eq precess\(ulcoords + + +# AIRMASS -- Airmass calculation utility. Airmass formulation +# from Allen "Astrophysical Quantities" 1973, p. 125, 133. +# +# The logical task airmass has three parameters: +# elevation angular height above horizon +# scale scale height of atmosphere +# airmass calculated air mass + +procedure airmass() + +real elevation, scale, airmass, x # local variables +real clgetr() # functions + +begin + # Get type-real parameters "elevation" and "scale" from CL. + elevation \(eq clgetr ("elevation") + scale \(eq clgetr ("scale") + + # Compute the airmass, given the elevation and scale. + x \(eq scale \(** sin (elevation) + airmass \(eq sqrt (x\(**\(**2 + 2 \(** scale + 1) \(mi x + + # Print result on the standard output, and output the + # computed air mass to the CL parameter "airmass". + + call printf ("airmass: %10.3f\\\\n") + call pargr (airmass) + call clputr ("airmass", airmass) +end +.DE +.cs 1 + + +.DS L +.cs 1 22 +# PRECESS_COORDS -- Precess coordinates from year1 to year2. +# This task is a filter, which reads coordinate pairs from the +# standard input, performs the precession, and outputs the +# precessed coordinates on the standard output. +.DE +.cs 1 + + +.DS L +.cs 1 22 +procedure precess\(ulcoords() + +real default\(ulyear1, year1 # year to precess from +real default\(ulyear2, year2 # year to precess to +double ra1, dec1 # input coordinates +double ra2, dec2 # precessed coordinates +int fscan(), nscan() # formatted input functions +real clgetr() # get real parameter function + +begin + # Get the default "year" parameters from the CL. + default\(ulyear1 \(eq clgetr ("year1") + default\(ulyear2 \(eq clgetr ("year2") + + # Read and precess coordinate pairs from the standard input + # until EOF is detected. Format "ra dec [year1 [year2 ]]". + + while (fscan (STDIN) !\(eq EOF) { + call gargd (ra1) + call gargd (dec1) + call gargr (year1) + call gargr (year2) + + if (nscan() \(eq\(eq 3) # no year2 given + year2 \(eq default\(ulyear2 + else if (nscan() \(eq\(eq 2) # no year1 given + year1 \(eq default\(ulyear1 + else if (nscan() < 2) { + call fprintf (STDERR, "invalid coordinates\\\\n") + next # do next iteration + } + + # Call precession subprogram to precess the coordinates, + # print result on standard output (hms hms yyyy.y). + + call precess (ra1, dec1, ra2, dec2, year1, year2) + call printf ("ra: %12.1h dec: %12.1h %7.1f\\\\n") + call pargd (ra2) + call pargd (dec2) + call pargr (year2) + } +end +.DE +.cs 1 |