home *** CD-ROM | disk | FTP | other *** search
/ ftp.cs.arizona.edu / ftp.cs.arizona.edu.tar / ftp.cs.arizona.edu / icon / doc / ipd151.txt < prev    next >
Text File  |  1996-03-10  |  9KB  |  243 lines
  1. Icon Program Library Submissions
  2.  
  3. Ralph E. Griswold
  4.  
  5. Department of Computer Science
  6. The University of Arizona
  7. Tucson, Arizona
  8.  
  9. IPD151e
  10. March 5, 1996
  11.  
  12. ----------------------------------------------------------------------------
  13.  
  14. The Icon program library consists of programs, collections of procedures,
  15. include files, data, documentation, and packages that contain more complex
  16. applications. The programs range from simple utilities to sophisticated
  17. text-generation applications.
  18.  
  19. In addition to providing useful programs and procedures, the Icon program
  20. library also is an interesting source of examples of programming in Icon,
  21. which may be useful to persons learning Icon.
  22.  
  23. Most of the material in the Icon program library is contributed by users --
  24. the work of several dozen programmers.
  25.  
  26. The Icon Project accepts contributions to the Icon program library, checks
  27. them to make sure they work, and packages them for distribution. Since many
  28. of the programs are complicated, it isn't practical for us to test them
  29. extensively or to certify that they work entirely as advertised.
  30. Nonetheless, many of the programs in the library are in regular use.
  31.  
  32. Contributions to the Icon Program Library
  33.  
  34. We welcome submissions of new material to the Icon program library, but
  35. there are a few requirements. Look at the examples in the next section.
  36.  
  37. Contributed programs must be adequately documented and should be accompanied
  38. by test data. Test files that are read as standard input and produce results
  39. to standard output are best. In some cases, data read from standard input
  40. may not be appropriate. Send what you think is best, but realize that our
  41. resources are limited and programs that are easy to test are more likely to
  42. get into the library and to get there sooner.
  43.  
  44. Contributions to the Icon program library must be free of any distribution
  45. restrictions.
  46.  
  47. We reserve the right to modify submitted programs to correct errors, to
  48. improve code, and to make them conform to library conventions.
  49.  
  50. Finally, we reserve the right to decide what material to include in the
  51. library and to modify it as we feel appropriate. The main considerations are
  52. quality, usefulness, and compliance with the library format. Submissions
  53. that duplicate functionality that already exists in the library generally
  54. are not accepted unless they are substantially better than what's already in
  55. the library.
  56.  
  57. All submissions are acknowledged, but decisions on inclusion in the library
  58. may not be made immediately. If you've submitted material in the past that's
  59. not appeared in the library, ask us about its status -- we have a lot of
  60. material from past years that lacks adequate documentation. And in some
  61. cases we've lost touch with the persons who submitted material.
  62.  
  63. Of course, we give full credit to the authors of program material that's
  64. included in the library.
  65.  
  66. Even if you don't have anything to contribute to the library, you may find a
  67. bug or make an improvement to the library. By all means let us know about
  68. such things.
  69.  
  70. Example of a Program
  71.  
  72. Heading information must be in the format shown (it's processed by programs
  73. used to maintain the library). Keep the subject on one line and as short as
  74. possible. Do not put other information, including version and modification
  75. information in the header box; place it below.
  76.  
  77. A description of the material in the file must follow the heading. It should
  78. explain what the program does and be sufficiently detailed so that use is
  79. clear. Command-line options should be clearly evident.
  80.  
  81. A description of the material in the file must follow the heading. It should
  82. explain what the program does and be sufficiently detailed so that use is
  83. clear. Command-line options should be clearly evident.
  84.  
  85. The code itself should begin with link, global, and record declarations.
  86.  
  87. The main procedure should appear first, followed by other procedures,
  88. preferably in alphabetical order.
  89.  
  90. Declare all local identifiers.
  91.  
  92. ############################################################################
  93. #
  94. #       File:     deal.icn
  95. #
  96. #       Subject:  Program to deal bridge hands
  97. #
  98. #       Author:   Ralph E. Griswold
  99. #
  100. #       Date:     June 20, 1994
  101. #
  102. ############################################################################
  103. #
  104. #     This program shuffles, deals, and displays hands in the game
  105. #  of bridge. An example of the output of deal.icn is
  106. #
  107. #                 S: KQ987
  108. #                 H: 52
  109. #                 D: T94
  110. #                 C: T82
  111. #
  112. #       S: 3                 S: JT4
  113. #       H: T7                H: J9863
  114. #       D: AKQ762            D: J85
  115. #       C: QJ94              C: K7
  116. #
  117. #                 S: A652
  118. #                 H: AKQ4
  119. #                 D: 3
  120. #                 C: A653
  121. #
  122. #  Options: The following options are available:
  123. #
  124. #       ­p;h n Produce n hands. The default is 1.
  125. #
  126. #       ­p;s n Set the seed for random generation to n.  Different seeds give
  127. #            different hands. The default seed is 0.
  128. #
  129. ############################################################################
  130. #
  131. #  Links: options, shuffle
  132. #
  133. ############################################################################
  134.  
  135. link options, shuffle
  136.  
  137. global deck, deckimage, handsize, suitsize, denom, rank, blanker
  138.  
  139. procedure main(args)
  140.    local hands, opts
  141.  
  142.    deck := deckimage := string(&letters)        # initialize global variables
  143.    handsize := suitsize := *deck / 4
  144.    rank := "AKQJT98765432"
  145.    blanker := repl(" ",suitsize)
  146.    denom := &lcase[1+:suitsize]
  147.  
  148.    opts := options(args,"h+s+")
  149.    hands := \opts["h"] | 1
  150.    &random := \opts["s"]
  151.  
  152.    every 1 to hands do
  153.       display()
  154.  
  155. end
  156.  
  157. #  Display the hands
  158. #
  159. procedure display()
  160.    local layout, i
  161.    static bar, offset
  162.          .
  163.          .
  164.          .
  165.  
  166. Example of a Collection of Procedures
  167.  
  168. Heading information for collections of procedures is similar to that for
  169. programs.
  170.  
  171. A prototype call for each procedure should be given with an example of the
  172. results, if appropriate.
  173.  
  174. Each procedure should have a brief explanatory comment on the line in which
  175. the reserved word procedure appears. A colon must immediately follow the
  176. sharp sign if the procedure is to appear in the index listing for the
  177. library.
  178.  
  179. ############################################################################
  180. #
  181. #       File:     numbers.icn
  182. #
  183. #       Subject:  Procedures to format and convert numbers
  184. #
  185. #       Author:   Ralph E. Griswold, Tim Korb, and Robert J. Alexander
  186. #
  187. #       Date:     May 28, 1995
  188. #
  189. ############################################################################
  190. #
  191. #     These procedures format numbers in various ways:
  192. #
  193. #     commas(s)         inserts commas in s to separate digits into groups
  194. #                       of three.
  195. #
  196. #     digred(i)         reduction of number by adding digits until one digit
  197. #                       is reached.
  198. #
  199. #     div(i, j)         produces the result of real division of i by j.
  200. #
  201. #     fix(i, j, w, d)   formats i / j as a real (floating-point) number in
  202. #                       a field of width w with d digits to the right of
  203. #                       the decimal point, if possible. j defaults to 1,
  204. #                       w to 8, and d to 3. If w is less than 3 it is set
  205. #                       to 3. If d is less than 1, it is set to 1. The
  206. #                       function fails if j is 0 or if the number cannot
  207. #                       be formatted.
  208. #
  209. #     roman(i)          converts i to Roman numerals.
  210. #
  211. #     spell(i)          spells out i in English.
  212. #
  213. #     unroman(s)        converts Roman numerals to integers.
  214. #
  215. ############################################################################
  216.  
  217. procedure commas(n)      #: insert commas in integer
  218.  
  219.    if *n < 4 then return n
  220.    else return commas(left(n, *n ­p; 3)) || map(",123", "123", right(n,3))
  221.  
  222. end
  223.                 .
  224.                 .
  225.                 .
  226.  
  227. Submitting Library Material
  228.  
  229. Material for the library must be in machine-readable form. You can send
  230. library submissions to us on MS-DOS or Macintosh diskettes, by e-mail to
  231. icon-project@cs.arizona.edu, or upload them to our FTP incoming area. If you
  232. upload a file, notify us by e-mail so we can pick it up before it gets
  233. deleted by the automatic garbage-collection process.
  234.  
  235. If you want to compress your submission, for Unix, use compress; for MS-DOS
  236. Lharc, Lha, or Zip; or, for the Macintosh, a BinHexed self-extracting
  237. archive or any other format Stuffit Deluxe can handle. If you'd like to use
  238. another format, check with us before uploading to be sure we can deal with
  239. it.
  240.  
  241. ----------------------------------------------------------------------------
  242. Icon home page
  243.