Magazyn Amiga 13

home *** CD-ROM | disk | FTP | other *** search

/ Magazyn Amiga 13 / MA_Cover_13.bin / source / c / apl / manual < prev next >

Wrap

Text File | 1999-11-23 | 73.3 KB | 1,765 lines

APL\11 An APL Interpreter for UNIX* Michael Cain November 12, 1992 111.000 IIInnntttrrroooddduuuccctttiiiooonnn This manual describes APL\11, an APL interpreter that runs under the UNIX operating system. The interpreter is written in C and the source code is freely available. I currently check a single set of source code on all of o SunOS 4.1 on a Sun3 using the bundled cc, o SunOS 4.1 on a SPARC using the bundled cc, o SunOS 4.1 on a SPARC using GNU gcc 1.40, and o LINUX on a 386sx using GNU gcc 2.2.2. The code is reasonably portable, subject to several restric- tions including interchangeable pointers and ints. Porta- bility is discussed in more detail in another section. APL\11 has a relatively long history. The original program was written by Ken Thompson at Bell Laboratories, apparently in the days before Version 6 UNIX. This version of the interpreter was extensively modified at Purdue University. Other versions have been included on the Berkeley distribu- tion tapes. I got the Purdue version in 1981 while I was working at Bell Labs, then carried it with me to Bellcore and U S WEST. Early in '92, I acquired a 386sx, a copy of Linus Torvalds' linux, and a copy of Bellcore's MGR windowing software. And a little voice in the back of my head that said "This mul- titasking virtual-memory windowed system is nice, and if it had APL it would be just about perfect!" There's no accounting for taste. After asking USENET, it was apparent that no other source-code available UNIX-based APL inter- preters had been written. Which eventually led to the cur- rent situation. AT&T has given permission to distribute the source code, and I've cleaned it up, fixed several errors, written some new documentation and formatted a lot of the old Purdue documentation, added a little additional func- tionality. It's available for general use. Subject to the various lawyer-type restrictions in the next section. It's important to acknowledge the contributions of others: Ken Thompson, for starting it; John Bruner, the graduate student at Purdue from whom I got my copy and, based on the __________ * UNIX is a registered trademark. - 2 - comments in the code, did a lot of work on making the inter- preter more robust; Anthony Reeves, then of the EE faculty at Purdue, whose name appears on much of the documentation; Marty Glopta at Bell Labs who did a lot of the initial leg- work involved in getting approval to distribute the source; and Lee Dickey for allowing me to use watserv1 as a distribution medium. I plan to provide support for the interpreter as my personal time and interests permit. The normal distribution channel will be the ftp archive at watserv1.waterloo.edu. If you are actively using APL\11, drop me a line. Mail should be sent to mcain@advtech.uswest.com. Bug reports are welcome, although I can't promise how soon they'll get fixed. Patches that fix bugs are even more welcome. I would like to extend the interpreter to include more modern APL fea- tures like nested arrays. Enjoy! - 3 - 222.000 LLLeeegggaaalll SSStttuuuffffff 1. Definitions: "Licensor" is U S WEST Advanced Tech- nologies, Inc., a Colorado corporation, whose principal place of business is located at 4001 Discovery Drive, Boulder, Colorado, 80303. "Software" means the source code computer programs known as APL\11 and all related materials, documentation, and information received by Licensee from Licensor. 2. Rights in Software: Licensor has obtained license rights under a quit claim license from AT&T which allows the free distribution of the Software to third persons. 3. License Grant: In accordance with the terms herein, Licensor grants to Licensee and Licensee accepts from Licensor a royalty free, perpetual, non-exclusive and non-transferable license to use, copy, modify and sublicense the Software to third persons. 4. Warranty Disclaimer: THIS SOFTWARE IS LICENSED "AS IS," AND LICENSOR DISCLAIMS ANY AND ALL WARRANTIES, WHETHER EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 5. Indemnity: Licensee hereby indemnifies Licensor and holds Licensor harmless from and against any and all claims, including claims of infringement, which arise out of Licensee's use or sublicense of the Software as licensed hereunder. 6. Limitation of Liability: In no event shall Licensor be liable for any indirect, incidental, consequential, special, or exemplary damages or lost profits, even if Licensor has been advised of the possibility of such damages. SOME STATES DO NOT ALLOW THE LIMITATION OR EXCLUSION OF LIABILITY FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE LIMITATION OR EXCLUSION MAY NOT APPLY TO YOU. 7. General Provisions: A. This License shall be governed by the laws of the State of Colorado. B. Licensee also agrees not to use any trade name, service mark, or trademark of Licensor or refer to Licensor in any promotional activity or material without first obtaining the prior written consent of Licensor. C. No action, regardless of form, arising out of the License may be brought by Licensee more than one year after the cause of action has arisen. - 4 - D. If any provision of this License is invalid under any applicable statute or rule of law, it is to that extent to be deemed omitted. E. The waiver or failure of Licensor to exercise in any respect any right provided for herein shall not be deemed a waiver of any further right hereunder. F. Each party acknowledges that it has read this License, it understands it, and agrees to be bound by its terms, and further agrees that this is the complete and exclusive statement of the License betweeen the two parties, which supersedes all prior proposals, understandings, whether oral or written, between the parties relating to this License. This License may not be modified or amended except by written instrument duly executed by both parties. - 5 - 333.000 BBBuuuiiillldddiiinnnggg ttthhheee IIInnnttteeerrrppprrreeettteeerrr -- SSSiiimmmpppllleee CCCaaassseee This section describes the steps needed to build the APL\11 interpreter from source, assuming that nothing goes wrong. Building the interpreter requires yacc and a K&R-compatible C compiler. A simple makefile is included with the source. The command $ make with no arguments should produce an executable file named "apl". If make is not available, the interpreter can be built by hand almost as easily. The sequence of commands $ yacc apl.y $ cc -o apl *.c -lm [compiler diagnostics] $ should produce the same executable file. A relatively large number of warnings will be issued by modern C compilers. The reasons are discussed in more detail in the next sec- tion. A quick test of the interpreter can be run with the command $ ./apl <quick which should get the following results $ ./apl <quick a p l 1 1 12 nov 1992 clear ws a{1 2 3 b{3 4 5 a+b 4 6 8 aXb 3 8 15 a%b .333333333 .500000000 .600000000 aJ.*b 1 1 1 8 16 32 27 81 243 )off $ If so, you can skip the next section. If not, getting APL running on your machine will be somewhat more complicated. - 6 - 444.000 BBBuuuiiillldddiiinnnggg ttthhheee IIInnnttteeerrrppprrreeettteeerrr -- HHHaaarrrddd CCCaaassseee Portability is a relative thing. Successfully moving a piece of code from one machine to another involves many dif- ferent factors. This section discusses some of the assump- tions made by the APL\11 source code. Moving the inter- preter to a machine on which some of those assumptions are no longer true will probably be quite painful. This material is intended to help you decide if you are in that situation, or if there's still some hope of an "easy" fix. The APL\11 source shows its age in several ways. First, it's K&R rather than ANSI C. Secoond, it predates the void data type, so is full of functions of type int that should be type void. Third, it goes back to the bad old days when pointers and ints were treated as though they were interchangeable. Because of these things, running the code through a modern C compiler results in a lot of warnings. The assumption that pointers (all types of pointers) and ints are interchangeable is critical. I seriously doubt that the code could ever be ported to an environment where this is not true. Some of the MS-DOS compiler models do not satisfy this condition. The code also does a lot of pointer arithmetic and comparisons. If pointers can't be treated as ints, these are apt to be a source of problems. Again, situations like the MS-DOS segmented models should be avoided. While the code doesn't use very many different types of structures, it does some fairly ugly things with the ones that are defined. I believe that the following is the worst case. If your compiler doesn't mess this up, it probably won't mess up the other structures. struct item { int rank; int type; int size; int index; data *datap; int dim[MRANK]; }; Item structures are not directly allocated. Instead, when a new item is being created, the code computes the amount of storage actually needed to hold the item and information about it. This is space for the four ints rank, type, size and index, space for as many ints as the value in rank, and space for as many datas as the value in size. Data is usually defined as a double. Assuming that p points to the allocated space, p->datap is set to &(p->dim[p->rank]). Clearly, inserting padding for alignment or some rearrange- ments of the elements of the structure will break the code. - 7 - Another assumption made by the code is that doubles (or floats in the case of a single-precision version) do not have any alignment requirements. Some machines, for exam- ple, require that a double begin at an address that is a multiple of eight. Compilation of constant numeric expres- sions into byte code will be broken if the machine has alignment requirements. Fortunately, starting a double at an arbitrary location is okay with most contemporary proces- sors. However, some optimizing compilers may force align- ment in order to improve execution speed. As previously mentioned, exceptions are an area where it is hard to write portable code. I have attempted to make the source code portable in the compiler sense by #ifdef'ing each use of an exception name (or signal name, if you prefer). For example, #ifdef SIGPIPE signal(SIGPIPE, panic); #endif This makes the compiler happy, but is not enough to guarantee that the interpreter will do the expected thing in all exception cases. - 8 - 555.000 RRRuuunnnnnniiinnnggg ttthhheee IIInnnttteeerrrppprrreeettteeerrr The APL\11 interpreter is invoked with the simple command "apl". APL (from here on I'll generally use APL and APL\11 interchangeably; if I mean some other APL, it should be clear from context) responds with a header message. A work- space name may be provided as a command-line argument. If the named workspace can be found, it is loaded. If it is not found, APL looks for a workspace named "continue" and loads that instead. If a workspace is loaded and contains a latent expression, the latent expression is executed. Workspaces are simply UNIX data files. The name of the wor- kspace is the same as the file name. Workspaces can be saved in either native or portable form. Save and load in the native form is much quicker than the portable form. The portable format used by APL\11 does not, unfortunately, con- form to the standard workspace interchange format. So while it allows APL11 workspaces to be moved from one machine running APL11 to another, workspaces can't be moved to other APLs. Once entered, the main command loop prompts the user for input. The user types an APL system command or expression. APL attempts to execute the expression. The set of system commands is described in detail in a later section. Many, such as ")off" and ")clear" are much the same as the system commands of other APLs. Some, such as ")editf" and ")read", are unique (in my experience) to APL\11. 555.111 CCChhhaaarrraaacccttteeerrr SSSeeettt APL uses the ASCII character set to represent APL charac- ters. The particular mapping takes some getting used to. The complete allowed character set is described in detail in Appendix A. A quick description is provided here. o Names, such as used for variables and functins, use lower-case alphanumerics. A second character set, cor- responding to the traditional understruck characters, is also available and is generated by overstriking the lower-case characters with an upper-case "F". o Where a particular non-alphanumeric APL character has a look-alike in the ASCII set, the look-alike is used. This covers plus, minus, equal, square brackets, etc. o Where there are no true look-alikes, one of two rules is followed. If there is an ASCII character that resembles the APL character, it is used. This leads to "%" for divide, "X" for multiplication, etc. o The other way of handling characters is to use the upper-case ASCII character at the corresponding keyboard position. This rule yields "A" for alpha, "R" - 9 - for rho, "E" for epsilon, "Y" for the up-arrow (take), "U" for the down-arrow (drop), etc. o Overstruck characters are typed using backspace. The order in which the component characters are typed does not matter. One common problem occurs when backspace is also used as the erase character. In that case, the backspace must be "escaped" in some fashion so that it actually reaches APL. Or the user may find it more convenient to change the erase character to something else that is used by neither the interpreter or the tty driver (something like control-F). The internal character set is such that it should be a straightforward matter to write input and output filters for interacting with the interpreter. These filters would be specific to particular display devices. Unfortunately, display editors will generally not work gracefully with such filters. At some point in the future, I would like to add some simple function editing capabilities to the interpreter itself in order to get around that problem. Literal character strings have been extended somewhat in order to be more UNIX-like. The backslash character is used to indicate some special characters. \n is newline, \b is backspace, \t is tab, \r is carriage return, and \\ is a backslash. The backslash can also be used to specify three- digit octal values. Using an octal value, the ASCII ESC character would be \033. This extension makes it easier to handle things like escape sequences for terminal control. By way of some summary, here is a transcript of a short APL session. I have always liked APL\11's )script capability for recording a session. Notice that since function editing is done by an external editor, none of the editing portion of the session appears in the record. Also, the plot func- tion is my own, and isn't very good. linux> apl a p l \ 1 1 12 nov 1992 clear ws )script log [new file] )load utility.ws 18.52.14 08/25/92 utility.ws )fns plot and vs space )editf and a{100 1RI100 C a is one column, 1-100 a{a-1 C subtract 1 from everything a{aX0.0628 C map to 0 to two-pi a{a,(1Oa),2Oa C add sine and cosine columns 20 60 plot a C plot - 10 - 1.00 XXXXX OOOOOOOOO XXXX | XX OO OO XX | XXO O X | OXX O X | OO X OO X .50 | OO X OO X | OO X OO X | O X O X | O XX O X |O XX O X .00 O X O XX O | XX OO XX O | X O X O | X OO X OO | X OO X OO -.50 | X OO XX O | X OXX O | X XXO O | XX XX OOO OO | XXXXXXXX OOOOOOOOO -1.00 | | | | | | | .00 1.17 2.33 3.50 4.67 5.83 7.00 )script off 555.222 SSSaaavvviiinnnggg aaannnddd LLLoooaaadddiiinnnggg Workspaces are explicitly loaded by the command ")load wsname". The current workspace can be explicitly saved by the command ")save wsname". The workspace name must always be provided. Additional information about the )load and )save system commands, as well as the other system commands supported by APL\11, is provided in Appendix B. A saved workspace includes function definitions and variables. If there are suspended functions, all of the local variables for those functions are also saved. However, the APL state indicator is not saved, so that those variables become global in scope when the saved workspace is loaded. Trying to save the state indicator is very hard in the current version of the interpreter because of the way the main program loop is implemented. Someone should fix this sometime. )save and )load write and read native-mode workspaces. The commands )psave and )pload write and read workspaces in a more portable format. This format should be portable from one machine to another, so long as they both use the ASCII character set. When examined manually, the format can be seen to be somewhat human readable. Editing a saved work- space is not safe. Function definitions are terminated by a null character, which most editors will simply drop while reading. The image saved by the editor would not be accept- able when read by APL. - 11 - )psave and )pload are slower than their native-mode equivalents, especially if the workspace contains large amounts of data. Saving a workspace in portable format can result in some loss of precision for floating point values. This is a result of the portable workspace format, which represents numbers using decimal digits and ASCII characters (that is, "1.23456e-78"). 555.333 FFFuuunnnccctttiiiooonnn EEEdddiiitttiiinnnggg APL\11 does not include a built-in editing capability. All functions are edited by dumping the source code into a tem- porary file and then invoking the user's editor-of-choice on that temporary file. The temporary file is created in /tmp. Which editor is invoked is determined by the value of the shell variable EDITOR. If EDITOR is not defined, the name of the editor defaults to "vile", a clone of Berkeley vi. I thought about defaulting to "ed", but decided that only us old-timers remember how to use line-oriented non- display editing. The new function definition is read back in when the editing process terminates. The source code is not compiled into byte codes until the "executable" is actually needed. Syntax errors in the source code will not be detected until compilation occurs. As described previously, overstruck characters must have the form a-backspace-b. In order to use these characters in a function, the editor must be cap- able of putting real backspaces into the source file. Most editors are capable of displaying and inserting backspaces, but may vary in the details of how it's actually done. APL will not allow the user to edit suspended functions. If the user attempts to do so, APL responds with the message "si damage -- type ')reset'". There isn't any actual damage to the state indicator, although the message might be inter- preted that way. Another reason for adding simple function editing capabilities to APL\11 itself (see also the preced- ing section on "Function Editing") is to allow the user to modify suspended functions when such changes do not create any problems. 555.444 EEExxxccceeeppptttiiiooonnnsss Proper handling of exception conditions is one of the hardest areas to make truly portable. Different machines and operating systems allow different kinds of exceptions to occur. Some are pretty much the same on all machines; divi- sion by zero is an error on most computers*. Bad pointers, __________ * One exception that I know about is old CDC hardware. There, division by zero results in a special bit pat- - 12 - on the other hand, can result in a variety of different errors on different machines: segmentation violations, bus errors, etc. I have attempted to make the source code portable in the compiler sense by #ifdef'ing each use of an exception name (or signal name, if you prefer). For example, #ifdef SIGPIPE signal(SIGPIPE, panic); #endif This keeps the compiler happy because the code doesn't reference signals that don't exist. However, on any partic- ular machine there may be signals which exist but are not properly trapped. When the corresponding exceptions occur, the system default action (often a core dump) will be taken rather than the interpreter's recovery actions. __________ tern representing an indefinite or undefined value, but is not an error. However, attempting to use the indefinite value in a subsequent calculation is an error. The subsequent calculation always seemed to be in a different subroutine several pages away in the source listing. This made debugging more difficult. - 13 - 666.000 IIInnnttteeerrrnnnaaalllsss Someday, this section will describe the internal workings of the APL\11 interpreter. It is intended as a starting point for a programmer attempting to modify the interpreter itself. It will contain a lot of information that I wish I had had before I started working on the code. However, that day has not yet arrived, and these couple of paragraphs are placeholders only. For the brave of heart who jump in anyway, some housekeeping hints. I edit C language source code in a fairly big text window (40 rows of 90 columns) with tab stops set at every fourth column. I've been through the entire body of code and brought it pretty much into alignment with my own per- sonal preferences for things like indenting, grouping, and brace placement. Looking at the code using other arrange- ments such as eight-column tab stops or a "normal" 24 by 80 screen will probably make things look uglier than they actually are. 666.111 PPPrrriiinnnccciiipppllleee DDDaaatttaaa SSStttrrruuuccctttuuurrreeesss 666.222 MMMaaaiiinnn PPPrrrooogggrrraaammm LLLooooooppp 666.333 CCCooommmpppiiillliiinnnggg 666.444 EEExxxeeecccuuutttiiiooonnn - 14 - AAAppppppeeennndddiiixxx AAA TTThhheee AAAPPPLLL\111111 CCChhhaaarrraaacccttteeerrr SSSeeettt This section provides a quick reference for the character set used by the APL\11 interpreter. Note that both upper- and lower-case characters are used. <bs> denotes backspace. a-z letter 0-9 digit ` negative sign '--' string C <bs> J C comment ( ) [ ; ] indexing L quad L <bs> ' quote quad dyadic monadic ------ ------- + add plus - sub negate X mult sign % div reciprical | mod absolute value D min floor S max ceiling * pwr exp O <bs> * log ln (log base e) O circle funct pi times ' <bs> . combinatorial factorial ! combinatorial factorial ^ and V or ^ <bs> nand V <bs> nor < lt > gt $ le & ge = eq # ne not ? deal random number R rho rho I iota iota E epsilon N encode B decode \ <bs> O transpose transpose , catenate ravel * Y take U drop { assign } goto B <bs> N i-beam i-beam L <bs> % matrix div matrix inverse - 15 - | <bs> H grade up * G <bs> | grade down * B <bs> J execute N <bs> J format / compress * / <bs> - compress \ expand * \ <bs> - expand O <bs> | rotate reverse * O <bs> - rotate reverse op / reduce * op / <bs> - reduce J.op outer product op.op inner product * may be subscripted with a scalar - 16 - AAAppppppeeennndddiiixxx BBB SSSyyysssttteeemmm CCCooommmmmmaaannndddsss The following is a complete list of APL system commands. )clear This command is used to completely initialize an APL workspace. Usually when APL is started, it will print: "clear ws". This means that no internal variables or functions are defined. Sometimes, it is desirable to completely erase everything, and this command serves that purpose. To let you know that everything has been erased, APL will output the message "clear ws". )erase list This command is handy when it is desirable to get rid of parts of a workspace without using ")clear" to eliminate all of it. A list of function and variable names (separated by spaces or tabs) may be specified. The named functions and variables will be deleted from the internal workspace. The remainder of the workspace will not be affected. )save xxx This command causes APL to write its internal workspace into a UNIX file. This allows the current session to be resumed at a later time. If the save is successful, APL will output the date and time. )vsave xxx This command allows parts of a workspace to be saved. The functions and variables which are specified will be saved in a UNIX file in the same format as produced by ")save". APL will prompt for the names of the functions and variables to be saved. When you have entered the last name, type a blank line to end the save operation. The workspace you have created with ")vsave" may be loaded with ")load" at some later time. ")vsave" does not affect variables in the internal workspace. )load xxx This command is used to tell APL to load the UNIX file "xxx" into APL as a workspace. After the file is loaded, APL's internal work- space will be the same as it was when the wor- kspace file was saved with ")save", and that previous APL session may be resumed. If the workspace file exists and is successfully loaded, APL will print the time and date that the workspace was last saved. )copy xxx This command instructs APL to locate the UNIX file "xxx" and load it into its internal work- space, similar to the ")load" command. The difference between ")load" and ")copy" is that - 17 - ")load" will replace the current internal wor- kspace with the one being read in, while ")copy" merges the current internal workspace with the one being read in. Functions and variables which are loaded from the file take precedence over functions and variables of the same name existing already in the internal workspace. )digits n This command is used to specify to APL how many digits are to be displayed when a number is printed in floating-point or exponential format. By default, APL will print 9 digits. You may specify any number between 1 and 19 for the number of digits (n). APL will answer with the number of digits it was using. )origin n This command is used to change the "origin". By default, the origin is 1. The "origin" is the starting index for arrays. For example, if the origin is 0, then the first element of a 3-element array A is A[0]. If the origin is 5, the first element will be A[5]. Although standard APL permits only 0 or 1 for the origin, APL\11 allows any integer value. APL will answer with the origin it was using. )width n This command tells APL to print n characters per line. This is useful to keep output from being printed outside of the physical terminal width. Lines longer than this length will be "wrapped-around". APL answers this command with the previous terminal width. )off This command does the same thing that a control-D does -- it terminates the APL ses- sion. )continue ")continue" is a combination of the ")save" and ")off" commands. The internal workspace is saved in a file named "continue", and then APL is terminated. Since APL will by default look for the file "continue" in the current directory when it is next run, this provides a convenient method of suspending and resuming an APL session. )fns This command causes APL to list the names of all of the functions which are defined in its internal workspace. )vars This command causes APL to list the names of all of the variables which are defined in its internal workspace. - 18 - )lib This command is similar to the UNIX "ls". It causes APL to list the names of all of the UNIX files in the current directory. Long file names tend to result in ugly output; I modified the existing code to use more contem- porary (read file system independent) methods to get the names, but didn't change it in any other ways. Names are truncated to 14 charac- ters and don't always line up nicely in columns. )editf xxx This command is used to create and edit func- tions. If the function named "xxx" exists in the workspace, APL will write it into a tem- porary file in /tmp and then will invoke the editor defined by the shell variable EDITOR to edit that file. If EDITOR is not defined, the default value "vile" is used. When you have finished editing the file, and you exit the editor, APL will come back and will read the function in from the temporary file. )edit xxx This command is similar to ")editf" except that "xxx" is a UNIX filename. APL will exe- cute the editor to edit the file named "xxx", and when the editing is complete, APL will read that file into the workspace. The dif- ference between ")edit" and ")editf" is that ")editf" essentially edits functions directly from the workspace, while ")edit" gets the functions from a named file. )read xxx At times it is desirable to read a function which is stored in an ASCII file into the internal workspace without editing it. The ")read" command causes APL to read the file named "xxx" into the workspace as a function. Note that ")read" and ")load" are _n_o_t the same thing. ")load" reads a complete new workspace into APL from a workspace-format file, while ")read" reads a function from an ASCII file and adds it to the current workspace. )write xxx This command is the complement of ")read". It takes the function "xxx" from the current wor- kspace and writes it to an ASCII file named "xxx". This is useful for writing functions which will be ")read" later into other work- spaces or which will be printed on the line- printer. Note ")write" and ")vsave" are not the same thing, for ")write" is used to write a function into an ASCII file and ")vsave" saves a selected subset of the internal work- space in a workspace-format file. - 19 - )drop list This command performs the same function as UNIX "rm". The names of the files to be deleted should be separated by spaces or tabs. The files may be APL workspaces, ASCII files, or any other type of file. )script xxx This command places APL into a "protocol" mode. Following this command, APL will copy all input from the terminal and output to the terminal to the file "xxx". Thus, "xxx" is a complete transcript of the APL session. To turn off the script file, type ")script off". The protocol file which is produced will contain all of the output produced by APL itself, but will, unfortunately, not contain any output produced by another process (such as the editor). )trace This command turns on APL's internal "trace" mode. When tracing is turned on, APL will report the function name and line number of each line in every function executed. Thus, the flow of execution from the start to the end of a run can be followed. )untrace This command turns off "trace" mode. )si This command is useful when something goes wrong. When an error occurs, the function that was executing is "suspended". The ")si" command causes APL to print a traceback of the suspended functions. Each function is listed, in the reverse order that it was called. The current line number for each function is also printed. Functions followed by an asterisk ("*") were suspended due to an error; these were called by functions listed on the follow- ing lines whose names are not followed by an asterisk. )reset This command is used to reset the state indicator. All suspended functions are reset; the state indicator will be cleared. APL returns to the global level. )shell This command is useful when it is desired to escape from the APL environment temporarily without having to save the current internal workspace, exit APL, and later re-enter APL and reload the workspace. ")shell" invokes the UNIX shell indicated by the SHELL environ- ment variable. If SHELL is not defined, the shell defaults to "/bin/sh". When you exit the shell, you return to APL. - 20 - )list xxx This command causes APL to print out the func- tion named "xxxx". This is very handy for looking at a function without having to use the editor -- especially when an error has occurred and you want to look at a function without disturbing the state indicator. )prws This command causes APL to print the contents of the workspace in a readable format. Non- scalar variables are displayed along with their dimensions; functions are displayed as via the ")list" system command. While a work- space listing can be placed into a file by use of a script file, a more efficient means of generating a workspace listing is to use the program "prws". )debug This command invokes "debug mode." In this mode, every action which APL takes is logged on the terminal. This mode is excellent for generating reams of hopelessly cryptic output and exists only to facilitate APL development. It is not intended for general use. Debug mode can be turned off by issuing the ")debug" system command a second time. )code fn This command causes APL to print the compiled internal code for the function "fn". This is also intended for APL system development and not for general use. )memory The result of this command is a report on cur- rent dynamic memory usage. The basic form is "n bytes in m blocks". These values represent memory in use rather than memory available. Available memory is not terribly meaningful when the process size can be increased on request until some system limit is reached. - 21 - AAAppppppeeennndddiiixxx CCC AAAPPPLLL\111111 QQQuuuaaaddd FFFuuunnnccctttiiiooonnnsss The following quad functions are defined under APL\11: Lcr 'name' The result of "Lcr" is a character array containing the function whose name is passed as an argument. Lfx newfn The contents of the character array specified as an argument are fixed as an APL function. Lrun 'unix command' The argument passed to "Lrun" is executed as a UNIX shell command. Lfork xx "xx" is a dummy argument. A "fork" system call is performed. This quad function should be used by experienced UNIX users only and probably will be followed by a "Lexec" quad function. The process- id of the child is returned to the parent; a zero is returned to the child. Lexec matrix Takes a two-dimensional character matrix and formats it into a UNIX "exec" system call. The matrix passed as an argument must be two- dimensional, the rows must be fIzerofR terminated. This quad function should be used by experienced UNIX users only. Lwait xx This quad function is used in con- junction with "Lfork" -- it returns a 3-element vector of information about a child process which has ter- minated. The first element is either the PID of a completed child process or -1 (no children). The second is the status of the dead PID and the last is the completion code. This quad function should be used by experienced UNIX users only. Lexit code This quad function is used to ter- minate the execution of the current process, with the completion code "code". It should be used to ter- minate child processes and can be used to terminate an APL session; however, it is recommended that "Lexit" be used by experienced UNIX users only. - 22 - Lpipe xx This quad function can be used to set up a pipe (used for interprocess communication) It returns a 2-ele- ment vector containing the two "pipe" file descriptors. Lchdir 'directory' This quad function can be used to change APL to another directory. Normally, APL runs in the directory that you were in when it was started by the "apl" command. This function changes APL to another directory. The argument is a character vector specifying the new directory (there is NO way to default this). A 0 is returned if the "chdir" was suc- cessful; a -1 is returned if it failed. mode Lopen 'file' This function is dyadic. It opens a UNIX file for use by an APL function with calls via "Lread" and "Lwrite". The first argument is the mode for the open (0=read, 1=write, 2=read/ write). The second argument is a character vector containing the file name. The file descriptor of the opened file is returned (-1 for error). Lclose fd This function complements "Lopen". The argument is the file descriptor of a UNIX file to be closed. This function returns 0 for success or -1 for failure. mode Lcreat 'file' This function creates a UNIX file. If the file already exists, it is truncated to zero length. The crea- tion mode is specified as the first argument (see CHMOD(I) for mode description). The filename is specified in a character vector as the second argument. The file descriptor of the created file (or - 1 for error) is returned. fd Lread nbytes This function reads a specified number of bytes from a designated file. The first argument is the file descriptor; the second is the number of bytes to be read. The data which is read is returned. Note that the returned vector is always character data -- to convert to numeric format see the function - 23 - "Lfloat". fd Lwrite data This function writes data to a specified file. The first argument is the file descriptor; the second is the data to be written. The number of bytes written is returned as the count. Any type of data (character or numeric) may be writ- ten in this manner. Lseek (fd,pos,mode) This function executes the "seek" system call on a UNIX file. The argument to "Lseek" is a three-ele- ment vector containing the file descriptor, seek offset, and mode (see SEEK (II)). A 0 is returned for a successful seek; -1 is returned if an error is detected. pid Lkill signal This function executes the "kill" system call. The first argument specifies what process is to be signalled. The second argument specifies what signal is to be sent. A 0 is returned for a successful "kill"; -1 is returned if the speci- fied process could not be found or is not owned by the current user. For more information on signals, see KILL (II). Lrd fd This function reads one line from the file descriptor specified. If the line is completely blank, a null string is returned. An end-of-file will also return a null string. Otherwise, the returned value is the character string which was read. Lrm 'filename' The specified file will be removed, equivalent to )drop filename. A 0 is returned for a successful remove; -1 is returned if the file could not be removed or does not exist. Ldup fd This function executes the "dup" system call. It returns an integer number which may be used as a file descriptor on later I/O calls. The new file descriptor is a duplicate of the argument "fd". If the argu- ment file descriptor could not be duplicated, -1 is returned. - 24 - fd Lap 'string' This quad function is used to append a character string onto the end of a UNIX file. The first argument specifies the file descriptor of the file (which should have been opened earlier). The second argument is a character array which is to be appended. A carriage return is automatically appended to the end of each row of the character array when it is appended to the end of the file. Lrline fd This quad function is identical to "Lrd", described above. Lnc 'arg' This function can be used to deter- mine what type of variable an APL symbol is. The apl symbol must be specified inside quote marks, as shown. The returned value will be: 0 -- symbol is undefined 2 -- symbol is a label or variable 3 -- symbol is a function name 4 -- unknown type (should not occur) Lnl arg The argument should be a scalar or vector with components 1, 2, or 3. This function returns a two-dimen- sional character array containing the names of all items whose types are specified in the vector (same type definitions as for "Lnc" above). The ordering of names in the matrix is fortuitous. signal Lsig action This quad function allows signal processing to be turned on and off under APL function control. The first argument is the signal whose processing is to be changed. The second argument specifies how the signal will be processed -- if zero, the signal will cause termination of APL and a possible core dump; if non-zero, the signal will be ignored. Note that the special way in which interrupts and other signals are processed by APL is turned off by a call to "Lsig" and cannot be turned back on. A -1 is returned on error, a positive number or zero for success. Lfloat charvect This quad function is useful in con- junction with "Lwrite" and "Lread". - 25 - While any type of data may be writ- ten to a UNIX file with "Lwrite", when it is read with "Lread" it will be interpreted as character data. This function will convert a character array into numeric form. The array must be a multiple of 4 elements long for apl2 and 8 for apl. The converted array is the returned value. - 26 - AAAppppppeeennndddiiixxx DDD III-BBBeeeaaammmsss The following monadic i-beam functions are available: 20 This i-beam returns the time-of-day as the total number of 1/60 seconds which have elapsed since midnight. Division by 60 gives the number of seconds since mid- night, etc. 21 This i-beam returns the total amount of CPU time used by the current APL session in 1/60 seconds. This includes the amount of time spent by the system perfor- ming I/O (sys time) and computational time ("user" time). 22 This i-beam returns the number of 8-bit bytes which are left in the workspace. However, this value is not really meaningful since the in-core workspace will be expanded, if possible, when full. 24 This i-beam returns the time-of-day (in 1/60 seconds) when the current APL session was begun. 25 This i-beam returns the current date as a 6-digit number of the form fImmddyyfR. Thus, February 23, 1978 would be 022378. 26 This i-beam returns the line number in the function currently being executed. Thus, if it is used in line 3 of a function, it will return 3. 27 This i-beam returns a vector of the line numbers in pending functions (functions which called the current function and are waiting for its completion). 28 This i-beam returns the date (as a 6-digit number, fImmddyyfR) when the current APL session began. 29 This i-beam returns the current origin, set by the ")origin" system command. 30 This i-beam returns the current width, as set by the ")width" system command. 31 This i-beam returns the current number of digits to be displayed, as set by the ")digits" system command. 32 This i-beam returns the number of workspace bytes which are being used. It is the complement of i-beam 22, which tells how many bytes are unused. Thus, the maximum workspace size (in bytes) can be calculated by adding i-beams 22 and 32. 36 This i-beam returns the second element of the vector returned by i-beam 27 -- that is, it returns the line - 27 - number of the function which called the current func- tion. 40 This i-beam returns the total amount of CPU time spent by any child processes of APL. Children of APL include the editor, the shell if ")shell" is used, anything run by "Lrun", and any processes executed using "Lfork". 41 This i-beam returns the total amount of "user" time spent by APL and all of its children. 42 This i-beam returns the total "system" time spent by APL and all of its children. 43 This i-beam returns the total amount of "user" time (computational time) spent by APL. 44 This i-beam returns the total amount of "sys" (I/O and other system calls) time spent by APL. 96 This i-beam causes APL to dump its stack on the ter- minal. It is intended for system development of APL, and is probably useful only in generating a big messy- looking display. 97 This i-beam returns the total number of elements on APL's internal stack. It is intended for system development and debugging of APL itself. 98 This i-beam function turns off the trace of all memory allocations and deallocations which i-beam 99 turns on. It returns a 1 if the trace was on, and a 0 if it was off already. 99 This i-beam turns on the alloc/free trace mentioned above, which i-beam 98 turns off. It also returns a 1 if the trace was already on, or a 0 if it was off. The following dyadic i-beam functions were implemented to compensate for the lack of sufficient quad variables. They may be subject to future change. The function is specified by the right argument, the left argument is a parameter to that function. The available i-beams are: 29 This i-beam may be used to set the origin to any per- mitted value. The left argument specifies the new origin, and the previous origin is returned. 30 This i-beam may be used to set the terminal width to any permitted value. The left argument specifies the new width, and the previous width is returned. 31 This i-beam may be used to set the number of digits displayed to any permitted value. The left argument specifies the new number of digits, and the previous - 28 - value is returned. 34 This i-beam implements the system "nice" function. The "nice" of the APL process will be set to the value specified by the left argument. A zero will be returned for success, a -1 is returned for failure. This is intended for background processing, not interactive use of APL. 35 This i-beam implements the system "sleep" function. APL will suspend itself for the number of seconds specified (by the left argument). The value returned is the value of the left argument. 63 This i-beam implements the system "empty" function. The left argument specifies a file descriptor of a pipe. If the pipe is empty, a 1 will be returned, if not-empty, a 0 will be returned. A -1 will be returned if the file descriptor is illegal or is not a pipe. 90 Normally, APL will not exit if it reads an end-of-file from a terminal. This safety feature may be disabled by using i-beam 90 with a zero left argument. A non- zero right argument restores the requirement that the user exit with ")off" or ")continue". [Note: this fea- ture cannot be enabled if the input device is not a terminal.] 99 This i-beam causes the buffered version of APL to flush the buffer associated with the file descriptor speci- fied as the left argument. A 0 is returned for suc- cess, -1 for failure. In unbuffered APL, 0 is always returned and no action is taken (since the command is meaningless). Note that flushing a pipe used for input may cause information to be lost.