home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / ICONPL8.ZIP / TR90-7.DOC < prev    next >
Text File  |  1990-03-23  |  17KB  |  727 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                     The Icon Program Library*
  15.  
  16.  
  17.                         Ralph E. Griswold
  18.  
  19.  
  20.  
  21.  
  22.  
  23.                             TR 90-7b
  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 1, 1990; last revised Mark 8, 1990
  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 CCR-8713690.
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.                     The Icon Program Library
  77.  
  78.  
  79.  
  80.  
  81. 1.__Introduction
  82.  
  83.    The Icon program library consists of Icon programs and pro-
  84. cedures as well as data. Icon Version 8 is required to run most
  85. of the library [1,2].
  86.  
  87.    In addition to the Icon program library proper, the library
  88. distribution contains an object-oriented version of Icon written
  89. in Icon. See [3] for instructions for unloading and using this
  90. program.
  91.  
  92.    Section 6 briefly describes the contents of the library. More
  93. compete documentation is contained in comments in the program and
  94. procedure files. You may wish to print these files to have docu-
  95. mentation handy.
  96.  
  97.    The material in the Icon program library was contributed by
  98. Icon users. It is in the public domain and may be copied freely.
  99. The Icon Project packages and distributes the library as a ser-
  100. vice to Icon programmers. The Icon project makes no warranties of
  101. any kind as to the correctness of the material in the library or
  102. its suitability for any application. The responsibility for the
  103. use of the library lies entirely with the user.
  104.  
  105.  
  106. 2.__Unloading_the_Library
  107.  
  108.    The Icon program library consists of three parts: programs,
  109. collections of procedures, and data. Normally, these components
  110. should be placed in separate directories named progs, procs, and
  111. data.  The method of unloading the distribution files varies from
  112. system to system; system-specific instructions are included
  113. separately.
  114.  
  115.    The physical division of the library into progs, procs, and
  116. data is motivated by logical and organizational considerations,
  117. not operational ones. Other names can be used and all the
  118. material can be placed in one directory, for example. This may be
  119. necessary on some systems.
  120.  
  121.  
  122. 3.__Link_Search_Paths
  123.  
  124.    Many of the programs link procedures. For example, options is
  125. used by many programs for processing command-line options and is
  126. linked from ``ucode'' files obtained from translating
  127.  
  128.  
  129.  
  130.                               - 1 -
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139. options.icn.
  140.  
  141.    Icon searches for ucode files first in the current directory
  142. and then in directories specified by the IPATH environment vari-
  143. able.  IPATH consists of a sequence of blank-separated path
  144. names. The search is in the order of the names. For example, on a
  145. UNIX system running csh,
  146.  
  147.         setenv IPATH "../procs /usr/icon/ilib"
  148.  
  149.  
  150. results in a search for file names in link declarations first in
  151. the current directory, then in ../procs, and finally in
  152. /usr/icon/ilib.
  153.  
  154.    The method of setting IPATH varies from system to system.
  155. Since the current directory always is searched first, if ucode
  156. files are placed in the same directory as the program files,
  157. IPATH need not be set. See the next section.
  158.  
  159.  
  160. 4.__Installing_the_Library
  161.  
  162.    Installing the Icon program library consists of two steps: (1)
  163. translating the procedure files to produce ucode files and (2)
  164. compiling the programs.
  165.  
  166.    Ucode files are produced by translating the procedure files
  167. with the -c option to icont, as in
  168.  
  169.         icont -c options
  170.  
  171. which translates options.icn. The result is two ucode files named
  172. options.u1 and options.u2. The .u1 files contains the procedure's
  173. code and the .u2 file contains global information about the pro-
  174. cedure.  It is these files that a link declaration such as
  175.  
  176.         link options
  177.  
  178. needs.
  179.  
  180.    A script for translating all the procedure files is provided
  181. with the most distributions.  Once the procedure files have been
  182. translated, the ucode files can be moved to any place that is
  183. accessible from IPATH.
  184.  
  185.    The programs are compiled using icont without the -c option,
  186. as in
  187.  
  188.         icont deal
  189.  
  190.  
  191. which compiles deal.icn, a program that produces randomly
  192. selected bridge hands. The result of compiling a program is an
  193.  
  194.  
  195.  
  196.                               - 2 -
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205. ``icode'' file whose name is system dependent. On some systems,
  206. the name is the same as the name of the program file with the
  207. .icn suffix removed (for example, deal). On other systems, the
  208. icode file has the suffix .icx in place of .icn (for example,
  209. deal.icx).
  210.  
  211.    On systems that support the direct execution of icode files
  212. (UNIX, for example), an icode file can be run just by entering
  213. its name on the command line, as in
  214.  
  215.         deal
  216.  
  217.  
  218.    On other systems (MS-DOS, for example), icode files must be
  219. run using the Icon executor, iconx, as in
  220.  
  221.         iconx deal
  222.  
  223. (This also works on systems that support direct execution.) Note
  224. that the suffix (if any) need not be mentioned.
  225.  
  226.    Many Icon programs take arguments and options from the command
  227. line. Options are identified by dashes. For example, in
  228.  
  229.         deal -h 10
  230.  
  231. the -h 10 instructs deal to produce 10 hands.
  232.  
  233.    Icode files can be moved to any location. Ucode files are
  234. needed only during compilation. They need not be accessible when
  235. icode files are run.
  236.  
  237.  
  238. 5.__Usage_Notes
  239.  
  240.    It is important to read the documentation at the beginning of
  241. programs and procedures in the library. It includes information
  242. about special requirements, limitations, known bugs, and so
  243. forth.
  244.  
  245.    Some of the programs in the Icon program library are quite
  246. large and may require more memory than is available on some per-
  247. sonal computers.
  248.  
  249.    The library has evolved over a period of time. Some programs
  250. were written to run under earlier versions of Icon and do not
  251. take advantage of all the features of Version 8.
  252.  
  253.    The procedure getopt, used to process command-line options in
  254. the previous version of the library, has been replaced by the
  255. procedure options, which is somewhat easier to use. If you
  256. presently use getopt in other programs, you may wish to convert
  257. to options.
  258.  
  259.  
  260.  
  261.  
  262.                               - 3 -
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271. 6.__Library_Contents
  272.  
  273.    As mentioned earlier, detailed documentation about programs
  274. and procedures is contained in their files. A brief catalog of
  275. the contents of the Icon program library follows.
  276.  
  277. 6.1__Programs
  278.  
  279.      animal:    Play the familiar ``animal'' game.
  280.  
  281.      calc:      Calculate Icon values.
  282.  
  283.      colm:      Arrange data items in columns.
  284.  
  285.      concord:   Produce a concordance.
  286.  
  287.      cross:     Arrange words in intersecting crossword fashion.
  288.  
  289.      csgen:     Generate sentences from a context-sensitive gram-
  290.                 mar.
  291.  
  292.      deal:      Display randomly generated bridge hands.
  293.  
  294.      delam:     Delaminate file into several files according to
  295.                 field specifications.
  296.  
  297.      delamc:    Delaminate file into several files according to
  298.                 tabs.
  299.  
  300.      diffn:     Show differences among several files.
  301.  
  302.      diffword:  List the distinct words in a file.
  303.  
  304.      edscript:  Produce script for the ed editor.
  305.  
  306.      empg:      Produce program to measure Icon expressions.
  307.  
  308.      farb:      Produce a ``Farberism''.
  309.  
  310.      fileprnt:  Display representations of characters in a file.
  311.  
  312.      filter:    Filter file.
  313.  
  314.      format:    Format text.
  315.  
  316.      gcomp:     Produce the complement of a UNIX file specifica-
  317.                 tion.
  318.  
  319.      grpsort:   Sort groups of lines.
  320.  
  321.      hufftab:   Compute state transitions for Huffman decoding.
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.                               - 4 -
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.      ilnkxref:  Produce link cross-reference of Icon program.
  338.  
  339.      ipp:       Preprocess Icon programs.
  340.  
  341.      iprint:    Print Icon program.
  342.  
  343.      ipsort:    Sort procedures in Icon program.
  344.  
  345.      ipsplit:   Split Icon program into separate procedure files.
  346.  
  347.      ipxref:    Produce cross reference for Icon program.
  348.  
  349.      itab:      Entab Icon program.
  350.  
  351.      iundecl:   Find undeclared Icon identifiers.
  352.  
  353.      iwriter:   Produce Icon expressions that write lines of
  354.                 file.
  355.  
  356.      krieg:     Play game of kriegspiel.
  357.  
  358.      kross:     Show all intersecting characters in two strings.
  359.  
  360.      kwic:      Produce index of keywords in context.
  361.  
  362.      labels:    Format mailing labels.
  363.  
  364.      lam:       Laminate several files into one file.
  365.  
  366.      latexidx:  Process LaTeX .idx file.
  367.  
  368.      linden:    Generate strings in 0L-system.
  369.  
  370.      lisp:      Interpret Lisp program.
  371.  
  372.      loadmap:   Produce load map of UNIX object file.
  373.  
  374.      miu:       Generate strings in MIU system.
  375.  
  376.      memsum:    Summarize memory usage of Icon program.
  377.  
  378.      monkeys:   Generate random text.
  379.  
  380.      pack:      Package a group of files in a single file (see
  381.                 unpack).
  382.  
  383.      parens:    Generate random parenthesis-balanced strings.
  384.  
  385.      parse:     Parse infix expressions (see also parsex).
  386.  
  387.      parsex:    Parse arithmetic expressions (see also parse).
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.                               - 5 -
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.      press:     Compress or uncompress file.
  404.  
  405.      proto:     Compile all Icon syntactic forms.
  406.  
  407.      queens:    Generate solutions to the n-queens problem (see
  408.                 also vnq).
  409.  
  410.      recgen:    Produce recognizer for context-free language.
  411.  
  412.      roffcmds:  List commands and macros in roff text.
  413.  
  414.      rsg:       Generate random sentences from grammar.
  415.  
  416.      ruler:     Write character ruler.
  417.  
  418.      shuffile:  Shuffle lines in a file.
  419.  
  420.      solit:     Play solitaire.
  421.  
  422.      tablc:     Tabulate characters in a file.
  423.  
  424.      tablw:     Tabulate words in a file.
  425.  
  426.      textcnt:   Tabulate properties of a text file.
  427.  
  428.      trim:      Trim lines in a file.
  429.  
  430.      turing:    Simulate a Turing machine.
  431.  
  432.      unique:    Filter out identical adjacent lines of a file.
  433.  
  434.      unpack:    Unpackage a group of files (see pack).
  435.  
  436.      vnq:       Display solutions to the n-queens problem
  437.                 interactively on an ANSI-standard terminal (see
  438.                 also queens).
  439.  
  440.      zipsort:   Sort labels by ZIP code.
  441.  
  442.      6.2__Procedures
  443.  
  444.      allof:     Perform iterative conjunction.
  445.  
  446.      bincvt:    Convert binary data.
  447.  
  448.      bold:      Enbolden and underscore text.
  449.  
  450.      codeobj:   Encode and decode Icon values as strings (see
  451.                 also object).
  452.  
  453.      collate:   Collate and decollate strings.
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.                               - 6 -
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.      colmize:   Arrange data in columns.
  470.  
  471.      complex:   Perform complex arithmetic.
  472.  
  473.      currency:  Format in American currency.
  474.  
  475.      dif:       Generate differences.
  476.  
  477.      escape:    Interpret Icon literal escapes.
  478.  
  479.      filename:  Parse file name.
  480.  
  481.      fullimag:  Produce full image of Icon value (see also image
  482.                 and ximage).
  483.  
  484.      gcd:       Compute greatest common divisor.
  485.  
  486.      gener:     Generate various strings.
  487.  
  488.      hexcvt:    Convert hexadecimal numbers.
  489.  
  490.      image:     Produce image of Icon value.
  491.  
  492.      isort      Sort with customization.
  493.  
  494.      largint:   Perform arbitrary-precision integer arithmetic.
  495.  
  496.      lmap:      Map list elements.
  497.  
  498.      mapbit:    Map string into its bit representation.
  499.  
  500.      math:      Perform mathematical computations.
  501.  
  502.      morse:     Convert string to Morse code.
  503.  
  504.      ngrams:    Tabulate n-grams in a text file.
  505.  
  506.      numbers:   Convert numbers to various forms.
  507.  
  508.      object:    Encode and decode Icon values as strings (see
  509.                 also codeobj).
  510.  
  511.      options:   Process command-line options.
  512.  
  513.      patterns:  Perform SNOBOL4-style pattern matching.
  514.  
  515.      patword:   Produce letter pattern for a word.
  516.  
  517.      pdae:      Perform programmer-defined argument evaluation.
  518.  
  519.      pdco:      Perform programmer-defined control operations.
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.                               - 7 -
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.      permute:   Perform permutations, combinations, and other
  536.                 character rearrangements.
  537.  
  538.      phoname:   Generate possible words from telephone numbers.
  539.  
  540.      printcol:  Print columnar data.
  541.  
  542.      printf:    Format in C printf style.
  543.  
  544.      radcon:    Convert radix.
  545.  
  546.      rational:  Perform rational arithmetic.
  547.  
  548.      segment:   Segment string.
  549.  
  550.      seqimage:  Produce string image of Icon result sequence.
  551.  
  552.      shquote:   Quote words for shells.
  553.  
  554.      shuffle:   Shuffle string or list.
  555.  
  556.      snapshot:  Show state of Icon string scanning.
  557.  
  558.      strings:   Perform operations on strings.
  559.  
  560.      structs:   Perform operations on structures.
  561.  
  562.      tuple:     Simulate n-tuples.
  563.  
  564.      usage:     Provide interface operations.
  565.  
  566.      wildcard:  Match UNIX wild-card patterns.
  567.  
  568.      wrap:      Wrap text lines.
  569.  
  570.      ximage:    Produce image of Icon value (see also fullimag
  571.                 and image).
  572.  
  573. 6.3__Data
  574.  
  575.      *.csg:     Input to csgen.
  576.  
  577.      *.krs:     Input to kross.
  578.  
  579.      *.lbl:     Input to label.
  580.  
  581.      *.lin:     Input to linden.
  582.  
  583.      *.rsg:     Input to rsg.
  584.  
  585.      *.tur:     Input to turing.
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.                               - 8 -
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.      *.txt:     Sample text.
  602.  
  603.      *.wrd:     Word lists.
  604.  
  605.      farber.sen:Farberisms.
  606.  
  607.      palin.sen: Palindromic sentences.
  608.  
  609.  
  610. 7.__Future_Library_Releases
  611.  
  612.    There are many contributions to the Icon program library that
  613. have not yet been distributed. This material includes:
  614.  
  615.      +  Programs that are operating-system specific.
  616.  
  617.      +  Complex packages.
  618.  
  619.      +  Programs that require specific data files.
  620.  
  621.      +  Programs that need more documentation.
  622.  
  623.      +  Recent arrivals.
  624.  
  625. The Icon program library will be updated as this material is put
  626. into a form suitable for distribution.
  627.  
  628.  
  629. 8.__Note_to_Contributors
  630.  
  631.    Material for the Icon program library always is welcome. It
  632. must be prepared in the style exemplified by the material in this
  633. release. Adequate documentation is essential; it must be in the
  634. format used for present library - we do not have the resources to
  635. rewrite or reformat contributed documentation. Test data also
  636. must be provided - at least enough so that we can determine that
  637. the contributed program material is basically functional. In
  638. cases where test data is impractical because of the nature of the
  639. contribution, instructions for testing should be provided.
  640.  
  641.    Program material can be submitted by electronic mail at one of
  642. the addresses given in the next section or on magnetic media.
  643. Printed listings are not acceptable.
  644.  
  645.    Contributions to the Icon program library must be free of any
  646. restrictions. The decision to include contributed material in the
  647. Icon program library rests entirely with the Icon Project.  The
  648. Icon Project reserves the right to modify submissions to conform
  649. to library standards, to correct errors, and to make improve-
  650. ments.  Contributors wil be consulted in the case of substantial
  651. changes.
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.                               - 9 -
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667. 9.__Bugs
  668.  
  669.    If you find a bug in the Icon program library or can suggest
  670. an improvement, please let us know:
  671.  
  672.         Icon Project
  673.         Department of Computer Science
  674.         Gould-Simpson Building
  675.         The University of Arizona
  676.         Tucson, AZ   85721
  677.         U.S.A.
  678.         (602) 621-4049
  679.         icon-project@cs.arizona.edu     (Internet)
  680.         ... {uunet, allegra, noao}!arizona!icon-project     (uucp)
  681.  
  682.  
  683. Acknowledgements
  684.  
  685.    The following persons contributed material to this release of
  686. the Icon program library:
  687.  
  688.         Paul Abrahams       Anthony Hewitt      Gregg M. Townsend
  689.         Robert J. Alexander Thomas R. Hicks     Kenneth Walker
  690.         Allan J. Anderson   Tim Korb            Stephen B. Wampler
  691.         David S. Cargo      William P. Malloy   Kurt A. Welgehausen
  692.         nary A. Coutant     William H. Mitchell Robert C. Wieland
  693.         Ward Cunningham     Jerry Nowlin        Cheyenne Wills
  694.         Michael Glass       Randal L. Schwartz  George D. Yee
  695.         Ralph E. Griswold   David Slate         David Yost
  696.  
  697.  
  698. References
  699.  
  700.  
  701. 1.   R. E. Griswold and M. T. Griswold, The Icon Programming
  702.      Language, Prentice-Hall, Inc., Englewood Cliffs, NJ, 1983.
  703.  
  704. 2.   R. E. Griswold, Version 8 of Icon, The Univ. of Arizona
  705.      Tech. Rep. 90-1, 1990.
  706.  
  707. 3.   C. L. Jeffery, Programming in Idol - An Object Primer, The
  708.      Univ. of Arizona Tech. Rep. 90-10, 1990.
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.                              - 10 -
  725.  
  726.  
  727.