![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to Description1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / contrib / B / doc|
Return to Description1 CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / B / doc |
1.1 ! root 1: .\" Copyright (c) Stichting Mathematisch Centrum, Amsterdam, 1984. ! 2: .Du START ! 3: .sp 1 ! 4: .in 0 ! 5: .ce 99 ! 6: DESCRIPTION OF B ! 7: ! 8: Lambert Meertens ! 9: Steven Pemberton ! 10: ! 11: CWI ! 12: Amsterdam ! 13: ! 14: April 1984 ! 15: .ce 0 ! 16: .Co ! 17: .ds Sn Contents ! 18: .bp ! 19: .in 15 ! 20: .nf ! 21: .ps 8 ! 22: .vs 10 ! 23: CONTENTS ! 24: ! 25: 0.\0INTRODUCTION ! 26: 1.\0VALUES IN B ! 27: 2.\0SYNTAX DESCRIPTION METHOD ! 28: 3.\0REPRESENTATIONS ! 29: 4.\0UNITS ! 30: 4.1.\0HOW-TO-UNITS ! 31: 4.2.\0YIELD-UNITS ! 32: 4.3.\0TEST-UNITS ! 33: 4.4.\0REFINEMENTS ! 34: 4.5.\0COMMAND-SUITES ! 35: 5.\0COMMANDS ! 36: 5.1.\0\0SIMPLE-COMMANDS ! 37: 5.1.1.\0\0CHECK-COMMANDS ! 38: 5.1.2.\0\0WRITE-COMMANDS ! 39: 5.1.3.\0\0READ-COMMANDS ! 40: 5.1.4.\0\0PUT-COMMANDS ! 41: 5.1.5.\0\0DRAW-COMMANDS ! 42: 5.1.6.\0\0CHOOSE-COMMANDS ! 43: 5.1.7.\0\0SET-RANDOM-COMMANDS ! 44: 5.1.8.\0\0REMOVE-COMMANDS ! 45: 5.1.9.\0\0INSERT-COMMANDS ! 46: 5.1.10.\0DELETE-COMMANDS ! 47: 5.1.11.\0QUIT-COMMAND ! 48: 5.1.12.\0RETURN-COMMANDS ! 49: 5.1.13.\0SUCCEED-COMMAND ! 50: 5.1.14.\0FAIL-COMMAND ! 51: 5.1.15.\0USER-DEFINED-COMMANDS ! 52: 5.1.16.\0REFINED-COMMANDS ! 53: 5.2.\0CONTROL-COMMANDS ! 54: 5.2.1.\0IF-COMMANDS ! 55: 5.2.2.\0SELECT-COMMANDS ! 56: 5.2.3.\0WHILE-COMMANDS ! 57: 5.2.4.\0FOR-COMMANDS ! 58: 6.\0EXPRESSIONS, TARGETS AND TESTS ! 59: 6.1.\0EXPRESSIONS ! 60: 6.1.1.\0NUMERIC-CONSTANTS ! 61: 6.1.2.\0TARGET-CONTENTS ! 62: 6.1.3.\0TRIMMED-TEXTS ! 63: 6.1.4.\0TABLE-SELECTIONS ! 64: 6.1.5.\0DISPLAYS ! 65: 6.1.6.\0FORMULAS ! 66: Formulas with user-defined functions ! 67: Formulas with predefined functions ! 68: 6.1.7.\0REFINED-EXPRESSIONS ! 69: 6.2.\0TARGETS ! 70: 6.2.1.\0IDENTIFIERS ! 71: 6.2.2.\0TRIMMED-TEXT-TARGETS ! 72: 6.2.3.\0TABLE-SELECTION-TARGETS ! 73: 6.3.\0TESTS ! 74: 6.3.1.\0ORDER-TESTS ! 75: 6.3.2.\0PROPOSITIONS ! 76: Propositions with user-defined predicates ! 77: Propositions with predefined predicates ! 78: 6.3.3.\0REFINED-TESTS ! 79: 6.3.4.\0CONJUNCTIONS ! 80: 6.3.5.\0DISJUNCTIONS ! 81: 6.3.6.\0NEGATIONS ! 82: 6.3.7.\0QUANTIFICATIONS ! 83: INDEX ! 84: .ps 10 ! 85: .vs 12 ! 86: .in 0 ! 87: .ds Sn Introduction ! 88: .bp ! 89: .St 0 INTRODUCTION ! 90: .fi ! 91: .Tx ! 92: \*B is a simple but powerful new programming language, designed for use in ! 93: personal computing. ! 94: (Note: the name ``\*B'' is only a temporary working title, ! 95: and the new language bears no relation to the predecessor of ! 96: C.)\ ! 97: The foremost aim in the design of \*B has been the ease of use for ! 98: programmers who want to produce working programs without having ! 99: to master a complex tool. ! 100: An implementation of \*B is available from the \*B group at ! 101: the CWI, currently only under UNIX* or its look-alikes, but soon ! 102: (scheduled early 1985) also for the IBM-PC under MS-DOS. ! 103: Remarks concerning the implementation appear in this description ! 104: between double braces {{ and }}. ! 105: .sp 0.6v ! 106: This description of \*B originated from a text, prepared by ! 107: the first author, for use in teaching \*B during the Fall ! 108: term of 1982 at New York University. ! 109: The aim is to provide a reference book for the users of \*B that is more ! 110: accessible than the somewhat formal ``Draft Proposal'' [2]. ! 111: While it is not a text book, it should also be useful ! 112: to people who already have ample programming ! 113: experience and want to learn \*B. ! 114: A text book for beginners is also available from the CWI [1]. ! 115: .sp 0.6v ! 116: In this description we have tried to remain close to the Draft Proposal ! 117: in order to facilitate cross-referencing. To this end, all section numbers ! 118: from section 4 onwards are the same as in the Draft Proposal. ! 119: However there are some changes in terminology. ! 120: Some minor differences are ! 121: .sp 0.6v ! 122: .ta 2m \w'mmTYPE-TYPES-expressionmm'u \w'mmTYPE-TYPES-expressionmm'u+\w'multiple-expressionmm'u ! 123: .nf ! 124: \& Draft Proposal: This description: ! 125: .sp 0.4v ! 126: \& textual-display text-display ! 127: \& textual-body text-body ! 128: \& LIST-body optional-list-body ! 129: \& TABLE-body optional-table-filler-series ! 130: .fi ! 131: .sp 0.6v ! 132: But the main difference is perhaps in the treatment of ``collateral'': ! 133: .sp 0.6v ! 134: .nf ! 135: \& Draft Proposal: This description: Examples ! 136: .sp 0.4v ! 137: \& collateral-expression expression \*(<:a (a, b) a, b\*(:> ! 138: \& TYPE-expression single-expression \*(<:a (a, b)\*(:> ! 139: \& TYPE-TYPES-expression multiple-expression \*(<: a, b\*(:> ! 140: .fi ! 141: .sp 0.6v ! 142: Whereas these are purely descriptional differences, ! 143: there are also a few differences in content. ! 144: Where the Draft Proposal has the keyword \*(<:ALLOW\*(:>, ! 145: \*B now has the keyword \*(<:SHARE\*(:>; ! 146: a command \*(<:READ\*(:>\ ...\ \*(<:RAW\*(:> has been added; ! 147: and approximate-constants may no longer consist of just an exponent-part: ! 148: \*(<:E-1\*(:> must now be written \*(<:1E-1\*(:>. ! 149: .sp 0.6v ! 150: References ! 151: .sp 0.5v ! 152: .in +\w'[1]\ 'u ! 153: .ti 0 ! 154: [1]\ \fIComputer Programming for Beginners, Introducing the B Language, ! 155: Part 1\fP, ! 156: .br ! 157: Leo Geurts, CWI, Amsterdam, 1984 ! 158: .sp 0.5v ! 159: .ti 0 ! 160: [2]\ \fIDraft Proposal for the B Programming Language\fP, ! 161: .br ! 162: Lambert Meertens, CWI, Amsterdam, 1981 ! 163: .sp 0.6v ! 164: .in 0 ! 165: *\ \s-2Unix is a trademark of Bell Laboratories.\s0 ! 166: .fi ! 167: .SN 1 ! 168: .bp ! 169: .St 1 "VALUES IN \*B" ! 170: .de tY ! 171: .sp 1 ! 172: .ne 5 ! 173: .in \w'Compounds\0\0'u ! 174: .ta \w'Compounds\0\0'u ! 175: .ti 0 ! 176: \\$1\t\c ! 177: .. ! 178: .Xx number ! 179: .Xx exact number ! 180: .Xx approximate number ! 181: .Xx text ! 182: .Xx character ! 183: .Xx order ! 184: .Xx compound ! 185: .Xx field ! 186: .Xx list ! 187: .Xx entry ! 188: .Xx list entry ! 189: .Xx table ! 190: .Xx table entry ! 191: .Xx key ! 192: .Xx associate ! 193: .Tx ! 194: \*B has two basic types of values: numbers and texts, and three ways of making ! 195: new types of values from existing ones: compounds, lists and tables. ! 196: The built-in functions for operating on these values are described ! 197: in section 6.1.6 entitled ``Formulas with predefined functions''. ! 198: .tY Numbers ! 199: Numbers come in two kinds: exact and approximate. ! 200: Exact numbers are rational numbers. ! 201: For example, \*(<:1.25\*(:> = \*(<:5/4\*(:>, and \*(<:(1/3)*3\*(:> = \*(<:1\*(:>. ! 202: There is no restriction on the size of numerator and denominator. ! 203: Approximate numbers are implemented by whatever the hardware has to offer ! 204: for fast but approximate arithmetic (floating point). ! 205: .br ! 206: The arithmetic operations and many other functions give an exact result ! 207: when their operands are exact, ! 208: and an approximate result otherwise, ! 209: but the function \*(<:sin\*(:>, for example, always returns an approximate number. ! 210: .br ! 211: An exact number can be made approximate with the \*(<:~\*(:> function ! 212: (e.g. \*(<:~1.25\*(:>); ! 213: the functions \*(<:round\*(:>, \*(<:floor\*(:> and \*(<:ceiling\*(:> can be used to convert ! 214: an approximate number to an exact one. ! 215: .br ! 216: Exact and approximate numbers may be mixed in arithmetic, as in \*(<:4 * atan 1\*(:>. ! 217: .tY Texts ! 218: Texts (strings) are composed of printable ASCII characters. ! 219: They are variable length, and are ordered in the usual lexicographic way: ! 220: \&\*(<:'a' < 'aa' < 'b'\*(:>. ! 221: There is no type ``character'': a text of length one will do. ! 222: .br ! 223: The printable characters ! 224: are the 95 characters represented on the lines below, ! 225: where the blank space preceding `\*(<:!\*(:>' stands for the ! 226: (otherwise invisible) space character: ! 227: .Di 5 ! 228: \*(<: !"#$%&'()*+,-./0123456789:;<=>? ! 229: @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_ ! 230: `abcdefghijklmnopqrstuvwxyz{|}~\*(:> ! 231: .br ! 232: .Ed ! 233: The ordering ! 234: on the characters is the ASCII collating order, which is the order ! 235: in which the characters are displayed above. ! 236: .tY Compounds ! 237: A compound consists of a sequence of other values, its ``fields''. ! 238: For example, ! 239: the number \*(<:3\*(:> and the text \*(<:'xyz'\*(:> may be combined to give the ! 240: compound \*(<:3, 'xyz'\*(:>. ! 241: Compounds are also ordered lexicographically. ! 242: .br ! 243: For example, \*(<:(3, 'xyz') < (3, 'yz') < (pi, 'aaa')\*(:>. ! 244: For this to be meaningful, the compounds that are compared must ! 245: be of the same type. ! 246: This means that they have the ! 247: same number of fields, and that corresponding fields are of the same type. ! 248: .br ! 249: The only way to obtain the individual fields of a compound is to put it ! 250: in a multiple-target with the right number of components, as in ! 251: .Di 1 ! 252: \*(<:PUT name IN last'name, first'name, middle'name\*(:>. ! 253: .Ed ! 254: .tY Lists ! 255: A list is a \fIsorted\fP sequence of values, its ``entries''. ! 256: All entries of a list must be of the same type, and this determines ! 257: the type of the list. ! 258: The length of a list may vary without influencing its type. ! 259: When an entry is inserted in a list (with an \*(<:INSERT\*(:> command), it is automatically ! 260: inserted in the list in the proper position in the sorting order. ! 261: A list may contain duplicates of the same entry. ! 262: Entries may be removed with the \*(<:REMOVE\*(:> command. ! 263: Again, lists themselves are ordered lexicographically. ! 264: .tY Tables ! 265: A table consists of a (sorted) sequence of ``table entries''. ! 266: Each table entry is a pair of two values: a \fIkey\fP and an \fIassociate\fP. ! 267: All keys of a table must be of the same type; similarly, all associates must ! 268: also be of the same type (but that type may be different to ! 269: that of the keys). ! 270: A table may not contain duplicate keys. ! 271: If \*(<:k\*(:> is a key of the table \*(<:t\*(:>, then \*(<:t[k]\*(:> ! 272: gives the associate corresponding to \*(<:k\*(:>. ! 273: New entries can be made, or existing entries modified, by putting the ! 274: associate value in the table after selecting with the key value, as ! 275: in \*(<:PUT a IN t[k]\*(:>. ! 276: Entries can be deleted with the \*(<:DELETE\*(:> command, as in \*(<:DELETE t[k]\*(:>. ! 277: The ordering is again lexicographic. ! 278: .St 2 "SYNTAX DESCRIPTION METHOD" ! 279: .Tx ! 280: The syntax of \*B is given in the following form: ! 281: each rule starts with the name of the thing being defined followed by a colon; ! 282: following this are one or more alternatives, ! 283: each marked with a \(bu in front. ! 284: Each alternative is composed of symbols that stand for ! 285: themselves, or the names of other rules. ! 286: These other rules are then defined elsewhere in the grammar, ! 287: or possibly in the same rule. ! 288: As an example, here is a simple grammar for a small part of English: ! 289: .Sy 4 ! 290: .Pn sentence 3 ! 291: .Al ! 292: declarative ! 293: .Al ! 294: declarative \*(<:,\*(:> connective\0sentence ! 295: .Pn declarative 3 ! 296: .Al ! 297: collective-noun\0verb\0collective-noun ! 298: .Al ! 299: collective-noun \*(<:do not\*(:> verb\0collective-noun ! 300: .Pn collective-noun 2 ! 301: .Al ! 302: \*(<:cats\*(:> ! 303: .Al ! 304: \*(<:dogs\*(:> ! 305: .Al ! 306: \*(<:people\*(:> ! 307: .Al ! 308: \*(<:the police\*(:> ! 309: .Pn verb 2 ! 310: .Al ! 311: \*(<:love\*(:> ! 312: .Al ! 313: \*(<:hate\*(:> ! 314: .Al ! 315: \*(<:eat\*(:> ! 316: .Al ! 317: \*(<:hassle\*(:> ! 318: .Pn connective 2 ! 319: .Al ! 320: \*(<:and\*(:> ! 321: .Al ! 322: \*(<:but\*(:> ! 323: .Al ! 324: \*(<:although\*(:> ! 325: .Al ! 326: \*(<:because\*(:> ! 327: .Al ! 328: \*(<:yet\*(:> ! 329: .Tx ! 330: This produces sentences like: ! 331: .Di 4 ! 332: .in -6 ! 333: \*(<:dogs do not love the police\*(:> ! 334: \*(<:the police hassle dogs\*(:> ! 335: \*(<:cats do not hate cats , but cats hate dogs , because dogs hate cats\*(:> ! 336: \*(<:people eat dogs , yet dogs love people\*(:> ! 337: .in +6 ! 338: .Ed ! 339: .in 0 ! 340: You will notice that the names of rules are in a different ! 341: typeface to words that stand for themselves. ! 342: In the grammar of \*B that follows, furthermore, rule names ! 343: are all in lower-case letters, while words that stand for themselves are all ! 344: in upper-case letters, so they are easily distinguished. ! 345: .sp ! 346: It often happens that a part of an alternative is optional. ! 347: There is a special rule for this: ! 348: .Sy 4 ! 349: .Pr empty 2 ! 350: .Al ! 351: .br ! 352: .Pr optional-ANYTHING 3 ! 353: .Al ! 354: empty ! 355: .Al ! 356: ANYTHING ! 357: .Tx ! 358: The ``optional'' rule is included to save many rules in the definition. ! 359: For example, it stands for a rule ! 360: .Pn optional-comment 3 ! 361: .Al ! 362: empty ! 363: .Al ! 364: comment ! 365: .Tx ! 366: and similar rules. ! 367: (Empty produces an empty result.) ! 368: .St 3 REPRESENTATIONS ! 369: .Xx indentation ! 370: .Xx increase-indentation ! 371: .Xx decrease-indentation ! 372: .Xx new-line-proper ! 373: .Xx keyword ! 374: .Xx tag ! 375: .Pr new-line 2 ! 376: .Sl ! 377: optional-comment\0new-line-proper\0indent ! 378: .Ps ! 379: A \*B program consists of indented lines. ! 380: A new-line-proper marks a transition to a new line. ! 381: An indent stands for the left margin blank offset. ! 382: Initially, the left margin has zero width. ! 383: The indentation is increased by an increase-indentation ! 384: and decreased again by a decrease-indentation. ! 385: These always come in pairs and serve for grouping, just as BEGIN-END pairs ! 386: do in other programming languages. ! 387: An increase-indentation is always preceded by a line ending with a colon ! 388: (possibly followed by comment). ! 389: .Pr comment 3 ! 390: .Al ! 391: optional-new-line-proper\0optional-spaces ! 392: \*(<:\\\*(:> comment-body\0optional-further-comment ! 393: .Pr further-comment 3 ! 394: .Al ! 395: new-line-proper\0optional-spaces ! 396: \*(<:\\\*(:> comment-body\0optional-further-comment ! 397: .Pr spaces 2 ! 398: .Sl ! 399: space\0optional-spaces ! 400: .Ps ! 401: Comments may be placed at the end of a line or may stand alone ! 402: on a line. ! 403: No comment may precede the first line of a unit (see section 4). ! 404: .br ! 405: A comment-body may be any sequence of printable characters. ! 406: .Sx 2 comment: ! 407: \*(<:\\modified 6/4/84 to reject passwords of length < 6\*(:> ! 408: .Tx ! 409: Keywords are composed of CAPITAL letters (\*(<:A\*(:> to \*(<:Z\*(:>), digits, ! 410: and quotes (\*(<:'\*(:> and \*(<:"\*(:>). ! 411: A keyword must start with a letter. ! 412: For example, \*(<:A3'B"\*(:> is a keyword. ! 413: .Tx ! 414: Tags are composed of lower-case letters (\*(<:a\*(:> to \*(<:z\*(:>), digits, ! 415: and quotes (\*(<:'\*(:> and \*(<:"\*(:>). ! 416: A tag must start with a letter. ! 417: For example, \*(<:a3'b"\*(:> is a tag. ! 418: .Tx ! 419: Some other signs are composite: \*(<:..\*(:>, \*(<:**\*(:>, \*(<:*/\*(:>, \*(<:/*\*(:>, \*(<:^^\*(:>, ! 420: \*(<:<<\*(:>, \*(<:><\*(:>, \*(<:>>\*(:>, \*(<:<=\*(:>, \*(<:<>\*(:> and \*(<:>=\*(:>. ! 421: Spaces are freely allowed between symbols, but not ! 422: within keywords, tags, numeric-constants and composite signs. ! 423: Sometimes spaces are required to separate keywords and tags from following ! 424: symbols. ! 425: For example, \*(<:cos y\*(:> is not the same as \*(<:cosy\*(:>: the latter is ! 426: taken to be one tag. ! 427: .St 4 UNITS ! 428: .Xx work-space ! 429: .Sy 4 ! 430: .Pr unit 4 ! 431: .Al ! 432: how-to-unit ! 433: .Al ! 434: yield-unit ! 435: .Al ! 436: test-unit ! 437: .Ps ! 438: Units are the building blocks of a \*B ``program''. ! 439: Users can define new commands, functions and predicates by writing a unit. ! 440: These units reside in a work-space. ! 441: .Pr refinement-suite 2 ! 442: .Al ! 443: new-line\0refinement\0optional-refinement-suite ! 444: .Ps ! 445: When writing a unit, the specification of some parts ! 446: (commands, expressions and tests) may be deferred by ! 447: using a ``refinement''. ! 448: These refinements are then specified at the end of the unit. ! 449: .Se 3 4.1 HOW-TO-UNITS ! 450: .Xx keyword ! 451: .Xx user-defined-command ! 452: .Sy 3 ! 453: .Pr how-to-unit 3 ! 454: .Al ! 455: \*(<:HOW'TO\*(:> formal-user-defined-command\*(<::\*(:> ! 456: .br ! 457: command-suite ! 458: .br ! 459: optional-refinement-suite ! 460: .Pr formal-user-defined-command 2 ! 461: .Sl ! 462: keyword\0optional-formal-tail ! 463: .Ps ! 464: The first keyword of a formal-user-defined-command must be unique, i.e., ! 465: different from the first keywords of all predefined and other ! 466: user-defined commands. ! 467: So it is impossible to redefine the built-in commands of \*B. ! 468: It may also not be \*(<:HOW'TO\*(:>, \*(<:YIELD\*(:>, \*(<:TEST\*(:>, \*(<:SHARE\*(:> or \*(<:ELSE\*(:>. ! 469: Otherwise, it may be chosen freely. ! 470: There are no restrictions on the second and further keywords. ! 471: .Pr formal-tail 3 ! 472: .Al ! 473: formal-parameter\0optional-formal-trailer ! 474: .Al ! 475: formal-trailer ! 476: .Pr formal-trailer 2 ! 477: .Sl ! 478: keyword\0optional-formal-tail ! 479: .Pr formal-parameter 1 ! 480: .Sl ! 481: tag ! 482: .Ps ! 483: Note that, although actual-parameters (section 5.1.16) ! 484: and formal-operands (section 4.2) may be composite, ! 485: formal-parameters must be simple tags. ! 486: .Sx 5 \k1how-to-unit: ! 487: \*(<:HOW'TO PUSH value ON stack: ! 488: PUT value IN stack[#stack+1]\*(:> ! 489: .Tx ! 490: A how-to-unit defines the meaning of a new command ! 491: (see ``user-defined-commands'', section 5.1.16). ! 492: The above unit defines a \*(<:PUSH\*(:>\ ...\ \*(<:ON\*(:>\ ... command. ! 493: Once the command has been defined, it may be used in the ! 494: same way as the built-in commands. ! 495: Other user-defined commands may be used in the body of a unit ! 496: even if they have not yet been defined, ! 497: though they must be defined by the time the unit is invoked. ! 498: .Xe ! 499: .Sa ! 500: quit-command (5.1.11), ! 501: share-heading (4.5), ! 502: user-defined-commands (5.1.16). ! 503: .Se 3 4.2 YIELD-UNITS ! 504: .Xx "overloading of functions and predicates" ! 505: .Xx user-defined functions ! 506: .Xx formula ! 507: .Xx function ! 508: .Xx predicate ! 509: .Xx zeroadic ! 510: .Xx monadic ! 511: .Xx dyadic ! 512: .Sy 3 ! 513: .Pr yield-unit 3 ! 514: .Al ! 515: \*(<:YIELD\*(:> formal-formula\*(<::\*(:> ! 516: .br ! 517: command-suite ! 518: .br ! 519: optional-refinement-suite ! 520: .Pr formal-formula 4 ! 521: .Al ! 522: formal-zeroadic-formula ! 523: .Al ! 524: formal-monadic-formula ! 525: .Al ! 526: formal-dyadic-formula ! 527: .Pr formal-zeroadic-formula 2 ! 528: .Sl ! 529: zeroadic-function ! 530: .Pr formal-monadic-formula 2 ! 531: .Sl ! 532: monadic-function\0formal-operand ! 533: .Pr formal-dyadic-formula 2 ! 534: .Al ! 535: formal-operand\0dyadic-function\0formal-operand ! 536: .Ps ! 537: Functions must not be ``overloaded'' (multiply defined), ! 538: and a user-defined function must be represented by a tag. ! 539: However, a given tag may be used, at the same time, for ! 540: a dyadic-function and either a zeroadic- or a monadic-function or -predicate. ! 541: (In other words, you may not have a function that is both monadic ! 542: and zeroadic, for otherwise it would be impossible to decide what was meant ! 543: in cases such as \*(<:f + 1\*(:>, ! 544: where \*(<:f\*(:> could be either zeroadic or monadic, and the restrictions ! 545: also apply to combinations of functions and predicates.) ! 546: .Pr formal-operand 2 ! 547: .Sl ! 548: single-identifier ! 549: .Sx 5 \k1yield-unit: ! 550: \*(<:YIELD (a, b) over (c, d): ! 551: PUT c*c+d*d IN rr ! 552: RETURN (a*c+b*d)/rr, (-a*d+b*c)/rr\*(:> ! 553: .Xe ! 554: .Tx ! 555: A yield-unit defines the meaning of a new function ! 556: (see ``Formulas with user-defined functions'', section 6.1.6). ! 557: The example given above defines complex division. ! 558: (Complex numbers are not a built-in type of \*B.) ! 559: .br ! 560: Functions may be zeroadic (no operands), monadic (one trailing operand) ! 561: or dyadic (two operands, one at the left and one at the right). ! 562: .Sa ! 563: return-commands (5.1.12), ! 564: share-headings (4.5), ! 565: formulas with user-defined functions (6.1.6). ! 566: .Se 3 4.3 TEST-UNITS ! 567: .Xx "overloading of functions and predicates" ! 568: .Xx user-defined-predicates ! 569: .Xx test ! 570: .Xx formula ! 571: .Xx function ! 572: .Xx predicate ! 573: .Xx proposition ! 574: .Xx zeroadic ! 575: .Xx monadic ! 576: .Xx dyadic ! 577: .Sy 3 ! 578: .Pr test-unit 3 ! 579: .Al ! 580: \*(<:TEST\*(:> formal-proposition\*(<::\*(:> ! 581: .br ! 582: command-suite ! 583: .br ! 584: optional-refinement-suite ! 585: .Pr formal-proposition 4 ! 586: .Al ! 587: formal-zeroadic-proposition ! 588: .Al ! 589: formal-monadic-proposition ! 590: .Al ! 591: formal-dyadic-proposition ! 592: .Pr formal-zeroadic-proposition 2 ! 593: .Sl ! 594: zeroadic-predicate ! 595: .Pr formal-monadic-proposition 2 ! 596: .Al ! 597: monadic-predicate\0formal-operand ! 598: .Pr formal-dyadic-proposition 2 ! 599: .Al ! 600: formal-operand\0dyadic-predicate\0formal-operand ! 601: .Ps ! 602: Like functions, predicates must not be ``overloaded'', ! 603: though a given tag may be used, at the same time, for ! 604: a dyadic-predicate and either a zeroadic- or a monadic-function or -predicate. ! 605: .Sx 5 \k1test-unit: ! 606: \*(<:TEST a subset b: ! 607: REPORT EACH x IN a HAS x in b\*(:> ! 608: .Xe ! 609: .Tx ! 610: A test-unit defines the meaning of a new predicate ! 611: (see ``Propositions with user-defined predicates'', section 6.3.2). ! 612: Like functions, predicates may be zeroadic, monadic or dyadic. ! 613: .br ! 614: Tests do not return a value, but succeed or fail via the \*(<:REPORT\*(:>, ! 615: \*(<:SUCCEED\*(:> and \*(<:FAIL\*(:> commands. ! 616: .Sa ! 617: report-commands (5.1.13), ! 618: succeed-command (5.1.14), ! 619: fail-command (5.1.15), ! 620: share-headings (4.5), ! 621: propositions with user-defined predicates (6.3.2). ! 622: .Se 4 4.4 REFINEMENTS ! 623: .Xx keyword ! 624: .Sy 4 ! 625: .Pr refinement 4 ! 626: .Al ! 627: command-refinement ! 628: .Al ! 629: expression-refinement ! 630: .Al ! 631: test-refinement ! 632: .Pr command-refinement 2 ! 633: .Sl ! 634: keyword\*(<::\*(:> command-suite ! 635: .Ps ! 636: The keyword of a command-refinement must be different from the first keywords ! 637: of all predefined commands, ! 638: and it may also not be \*(<:HOW'TO\*(:>, \*(<:YIELD\*(:>, \*(<:TEST\*(:>, \*(<:SHARE\*(:> or \*(<:ELSE\*(:>. ! 639: It may, however, be the same as the first keyword of a user-defined-command. ! 640: .Sx 4 \k1command-refinement: ! 641: \*(<:SELECT'TASK: ! 642: PUT min tasks IN task ! 643: REMOVE task FROM tasks\*(:> ! 644: .Pr expression-refinement 2 ! 645: .Sl ! 646: tag\*(<::\*(:> command-suite ! 647: .Sx 4 expression-refinement: ! 648: \*(<:stack'pointer: ! 649: IF stack = {}: RETURN 0 ! 650: RETURN max keys stack\*(:> ! 651: .Pr test-refinement 2 ! 652: .Sl ! 653: tag\*(<::\*(:> command-suite ! 654: .Sx 4 test-refinement: ! 655: \*(<:special'case: ! 656: REPORT position+d = line'length\*(:> ! 657: .Xe ! 658: .Tx ! 659: Refinements support the method of ``top-down'' programming, also ! 660: known as programming by ``stepwise refinement''. ! 661: The body of a unit may be written using refined-commands, -expressions ! 662: and -tests that reflect the appropriate, coarse-grained, level of ! 663: abstraction for expressing the algorithmic intention. ! 664: In subsequent refinements, these may be refined to ! 665: the necessary detail, possibly in several steps. ! 666: As with units, there are three kinds of refinements. ! 667: The differences with units are: ! 668: .in (\w'\(em\ 'u+3m)u ! 669: .ti 3m ! 670: \(em\ refinements are bound to a unit and may not be invoked ! 671: from other units; ! 672: .ti 3m ! 673: \(em\ all tags known inside the unit are also known inside the ! 674: refinement; ! 675: .ti 3m ! 676: \(em\ no parameters or operands can be passed when the ! 677: refinement is invoked. ! 678: .in 0 ! 679: {{Currently, refinements may only occur within unit bodies, and not ! 680: in ``immediate commands''.}} ! 681: .Sa ! 682: refined-commands (5.1.17), ! 683: refined-expressions (6.1.7), ! 684: refined-tests (6.3.3). ! 685: .Se 4 4.5 COMMAND-SUITES ! 686: .Xx target ! 687: .Xx local ! 688: .Xx global ! 689: .Xx work-space ! 690: .Xx permanent environment ! 691: .Xx yield-unit ! 692: .Xx expression-refinement ! 693: .Xx return-command ! 694: .Xx test-unit ! 695: .Xx test-refinement ! 696: .Xx report-command ! 697: .Xx succeed-command ! 698: .Xx fail-command ! 699: .Sy 4 ! 700: .Pr command-suite 4 ! 701: .Al ! 702: simple-command ! 703: .Al ! 704: increase-indentation\0optional-share-heading ! 705: optional-command-sequence\0decrease-indentation ! 706: .Ps ! 707: A command-suite may only follow the preceding colon on the same line ! 708: if it is a simple-command. ! 709: Otherwise, it starts on a new line, with ! 710: all lines of the command-suite indented. ! 711: .Sx 4 command-suite ! 712: \*(<:SHARE name'list, abbreviation'table ! 713: IF name in keys abbreviation'table: ! 714: PUT abbreviation'table[name] IN name ! 715: IF name not'in name'list: ! 716: INSERT name IN name'list\*(:> ! 717: .Xe ! 718: .Pr share-heading 3 ! 719: .Al ! 720: new-line \*(<:SHARE\*(:> identifier\0optional-share-heading ! 721: .Ps ! 722: Tags used as targets (variables) in a unit ! 723: (except those that are formal-parameters) ! 724: are by default local to the unit. ! 725: If a target should be shared between several units, ! 726: this can be indicated by listing the tag ! 727: in a share-heading at the start of the unit body. ! 728: It stands then for a global target of the work-space. ! 729: The global targets together with their contents are also called the ``permanent ! 730: environment'', because they survive on logging out. ! 731: .br ! 732: A share-heading may only occur in the command-suite of a unit (and not ! 733: of a refinement or compound-command). ! 734: .Sx 2 share-heading ! 735: \*(<:SHARE name'list, abbreviation'table\*(:> ! 736: .Xe ! 737: .Pr command-sequence 2 ! 738: .Al ! 739: new-line\0command\0optional-command-sequence ! 740: .Ps ! 741: The execution of the command-suite of a yield-unit or ! 742: expression-refinement must end in a return-command, and return-commands ! 743: may only occur within such command-suites. ! 744: .Ps ! 745: The execution of the command-suite of a test-unit or ! 746: test-refinement must end in a report-, succeed- or fail-command, and these ! 747: may only occur within such command-suites. ! 748: .Sx 3 command-sequence ! 749: \*(<:IF name in keys abbreviation'table: ! 750: PUT abbreviation'table[name] IN name ! 751: IF name not'in name'list: ! 752: INSERT name IN name'list\*(:> ! 753: .Xe ! 754: .St 5 COMMANDS ! 755: .Xx immediate command ! 756: .Xx global ! 757: .Xx interrupt key ! 758: .Tx ! 759: Commands may be given as ``immediate commands'', directly from ! 760: the terminal, or may be part of a unit. ! 761: If commands are given as immediate commands, they are obeyed ! 762: directly. ! 763: Any targets in the command are then interpreted as global targets ! 764: from the permanent environment. ! 765: Within a unit, targets are local, unless they have been listed ! 766: in a share-heading (see above). ! 767: .br ! 768: If the user presses the interrupt key while a command is executing, ! 769: execution is aborted, and the user is prompted for another immediate command. ! 770: .Sy 3 ! 771: .Pr command 3 ! 772: .Al ! 773: simple-command ! 774: .Al ! 775: control-command ! 776: .Se 3 5.1 SIMPLE-COMMANDS ! 777: .Sy 3 ! 778: .Pr simple-command 3 ! 779: .Al ! 780: check-command ! 781: .Al ! 782: write-command ! 783: .Al ! 784: read-command ! 785: .Al ! 786: put-command ! 787: .Al ! 788: draw-command ! 789: .Al ! 790: choose-command ! 791: .Al ! 792: set-random-command ! 793: .Al ! 794: remove-command ! 795: .Al ! 796: insert-command ! 797: .Al ! 798: delete-command ! 799: .Al ! 800: terminating-command ! 801: .Al ! 802: user-defined-command ! 803: .Al ! 804: refined-command ! 805: .Pr terminating-command 3 ! 806: .Al ! 807: quit-command ! 808: .Al ! 809: return-command ! 810: .Al ! 811: report-command ! 812: .Al ! 813: succeed-command ! 814: .Al ! 815: fail-command ! 816: .Se 2 5.1.1 CHECK-COMMANDS ! 817: .Sy 2 ! 818: .Pr check-command 2 ! 819: .Sl ! 820: \*(<:CHECK\*(:> test ! 821: .Sx 3 \k1check-command: ! 822: \*(<:CHECK i >= 0 AND j >= 0 AND i+j <= n\*(:> ! 823: .Xe ! 824: .Tx ! 825: When a check-command is executed, its test is tested. ! 826: If the test fails, an error is reported and execution halts. ! 827: Otherwise, no message is given and execution continues. ! 828: Check-commands may be used, for example, to check the requirements of ! 829: parameters or operands on entry to a unit. ! 830: The liberal use of check-commands helps to get programs correct quickly. ! 831: .Se 3 5.1.2 WRITE-COMMANDS ! 832: .Xx convert to a text ! 833: .Xx permanent environment ! 834: .Xx interrupt key ! 835: .Sy 3 ! 836: .Pr write-command 3 ! 837: .Al ! 838: \*(<:WRITE\*(:> new-liners ! 839: .Al ! 840: \*(<:WRITE\*(:> optional-new-liners\0expression\0optional-new-liners ! 841: .Pr new-liners 2 ! 842: .Sl ! 843: \*(<:/\*(:> optional-new-liners ! 844: .Ex 3 ! 845: \k1write-commands: ! 846: \h'|\n1u'\*(<:WRITE //\*(:> ! 847: \h'|\n1u'\*(<:WRITE // 'Give a value in the range 1 through `n`: '\*(:> ! 848: .Tx ! 849: The expression is converted to a text and written to the screen. ! 850: Each \*(<:/\*(:> gives a transition to a new line. ! 851: Note that you write no comma before or after the \*(<:/\*(:>s. ! 852: .br ! 853: With the exception of adjacent texts, ! 854: values that are adjacent are written separated by a space. ! 855: Compounds within other values (within lists, tables or other compounds) ! 856: are written with commas between their fields, ! 857: and where necessary, the whole surrounded by brackets. ! 858: Similarly, inner texts are written enclosed by quotes. ! 859: Compounds and texts not within other values are output without commas, ! 860: brackets and quotes. ! 861: Thus, ! 862: .Di 2 ! 863: \*(<:WRITE 0, 1, ',', 2, '!', '!', 3 ! 864: WRITE {1; 2}, {['a','b']:('b','a'); ['b','a']:('a','b')} /\*(:> ! 865: .Ed ! 866: gives ! 867: .Di 1 ! 868: \*(<:0 1 , 2 !! 3 {1; 2} {['a', 'b']: ('b', 'a'); ['b', 'a']: ('a', 'b')}\*(:> ! 869: .Ed ! 870: For formatting purposes, see the operators \*(<:>>\*(:>, \*(<:<<\*(:>, and \*(<:><\*(:> ! 871: in section 6.1.6, ``Functions on Texts'', ! 872: and the conversions in text-displays in section 6.1.5, ``Displays''. ! 873: .Se 3 5.1.3 READ-COMMANDS ! 874: .Sy 3 ! 875: .Pr read-command 4 ! 876: .Al ! 877: \*(<:READ\*(:> target \*(<:EG\*(:> expression ! 878: .Al ! 879: \*(<:READ\*(:> target \*(<:RAW\*(:> ! 880: .Ex 3 ! 881: read-commands: ! 882: \*(<:READ n, s EG 0, '' ! 883: READ line RAW\*(:> ! 884: .Xe ! 885: .Tx ! 886: The execution of a read-command prompts the user ! 887: to supply one input line. ! 888: .br ! 889: If an \*(<:EG\*(:> part is present, the input is interpreted as an ! 890: \fIexpression\fP of the same type as the expression following \*(<:EG\*(:>. ! 891: (Usually, the example expression will consist of constants, ! 892: but other expressions are also allowed.) ! 893: The input expression is evaluated in the permanent environment ! 894: (so local tags of units cannot be used) and put in the target. ! 895: To input a text-display (literal), text quotes are required. ! 896: .br ! 897: If \*(<:RAW\*(:> is specified, the target must be a text target. ! 898: The input line is put in the target literally. ! 899: No text quotes are needed. ! 900: .br ! 901: If the user presses the interrupt key instead of supplying a value, ! 902: the read-command, and in fact the whole program, is aborted. ! 903: This is useful for entering a sequence of data of unspecified length. ! 904: .Se 3 5.1.4 PUT-COMMANDS ! 905: .Xx target ! 906: .Xx location ! 907: .Xx type ! 908: .Sy 3 ! 909: .Pr put-command 3 ! 910: .Sl ! 911: \*(<:PUT\*(:> expression \*(<:IN\*(:> target ! 912: .Sx 3 \k1put-command: ! 913: \*(<:PUT a+1, ({}, {1..a}) IN a, b\*(:> ! 914: .Xe ! 915: .Tx ! 916: The value of the expression is put in the target. ! 917: This means that the value will be held in a location ! 918: for the target, until a different value is put in the target, ! 919: or the target is deleted. ! 920: If no such location exists already, it is created on ! 921: the spot. ! 922: Here, as in other cases, the types must agree. ! 923: {{This is currently not checked in general.}} ! 924: See also the sections on various kinds of targets below (section 6.2). ! 925: .Se 2 5.1.5 DRAW-COMMANDS ! 926: .Xx random ! 927: .Xx number ! 928: .Sy 2 ! 929: .Pr draw-command 2 ! 930: .Sl ! 931: \*(<:DRAW\*(:> target ! 932: .Sx 3 \k1draw-command: ! 933: \*(<:DRAW r\*(:> ! 934: .Xe ! 935: .Tx ! 936: A random approximate number ! 937: (from \*(<:~0\*(:> up to, but not including, \*(<:~1\*(:>) ! 938: is drawn and put in the target. ! 939: .Se 4 5.1.6 CHOOSE-COMMANDS ! 940: .Xx text, list or table ! 941: .Xx random ! 942: .Xx character ! 943: .Xx list entry ! 944: .Xx associate ! 945: .Sy 4 ! 946: .Pr choose-command 4 ! 947: .Sl ! 948: \*(<:CHOOSE\*(:> target \*(<:FROM\*(:> expression ! 949: .Sx 3 \k1choose-command: ! 950: \*(<:CHOOSE exit FROM exits[current'room]\*(:> ! 951: .Xe ! 952: .Tx ! 953: The expression must have a text, list or table as value. ! 954: This value must not be empty. ! 955: An item is drawn at random from the value ! 956: (characters from a text, entries from a list and associates ! 957: from a table) ! 958: and put in the target. ! 959: The item is not removed from the value. ! 960: .Se 2 5.1.7 SET-RANDOM-COMMANDS ! 961: .Xx random ! 962: .Sy 2 ! 963: .Pr set-random-command 2 ! 964: .Sl ! 965: \*(<:SET'RANDOM\*(:> expression ! 966: .Sx 3 \k1set-random-command: ! 967: \*(<:SET'RANDOM 'Monte Carlo', run\*(:> ! 968: .Xe ! 969: .Tx ! 970: The (pseudo-)random sequence ! 971: used for draw- and choose-commands ! 972: is reset to a point, depending on the ! 973: value of the expression. ! 974: .Se 3 5.1.8 REMOVE-COMMANDS ! 975: .Xx list entry ! 976: .Sy 3 ! 977: .Pr remove-command 3 ! 978: .Sl ! 979: \*(<:REMOVE\*(:> expression \*(<:FROM\*(:> target ! 980: .Sx 3 \k1remove-command: ! 981: \*(<:REMOVE task FROM tasks\*(:> ! 982: .Xe ! 983: .Tx ! 984: The target must hold a list, and the value of the expression must be ! 985: an entry of that list. ! 986: The entry is removed. ! 987: If it was present more than once, only one instance is removed. ! 988: .Se 3 5.1.9 INSERT-COMMANDS ! 989: .Xx list entry ! 990: .Sy 3 ! 991: .Pr insert-command 3 ! 992: .Sl ! 993: \*(<:INSERT\*(:> expression \*(<:IN\*(:> target ! 994: .Sx 3 \k1insert-command: ! 995: \*(<:INSERT new'task IN tasks\*(:> ! 996: .Xe ! 997: .Tx ! 998: The target must hold a list. ! 999: The value of the expression is inserted as a list entry. ! 1000: If that entry was already present, one more instance will be present. ! 1001: .Se 2 5.1.10 DELETE-COMMANDS ! 1002: .Xx location ! 1003: .Xx table entry ! 1004: .Xx table-selection-target ! 1005: .Sy 2 ! 1006: .Pr delete-command 2 ! 1007: .Sl ! 1008: \*(<:DELETE\*(:> target ! 1009: .Sx 3 \k1delete-command: ! 1010: \*(<:DELETE t[i], u[i, j]\*(:> ! 1011: .Xe ! 1012: .Tx ! 1013: The location for the target ceases to exist. ! 1014: If a multiple-target is given, all its single-targets are deleted. ! 1015: If a table-selection-target is given, the table must contain the key ! 1016: that is used as selector. ! 1017: The table entry with that key is then deleted from the table. ! 1018: It is an error to delete a trimmed-text-target (e.g., \*(<:t@2\*(:>). ! 1019: .Se 2 5.1.11 QUIT-COMMAND ! 1020: .Xx how-to-unit ! 1021: .Xx command-refinement ! 1022: .Xx immediate-command ! 1023: .Xx permanent environment ! 1024: .Sy 2 ! 1025: .Pr quit-command 2 ! 1026: .Sl ! 1027: \*(<:QUIT\*(:> ! 1028: .Ps ! 1029: A quit-command may only occur in the command-suite of a ! 1030: how-to-unit or command-refinement, or as an immediate command. ! 1031: .Sx 3 \k1quit-command: ! 1032: \*(<:QUIT\*(:> ! 1033: .Xe ! 1034: .Tx ! 1035: The execution of a quit-command causes the termination of the execution ! 1036: of the how-to-unit or command-refinement in whose command-suite ! 1037: it occurs. ! 1038: If it occurs in a command-refinement, the execution of ! 1039: the invoking refined-command is thereby terminated and the further ! 1040: execution continues as if the refined-command had terminated normally. ! 1041: Otherwise, the execution of ! 1042: the invoking user-defined-command is terminated and the further ! 1043: execution continues similarly. ! 1044: .br ! 1045: Given as an immediate command, \*(<:QUIT\*(:> terminates the current ! 1046: session. ! 1047: All units and targets in the permanent environment ! 1048: survive and can be used again at the next session. ! 1049: .Se 2 5.1.12 RETURN-COMMANDS ! 1050: .Xx expression-refinement ! 1051: .Xx user-defined-function ! 1052: .Xx refined-expression ! 1053: .Xx yield-unit ! 1054: .Sy 2 ! 1055: .Pr return-command 2 ! 1056: .Sl ! 1057: \*(<:RETURN\*(:> expression ! 1058: .Sx 3 \k1return-command: ! 1059: \*(<:RETURN (a*c+b*d)/rr, (-a*d+b*c)/rr\*(:> ! 1060: .Xe ! 1061: .Tx ! 1062: The execution of a return-command causes the termination of the execution ! 1063: of the yield-unit or expression-refinement in whose command-suite ! 1064: it occurs. ! 1065: The value of the expression is returned as the value of the invoking ! 1066: user-defined function or refined-expression. ! 1067: Return-commands may only occur within the command-suite of a ! 1068: yield-unit or expression-refinement. ! 1069: .Se 2 5.1.13 REPORT-COMMANDS ! 1070: .Xx test-unit ! 1071: .Xx test-refinement ! 1072: .Xx user-defined-predicate ! 1073: .Xx refined-test ! 1074: .Xx bound tags ! 1075: .Pr report-command 2 ! 1076: .Sl ! 1077: \*(<:REPORT\*(:> test ! 1078: .Sx 3 \k1report-command: ! 1079: \*(<:REPORT i in keys t\*(:> ! 1080: .Xe ! 1081: .Tx ! 1082: The execution of a report-command causes the termination of the execution ! 1083: of the test-unit or test-refinement in whose command-suite ! 1084: it occurs. ! 1085: The invoking user-defined predicate or refined-test ! 1086: succeeds/fails if the test of the report-command succeeds/fails. ! 1087: If the invoker is a test-refinement, ! 1088: any bound tags set by a for-command (see section 5.2.4) or ! 1089: a quantification (section 6.3.7) will temporarily survive, ! 1090: as described under REFINED-TESTS (section 6.3.3). ! 1091: .br ! 1092: Report-commands may only occur within the command-suite of a ! 1093: test-unit or test-refinement. ! 1094: .br ! 1095: The command ``\*(<:REPORT\*(:> test'' is equivalent to ! 1096: .Di 3 ! 1097: \*(<:SELECT: ! 1098: \*(:>test\*(<:: SUCCEED ! 1099: ELSE: FAIL\*(:> ! 1100: .Ed ! 1101: .Se 2 5.1.14 SUCCEED-COMMAND ! 1102: .Xx test-unit ! 1103: .Xx test-refinement ! 1104: .Xx user-defined-predicate ! 1105: .Xx refined-test ! 1106: .Xx bound tags ! 1107: .Sy 2 ! 1108: .Pr succeed-command 2 ! 1109: .Sl ! 1110: \*(<:SUCCEED\*(:> ! 1111: .Sx 3 \k1succeed-command: ! 1112: \*(<:SUCCEED\*(:> ! 1113: .Xe ! 1114: .Tx ! 1115: The execution of a succeed-command causes the termination of the execution ! 1116: of the test-unit or test-refinement in whose command-suite ! 1117: it occurs. ! 1118: The invoking user-defined predicate or refined-test succeeds. ! 1119: As with report-commands, bound tags temporarily survive. ! 1120: .br ! 1121: Succeed-commands may only occur within the command-suite of a ! 1122: test-unit or test-refinement. ! 1123: .br ! 1124: The command \*(<:SUCCEED\*(:> is equivalent to \*(<:REPORT 0 = 0\*(:>. ! 1125: .Se 2 5.1.15 FAIL-COMMAND ! 1126: .Xx test-unit ! 1127: .Xx test-refinement ! 1128: .Xx user-defined-predicate ! 1129: .Xx refined-test ! 1130: .Xx bound tags ! 1131: .Sy 2 ! 1132: .Pr fail-command 2 ! 1133: .Sl ! 1134: \*(<:FAIL\*(:> ! 1135: .Sx 3 \k1fail-command: ! 1136: \*(<:FAIL\*(:> ! 1137: .Xe ! 1138: .Tx ! 1139: The execution of a fail-command causes the termination of the execution ! 1140: of the test-unit or test-refinement in whose command-suite ! 1141: it occurs. ! 1142: The invoking user-defined predicate or refined-test fails. ! 1143: As with report-commands, bound tags temporarily survive. ! 1144: .br ! 1145: Fail-commands may only occur within the command-suite of a ! 1146: test-unit or test-refinement. ! 1147: .br ! 1148: The command \*(<:FAIL\*(:> is equivalent to \*(<:REPORT 0 = 1\*(:>. ! 1149: .Se 2 5.1.16 USER-DEFINED-COMMANDS ! 1150: .Xx keyword ! 1151: .Xx how-to-unit ! 1152: .Xx quit-command ! 1153: .Sy 2 ! 1154: .Pr user-defined-command 2 ! 1155: .Sl ! 1156: keyword\0optional-actual-parameter\0optional-trailer ! 1157: .Pr trailer 2 ! 1158: .Sl ! 1159: keyword\0optional-actual-parameter\0optional-trailer ! 1160: .Pr actual-parameter 2 ! 1161: .Al ! 1162: identifier ! 1163: .Al ! 1164: target ! 1165: .Al ! 1166: expression ! 1167: .Ps ! 1168: The keywords and actual-parameters must correspond one to one to those ! 1169: of the formal-user-defined-command of one unique how-to-unit. ! 1170: .Ex 6 ! 1171: \k1user-defined-commands: ! 1172: \h'|\n1u'\*(<:CLEAN'UP\*(:> ! 1173: \h'|\n1u'\*(<:DRINK me\*(:> ! 1174: \h'|\n1u'\*(<:TURN a UPSIDE DOWN\*(:> ! 1175: \h'|\n1u'\*(<:PUSH v ON operand'stack\*(:> ! 1176: .Xe ! 1177: .Tx ! 1178: A user-defined-command is executed in the following steps: ! 1179: .in \w'2.\ 'u ! 1180: .ti 0 ! 1181: 1.\ Any local tags in the how-to-unit that might clash with tags currently ! 1182: in use are systematically replaced by other tags that do not cause conflict. ! 1183: .ti 0 ! 1184: 2.\ Each actual-parameter is placed between parentheses \*(<:(\*(:> and \*(<:)\*(:> ! 1185: and then ! 1186: substituted throughout the unit for the corresponding formal-parameter. ! 1187: .ti 0 ! 1188: 3.\ The command-suite of the unit, thus modified, is executed. ! 1189: .in 0 ! 1190: The execution of the user-defined-command is complete when the execution ! 1191: of this command-suite terminates (normally, or because of the execution ! 1192: of a quit-command). ! 1193: After the execution is complete, ! 1194: the local tags of the unit are no longer accessible. ! 1195: .Se 2 5.1.17 REFINED-COMMANDS ! 1196: .Xx keyword ! 1197: .Xx command-refinement ! 1198: .Xx quit-command ! 1199: .Sy 2 ! 1200: .Pr refined-command 2 ! 1201: .Sl ! 1202: keyword ! 1203: .Ps ! 1204: The keyword of a refined-command must occur as the keyword of one ! 1205: command-refinement in the unit ! 1206: in which it occurs. ! 1207: That command-refinement specifies the meaning of the refined-command. ! 1208: .Sx 3 \k1refined-command: ! 1209: \*(<:REMOVE'MULTIPLES\*(:> ! 1210: .Xe ! 1211: .Tx ! 1212: A refined-command is executed by executing ! 1213: the command-suite of the corresponding command-refinement. ! 1214: The execution of the refined-command is complete when the execution ! 1215: of this command-suite terminates ! 1216: (normally, or because of the execution of a quit-command). ! 1217: .Se 5 5.2 CONTROL-COMMANDS ! 1218: .Sy 5 ! 1219: .Pr control-command 5 ! 1220: .Al ! 1221: if-command ! 1222: .Al ! 1223: select-command ! 1224: .Al ! 1225: while-command ! 1226: .Al ! 1227: for-command ! 1228: .Se 2 5.2.1 IF-COMMANDS ! 1229: .Sy 2 ! 1230: .Pr if-command 2 ! 1231: .Sl ! 1232: \*(<:IF\*(:> test\*(<::\*(:> command-suite ! 1233: .Sx 3 \k1if-command: ! 1234: \*(<:IF i < 0: PUT -i, -j IN i, j\*(:> ! 1235: .Xe ! 1236: .Tx ! 1237: The test is tested. ! 1238: If it succeeds, the command-suite is executed; ! 1239: if it fails, the command-suite is not executed. ! 1240: .br ! 1241: (If something should be executed on failure too, or there are ! 1242: more alternatives, you should use a select-command instead.) ! 1243: .br ! 1244: The command ! 1245: ``\*(<:IF\*(:> test\*(<::\*(:> command-suite'' ! 1246: is equivalent to: ! 1247: .Di 3 ! 1248: \*(<:SELECT: ! 1249: \*(:>test\*(<:: \*(:>command-suite\*(<: ! 1250: ELSE: \\do nothing.\*(:> ! 1251: .Ed ! 1252: .Se 2 5.2.2 SELECT-COMMANDS ! 1253: .Sy 2 ! 1254: .Pr select-command 2 ! 1255: .Sl ! 1256: \*(<:SELECT:\*(:> alternative-suite ! 1257: .Pr alternative-suite 3 ! 1258: .Al ! 1259: increase-indentation\0new-line\0alternative-sequence\0decrease-indentation ! 1260: .Pr alternative-sequence 4 ! 1261: .Al ! 1262: single-alternative ! 1263: .Al ! 1264: else-alternative ! 1265: .Al ! 1266: single-alternative\0new-line\0alternative-sequence ! 1267: .Pr single-alternative 2 ! 1268: .Sl ! 1269: test\*(<::\*(:> command-suite ! 1270: .Pr else-alternative 2 ! 1271: .Sl ! 1272: \*(<:ELSE:\*(:> command-suite ! 1273: .Eo 5 select-commands:\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\k2\": ! 1274: \h'|\n1u'\*(<:SELECT:\*(:> \h'|\n2u'\*(<:SELECT:\*(:> ! 1275: \h'|\n1u'\*(<: a < 0: RETURN -a\*(:> \h'|\n2u'\*(<: a < 0: RETURN -a\*(:> ! 1276: \h'|\n1u'\*(<: a >= 0: RETURN a\*(:> \h'|\n2u'\*(<: ELSE: RETURN a\*(:> ! 1277: .Xe ! 1278: .Tx ! 1279: The tests of the alternatives are tested one by one, ! 1280: starting with the first and proceeding downwards, until one ! 1281: is found that succeeds. ! 1282: The corresponding command-suite is then executed. ! 1283: \*(<:ELSE\*(:> may be used in the final alternative as a test that always succeeds. ! 1284: If all the tests fail, an error is reported. ! 1285: .Se 2 5.2.3 WHILE-COMMANDS ! 1286: .Xx terminating command ! 1287: .Sy 2 ! 1288: .Pr while-command 2 ! 1289: .Sl ! 1290: \*(<:WHILE\*(:> test\*(<::\*(:> command-suite ! 1291: .Sx 3 \k1while-command: ! 1292: \*(<:WHILE x > 1: PUT x/10, c+1 IN x, c\*(:> ! 1293: .Xe ! 1294: .Tx ! 1295: If the test succeeds, the command-suite is executed, and the ! 1296: while-command is repeated, and so on, until the test fails, ! 1297: or until an escape is forced by a terminating command. ! 1298: If the test fails the very first time, the command-suite is ! 1299: not executed at all. ! 1300: .Se 3 5.2.4 FOR-COMMANDS ! 1301: .Xx text, list or table ! 1302: .Xx character ! 1303: .Xx list entry ! 1304: .Xx associate ! 1305: .Xx target ! 1306: .Xx bound tags ! 1307: .Sy 3 ! 1308: .Pr for-command 3 ! 1309: .Sl ! 1310: \*(<:FOR\*(:> in-ranger\*(<::\*(:> command-suite ! 1311: .Pr in-ranger 2 ! 1312: .Sl ! 1313: identifier \*(<:IN\*(:> expression ! 1314: .Sx 3 \k1for-command: ! 1315: \*(<:FOR i, j IN keys t: PUT t[i, j] IN t'[j, i]\*(:> ! 1316: .Xe ! 1317: .Tx ! 1318: The value of the expression must be a text, list or table. ! 1319: One by one, each item of that value ! 1320: (characters for a text, list entries for a list and associates for a table) ! 1321: is put in the identifier, and the command-suite executed. ! 1322: For example, ! 1323: .Di 1 ! 1324: \*(<:FOR c IN 'ABC': WRITE 'letter is', c /\*(:> ! 1325: .Ed ! 1326: is equivalent to ! 1327: .Di 3 ! 1328: \*(<:WRITE 'letter is', 'A' / ! 1329: WRITE 'letter is', 'B' / ! 1330: WRITE 'letter is', 'C' /\*(:> ! 1331: .Ed ! 1332: If \*(<:t\*(:> is a table, then ! 1333: ``\*(<:FOR a IN t: TREAT a\*(:>'' ! 1334: treats the associates of \*(<:t\*(:> in the same way as ! 1335: .Di 3 ! 1336: \*(<:FOR k IN keys t: ! 1337: PUT t[k] IN a ! 1338: TREAT a\*(:> ! 1339: .Ed ! 1340: The tags of the identifier of a for-command may not be used as targets ! 1341: or target-contents ! 1342: outside such a for-command. ! 1343: They are ``bound tags'', and lose their meaning outside the ! 1344: for-command. ! 1345: There is one exception to this rule: ! 1346: if a for-command is used in a test-refinement, and within ! 1347: the for-command a report-, succeed- or fail-command is ! 1348: executed, the currently bound tags will temporarily survive ! 1349: as described under REFINED-TESTS (section 6.3.3). ! 1350: .Sa ! 1351: quantifications (6.3.7).
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.