From 8cf89eadabee6c719b264431a5ecaa82c834f9b2 Mon Sep 17 00:00:00 2001 From: "Eric S. Raymond" Date: Mon, 7 Nov 1994 09:07:38 +0000 Subject: [PATCH] Initial revision --- cupl.doc | 528 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 528 insertions(+) create mode 100644 cupl.doc diff --git a/cupl.doc b/cupl.doc new file mode 100644 index 0000000..739df4c --- /dev/null +++ b/cupl.doc @@ -0,0 +1,528 @@ + THE ORIGINAL CUPL DOCUMENTATION + +We reproduce here, for reference, a nearly exact transcription of Appendix A +of the Walker manual, "CUPL: The Cornell University Programming Language". + +Tags of the form [See m-n: ...] not part of the original document; they are +references (by section-page number in the original manual) to notes which +follow the appendix transcription. These notes are also excerpts from the +manual. + +There are a few typographical changes to fit it into the ASCII character set. +The differences: + + * ^[-+]nnn is used to render exponent superscripts. + + * subscripts are simply appended to their metavariables. + + * `x' between digits is used to render the multiplication sign. + + * lines of dashes below headings indicate underscores. + + * page breaks in the original are represented by form feeds here. + +Otherwise, the appendix A transcription is exact, even down to hyphen breaks +and spacing. In the following notes, hyphen breaks and exact spacing are not +preserved, but the original text is, with the following additional +typographical changes: + + * |a| is used to render the absolute-value operation. + + * <= and < are used to render non-ASCII symbols. + + * In the original, a couple of instances of |x * 10**n| and |y * 10**n| + were actually set as |10^nx| and |10^ny|, where ^n represents a + superscript. This is excessively hard to read in ASCII. + +The combination of Appendix A and the notes includes essentially all the +manual's documentation of the CUPL language itself. We have not transcribed +appendix D, "Error Considerations and Actions", nor appendix B, "Functions", +because the former depends on the parsing machinery of the original compiler +and the latter documents range restrictions and precision constraints for the +special functions (which are not duplicated in our implementation). + +The following .cupl files, included with this distribution, are also +transcribed from the manual. We include every non-pathological program +example. The following list maps programs to original page numbers: + +cubic.cupl -- 7-7 (boxed) +fancyquad.cupl -- 2-8 (coding form example) +poly11.cupl -- 7-9 (boxed) +power.cupl -- 3-4 (exercise 5b) +prime.cupl -- 12-5 (boxed) +quadratic.cupl -- 2-2 (boxed) +random.cupl -- 10-2 (boxed) +rise.cupl -- 3-15 (exercise 7) +simplequad.cupl -- 2-1 (boxed) +squares.cupl -- 5-7 (output example) +sum.cupl -- 3-4 (exercise 5a) + +We have supplied leading comments for most of these; they are otherwise +unaltered. + +---------------------------------- CUT HERE ---------------------------------- + Appendix A + + Summary of CUPL + + +ELEMENTS OF THE LANGUAGE + + Characters + ---------- + Letters: A B C D E F G H I J K L M N O P Q R S T U V W X Y Z + Digits: 0 1 2 3 4 5 6 7 8 9 + Special Characters: + - * / ( ) . , ' = + + Numbers + ------- + Normal decimal usage: e.g. 3, 1.725, -.06 . + "Scientific" notation: -1.2E-3 for -1.2 x 10^3 . + Truncated to 9 significant figures by the system. + Range: Absolute values from 10^-78 to 10^76, and 0 . + + Variables and Labels + -------------------- + a. Consist of 1 to 8 letters or digits, beginning with + a letter; no blanks or special characters. + + b. Must not be one of the following "reserved words": + + ABS DOT IF OR THEN + ALL ELSE INV PERFORM TIMES + ALLOCATE END LE POSMAX TO + AND EXP LET POSMIN TRC + ATAN FLOOR LN RAND TRN + BLOCK FOR LOG READ WATCH + BY GE LT SGM WHILE + COMMENT GO MAX SIN WRITE + COS GT MIN SQRT + DET IDN NE STOP + + c. Must be unique--same name cannot be used for both a + label and a variable. + + d. Variables have automatic initial value of zero. + + e. Variables can be scalar, vector, or matrix. [See 8-3 and 9-8] + + If A is a matrix variable: + + A refers to the entire matrix. + A(I,J) refers to the element at the + intersection of the ith row + and the jth column + A(*,J) refers to the jth column + A(I,*) refers to the ith row + + A-2 + + If V is a vector variable: + + V refers to the entire vector + V(I) refers to the ith component. + + [See 11-3 for subscript round-off rules] + + f. A vector is a 1-column matrix + + g. IDN is the identity matrix of any appropriate size. + + Arithmetic Operators + -------------------- + a. +, -, /, * for multiplication, ** for exponentiation + + b. Normal precedence: **, * and /, + and - + Parentheses from inner to outer. + Sequence of + and - from left to + right. + + c. Types of operand: +, -, /, *, ** for scalars + +, -, *, and numerator of / for + vectors and matrices. + + Spacing + ------- + No spaces, or splitting at end of line, in any number, + variable, label, reserved word, or **. Spaes allowable + anywhere else. + + Functions + --------- + Form Action Type of Argument + ---- ------ ---------------- + ABS(a) absolute value of a any expression + ATAN(a) arctangent of a, in numerical valued + radians expression + COS(a) cosine of a, a in numerical valued + radians expression + EXP(e) e raised to a power numerical valued + expression + FLOOR(a) greatest integer not numerical valued + exceeding a expression + LOG(a) natural og of a numerical valued + expression + SQRT(a) positive square root numerical valued + of a expression + SIN(a) sine of a, a in numerical valued + radians expression + MAX(a,b,...) maximum value of all any expressions + elements of all + arguments + + A-3 + + MIN(a,b,...) minimum value of all any expressions + elements of all + arguments + RAND(a) next pseudo-random any expression + number, or array + of numbers, in a + sequence in which + a was the last + DET(a) determinant of a square array valued + expression + DOT(a,b) dot product of a vector-valued expres- + and b sions of equal + dimensions + INV(a) inverse of a square array valued + expression + POSMAX(a) row position of maxi- array valued expression + mum element of a + POSMIN(a) row position of mini- array valued expression + mum element of a + SGM(a) sigma of a (sum of array valued expression + all elements) + TRC(a) trace of a (sum of array valued expression + elements on prin- + cipal diagonal) + TRN(a) transpose of a array valued expression + + Relations + --------- + Symbol With scalar expressions With array expressions + ------ ----------------------- ---------------------- + = equals all corresponding ele- + ments equal + NE not equal to at least one pair of + corr. ele. not equal + LE less than or equal to all corr. ele. less than + or equal + GE greater than or equal all corr. ele. greater + to than or equal + LT less than all corr. ele. less than + or equal; at least one + less than + GT greater than all corr. ele. greater + than or equal; at least + one greater than + + [See 11-4 for round-off rules applying to relations] + +STATEMENTS + + The following symbols are used in the statement descriptions: + + v1, v2, ... variables (scalar, vector, or + matrix except as noted) + + A-4 + + r1, r2, ... relations + + slabel1, slabel2, ... statement labels + + blabel1, blabel2, ... block labels + + e1, e2, ... arithmetic expressions (a meaningful + and conformable combination of + numbers, variables, functions, and + arithmetic operators) + +Statements should begin in column 10 of the programming form. If +continued onto more than one line, the second and aubsequent lines +should begin in column 15. Columns 73 to 80 must not be used. + +Any statement may be given a label--beginning in column 1 of the +form. + + Assignment Statement + -------------------- + LET v1 = e1 + + Sequence Control Statements + --------------------------- + GO TO slabel1 + + GO TO blabel1 Used only inside block 'blabel'; + causes skip to end of block. + + IF e1 r1 e2 THEN s1 ELSE s2 where s1 and s2 are any type + of statement except IF or + PERFORM. + + Either the THEN phrase or the ELSE phrase may + be omitted, but one or both must be given. + + Compound conditions may be used: + + IF e1 r1 e2 AND e3 r2 e4 AND ... THEN s1 ELSE s2 + + IF e1 r1 e2 OR e3 r2 e4 OR ... THEN s1 ELSE s2 + + but AND and OR phrases may not be mixed in the same + statement. --- + + STOP + + Iteration Control Statements + ---------------------------- + A 'block' consists of a sequence of statements preceded by + + blabel1 BLOCK and followed by blabel1 END + + A-5 + + A block may be located anywhere in the program; it is executed + only by a PERFORM statement calling it by name. Blocks + may be nested but not overlapped. A block may contain + any kind of statent, including PERFORM, except for a + PERFORM referring to the block itself. + + PERFORM blabel1 + + PERFORM blabel1 e1 TIMES where e1 has integer value. + + PERFORM blabel1 WHILE e1 r1 e2 + + Compound conditions may be used: + + WHILE e1 r1 e2 AND e3 r2 e4 AND ... + + WHILE e1 r1 e2 OR e3 r2 e4 OR ... + + but AND and OR phrases may not be mixed in the same + statement. + + PERFORM blabel1 FOR v1 = e1, e2, ... + + FOR sv1 = e1 TO e2 BY e3 where sv1 is + a scalar vari- + able + + The order of the TO and BY phrases can + be reversed; the BY phrase can be + omitted if e3 = 1. [See 8-3 for more] + + + Communication Statements + ------------------------ + READ v1, v2, ... [See 5-2 for description] + + WRITE v1, v2, ... , 'title message', ... , /v3, /v4 + + Three types of elements may appear in the list + after WRITE: + + 1. Variable. Prints: + + name of scalar and current value; + + name of vector and current values of + components; + + name of each row vector of matrix and + current value of components. + + 2. Variable preceded by a / . Current values + only are printed. + + A-6 + + 3. A message enclosed in single quotes. The + exact image will appear as a title on + the output. Any characters except the + quote may be used in such a message. A + message cannot continue onto a second + line on the programming form--a separate + item in the same or another WRITE state- + ment must be used. + + [See 5-3 and 8-10] for more formatting details] + + [WRITE ALL See 4-12 and 8-3 for a description] + + COMMENT A comment line can be inserted at any time by + writing COMMENT in the label field (columns 1-7) of + the programming form. Such a line will appear in + the program listing, but has no effect on execution. + + + Dimensioning of Vectors and Matrices + ------------------------------------ + ALLOCATE mv1(e1, e2), vv2(e3), ... where mv1 is a matrix + variable and vv2 is a vector + variable, and e1, e2 and e3 have + integer values. + + When space is initially allocated to an array, the + values of all the elements are zero. If space is + later changed by another allocation the values of + those elements common to the old and the new alloca- + tions are unchanged; the values of new elements are + zero. + + Tracing Changes in Value During Execution + ----------------------------------------- + + WATCH v1, v2, ... where v1 and v2 are scalar variables. + + This will cause the system to monitor the values of + each of the variables listed and print the new value + each time one of the listed variables is assigned a + value by a LET or READ statement. This operation is + temporary and is automatically discontinued for a + particular variable after 10 such assignments. [See 8-3] + + +DATA + + Data to be read by the execution of the READ statements is + provided on the same form, after the last statement of the + program. The first data line is indicated by writing *DATA + in columns 1 to 5. Data items may be entered on this line + beginning in column 7 and in columns 1 tto 72 of any following + lines + + + A-7 + + Data items are separated by commas. An item may be either a + number, n1, or an expression of the form v1 = n1 . The + latter form is for checking purposes--it must correspond to the + variable v1 in the associated READ statement. + + Data items are read in sequence as the program is executed. + To an array with q elements appearing in a READ statement, + there must correspond q successive items in the data list. + If the array is a matrix, the items must be ordered by rows. + +---------------------------------- CUT HERE ---------------------------------- + +Other quotes: + +From 4-12: + + Another statement that can be used for checking purposes is + + WRITE ALL + +This will cause the values of all of the variables in the program to be +printed. There is no WATCH ALL statement. + -- + +From 5-2: + + If READ v occurs in the program and the corresponding entry on the +datalist is w=n, where w is not the same as v, an error message is given. +The value n is assigned to v, no change is made in w, and the program +continues. Thus the inclusion of items of the type v=n in the data list +provides checks against the accidental omission of data or inclusion of +extra numbers. + + If the total data list is too short, the machine will give an error +message and will give the value 1 for each of the missing numbers. If the +list is too long the extra entries will be ignored but no error message will +be given. + +From 5-3: + + Numbers are given to 9 significant figures. A number n /= 0 in the range +.0001 <= |n| < 100000 is printed in the usual decimal form, e.g. -327.512736, +0.0243472150 . Zero is printed simply as 0. All other numbers appear in the +form mEp with 1 <= |m| < 10, e.g. -2.31562007E+04, 5.00000000E-17 . + + A line of output is divided into six "fields", each 20 characters long. +Each variable name or value occupies one field. The decimal point of a +number always comes at the seventh position in a field. Each WRITE statement +starts a new line, but within a given WRITE statement fields are used +consecutively, new lines being started as necessary. The one exception occurs +when the name of a variable would come at the end of a line and its value +on the next line; in this case, the last field is left blank and the name +starts the next line. + + A field may be purposely skipped by simply omitting a variable name; +for example, + + WRITE ,A,,,/B + +will put A and its value in fields 2 and 3, and the value of B in 6, +leaving fields 1, 4 and 5 vacant. The statement + + WRITE + +will cause a whole line to be skipped. + +From 8-3: + + The only restrictions on the use of a subscripted variable are in + + PERFORM k FOR v = --- + +and + + WATCH v,... + +Here v must be a non-subscripted variable. Also, WRITE ALL will print only +the values of the non-subscripted variables. + +From 8-10: + + 1. A new line is started for each vector and each row of a matrix. + + 2. Te values of the elements of a vector or a row of a matrix are +put successively in fields 2 through 6, repeating as necessary. + + 3. In field 1 of the first line used for a vector or for a row of +a matrix is put the name of the vector or a symbol for the row of the matrix, +unless these are suppressed by a slash before the array in the WRITE list. +The slash does not change the spacing described in 2 above. + + 4. A variable, subscripted or not, appearing in the WRITE list immediately +after an array, starts a new line. + + There is one exception to these rules. If M is a matrix with only one +column, to save space it will be printed as if it were a vector, that is, in +the form + + M = m11 m21 m31 etc. + +From 9-8: + + So much space is needed to compute INV(A) or DET(A) that the size of +A is limited to 40x40 in these expressions. + +From 11-3: + +Automatic Integer Round-off +--------------------------- +a. The value of a subscript is rounded to the nearest integer. + +b. If the round-off involves a change of greater than 10^-9 (approximately) + an error message is given. + +From 11-4: + +Automatic Relative Round-off for x r y +-------------------------------------- +a. If both x and y are zero the condition is applied as it stands. + +b. If either x or y is not zero: + + (i) Both x and y are multiplied by 10**n, where n is chosen so that + the larger of |x * 10**n|, |y * 10**n| lies between .1 and 1. + + (ii) x * 10**n and y * 10**n are truncated to 14 decimal places + + (iii) The specified condition is interpreted or the resulting numbers. + -- 2.43.0