Return to t-roffcmds.dat CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / icon / libtest

Annotation of 43BSD/contrib/icon/libtest/t-roffcmds.dat, revision 1.1

1.1     ! root        1: .so tmac.tr
        !             2: .de Ta
        !             3: .ta .8i +.8i +.8i +.8i +.8i +.8i +.8i
        !             4: ..
        !             5: .de Px
        !             6: .ta 3.5i
        !             7: ..
        !             8: .ds CF \s10- \\n(PN - \s0
        !             9: .de Ap
        !            10: .bp
        !            11: .ce 10
        !            12: \f3\\$1\f1
        !            13: .ce 0
        !            14: .sp 2
        !            15: .if !''\\$2' 'so \\$2
        !            16: ..
        !            17: .TR 84-10a
        !            18: .DA "June 27, 1984; Revised August 4, 1984"
        !            19: .Gr
        !            20: .TL
        !            21: Extensions to Version 5 of the Icon Programming Language
        !            22: .AU
        !            23: Ralph E. Griswold
        !            24: .AU
        !            25: Robert K. McConeghy
        !            26: .AU
        !            27: William H. Mitchell
        !            28: .AE
        !            29: .tr *\(**
        !            30: .NH
        !            31: Introduction
        !            32: .PP
        !            33: The standard features of Version 5 of Icon are described in
        !            34: Reference 1. Since Icon is the byproduct of a research effort that
        !            35: is concerned with the development of novel programming language
        !            36: facilities for processing nonnumeric data, it is inevitable that
        !            37: some extensions to the standard language will develop.
        !            38: .PP
        !            39: Some of these extensions are incorporated as features of new releases.
        !            40: Others are available as options that can be selected when the Icon
        !            41: system is installed [2]. This report describes the extensions that are included in
        !            42: Version 5.9 of Icon.
        !            43: .PP
        !            44: All the extensions are upward-compatible with standard Version 5 Icon.
        !            45: Their inclusion should not interfere with any program that works
        !            46: properly under the standard version.
        !            47: .NH
        !            48: New Version 5.9 Features
        !            49: .NH 2
        !            50: The Link Directive
        !            51: .PP
        !            52: Version 5.9 contains a link directive that simplifies the inclusion of
        !            53: separately translated libraries of Icon procedures. If \fIicont(1)\fR [3] is run
        !            54: with the \*M\-c\fR option, source files are translated into intermediate
        !            55: \fIucode\fR files (with names ending in \*M.u1\fR and \*M.u2\fR).
        !            56: For example,
        !            57: .Ds
        !            58: icont -c libe.icn
        !            59: .De
        !            60: produces the ucode files \*Mlibe.u1\fR and \*Mlibe.u2\fR. The ucode files
        !            61: can be incorporated in another program with the new link
        !            62: directive, which has the form
        !            63: .Ds
        !            64: link libe
        !            65: .De
        !            66: The argument of \*Mlink\fR is, in general, a list of identifiers or
        !            67: string literals that specify the names of files to be linked (without
        !            68: the \*M.u1\fR or \*M.u2\fR). Thus
        !            69: .Ds
        !            70: link libe, "/usr/icon/ilib/collate"
        !            71: .De
        !            72: specifies the linking of \*Mlibe\fR in the current directory and
        !            73: \*Mcollate\fR in \*M/usr/icon/ilib\fR.
        !            74: .PP
        !            75: The environment variable \fIIPATH\fR controls the location of files
        !            76: specified in link directives. \fIIPATH\fR should be have a value
        !            77: of the form \fIp1:p2: .\^.\^. pn\fR where each \fIpi\fR names a directory.
        !            78: Each directory is searched in turn to locate files named in link
        !            79: directives. The default value of \fIIPATH\fR is `.', that is, the
        !            80: current directory.
        !            81: .NH 2
        !            82: Installation Options
        !            83: .PP
        !            84: When an Icon system is installed, various configuration options
        !            85: are specified [2]. The value of the keyword \*M&options\fR is
        !            86: a string that contains the command line arguments that were used
        !            87: to configure Icon.
        !            88: .NH
        !            89: Optional Extensions
        !            90: .PP
        !            91: There are two extension options: sets (\*M\-sets\fR in \*M&options\fR),
        !            92: and a collection of experimental features (\*M\-xpx\fR in \*M&options\fR).
        !            93: .NH 2
        !            94: Sets
        !            95: .PP
        !            96: Sets are unordered collections of values and have the properties normally
        !            97: associated with sets in the mathematical sense.
        !            98: The function
        !            99: .Ds
        !           100: set(a)
        !           101: .De
        !           102: creates a set that contains the distinct elements of the list \*Ma\fR. For
        !           103: example,
        !           104: .Ds
        !           105: set(\^["abc",\*b3])
        !           106: .De
        !           107: creates a set with two members, \*Mabc\fR and 3.
        !           108: Note that
        !           109: .Ds
        !           110: set(\^[\^])
        !           111: .De
        !           112: creates an empty set.
        !           113: Sets, like
        !           114: other data aggregates in Icon, need not be homogeneous \(em a set
        !           115: may contain members of different types.
        !           116: .PP
        !           117: Sets, like other Icon data aggregates, are represented by pointers to
        !           118: the actual data. Sets can be members of sets, as in
        !           119: .Ds
        !           120: s1 := set(\^[1,\*b2,\*b3])
        !           121: s2 := set(\^[s1,\*b\^[\^]])
        !           122: .De
        !           123: in which \*Ms2\fR contains two members, one of which is a set of three
        !           124: members and the other of which is an empty list.
        !           125: .PP
        !           126: Any specific value can occur only once in a set. For example,
        !           127: .Ds
        !           128: set(\^[1,\*b2,\*b3,\*b3,\*b1])
        !           129: .De
        !           130: creates a set with the three members 1, 2, and 3.
        !           131: Set membership is determined the same way the equivalence of
        !           132: values is determined in the operation
        !           133: .Ds
        !           134: x === y
        !           135: .De
        !           136: For example,
        !           137: .Ds
        !           138: set(\^[\^[\^],\*b\^[\^]])
        !           139: .De
        !           140: creates a set that contains two distinct empty lists.
        !           141: .PP
        !           142: The functions and operations of Icon that apply to other data aggregates
        !           143: apply to sets as well. For example, if \*Ms\fR is a set,
        !           144: .Ds
        !           145: *s
        !           146: .De
        !           147: is the size of \*Ms\fR (the number of members in it). Similarly,
        !           148: .Ds
        !           149: type(s)
        !           150: .De
        !           151: produces the string \*Mset\fR and
        !           152: .Ds
        !           153: s := set(\^["abc",\*b3])
        !           154: write(image(s))
        !           155: .De
        !           156: writes \*Mset(2)\fR. Note that the string images of sets are in the
        !           157: same style as for other aggregates, with the size enclosed in
        !           158: parentheses.
        !           159: .PP
        !           160: The operation
        !           161: .Ds
        !           162: !s
        !           163: .De
        !           164: generates the members of \*Ms\fR, but in no predictable order. Similarly,
        !           165: .Ds
        !           166: ?s
        !           167: .De
        !           168: produces a randomly selected member of \*Ms\fR.
        !           169: These operations produce values, not variables \(em it is not possible
        !           170: to assign a value to \*M!s\fR or \*M?s\fR.
        !           171: .PP
        !           172: The function
        !           173: .Ds
        !           174: copy(s)
        !           175: .De
        !           176: produces a new set, distinct from \*Ms\fR, but which contains the same
        !           177: members as \*Ms\fR. The copy is made in the same fashion as the copy
        !           178: of a list \(em the members themselves are not copied.
        !           179: .PP
        !           180: The function
        !           181: .Ds
        !           182: sort(s)
        !           183: .De
        !           184: produces a list containing the members of \*Ms\fR in sorted order.
        !           185: Sets themselves occur after tables but before records in the sorting order.
        !           186: .PP
        !           187: The customary set operations are provided. The function
        !           188: .Ds
        !           189: member(s,\*bx)
        !           190: .De
        !           191: succeeds and returns the value of \*Mx\fR if \*Mx\fR is a member of
        !           192: \*Ms\fR, but fails otherwise. Note that
        !           193: .Ds
        !           194: member(s1,\*bmember(s2,\*bx))
        !           195: .De
        !           196: succeeds if \*Mx\fR is a member of both \*Ms1\fR and \*Ms2\fR.
        !           197: .PP
        !           198: The function
        !           199: .Ds
        !           200: insert(s,\*bx)
        !           201: .De
        !           202: inserts \*Mx\fR into the set \*Ms\fR and returns the value of \*Ms\fR
        !           203: (it is similar to \*Mput(a,\*bx)\fR in form). Note that
        !           204: .Ds
        !           205: insert(s,\*bs)
        !           206: .De
        !           207: adds \*Ms\fR as an member of itself.
        !           208: .PP
        !           209: The function
        !           210: .Ds
        !           211: delete(s,\*bx)
        !           212: .De
        !           213: deletes the member \*Mx\fR from the set \*Ms\fR and returns the
        !           214: value of \*Ms\fR.
        !           215: .PP
        !           216: The functions \*Minsert(s,\*bx)\fR and \*Mdelete(s,\*bx)\fR always
        !           217: succeed, whether or not \*Mx\fR is in \*Ms\fR. This allows their
        !           218: use in loops
        !           219: in which failure may occur for other reasons. For example,
        !           220: .Ds
        !           221: s := set(\^[\^])
        !           222: while insert(s,\*bread())
        !           223: .De
        !           224: builds a set that consists of the (distinct) lines from the standard
        !           225: input file.
        !           226: .PP
        !           227: The operations
        !           228: .Ds
        !           229: s1 ++ s2
        !           230: s1 ** s2
        !           231: s1 -- s2
        !           232: .De
        !           233: create the union, intersection, and difference of \*Ms1\fR and \*Ms2\fR,
        !           234: respectively. In each case, the result is a new set.
        !           235: .PP
        !           236: The use of these operations on csets is unchanged. There is no
        !           237: automatic type conversion between csets and sets; the result of the
        !           238: operation depends on the types of the arguments. For example,
        !           239: .Ds
        !           240: \&'aeiou' ++ 'abcde'
        !           241: .De
        !           242: produces
        !           243: the cset \*Mabcdeiou\fR, while
        !           244: .Ds
        !           245: set(\^[1,\*b2,\*b3]) ++ set(\^[2,\*b3,\*b4])
        !           246: .De
        !           247: produces a set that contains 1, 2, 3, and 4. On the other hand,
        !           248: .Ds
        !           249: set(\^[1,\*b2,\*b3]) ++ 4
        !           250: .De
        !           251: results in Run-time Error 119 (\*Mset expected\fR).
        !           252: .SH
        !           253: Examples
        !           254: .a
        !           255: .LP
        !           256: \fIWord Counting:\fR
        !           257: .PP
        !           258: The following program lists, in alphabetical order, all the different
        !           259: words that occur in the standard input file:
        !           260: .Ds
        !           261: .Px
        !           262: procedure main()
        !           263:    letter := &lcase ++ &ucase
        !           264:    words := set(\^[\^])
        !           265:    while text := read() do
        !           266:       text ? while tab(upto(letter)) do
        !           267:          insert(words,\*btab(many(letter)))
        !           268:    every write(!sort(words))
        !           269: end
        !           270: .De
        !           271: .LP
        !           272: \fIThe Sieve of Eratosthenes:\fR
        !           273: .PP
        !           274: The follow program produces prime numbers, using the classical ``Sieve of
        !           275: Eratosthenes'':
        !           276: .Ds
        !           277: .Px
        !           278: procedure main(a)
        !           279:    local limit, s, i
        !           280:    limit := a\^[1] | 5000      # limit to 5000 if not specified
        !           281:    s := set(\^[])
        !           282:    every insert(s,\*b1 to limit)
        !           283:    every member(s,\*bi := 2 to limit) do
        !           284:       every delete(s,\*bi + i to limit by i)
        !           285:    primes := sort(s)
        !           286:    write("There are ",\*b*primes,\*b" primes in the first ",\*blimit,\*b" integers.")
        !           287:    write("The primes are:")
        !           288:    every write(right(!primes,\*b*limit + 1))
        !           289: end
        !           290: .De
        !           291: .NH
        !           292: Expermental Features
        !           293: .NH 2
        !           294: PDCO Invocation Syntax
        !           295: .PP
        !           296: The experimental features include the procedure invocation syntax that is
        !           297: used for programmer-defined control operations [4].
        !           298: In this syntax, when braces are used in place of parentheses to
        !           299: enclose an argument list, the arguments are passed as a list
        !           300: of co-expressions. That is,
        !           301: .Ds
        !           302: p{\*1, \*2, \*(El, \*n}
        !           303: .De
        !           304: is equivalent to
        !           305: .Ds
        !           306: p(\^[create \*1, create \*2, \*(El, create \*n])
        !           307: .De
        !           308: Note that
        !           309: .Ds
        !           310: p{\^}
        !           311: .De
        !           312: is equivalent to
        !           313: .Ds
        !           314: p(\^[\^\^])
        !           315: .De
        !           316: .NH 2
        !           317: Invocation Via String Name
        !           318: .PP
        !           319: The experimental features allow a string-valued expression that corresponds to the
        !           320: name of a procedure or operation to be used in place of the
        !           321: procedure or operation in an invocation expression. For example,
        !           322: .Ds
        !           323: "image"(x)
        !           324: .De
        !           325: produces the same call as
        !           326: .Ds
        !           327: image(x)
        !           328: .De
        !           329: and
        !           330: .Ds
        !           331: "-"(i,\*bj)
        !           332: .De
        !           333: is equivalent to
        !           334: .Ds
        !           335: i - j
        !           336: .De
        !           337: .PP
        !           338: In the case of operations, the number of arguments determines
        !           339: the operation. Thus
        !           340: .Ds
        !           341: "-"(i)
        !           342: .De
        !           343: is equivalent to
        !           344: .Ds
        !           345: -i
        !           346: .De
        !           347: Since \*Mto-by\fR is an operation, despite its reserved-word syntax,
        !           348: it is included in this facility with the string name \*M...\fR .
        !           349: Thus
        !           350: .Ds
        !           351: "..."(1,\*b10,\*b2)
        !           352: .De
        !           353: is equivalent to
        !           354: .Ds
        !           355: 1 to 10 by 2
        !           356: .De
        !           357: Similarly, range specifications are represented by \*M":"\fR, so that
        !           358: .Ds
        !           359: ":"(s,i,j)
        !           360: .De
        !           361: is equivalent to
        !           362: .Ds
        !           363: s\^[i:j]
        !           364: .De
        !           365: .PP
        !           366: Defaults are not provided for omitted or null-valued arguments in this
        !           367: facility. Consequently,
        !           368: .Ds
        !           369: "..."(1,\*b10)
        !           370: .De
        !           371: results in a run-time error when it is evaluated.
        !           372: .PP
        !           373: The subscripting operation also is available with the string name
        !           374: \*M[\^\^]\fR. Thus
        !           375: .Ds
        !           376: "[\^\^]"(&lcase,\*b3)
        !           377: .De
        !           378: produces \*Mc\fR.
        !           379: .PP
        !           380: String names are available for all the operations in Icon, but not for
        !           381: control structures. Thus
        !           382: .Ds
        !           383: "|"(\*1,\*b\*2)
        !           384: .De
        !           385: is erroneous.
        !           386: Note that string scanning is a control structure.
        !           387: .PP
        !           388: Field references, of the form
        !           389: .Ds
        !           390: \*0 . \fIfieldname\fR
        !           391: .De
        !           392: are not operations in the ordinary sense and are not available
        !           393: via string invocation.
        !           394: .PP
        !           395: String names for procedures are available through global identifiers.
        !           396: Note that the names of functions, such as \*Mimage\fR, are global
        !           397: identifiers. Similarly, any procedure-valued global identifier may be
        !           398: used as the string name of a procedure. Thus in
        !           399: .Ds
        !           400: global q
        !           401: 
        !           402: procedure main()
        !           403:    q := p
        !           404:    "q"("hi")
        !           405: end
        !           406: 
        !           407: procedure p(s)
        !           408:    write(s)
        !           409: end
        !           410: .De
        !           411: the procedure \*Mp\fR is invoked via the global identifier \*Mq\fR.
        !           412: .NH 2
        !           413: Conversion to Procedure
        !           414: .PP
        !           415: The experimental features include the function \*Mproc(x,\*bi)\fR, which
        !           416: converts \*Mx\fR to a procedure, if possible.
        !           417: If \*Mx\fR is procedure-valued, its value is returned unchanged. If the
        !           418: value of \*Mx\fR is a string that corresponds to the name of a procedure
        !           419: as described in the preceding section, the corresponding procedure
        !           420: value is returned.
        !           421: The value of \*Mi\fR is used to distinguish between
        !           422: unary and binary operators.
        !           423: For example, \*Mproc("^",\*b2)\fR produces the exponentiation operator, while
        !           424: \*Mproc("^",\*b1)\fR produces the co-expression refresh operator.
        !           425: If \*Mx\fR cannot be converted to a procedure, \*Mproc(x,\*bi)\fR fails.
        !           426: .NH 2
        !           427: Integer Sequences
        !           428: .PP
        !           429: To facilitate the generation of integer sequences that have no limit,
        !           430: the experimental features include
        !           431: the function \*Mseq(i,\*bj)\fR. This function has the
        !           432: result sequence {\^i, i+j, i+2j, \*(El }. Omitted or null values for \*Mi\fR
        !           433: and \*Mj\fR
        !           434: default to 1. Thus the result sequence for \*Mseq()\fR is
        !           435: {\^1, 2, 3, \*(El }.
        !           436: .SH
        !           437: Acknowledgements
        !           438: .PP
        !           439: The design of sets for Icon was done as part of a class project.
        !           440: In addition to the authors of this paper, the following persons
        !           441: participated in the design:
        !           442: John Bolding, Owen Fonorow, Roger Hayes, Tom Hicks, Robert Kohout,
        !           443: Mark Langley, Susan Moore, Maylee Noah, Janalee O'Bagy, Gregg Townsend, and Alan Wendt.
        !           444: .SH
        !           445: References
        !           446: .LP
        !           447: 1.  Griswold, Ralph E. and Madge T. Griswold. \fIThe Icon Programming
        !           448: Language\fR, Prentice-Hall, Inc., Englewood Cliffs, New Jersey. 1983.
        !           449: .LP
        !           450: 2.  Griswold, Ralph E. and William H. Mitchell.
        !           451: \fIInstallation and Maintenance Instructions for Version 5.9 of
        !           452: Icon\fR, Technical Report TR 84-13, Department of Computer Science,
        !           453: The University of Arizona.
        !           454: August 1984.
        !           455: .LP
        !           456: 3.  Griswold, Ralph E. and William H. Mitchell. \fIICONT(1)\fR,
        !           457: manual page for \fIUNIX Programmer's Manual\fR, Department of Computer
        !           458: Science, The University of Arizona. August 1984.
        !           459: .LP
        !           460: 4.  Griswold, Ralph E. and Michael Novak. ``Programmer-Defined Control
        !           461: Operations'', \fIThe Computer Journal\fR, Vol. 26, No. 2 (May 1983).
        !           462: pp. 175-183.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.