home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: WPS_PM / WPS_PM.zip / ICONPL2.ZIP / DOCS.ARC / VERSION7.DOC < prev   
Text File  |  1988-02-03  |  43KB  |  1,651 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                        Version 7 of Icon*
  15.  
  16.  
  17.                         Ralph E. Griswold
  18.                         Gregg M. Townsend
  19.                          Kenneth Walker
  20.  
  21.  
  22.  
  23.                             TR 88-5a
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.                         January 16, 1988
  50.  
  51.  
  52.                  Department of Computer Science
  53.  
  54.                     The University of Arizona
  55.  
  56.                       Tucson, Arizona 85721
  57.  
  58.  
  59.  
  60.  
  61. *This work was supported by the National Science Foundation under
  62. Grant DCR-8401831.
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.                         Version 7 of Icon
  77.  
  78.  
  79.  
  80.  
  81. 1.  Background
  82.  
  83.    The current version of Icon is Version 7.  Version 7 contains
  84. a number of features not present in earlier versions, but other-
  85. wise is nearly the same as Version 5.  The Icon book [1], which
  86. describes Version 5, continues to serve as the primary reference
  87. for Version 7.  This report supplements the present Icon book.
  88. Together, the book and this report provide a complete description
  89. of Version 7.
  90.  
  91.    Most of the language extensions in Version 7 are upward-
  92. compatible with Version, 5 and almost all Version 5 and Version 6
  93. Icon programs work properly under Version 7. New features are
  94. described in Section 2.  However, some of the more
  95. implementation-dependent aspects described in the Version 5 book
  96. are now obsolete. See Section 3.
  97.  
  98.  
  99. 2.  Features of Version 7
  100.  
  101.    The major differences between Version 7 and Version 5 are
  102. listed below.  Features that are new since Version 6 are identi-
  103. fied by squares ([]).  Such designations are not precise, since
  104. there are many interactions between features in different ver-
  105. sions; they are intended only to focus attention.
  106.  
  107.         A declaration to allow the inclusion of separately
  108.         translated Icon programs.
  109.  
  110.         A set data type.
  111.  
  112.         New options for sorting tables.
  113.  
  114.         Syntax to support the use of co-expressions in
  115.         programmer-defined control operations.
  116.  
  117.         The invocation of functions and operators by their string
  118.         names.
  119.  
  120.      [] New functions, especially for interfacing the operating
  121.         system and manipulating bits.
  122.  
  123.      [] Correction of the handling of scanning environments.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                              - 1 -
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.      [] Correction of the handling of co-expression return points
  140.         and new co-expression facilities.
  141.  
  142.      [] Declaration of procedures with a variable number of argu-
  143.         ments.
  144.  
  145.      [] The ability to convert potential run-time errors to
  146.         expression failure.
  147.  
  148.      [] New keywords.
  149.  
  150.      [] Error traceback, which provides detailed information
  151.         about the source of run-time errors.
  152.  
  153. 2.1  The Link Declaration
  154.  
  155.    The link declaration simplifies the inclusion of separately
  156. translated libraries of Icon procedures. If icont [2] is run with
  157. the -c option, source files are translated into intermediate
  158. ucode files (with names ending in .u1 and .u2).  For example,
  159.  
  160.         icont -c libe.icn
  161.  
  162. produces the ucode files libe.u1 and libe.u2. The ucode files can
  163. be incorporated in another program with the new link declaration,
  164. which has the form
  165.  
  166.         link libe
  167.  
  168. The argument of link is, in general, a list of identifiers or
  169. string literals that specify the names of files to be linked
  170. (without the .u1 or .u2). Thus, when running under UNIX*,
  171.  
  172.         link libe, "/usr/icon/ilib/collate"
  173.  
  174. specifies the linking of libe in the current directory and col-
  175. late in /usr/icon/ilib.  The syntax for paths may be different
  176. for other operating systems.
  177.  
  178.    The environment variable IPATH controls the location of files
  179. specified in link declarations. The value of IPATH should be a
  180. blank-separated string of the form p1 p2  ... pn where each pi
  181. names a directory.  Each directory is searched in turn to locate
  182. files named in link declarations. The default value of IPATH is
  183. the current directory. The current directory is always searched
  184. first, regardless of the value of IPATH.
  185.  
  186. 2.2  New Functions
  187.  
  188.    Most of the new functions are described in this section. See
  189. subsequent sections for functions specifically related to other
  190.                           
  191. *UNIX is a trademark of AT&T Bell Laboratories.
  192.  
  193.  
  194.  
  195.  
  196.                              - 2 -
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205. new features.
  206.  
  207.  [] System-Interface Functions
  208.  
  209. getenv(s)
  210.  
  211.    getenv(s) produces the value of the environment variable s. It
  212. fails if the environment variable is not set. It also fails on
  213. systems that do not support environment variables.
  214.  
  215. remove(s)
  216.  
  217.    remove(s) removes the file named s. Subsequent attempts to
  218. open the file fail, unless it is created anew. If the file is
  219. open, the behavior of remove(s) is system dependent. remove(s)
  220. fails if it is unsuccessful.
  221.  
  222. rename(s1,s2)
  223.  
  224.    rename(s1,s2) causes the file named s1 to be henceforth known
  225. by the name s2.  The file named s1 is effectively removed. If a
  226. file named s2 exists prior to the renaming, the behavior is sys-
  227. tem dependent.  rename(s1,s2) fails if unsuccessful, in which
  228. case if the file existed previously it is still known by its ori-
  229. ginal name. Among the other possible causes of failure would be a
  230. file currently open, or a necessity to copy the file's contents
  231. to rename it.
  232.  
  233. seek(f,i)
  234.  
  235.    seek(f,i) seeks to position i in file f.  As with other posi-
  236. tions in Icon, a nonpositive value of i can be used to reference
  237. a position relative to the end of f.  i defaults to 1.  seek(f,i)
  238. returns f but fails if an error occurs.
  239.  
  240. where(f)
  241.  
  242.    where(f) returns the current byte position in the file f.
  243.  
  244.  [] Characters and Ordinals
  245.  
  246. char(i)
  247.  
  248.    char(i) produces a string containing the character whose
  249. internal representation, or ordinal, is the integer i. i must be
  250. between 0 and 255 inclusive.  If i is out of range, or not con-
  251. vertible to integer, a run-time error occurs.
  252.  
  253. ord(s)
  254.  
  255.    ord(s) produces an integer between 0 and 255 representing the
  256. ordinal, or internal representation, of a character. If s is not
  257. convertible to string, or if the string's length is not 1, a
  258. run-time error occurs.
  259.  
  260.  
  261.  
  262.                              - 3 -
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  [] Tab Expansion and Insertion
  272.  
  273. detab(s,i1,i2,...,in)
  274.  
  275.    detab(s,i1,i2,...,in) replaces each tab character in s by one
  276. or more space characters, using tab stops at i1,i2...,in, and
  277. then additional tab stops created by repeating the last interval
  278. as necessary. The default is detab(s,9).
  279.  
  280.    Tab stops must be positive and strictly increasing. There is
  281. an implicit tab stop at position 1 to establish the first inter-
  282. val. Examples:
  283.  
  284. detab(s)             tab stops at 9, 17, 25, 33, ...
  285. detab(s,5)           tab stops at 5, 9, 13, 17, ...
  286. detab(s,8,12)        tab stops at 8, 12, 16, 20, ...
  287. detab(s,11,18,30,36) tab stops at 11, 18, 30, 36, 42, 48, ...
  288.  
  289. For purposes of tab processing, "\b" has a width of -1, and "\r"
  290. and "\n" restart the counting of positions. Other nonprinting
  291. characters have zero width, and printing characters have a width
  292. of 1.
  293.  
  294. entab(s,i1,i2,...,in)
  295.  
  296.    entab(s,i1,i2,...,in) replaces runs of consecutive spaces with
  297. tab characters.  Tab stops are specified in the same manner as
  298. for the detab function. Any existing tab characters in s are
  299. preserved, and other nonprinting characters are treated identi-
  300. cally with the detab function.  The default is entab(s,9).
  301.  
  302.    A lone space is never replaced by a tab character;  however, a
  303. tab character may replace a single space character that is part
  304. of a longer run.
  305.  
  306.  [] Bit-Wise Functions
  307.  
  308.    The following functions operate on the individual bits compos-
  309. ing one or two integers. All produce an integer result.
  310.  
  311. iand(i,j)   produces the bit-wise and of i and j
  312. ior(i,j)    produces the bit-wise inclusive or of i and j
  313. ixor(i,j)   produces the bit-wise exclusive or of i and j
  314. icom(i)     produces the bit-wise complement (one's complement) of i
  315. ishift(i,j) If j is positive, produces i shifted left by j bit positions.
  316.             If j is negative, produces i shifted right by -j bit positions.
  317.             If j is zero, produces i.
  318.             In all cases, vacated bit positions are filled with zeroes.
  319.  
  320.  
  321.  [] Executable Images
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.                              - 4 -
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337. save(s)
  338.  
  339.    The function save(s) saves an executable image of an executing
  340. Icon program in the file named s. This function presently is
  341. implemented only on 4.nbsd UNIX systems. See Section 2.11 for a
  342. method of determining if this feature is implemented.
  343.  
  344.    save can be called from any point in a program. It accepts a
  345. single argument that names the file that is to receive the
  346. resulting executable.  The named file is created if it does not
  347. exist. Any output problems on the file cause save to fail. For
  348. lack of anything better, save returns the number of bytes in the
  349. data region.
  350.  
  351.    When the new executable is run, execution of the Icon program
  352. begins in the main procedure. Global and static variables have
  353. the value they had when save was called, but all dynamic local
  354. variables have the null value. Any initial clauses that have been
  355. executed are not re-executed.  As usual, arguments present on the
  356. command line are passed to the main procedure as a list.  Command
  357. line input and output redirections are processed normally, but
  358. any files that were open are no longer open and attempts to read
  359. or write them will fail.
  360.  
  361.    When the Icon interpreter starts up, it examines a number of
  362. environment variables to determine various operational parame-
  363. ters. When a saved executable starts up, the environment vari-
  364. ables are not examined; the parameter values recorded in the exe-
  365. cutable are used instead.  Note that many of the parameter values
  366. are dynamic and may have changed considerably from values sup-
  367. plied initially.
  368.  
  369.    Consider an example:
  370.  
  371.         global hello
  372.         procedure main()
  373.            initial {
  374.               hello := "Hello World!"
  375.               save("hello") | stop("Error saving to 'hello'")
  376.               exit()
  377.               }
  378.            write(hello)
  379.         end
  380.  
  381.  
  382.    The global variable hello is assigned "Hello World!" and then
  383. the interpreter is saved to the file hello. The program then
  384. exits.  When hello is run, main's initial clause is skipped since
  385. it has already been executed. The variable hello has retained its
  386. value and the call to write produces the expected greeting.
  387.  
  388.    It is possible to call save any number of times during the
  389. course of execution. Saving to the same file each time is rather
  390. uninteresting, but imagine a complex data structure that passes
  391.  
  392.  
  393.  
  394.                              - 5 -
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403. through levels of refinement and then saving out a series of exe-
  404. cutables that capture the state of the structure at given times.
  405.  
  406.    Saved executables contain the entire data space present at the
  407. time of the save and thus can be quite large. Saved executables
  408. on the VAX are typically around 250k bytes.
  409.  
  410. Integer Sequences
  411.  
  412.    seq(i,j) generates an infinite sequence of integers starting
  413. at i with increments of j. An omitted or null-valued argument
  414. defaults to 1. For example, seq() generates 1, 2, 3, ... .
  415.  
  416. 2.3  Structures
  417.  
  418. Sets
  419.  
  420.    Sets are unordered collections of values and have many of the
  421. properties normally associated with sets in the mathematical
  422. sense.  The function
  423.  
  424.         set(a)
  425.  
  426. creates a set that contains the distinct elements of the list a.
  427. For example,
  428.  
  429.         set(["abc",3])
  430.  
  431. creates a set with two members, abc and 3.
  432.  
  433.    [] The default value for an omitted argument to set is an
  434. empty list.  Consequently,
  435.  
  436.         set()
  437.  
  438. creates an empty set.
  439.  
  440.    Sets, like other data aggregates in Icon, need not be homo-
  441. geneous - a set may contain members of different types.
  442.  
  443.    Sets, like other Icon data aggregates, are represented by
  444. pointers to the actual data. Sets can be members of sets, as in
  445.  
  446.         s1 := set([1,2,3])
  447.         s2 := set([s1,[]])
  448.  
  449. in which s2 contains two members, one of which is a set of three
  450. members and the other of which is an empty list.
  451.  
  452.    Any specific value can occur only once in a set. For example,
  453.  
  454.         set([1,2,3,3,1])
  455.  
  456. creates a set with the three members 1, 2, and 3.  Set membership
  457.  
  458.  
  459.  
  460.                              - 6 -
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469. is determined the same way the equivalence of values is deter-
  470. mined in the operation
  471.  
  472.         x === y
  473.  
  474. For example,
  475.  
  476.         set([[],[]])
  477.  
  478. creates a set that contains two distinct empty lists.
  479.  
  480.    Several set operations are provided. The function
  481.  
  482.         member(s,x)
  483.  
  484. succeeds and returns the value of x if x is a member of s, but
  485. fails otherwise. Note that
  486.  
  487.         member(s1,member(s2,x))
  488.  
  489. succeeds if x is a member of both s1 and s2.
  490.  
  491.    The function
  492.  
  493.         insert(s,x)
  494.  
  495. inserts x into the set s and returns the value of s.  Note that
  496. insert(s,x) is similar to put(a,x) in form.  A set may contain (a
  497. pointer to) itself:
  498.  
  499.         insert(s,s)
  500.  
  501. adds s as an member of itself.
  502.  
  503.    The function
  504.  
  505.         delete(s,x)
  506.  
  507. deletes the member x from the set s and returns the value of s.
  508.  
  509.    The functions insert(s,x) and delete(s,x) always succeed,
  510. whether or not x is in s. This allows their use in loops in which
  511. failure may occur for other reasons. For example,
  512.  
  513.         s := set()
  514.         while insert(s,read())
  515.  
  516. builds a set that consists of the (distinct) lines from the stan-
  517. dard input file.
  518.  
  519.    The operations
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.                              - 7 -
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.         s1 ++ s2
  536.         s1 ** s2
  537.         s1 -- s2
  538.  
  539. create the union, intersection, and difference of s1 and s2,
  540. respectively. In each case, the result is a new set.
  541.  
  542.    The use of these operations on csets is unchanged. There is no
  543. automatic type conversion between csets and sets; the result of
  544. the operation depends on the types of the arguments. For example,
  545.  
  546.         'aeiou' ++ 'abcde'
  547.  
  548. produces the cset 'abcdeiou', while
  549.  
  550.         set([1,2,3]) ++ set([2,3,4])
  551.  
  552. produces a set that contains 1, 2, 3, and 4. On the other hand,
  553.  
  554.         set([1,2,3]) ++ 4
  555.  
  556. results in Run-time Error 119 (set expected).
  557.  
  558.    The functions and operations of Icon that apply to other data
  559. aggregates apply to sets as well. For example, if s is a set,
  560.  
  561.         *s
  562.  
  563. is the size of s (the number of members in it). Similarly,
  564.  
  565.         type(s)
  566.  
  567. produces the string set.  The string images of sets are in the
  568. same style as for other aggregates, with the size enclosed in
  569. parentheses. Therefore,
  570.  
  571.         s := set(["abc",3])
  572.         write(image(s))
  573.  
  574. writes set(2).
  575.  
  576.    The operation
  577.  
  578.         !s
  579.  
  580. generates the members of s, but in no predictable order. Simi-
  581. larly,
  582.  
  583.         ?s
  584.  
  585. produces a randomly selected member of s.  These operations pro-
  586. duce values, not variables - it is not possible to assign a value
  587. to !s or ?s.
  588.  
  589.  
  590.  
  591.  
  592.                              - 8 -
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.    The function
  602.  
  603.         copy(s)
  604.  
  605. produces a new set, distinct from s, but which contains the same
  606. members as s. The copy is made in the same fashion as the copy of
  607. a list - the members themselves are not copied.
  608.  
  609.    The function
  610.  
  611.         sort(s)
  612.  
  613. produces a list containing the members of s in sorted order.
  614. Sets occur after tables but before records in Icon's collating
  615. sequence.
  616.  
  617. Examples
  618.  
  619. Word Counting:
  620.  
  621.    The following program lists, in alphabetical order, all the
  622. different words that occur in standard input:
  623.  
  624.         procedure main()
  625.            letter := &lcase ++ &ucase
  626.            words := set()
  627.            while text := read() do
  628.               text ? while tab(upto(letter)) do
  629.                  insert(words,tab(many(letter)))
  630.            every write(!sort(words))
  631.         end
  632.  
  633.  
  634. The Sieve of Eratosthenes:
  635.  
  636.    The follow program produces prime numbers, using the classical
  637. ``Sieve of Eratosthenes'':
  638.  
  639.         procedure main()
  640.            local limit, s, i
  641.            limit := 5000
  642.            s := set()
  643.            every insert(s,1 to limit)
  644.            every member(s,i := 2 to limit) do
  645.               every delete(s,i + i to limit by i)
  646.            primes := sort(s)
  647.            write("There are ",*primes," primes in the first ",limit," integers.")
  648.            write("The primes are:")
  649.            every write(right(!primes,*limit + 1))
  650.         end
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.                              - 9 -
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  [] Tables
  668.  
  669.    The functions member, insert, and delete apply to tables as
  670. well as sets.
  671.  
  672.    The function member(t,x) succeeds if x is an entry value (key)
  673. in the table t, but fails otherwise.
  674.  
  675.    The function insert(t,x,y) inserts the entry value x into
  676. table t with the assigned value y. If there already was an entry
  677. value x in t, its assigned value is changed.  Note that insert
  678. has three arguments when used with tables, as compared to two
  679. when used with sets. An omitted third argument defaults to the
  680. null value.
  681.  
  682.    The function delete(t,x) removes the entry value x and its
  683. corresponding assigned value from t. If x is not an entry value
  684. in t, no operation is performed; delete succeeds in either case.
  685.  
  686.  [] Sorting Order for Elements of Lists and Tables
  687.  
  688.    A complete ordering is now defined for structures (lists,
  689. sets, tables, and records) and csets that appear in a larger
  690. structure to be sorted.  Different types are still kept separate,
  691. but within each structure type, elements are now sorted chrono-
  692. logically (in the order they were created). All of the different
  693. record types are sorted together.  Csets are sorted lexically, in
  694. the same fashion as strings.
  695.  
  696. Sorting Options for Tables
  697.  
  698.    Two new options are available for sorting tables. These
  699. options are specified by the values 3 and 4 as the second argu-
  700. ment of sort(t,i).  Both of these options produce a single list
  701. in which the entry values and assigned values of table elements
  702. alternate. A value of 3 for i produces a list in which the entry
  703. values are in sorted order, and a value of 4 produces a list in
  704. which the assigned values are in sorted order. For example, if
  705. the table wcount contains elements whose entry values are words
  706. and whose corresponding assigned values are counts, the following
  707. code segment writes out a list of the words and their counts,
  708. with the words in alphabetical order:
  709.  
  710.         a := sort(wcount,3)
  711.         every i := 1 to *a - 1 by 2 do
  712.            write(a[i]," : ",a[i + 1])
  713.  
  714.  
  715.    The main advantage of the new sorting options is that they
  716. only produce a single list, rather than a list of lists as pro-
  717. duced by the options 1 and 2. The amount of space needed for the
  718. single list is proportionally much less than for the list of
  719. lists.
  720.  
  721.  
  722.  
  723.  
  724.                              - 10 -
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733. 2.4  Programmer-Defined Control Operations
  734.  
  735.    As described in [3], co-expressions can be used to provide
  736. programmer-defined control operations. Version 7 provides support
  737. for this facility by means of an alternative syntax for procedure
  738. invocation in which the arguments are passed in a list of co-
  739. expressions. This syntax uses braces in place of parentheses:
  740.  
  741.         p{expr1, expr2, ..., exprn}
  742.  
  743. is equivalent to
  744.  
  745.         p([create expr1, create expr2, ..., create exprn])
  746.  
  747. Note that
  748.  
  749.         p{}
  750.  
  751. is equivalent to
  752.  
  753.         p([])
  754.  
  755.  
  756. 2.5  Invocation By String Name
  757.  
  758.    A string-valued expression that corresponds to the name of a
  759. procedure or operation can be used in place of the procedure or
  760. operation in an invocation expression. For example,
  761.  
  762.         "image"(x)
  763.  
  764. produces the same call as
  765.  
  766.         image(x)
  767.  
  768. and
  769.  
  770.         "-"(i,j)
  771.  
  772. is equivalent to
  773.  
  774.         i - j
  775.  
  776.  
  777.    In the case of operator symbols with unary and binary forms,
  778. the number of arguments determines the operation. Thus
  779.  
  780.         "-"(i)
  781.  
  782. is equivalent to
  783.  
  784.         -i
  785.  
  786. Since to-by is an operation, despite its reserved-word syntax, it
  787.  
  788.  
  789.  
  790.                              - 11 -
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799. is included in this facility with the string name "..." .  Thus
  800.  
  801.         "..."(1,10,2)
  802.  
  803. is equivalent to
  804.  
  805.         1 to 10 by 2
  806.  
  807. Similarly, range specifications are represented by ":", so that
  808.  
  809.         ":"(s,i,j)
  810.  
  811. is equivalent to
  812.  
  813.         s[i:j]
  814.  
  815. The subscripting operation is available with the string name
  816. "[]". Thus
  817.  
  818.         "[]"(&lcase,3)
  819.  
  820. produces c.
  821.  
  822.    Defaults are not provided for omitted or null-valued arguments
  823. in this facility. Consequently,
  824.  
  825.         "..."(1,10)
  826.  
  827. results in a run-time error when it is evaluated.
  828.  
  829.    Arguments to operators invoked by string names are derefer-
  830. enced. Consequently, string invocation for assignment operations
  831. is ineffective and results in error termination.
  832.  
  833.    String names are available for the operations in Icon, but not
  834. for control structures. Thus
  835.  
  836.         "|"(expr1,expr2)
  837.  
  838. is erroneous.  Note that string scanning is a control structure.
  839.  
  840.    Field references, of the form
  841.  
  842.         expr . fieldname
  843.  
  844. are not operations in the ordinary sense and are not available
  845. via string invocation.  In addition, conjunction is not available
  846. via string invocation, since no operation is actually performed.
  847.  
  848.    String names for procedures are available through global iden-
  849. tifiers.  Note that the names of functions, such as image, are
  850. global identifiers. Similarly, any procedure-valued global iden-
  851. tifier may be used as the string name of a procedure. Thus in
  852.  
  853.  
  854.  
  855.  
  856.                              - 12 -
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.         global q
  866.  
  867.         procedure main()
  868.            q := p
  869.            "q"("hi")
  870.         end
  871.  
  872.         procedure p(s)
  873.            write(s)
  874.         end
  875.  
  876. the procedure p is invoked via the global identifier q.
  877.  
  878.    The function proc(x,i) converts x to a procedure, if possible.
  879. If x is procedure-valued, its value is returned unchanged. If the
  880. value of x is a string that corresponds to the name of a pro-
  881. cedure as described in the preceding section, the corresponding
  882. procedure value is returned.  The value of i is used to distin-
  883. guish between unary and binary operators.  For example,
  884. proc("*",2) produces the multiplication operator, while
  885. proc("*",1) produces the size operator.  The default value for i
  886. is 1.  If x cannot be converted to a procedure, proc(x,i) fails.
  887.  
  888. 2.6   [] String Scanning
  889.  
  890.    Scanning environments (&subject and &pos) are now maintained
  891. correctly.  In particular, they are are now restored when a scan-
  892. ning expression is exited via break, next, return, fail, and
  893. suspend. This really is a correction of a bug, although the
  894. former handling of scanning environments is described as a
  895. `feature' in the Icon book. Note also that this change could
  896. affect the behavior of existing Icon programs.
  897.  
  898. 2.7   [] Procedures with a Variable Number of Arguments
  899.  
  900.    A procedure can be made to accept a variable number of argu-
  901. ments by appending [] to the last (or only) parameter in the
  902. parameter list.  An example is:
  903.  
  904.         procedure p(a,b,c[])
  905.           suspend a + b + !c
  906.         end
  907.  
  908.  
  909. If called as p(1,2,3,4,5), the parameters have the following
  910. values:
  911.  
  912.         a    1
  913.         b    2
  914.         c    [3,4,5]
  915.  
  916.  
  917.    The last parameter always contains a list. This list consists
  918. of the arguments not used by the previous parameters. If the
  919.  
  920.  
  921.  
  922.                              - 13 -
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931. previous parameters use up all the arguments, the list is empty.
  932. If there are not enough arguments to satisfy the previous parame-
  933. ters, the null value will be used for the remaining ones, but the
  934. last parameter will still contain the empty list.
  935.  
  936.    The following procedure, which models the function write, but
  937. keeps a count of the number of arguments written, illustrates a
  938. use of this feature:
  939.  
  940.         global wcount
  941.  
  942.  
  943.         procedure Write(a[])
  944.            initial wcount := 0
  945.            wcount +:= *a
  946.            every writes(!a)
  947.            write()
  948.         end
  949.  
  950.  
  951. 2.8   [] Co-Expressions
  952.  
  953.    Co-expression return points are now handled properly, so that
  954. co-expressions can be used as coroutines.
  955.  
  956.    The image of a co-expression now includes an identifying
  957. number. Numbers start with 1 for &main and increase as new co-
  958. expressions are created.
  959.  
  960.    Co-expression activation and return are now traced along with
  961. procedure calls and returns if &trace is nonzero. Co-expression
  962. tracing shows the identifying numbers.
  963.  
  964.    There is a new keyword, ¤t, the current co-expression.
  965.  
  966. 2.9   [] Input and Output
  967.  
  968.    There no longer are any length limitations on the string pro-
  969. duced by read() or reads(), nor on the length of the argument to
  970. system() or the first argument of open().
  971.  
  972.    Formerly the value returned by write(x1,x2,...,xn) and
  973. writes(x1,x2,...,xn) was the last written argument converted to a
  974. string. The conversion is no longer performed. For example, the
  975. value returned by write(1) is the integer 1.
  976.  
  977.    Errors during writing (such as inadequate space on the output
  978. device) now cause error termination.
  979.  
  980.    The function read(f) reads the last line of the file f, even
  981. if that line does not end with a newline (Version 5 discarded
  982. such a line).
  983.  
  984.    If the file f is open as a pipe, close(f) returns the system
  985.  
  986.  
  987.  
  988.                              - 14 -
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997. code resulting from closing f instead of f.
  998.  
  999.    Icon no longer performs its own I/O buffering; instead, this
  1000. function is left to the operating system on which Icon runs. The
  1001. environment variable NBUFS is no longer supported.
  1002.  
  1003. 2.10  Errors
  1004.  
  1005.  [] Error Traceback
  1006.  
  1007.    A run-time error now shows a traceback, giving the sequence of
  1008. procedure calls to the site of the error, followed by a symbolic
  1009. rendering of the offending expression.  For example, suppose the
  1010. following program is contained in the file max.icn:
  1011.  
  1012.         procedure main()
  1013.            i := max("a",1)
  1014.         end
  1015.  
  1016.  
  1017.         procedure max(i,j)
  1018.            if i > j then i else j
  1019.         end
  1020.  
  1021. Its execution in Version 7 produces the following output:
  1022.  
  1023.         Run-time error 102
  1024.         File max.icn; Line 6
  1025.         numeric expected
  1026.         offending value: "a"
  1027.         Traceback:
  1028.            main()
  1029.            max("a",1) from line 2 in max.icn
  1030.            {"a" > 1} from line 6 in max.icn
  1031.  
  1032.  
  1033.  [] Error Conversion
  1034.  
  1035.    A new keyword, &error, is provided to allow users to convert
  1036. most run-time errors into expression failure. It behaves like
  1037. &trace: if it is zero, the default value, errors are handled as
  1038. usual. If it is non-zero, errors are treated as failure and
  1039. &error is decremented.
  1040.  
  1041.    There are a few errors that cannot be converted to failure:
  1042. arithmetic overflow and underflow, stack overflow, and errors
  1043. during program initialization.
  1044.  
  1045.    When an error is converted to failure in this way, three key-
  1046. words are set:
  1047.  
  1048.      +  &errornumber is the number of the error (e.g., 101).
  1049.         Reference to &errornumber fails if there has not been an
  1050.         error.
  1051.  
  1052.  
  1053.  
  1054.                              - 15 -
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.      +  &errortext is the error message (e.g., integer expected).
  1064.  
  1065.      +  &errorvalue is the offending value. Reference to &error-
  1066.         value fails if there is no specific offending value.
  1067.  
  1068. The function errorclear() removes the indication of the last
  1069. error. Subsequent references to &errornumber fail until another
  1070. error occurs.
  1071.  
  1072.    A use of these keywords is illustrated by the following pro-
  1073. cedure, which could be used to process potential run-time errors
  1074. that had been converted to failure:
  1075.  
  1076.         procedure ErrorCheck()
  1077.            write("\nError ",&errornumber)
  1078.            write(&errortext)
  1079.            write("offending value: ",image(&errorvalue))
  1080.            writes("\nDo you want to continue? (n)")
  1081.            if map(read()) == ("y" | "yes") then return
  1082.            else exit()
  1083.         end
  1084.  
  1085.  
  1086. For example,
  1087.  
  1088.            &error := -1
  1089.                .
  1090.                .
  1091.                .
  1092.            write(s) | ErrorCheck()
  1093.  
  1094. could be used to check for an error during writing, while
  1095.  
  1096.            (a := sort(t,3)) | ErrorCheck()
  1097.  
  1098. could be used to detect failure to sort a table into a list (for
  1099. lack of adequate storage).
  1100.  
  1101.    The function runerr(i,x) causes program execution to terminate
  1102. with error number i as if a corresponding run-time error had
  1103. occurred. If i is the number of a standard run-time error, the
  1104. corresponding error text is printed; otherwise no error text is
  1105. printed. The value of x is given as the offending value. If x is
  1106. omitted, no offending value is printed.
  1107.  
  1108.    This function is provided so that library procedures can be
  1109. written to terminate in the same fashion as built-in operations.
  1110. It is advisable to use error numbers for programmer-defined
  1111. errors that are well outside the range of numbers used by Icon
  1112. itself. See Appendix B. Error number 500 has the predefined text
  1113. program malfunction for use with runerr.  This number is not used
  1114. by Icon itself.
  1115.  
  1116.    A call of runerr is subject to conversion to failure like any
  1117.  
  1118.  
  1119.  
  1120.                              - 16 -
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129. other run-time error.
  1130.  
  1131. 2.11   [] Implementation Features
  1132.  
  1133.    Since different implementations of Icon may support different
  1134. features and some installations may chose to provide a subset of
  1135. the full Version 7, the keyword &features has been provided to
  1136. provide such information. &features generates the features of the
  1137. implementation on which the current program is running. For exam-
  1138. ple, on a 4.nbsd UNIX implementation,
  1139.  
  1140.         every write(&features)
  1141.  
  1142. produces
  1143.  
  1144.         UNIX
  1145.         co-expressions
  1146.         overflow checking
  1147.         direct execution
  1148.         environment variables
  1149.         error traceback
  1150.         executable images
  1151.         string invocation
  1152.         expandable regions
  1153.  
  1154.  
  1155.    Similarly, a program that uses co-expressions can check for
  1156. the presence of this feature:
  1157.  
  1158.         if not(&features == "co-expressions") then runerr(-401)
  1159.  
  1160.  
  1161. 2.12   [] Storage Management
  1162.  
  1163.    Storage is allocated automatically during the execution of an
  1164. Icon program, and garbage collections are performed automatically
  1165. to reclaim storage for subsequent reallocation.  There are three
  1166. storage regions: static, string, and block.  Only implementations
  1167. in which regions can be expanded support a static region.  See
  1168. [4] for more information.
  1169.  
  1170.    An Icon programmer normally need not worry about storage
  1171. management.  However, in applications that require a large amount
  1172. of storage or that must operate in a limited amount of memory,
  1173. some knowledge of the storage management process may be useful.
  1174.  
  1175.    The keyword &collections generates four values associated with
  1176. garbage collection: the total number since program initiation,
  1177. the number triggered by static allocation, the number triggered
  1178. by string allocation, and the number triggered by block alloca-
  1179. tion.  The keyword ®ions generates the current sizes of the
  1180. static, string, and block regions.  The keyword &storage gen-
  1181. erates the current amount of space used in the static, string,
  1182. and block regions. The value given for the static region
  1183.  
  1184.  
  1185.  
  1186.                              - 17 -
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195. presently is not meaningful.
  1196.  
  1197.    Garbage collection can be forced by the function collect().
  1198.  
  1199. 2.13  Version Checking
  1200.  
  1201.    The Icon translator converts a source-language program to an
  1202. intermediate form, called ucode. The Icon linker converts one or
  1203. more ucode files to a binary form called icode. The format of
  1204. Version 7 ucode and icode files is different from that of earlier
  1205. versions.  To avoid the possibility of malfunction due to incom-
  1206. patible ucode and icode formats, Version 7 checks both ucode and
  1207. icode files and terminates processing with an error message if
  1208. the versions are not correct.
  1209.  
  1210. 2.14  Odds and Ends
  1211.  
  1212.  [] Other Keywords
  1213.  
  1214.    In addition to the new keywords mentioned above, there are
  1215. three others:
  1216.  
  1217.      +  &digits, whose value is the cset '0123456789'.
  1218.  
  1219.      +  &line, the current source-code line number.
  1220.  
  1221.      +  &file, the current source-code file name.
  1222.  
  1223.  [] External Data Type
  1224.  
  1225.    There is a new data type, external, for use in extensions to
  1226. Icon that require the allocation of unstructured blocks of data.
  1227. This data type should not be visible in standard versions of
  1228. Icon.
  1229.  
  1230.  [] Addition to suspend
  1231.  
  1232.    The suspend control structure now has an optional do clause,
  1233. analogous to every-do. If a do clause is present in a suspend
  1234. control structure, its argument is evaluated after the suspend is
  1235. resumed and before possible suspension with another result.
  1236.  
  1237.    For example, the following expression might be used to count
  1238. the number of suspensions:
  1239.  
  1240.         suspend expr do count +:= 1
  1241.  
  1242.  
  1243.  [] Linker Options
  1244.  
  1245.    The option to generate diagnostic (.ux) files during linking
  1246. has been changed from -D to -L.
  1247.  
  1248.    The amount of space needed to associate source-program line
  1249.  
  1250.  
  1251.  
  1252.                              - 18 -
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261. numbers with executable code can be set by -Snn. The default
  1262. value of n is 1000.  Similarly, the amount of space needed to
  1263. associate file names with executable code can be set by -SFn. The
  1264. default is 10.
  1265.  
  1266.  [] Path to iconx
  1267.  
  1268.    For implementations that support direct execution of icode
  1269. files, the hardwired path to iconx is overridden by the value of
  1270. the environment variable ICONX, if it is set.
  1271.  
  1272.  [] File Names
  1273.  
  1274.    During translation and linking, the suffix .u is interpreted
  1275. as .u1, and no suffix is interpreted as .icn.
  1276.  
  1277.    On MS-DOS, VMS, and the Atari ST the icode file produced by
  1278. the linker now has the extension icx.  For example,
  1279.  
  1280.         icont prog.icn
  1281.  
  1282. produces an icode file named prog.icx. The extension need not be
  1283. given when using iconx:
  1284.  
  1285.         iconx prog
  1286.  
  1287. looks first for prog.icx; failing that it looks for prog.
  1288.  
  1289.  [] Redirection of Error Output
  1290.  
  1291.    The option -e now allows standard error output to be
  1292. redirected to a file. For example,
  1293.  
  1294.         iconx -e prog.err prog
  1295.  
  1296. executes prog and sends any error output to the file prog.err.
  1297. If - is given in place of a file name, error output is redirected
  1298. to standard output. On systems on which standard output can be
  1299. redirected to a file, -e - causes both error output and standard
  1300. output go to that file. For example,
  1301.  
  1302.         iconx -e - prog >prog.out
  1303.  
  1304. redirects both error output and standard output to prog.out.  The
  1305. use of - with -e is not available on the Atari ST or Macintosh.
  1306.  
  1307.  
  1308. 3.  Obsolete and Changed Features of Version 5
  1309.  
  1310.    The original implementation of Version 5 supported both a com-
  1311. piler (iconc) and an interpreter (icont).  Version 7 supports
  1312. only an interpreter. Interpretation is only slightly slower than
  1313. the execution of compiled code and the interpreter is portable
  1314. and gets into execution much more quickly than the compiler.
  1315.  
  1316.  
  1317.  
  1318.                              - 19 -
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327. However, it is not possible to load C functions with the inter-
  1328. preter as it was with the compiler.  A system for personalized
  1329. interpreters [5] is included with Version 7 for UNIX systems to
  1330. make it comparatively easy to add new functions and otherwise
  1331. modify the Icon run-time system.
  1332.  
  1333.    Some run-time environment variables have changed; see Appendix
  1334. A.  Several error messages have been changed.  Appendix B con-
  1335. tains a list of run-time error messages for Version 7.
  1336.  
  1337.  
  1338. 4.  Known Bugs in Version 7
  1339.  
  1340.  
  1341.      +  The text of some translator error messages is incorrect
  1342.         and may not correctly reflect the nature of errors.
  1343.  
  1344.      +  The translator does not detect arithmetic overflow in
  1345.         conversion of numeric literals. Very large numeric
  1346.         literals may have incorrect values.
  1347.  
  1348.      +  Integer overflow on multiplication and exponentiation may
  1349.         not be detected during execution.  Such overflow may
  1350.         occur during type conversion.
  1351.  
  1352.      +  Line numbers may be wrong in diagnostic messages related
  1353.         to lines with continued quoted literals.
  1354.  
  1355.      +  In some cases, trace messages may show the return of sub-
  1356.         scripted values, such as &null[2], that would be errone-
  1357.         ous if they were dereferenced.
  1358.  
  1359.      +  If a long file name for an Icon source-language program
  1360.         is truncated by the operating system, mysterious diagnos-
  1361.         tic messages may occur during linking.
  1362.  
  1363.      +  Stack overflow is checked using a heuristic that may not
  1364.         always be effective.
  1365.  
  1366.      +  If an expression such as
  1367.  
  1368.                 x := create expr
  1369.  
  1370.         is used in a loop, and x is not a global variable,
  1371.         unreferenceable co-expressions are generated by each suc-
  1372.         cessive create operation.  These co-expressions are not
  1373.         garbage collected.  This problem can be circumvented by
  1374.         making x a global variable or by assigning a value to x
  1375.         before the create operation, as in
  1376.  
  1377.                 x := &null
  1378.                 x := create expr
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.                              - 20 -
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.      +  Stack overflow in a co-expression may not be detected and
  1394.         may cause mysterious program malfunction.
  1395.  
  1396.  
  1397. 5.  Possible Differences Among Version 7 Implementations
  1398.  
  1399.    A few aspects of the implementation of Version 7 are specific
  1400. to different computer architectures and operating systems. Co-
  1401. expressions require a context switch that is implemented in
  1402. assembly language.  If this context switch is not implemented, an
  1403. attempt to activate a co-expression results in error termination.
  1404. Arithmetic overflow checking also generally requires assembly-
  1405. language routines and may not be supported on some implementa-
  1406. tions of Version 7.
  1407.  
  1408.    Some features of Icon, such as opening a pipe for I/O and the
  1409. system function, are not supported on all operating systems.
  1410.  
  1411. Acknowledgements
  1412.  
  1413.    In addition to the authors of this report, Dave Gudeman and
  1414. Bill Mitchell made significant contributions to Version 7 of
  1415. Icon.
  1416.  
  1417. References
  1418.  
  1419. 1.  Griswold, Ralph E. and Madge T. Griswold. The Icon Program-
  1420. ming Language, Prentice-Hall, Inc., Englewood Cliffs, New Jersey.
  1421. 1983.
  1422.  
  1423. 2.  Griswold, Ralph E. ICONT(1), manual page for UNIX
  1424. Programmer's Manual, Department of Computer Science, The Univer-
  1425. sity of Arizona. 1988.
  1426.  
  1427. 3.  Griswold, Ralph E. and Michael Novak. ``Programmer-Defined
  1428. Control Operations'', The Computer Journal, Vol. 26, No. 2 (May
  1429. 1983).
  1430.  
  1431. 4.  Griswold, Ralph E. and Madge T. Griswold.  The Implementation
  1432. of the Icon Programming Language, Princeton University Press,
  1433. Princeton, New Jersey. 1987.
  1434.  
  1435. 5.  Griswold, Ralph E. Personalized Interpreters for Version 7 of
  1436. Icon, Technical Report TR 88-7, Department of Computer Science,
  1437. The University of Arizona. 1988.
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.                              - 21 -
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.                Appendix A - Environment Variables
  1460.  
  1461.  
  1462.  
  1463.  
  1464.    There are a number of environment variables that can be set to
  1465. override the default values for sizes of Icon's storage regions
  1466. and other run-time parameters.  Except for ICONX, NOERRBUF, and
  1467. ICONCORE, the values assigned to these environment variables must
  1468. be numbers.  Default values for regions vary from system to sys-
  1469. tem and are given in users manuals.  Some implementations also
  1470. have other environment variables.
  1471.  
  1472.    The environment variables are:
  1473.  
  1474.      ICONX     If set, this environment variable is used for the
  1475.                location of iconx used to execute an icode file.
  1476.  
  1477.      TRACE     Specifies the initial value of &trace. The default
  1478.                value is zero.
  1479.  
  1480.      NOERRBUF  If set, standard error output is not buffered.
  1481.  
  1482.      ICONCORE  If set, a core dump is produced in the case of
  1483.                error termination.
  1484.  
  1485.      MSTKSIZE  Specifies the size in words of the main inter-
  1486.                preter stack.
  1487.  
  1488.      STRSIZE   Specifies the initial size in bytes of the allo-
  1489.                cated string region.
  1490.  
  1491.      HEAPSIZE  Specifies the initial size in bytes of the allo-
  1492.                cated block region.
  1493.  
  1494.      STATSIZE  Specifies the initial size in bytes of the static
  1495.                region in which co-expressions are allocated.
  1496.  
  1497.      STATINCR  Specifies the increment for expanding the static
  1498.                region. The default increment is one-fourth the
  1499.                initial size of the static region.
  1500.  
  1501.      COEXPSIZE Specifies the size in words of co-expression
  1502.                blocks.
  1503.  
  1504.      QLSIZE    Specifies the amount of space used for pointers to
  1505.                strings during garbage collection. Used only on
  1506.                implementations with fixed memory regions.
  1507.  
  1508.    An inappropriate setting of an environment variable prevents
  1509. the program from starting.
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.                              - 22 -
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.               Appendix B - Run-Time Error Messages
  1526.  
  1527.  
  1528.  
  1529.  
  1530.  
  1531.    A list of run-time error numbers and corresponding messages
  1532. follows.  Some implementations have additional run-time errors.
  1533.  
  1534.         101     integer expected
  1535.         102     numeric expected
  1536.         103     string expected
  1537.         104     cset expected
  1538.         105     file expected
  1539.         106     procedure or integer expected
  1540.         107     record expected
  1541.         108     list expected
  1542.         109     string or file expected
  1543.         110     string or list expected
  1544.         111     variable expected
  1545.         112     invalid type to size operation
  1546.         113     invalid type to random operation
  1547.         114     invalid type to subscript operation
  1548.         115     list or table expected
  1549.         116     invalid type to element generator
  1550.         117     missing main procedure
  1551.         118     co-expression expected
  1552.         119     set expected
  1553.         120     cset or set expected
  1554.         121     function not supported
  1555.         122     set or table expected
  1556.  
  1557.         201     division by zero
  1558.         202     remaindering by zero
  1559.         203     integer overflow
  1560.         204     real overflow, underflow, or division by zero
  1561.         205     value out of range
  1562.         206     negative first operand to real exponentiation
  1563.         207     invalid field name
  1564.         208     second and third arguments to map of unequal length
  1565.         209     invalid second argument to open
  1566.         210     non-ascending arguments to detab/entab
  1567.         211     by clause equal to zero
  1568.         212     attempt to read file not open for reading
  1569.         213     attempt to write file not open for writing
  1570.         214     input/output error
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.                              - 23 -
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.         301     interpreter stack overflow
  1592.         302     C stack overflow
  1593.         303     inadequate space for interpreter stack
  1594.         304     inadequate space in qualifier list
  1595.         305     inadequate space in static region
  1596.         306     inadequate space in string region
  1597.         307     inadequate space in block region
  1598.  
  1599.         401     co-expressions not implemented
  1600.  
  1601.         500     program malfunction
  1602.  
  1603.  
  1604.  
  1605.  
  1606.  
  1607.  
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.                              - 24 -
  1649.  
  1650.  
  1651.