home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_disks / 200-299 / ff277.lzh / Icon / guide.doc < prev    next >
Text File  |  1989-11-16  |  22KB  |  769 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                 Version 7.5 of Icon for the Amiga
  8.  
  9.                          Clinton Jeffery
  10.                           June 2, 1989
  11.  
  12.  
  13.  
  14.  
  15. 1.  Introduction
  16.  
  17.    This is an implementation of Version 7.5 of the Icon program-
  18. ming language for Amiga computers.
  19.  
  20.    This implementation is in the public domain and may be copied
  21. and used without restriction. Icon is distributed free of charge
  22. by the University of Arizona, except for the costs of media,
  23. documentation, handling and shipping. No warranties of any kind
  24. as to the correctness of this material or its suitability for any
  25. application are made or implied. The responsibility for the use
  26. of Icon rests entirely with the user.
  27.  
  28.  
  29. 2.  Documentation
  30.  
  31.    The basic reference for the Icon programming language is the
  32. book The Icon Programming Language by Ralph E. Griswold and Madge
  33. T. Griswold, Prentice-Hall, Inc., Englewood Cliffs, New Jersey,
  34. 1983.  313 pages,  ISBN 0-13-449777-5. $29.95.
  35.  
  36.    This book is available in many college bookstores or can be
  37. ordered through any bookstore that handles special orders or by
  38. telephone directly from Prentice-Hall: (201) 767-9520.  It also
  39. is available from the Icon Project at the Department of Computer
  40. Science at the University of Arizona.
  41.  
  42.    A brief overview of Icon is contained in technical report TR
  43. 83-3 [1] (overview.doc on the distribution diskette). Features
  44. that have been added to Icon since the book was written are
  45. described in TR 88-41 [2] (version7.doc on the distribution
  46. diskette). These technical reports, together with this document
  47. (guide.doc on the distribution diskette), provide enough informa-
  48. tion to write simple Icon programs, but if you are going to use
  49. Icon seriously, you will need the book.  You may also find it
  50. useful to examine the sample programs located on the distribution
  51. diskette.
  52.  
  53.  
  54. 3.  Hardware and Software Requirements
  55.  
  56.    This version was designed to run under V1.3 of the Amiga
  57. operating system software, and the rest of this document assumes
  58. you are using it.  Amiga Icon version 7.5 has not been tested at
  59. all under V1.1 or V1.2.  There is no fundamental reason it cannot
  60. be used with the older versions; if you want to run Icon with an
  61.  
  62.  
  63.  
  64. IPD56                         - 1 -                  June 2, 1989
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73. older version of the operating system you may have problems if
  74. Icon can't find a path to its executables or if you need to use
  75. environment variables.
  76.  
  77.    This version of Icon is command-line based.  It does not run
  78. under the workbench and does not have any support for Workbench
  79. icons or any of the special Amiga features at this time.  You
  80. should be able to use your choice of: the CLI (for older versions
  81. of AmigaDOS), the new AmigaShell, or some third party shell such
  82. as Matt Dillon's shell.
  83.  
  84.    This version does not run comfortably in 512K.  It does run
  85. comfortably if you have 1 megabyte or more main memory.  A hard
  86. disk is also essential for any serious programming work.
  87.  
  88.    If you have expansion RAM, the preferred method of using Icon
  89. is to copy the Icon binary files into the RAM: area and run icont
  90. and iconx from there.  If you do not have sufficient expansion
  91. memory for this, you will have to run from disk. If you have only
  92. 512k of memory you might be able to run Icon by making size
  93. assignments to the appropriate environment variables as described
  94. below, but this has not been verified.
  95.  
  96.  
  97. 4.  Location of icont and iconx
  98.  
  99.    The Icon system naturally follows the standard AmigaDOS search
  100. path to find executable files. That is, it looks first in the
  101. current directory, then in the C: directory, and finally in any
  102. other directories that you have added to the search path by means
  103. of the PATH command.
  104.  
  105.    This means that you probably will want to place your icont and
  106. iconx commands in your C: directory if you have room there, or
  107. you can add the directory where the Icon binaries are located to
  108. your search path if you are running from the ICON: diskette.
  109.  
  110.  
  111. 5.  Running Icon
  112.  
  113.    To translate and link an Icon source program file named
  114. myfile.icn first you must add Icon7.5:c to your path (or copy the
  115. executables to some directory where AmigaDOS can find them), and
  116. then type
  117.  
  118.         icont myfile
  119.  
  120. which translates and links myfile.icn and produces the file named
  121. myfile. You can then execute this by typing
  122.  
  123.         iconx myfile
  124.  
  125. This can be done all in one step as
  126.  
  127.  
  128.  
  129.  
  130. IPD56                         - 2 -                  June 2, 1989
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.         icont myfile -x
  140.  
  141.  
  142.    The usual standard input and standard output redirection is
  143. supported by the CLI, but note that the AmigaDOS standard is for
  144. the redirection to be given before the other arguments, thus:
  145.  
  146.         iconx <infile >outfile myprogram  myarg1 myarg2 ...
  147.  
  148. If the redirection arguments are not given immediately following
  149. the iconx, they do not work.
  150.  
  151.    It is not possible to redirect the standard error output in
  152. this version but it is possible to combine the standard error
  153. output with the standard output by using the command line switch
  154. -e - as follows:
  155.  
  156.         iconx >outfile -e - myprogram args args ...
  157.  
  158. All the output from the program including error messages is sent
  159. to outfile. Note that it is necessary to type the dash (-) fol-
  160. lowing the switch. Just typing -e has no effect; you must type -e
  161. -.  This switch is only allowed on the iconx command. It does
  162. work on the icont command.
  163.  
  164.  
  165. 6.  Testing the Installation
  166.  
  167.    There are a few programs on the distribution diskette that may
  168. be used for testing the installation and getting a feel for run-
  169. ning Icon.  The programs and appropriate data files are located
  170. in the samples directory.  Note that files containing Icon pro-
  171. grams must have the extension .icn. Such files should be plain
  172. text files (without line numbers or other extraneous informa-
  173. tion). The command processor icont produces an icode file that
  174. can be executed by iconx.  For example, an Icon program in the
  175. file prog.icn is translated and linked by
  176.  
  177.         icont prog
  178.  
  179. The result is an icode file (binary) with the name prog (with the
  180. extension removed).  This file can be run by
  181.  
  182.         iconx prog
  183.  
  184. Alternatively, icont can be instructed to execute the program
  185. after translating and linking by appending a -x to the command
  186. line, as in
  187.  
  188.         icont prog -x
  189.  
  190. In this case the file prog also is left and can be run subse-
  191. quently using iconx.
  192.  
  193.  
  194.  
  195.  
  196. IPD56                         - 3 -                  June 2, 1989
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.    Note that the icont  and iconx programs are executable binary
  206. files and, as such their locations can be discovered by the nor-
  207. mal AmigaDOS executable file path search mechanism. But the icode
  208. file produced by icont from the Icon source file is not a
  209. directly executable file. It essentially is a data file that is
  210. read by the Icon interpreter iconx. Therefore, the location of
  211. the icode file is not known to AmigaDOS. There is no path search
  212. for data files. So your icode file (prog in the above examples)
  213. must either be in the current directory, or you must specify its
  214. location by giving the drive or directory path as part of the
  215. filename.
  216.  
  217.    For example, if your current directory is RAM:, and you wish
  218. to run the Icon program prog.icn, which might be located in the
  219. directory df1:src, and you have placed icont in a location where
  220. AmigaDOS can find it, you would type
  221.  
  222.         icont df1:src/prog -x
  223.  
  224. In this case, the icode file prog would be left behind in ram:,
  225. which was your current directory, after it has been run.  You
  226. would then be able to run prog again by simply typing
  227.  
  228.         iconx prog
  229.  
  230. The sample programs are:
  231.  
  232.      hello.icn     This program prints the Icon version number,
  233.                    time, and date. Run this test as
  234.  
  235.                            icont hello
  236.                            iconx hello
  237.  
  238.                    Note that this can be done in one step with
  239.  
  240.                            icont hello -x
  241.  
  242.  
  243.      cross.icn     This program prints all the ways that two
  244.                    words intersect in a common character. The
  245.                    file cross.dat contains typical data. Run this
  246.                    test as
  247.  
  248.                            icont <cross.dat cross -x
  249.  
  250.  
  251.      meander.icn   This program prints the ``meandering strings''
  252.                    that contain all subsequences of a specified
  253.                    length from a given set of characters. Run
  254.                    this test as
  255.  
  256.                            icont <meander.dat meander -x
  257.  
  258.  
  259.  
  260.  
  261.  
  262. IPD56                         - 4 -                  June 2, 1989
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.      roman.icn     This program converts Arabic numerals to Roman
  272.                    numerals. Run this test as
  273.  
  274.                            icont roman -x
  275.  
  276.                    and provide some Arabic numbers from your con-
  277.                    sole.
  278.  
  279.      sieve.icn     This program produces prime numbers. Run this
  280.                    test as
  281.  
  282.                            icont <sieve.dat sieve -x
  283.  
  284.  
  285. If these tests work, your installation is probably correct and
  286. you should have a running version of Icon.
  287.  
  288.  
  289. 7.  Special I/O
  290.  
  291.    This version supports the standard AmigaDOS device names as
  292. files.  Thus, to write directly to the printer from your Icon
  293. program do this:
  294.  
  295.         fd := open("PRT:","w")
  296.         write(fd,"this will appear on your printer")
  297.         close(fd)
  298.  
  299. The existing CLI window is used for standard i/o unless these are
  300. redirected from the command line.
  301.  
  302.    To use the CLI window for i/o when standard input or output
  303. has been redirected elsewhere, you can open it as file * as
  304. explained in the AmigaDOS manual, thus:
  305.  
  306.         tty := open("*","b")
  307.         line := read(tty)
  308.         write(tty,line)
  309.         close(tty)
  310.  
  311. You can also open additional CON: or RAW: windows as described in
  312. the AmigaDOS manual, thus:
  313.  
  314.         con := open("CON:10/10/100/100/my window","b")
  315.         write(con,"This appears in a new window")
  316.         close(con)
  317.  
  318. Note that as soon as you close a special window it disappears.
  319.  
  320.    If you open a RAW: window for reading, notice that there is no
  321. echoing done for you and you must handle all the raw input as
  322. described in the AmigaDOS manual. RAW: i/o has not been exten-
  323. sively tested yet in this version, so it is possible that you may
  324. have problems. The AmigaDOS documentation is also notoriously
  325.  
  326.  
  327.  
  328. IPD56                         - 5 -                  June 2, 1989
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337. misleading.
  338.  
  339.  
  340. 8.  More on Running Icon
  341.  
  342.    For simple applications, the instructions for running Icon
  343. given in Section 6 may be adequate. The icont translator supports
  344. a variety of options that may be useful in special situations.
  345. There also are several aspects of execution that can be con-
  346. trolled with environment variables.  These are listed here. If
  347. you are new to Icon, you may wish to skip this section on the
  348. first reading but come back to it if you find the need for more
  349. control over the translation and execution of Icon programs.
  350.  
  351. 8.1  Arguments
  352.  
  353.    Arguments can be passed to the Icon program by appending them
  354. to the command line.  Such arguments are passed to the main pro-
  355. cedure as a list of strings.  For example,
  356.  
  357.         iconx prog text.dat log.dat
  358.  
  359. runs the icode file prog.icx, passing its main procedure a list
  360. of two strings, "text.dat" and "log.dat".  The program also can
  361. be translated and run with these arguments with a single command
  362. line by putting the arguments after the -x:
  363.  
  364.         icont prog -x text.dat log.dat
  365.  
  366. These arguments might be the names of files that prog.icn reads
  367. from and writes to. For example, the main procedure might begin
  368. as follows:
  369.  
  370.         procedure main(a)
  371.            in := open(a[1]) | stop("cannot open input file")
  372.            out := open(a[2],"w") | stop("cannot open output file")
  373.                        .
  374.                        .
  375.                        .
  376.  
  377. See also the information about the processing of command-line
  378. arguments given in Section 8.4.
  379.  
  380. 8.2  The Translator
  381.  
  382.    The icont translator can accept several Icon source files at
  383. one time.  When several files are given, they are translated and
  384. combined into a single icode file whose name is derived from the
  385. name of the first file.  For example,
  386.  
  387.         icont prog1 prog2
  388.  
  389. translates the files prog1.icn and prog2.icn and produces one
  390. icode file, prog1.icx.
  391.  
  392.  
  393.  
  394. IPD56                         - 6 -                  June 2, 1989
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.    A name other than the default one for the icode file produced
  404. by MiconfR can be specified by using the -o option, followed by
  405. the desired name. For example,
  406.  
  407.         icont -o probe.icx prog
  408.  
  409. produces the icode file named probe.icx rather than prog.icx.
  410.  
  411.    If the -c option is given to icont, the translator stops
  412. before producing an icode file and intermediate ``ucode'' files
  413. with the extensions .u1 and .u2 are left for future use (normally
  414. they are deleted).  For example,
  415.  
  416.         icont -c prog1
  417.  
  418. leaves prog1.u1 and prog1.u2, instead of producing prog1.icx.
  419. These ucode files can be used in a subsequent icont command by
  420. using the .u1 name. This saves translation time when the program
  421. is used again.  For example,
  422.  
  423.         icont prog2 prog1.u1
  424.  
  425. translates prog2.icn and combines the result with the ucode files
  426. from a previous translation of prog1.icn. Note that only the .u1
  427. name is given. The extension can be abbreviated to .u, as in
  428.  
  429.         icont prog2 prog1.u
  430.  
  431. Ucode files also can be added to a program using the link
  432. declaration in an Icon source program as described in [2].
  433.  
  434.    Icon source programs may be read from standard input.  The
  435. argument - signifies the use of standard input as a source file.
  436. In this case, the ucode files are named stdin.u1 and stdin.u2 and
  437. the icode file is named stdin.icx.
  438.  
  439.    The informative messages from the translator can be suppressed
  440. by using the -s option.  Normally, both informative messages and
  441. error messages are sent to standard error output.
  442.  
  443.    The -t option causes &trace to have an initial value of -1
  444. when the icode file is executed.  Normally, &trace has an initial
  445. value of 0.
  446.  
  447.    The option -u causes warning messages to be issued for unde-
  448. clared identifiers in the program.
  449.  
  450.    Icon has several tables related to the translation of pro-
  451. grams.  These tables are large enough for most programs, but
  452. translation is terminated with an error message, indicating the
  453. offending table, if there is not enough room.  If this happens,
  454. larger table sizes can be specified by using the -S option. This
  455. option has the form -S[cfgilnrstCFL]n, where the letter following
  456. the S specifies the table and n is the number of storage units to
  457.  
  458.  
  459.  
  460. IPD56                         - 7 -                  June 2, 1989
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469. allocate for the table.
  470.  
  471.      c  constant table          100
  472.      f  field table             100
  473.      g  global symbol table     200
  474.      i  identifier table        500
  475.      l  local symbol table      100
  476.      n  line number table      1000
  477.      r  record table            100
  478.      s  string space          20000
  479.      t  tree space            15000
  480.      C  code buffer           15000
  481.      F  file names               10
  482.      L  labels                  500
  483.  
  484. The units depend on the table involved, but the default values
  485. can be used as guides for appropriate settings of -S options
  486. without knowing the units.  For example,
  487.  
  488.         icont -Sc200 -Sg600 prog
  489.  
  490. translates prog.icn with twice the constant table space and three
  491. times the global symbol table space that ordinarily would be pro-
  492. vided.
  493.  
  494. 8.3  Environment Variables
  495.  
  496.    When an icode file is executed, several environment variables
  497. are examined to determine execution parameters.  The values
  498. assigned to these variables should be numbers.
  499.  
  500.    Environment variables are particularly useful in adjusting
  501. Icon's storage requirements. This may be necessary if your com-
  502. puter does not have enough memory to run programs that require an
  503. unusually large amount of data.  Particular care should be taken
  504. when changing default sizes: unreasonable values may cause Icon
  505. to malfunction.
  506.  
  507.    The following environment variables can be set to affect
  508. Icon's execution parameters. Their default values are listed in
  509. parentheses after the environment variable name:
  510.  
  511.         TRACE (undefined).  This variable initializes the value
  512.      of &trace.  If this variable has a value, it overrides the
  513.      translation-time -t option.
  514.  
  515.         NOERRBUF (undefined).  If this variable is set, &errout
  516.      is not buffered.
  517.  
  518.         STRSIZE (65000). This variable determines the initial
  519.      size, in bytes, of the region in which strings are stored.
  520.  
  521.         HEAPSIZE (65000).  This variable determines the initial
  522.      size, in bytes, of the region in which Icon allocates lists,
  523.  
  524.  
  525.  
  526. IPD56                         - 8 -                  June 2, 1989
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.      tables, and other objects.
  536.  
  537.         COEXPSIZE (2000). This variable determines the size, in
  538.      32-bit words, of each co-expression block.
  539.  
  540.         MSTKSIZE (10000). This variable determines the size, in
  541.      words, of the main interpreter stack.
  542.  
  543.         QLSIZE (5000). This variable determines the size, in
  544.      bytes, of the region used by the garbage collector for
  545.      pointers to strings.
  546.  
  547.    The maximum region size that can be specified is 65000.
  548.  
  549.    The special variable CHECKBREAK is used only in the Amiga ver-
  550. sion of Icon.  If the line
  551.  
  552.         CHECKBREAK=1
  553.  
  554. appears in your environment file, you should be able to interrupt
  555. the execution of an Icon program by typing Control-C or Control-
  556. D.
  557.  
  558.    If this environment variable is not set, you may still be able
  559. to interrupt the program, but only if it is doing i/o.  Icon runs
  560. significantly slower when CHECKBREAK is set but it is useful when
  561. developing programs.
  562.  
  563.    An example of memory region resizing may be seen in the sample
  564. environment file SmallIconEnv.
  565.  
  566.  
  567. 9.  Impacts for Users of Version 6 of Icon for the Amiga
  568.  
  569.    Persons who have used Version 6 of Icon under the Amiga will
  570. find only a few changes in Version 7.5, most of which are upward
  571. compatible extensions.  In addition to the language enhancements
  572. present in Version 7.5, the primary change visible to users of
  573. Version 6 for the Amiga is the new environment variable mechan-
  574. ism.  The old ``environment files'' are no longer used; instead
  575. the environment variable mechanism used by Aztec C 3.6a has been
  576. adopted.  A program called setenv is provided along with the
  577. Icont and Iconx executables for those of you without Aztec C.
  578. The command setenv foo returns the value of foo if there is any.
  579. The command setenv foo=bar sets the environment variable foo to
  580. the value bar.  Environment variables seem to work under Version
  581. 1.3 of AmigaDOS; they have not been tested under earlier versions
  582. of the operating system.
  583.  
  584.  
  585. 10.  Known Bugs
  586.  
  587.    A list of known bugs in Icon itself is given in [2].  Known
  588. bugs that are specific to the Amiga implementation of Icon are:
  589.  
  590.  
  591.  
  592. IPD56                         - 9 -                  June 2, 1989
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.      +  Floating-point numbers are occasionally printed rather
  602.         strangely.  In addition, floating-point numbers in this
  603.         implementation of Icon seem to have a smaller range of
  604.         legal values than in some other implementations of Icon.
  605.         This is due to the C compiler used to create Amiga Icon
  606.         Version 7.5.
  607.  
  608.  
  609. 11.  Reporting Problems
  610.  
  611.    Problems with Amiga Icon should be noted on a trouble report
  612. form (trouble.frm on the distribution diskette) and sent to
  613.  
  614.         Icon Project
  615.         Department of Computer Science
  616.         Gould-Simpson Building
  617.         The University of Arizona
  618.         Tucson, AZ   85721
  619.         U.S.A.
  620.         (602) 621-2018
  621.         icon-project@arizona.edu     (Internet)
  622.         ... {uunet, allegra, noao}!arizona!icon-project     (uucp)
  623.  
  624. If a program is involved, enclose it and any relevant data on a
  625. diskette.
  626.  
  627.  
  628. 12.  Registering Copies of Icon
  629.  
  630.    If you received your copy of Version 7.5 of Icon for the Amiga
  631. directly from the Icon Project, it has been registered in your
  632. name and you will receive the Icon Newsletter without charge.
  633. This Newsletter contains information about new implementations,
  634. updates, programming techniques, and information of general
  635. interest about Icon.
  636.  
  637.    If you received your copy of Version 7.5 of Icon for the Amiga
  638. from another source, please fill out a registration form
  639. (regis.frm in the documents on the distribution diskette) and
  640. send it to the Icon Project at the address listed above. This
  641. entitles you to a free subscription to the Icon Newsletter and
  642. assure that you receive information about updates.
  643.  
  644. Acknowledgements
  645.  
  646.    The design and development of the Icon programming language
  647. was supported, in part, by the National Science Foundation under
  648. grants MCS75-01397, MCS79-03890, MCS81-01916, DCR-8320138, DCR-
  649. 8401831, and DCR-8502015.
  650.  
  651.    Many individuals contributed to the design and implementation
  652. of Icon. The principal ones are Cary Coutant, Dave Gudeman, Dave
  653. Hanson, Tim Korb, Bill Mitchell, Kelvin Nilsen, Janalee O'Bagy,
  654. Gregg Townsend, and Steve Wampler.
  655.  
  656.  
  657.  
  658. IPD56                        - 10 -                  June 2, 1989
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.    Rob McConeghy originally adapted Version 6 of Icon to run on
  668. the Amiga.  Much of the Version 7.5 configuration for the Amiga
  669. is based on his work.
  670.  
  671. References
  672.  
  673.  
  674. 1.   R. E. Griswold, An Overview of the Icon Programming
  675.      Language, The Univ. of Arizona Tech. Rep. 83-3h, 1983.
  676.  
  677. 2.   R. E. Griswold, G. M. Townsend and K. Walker, Version 7.5 of
  678.      Icon, The Univ. of Arizona Tech. Rep. 88-41, 1988.
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724. IPD56                        - 11 -                  June 2, 1989
  725.  
  726.  
  727. . 88-41, 1988.
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.  
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.