1This is kawa.info, produced by makeinfo version 6.6 from kawa.texi. 2 3START-INFO-DIR-ENTRY 4* kawa: (kawa). The Kawa Scheme language 5END-INFO-DIR-ENTRY 6 7 8File: kawa.info, Node: Datum syntax, Next: Hash-prefixed forms, Prev: Lexical syntax, Up: Syntax 9 107.4 Datum syntax 11================ 12 13The datum syntax describes the syntax of syntactic data in terms of a 14sequence of LEXEMEs, as defined in the lexical syntax. 15 16 The following grammar describes the syntax of syntactic data in terms 17of various kinds of lexemes defined in the grammar in section “Lexical 18Syntax”: 19 20 DATUM ::= DEFINING-DATUM 21 | NONDEFINING-DATUM 22 | DEFINED-DATUM 23 NONDEFINING-DATUM ::= LEXEME-DATUM 24 | COMPOUND-DATUM 25 26 LEXEME-DATUM ::= BOOLEAN | NUMBER 27 | CHARACTER | STRING | SYMBOL 28 SYMBOL ::= IDENTIFIER 29 COMPOUND-DATUM ::= LIST | VECTOR | UNIFORM-VECTOR | ARRAY-LITERAL | EXTENDED-STRING-LITERAL | XML-LITERAL 30 LIST ::= ‘(’DATUM*‘)’ 31 | ‘(’DATUM^{+} ‘.’ DATUM‘)’ 32 | ABBREVIATION 33 VECTOR ::= ‘#(’DATUM^{*}‘)’ 34 357.4.1 Datum labels 36------------------ 37 38 DATUM-LABEL ::= ‘#’INDEXNUM‘=’ 39 DEFINING-DATUM ::= DATUM-LABEL^{+}NONDEFINING-DATUM 40 DEFINED-DATUM ::= ‘#’INDEXNUM‘#’ 41 INDEXNUM ::= DIGIT^{+} 42 43 The lexical syntax ‘#N=DATUM’ reads the same as DATUM, but also 44results in DATUM being labelled by N, which must a sequence of digits. 45 46 The lexical syntax ‘#N#’ serves as a reference to some object 47labelled by ‘#N=’; the result is the same object (in the sense of ‘eq?’) 48as the ‘#N=’. 49 50 Together, these syntaxes permit the notation of structures with 51shared or circular substructure. 52 53 (let ((x (list 'a 'b 'c))) 54 (set-cdr! (cddr x) x) 55 x) ⇒ #0=(a b c . #0#) 56 57 The scope of a datum label is the portion of the outermost datum in 58which it appears that is to the right of the label. Consequently, a 59reference ‘#N#’ can occur only after a label ‘#N=’; it is an error to 60attempt a forward reference. In addition, it is an error if the 61reference appears as the labelled object itself (as in ‘#N=#N#’), 62because the object labelled by ‘#N=’ is not well defined in this case. 63 647.4.2 Abbreviations 65------------------- 66 67 ABBREVIATION ::= R6RS-ABBREVIATION | KAWA-ABBREVIATION 68 R6RS-ABBREVIATION ::= ABBREV-PREFIX DATUM 69 ABBREV-PREFIX ::= ‘’’ | ‘‘’ | ‘,’ | ‘,@’ 70 | ‘#’’ | ‘#‘’ 71 KAWA-ABBREVIATION ::= XXX 72 73 The following abbreviations are expanded at read-time: 74 75‘’’DATUM 76 means ‘(quote’ DATUM‘)’. 77 78‘‘’DATUM 79 means ‘(quasiquote’ DATUM‘)’. 80 81‘,’DATUM 82 means ‘(unquote’ DATUM‘)’. 83 84‘,@’DATUM 85 means ‘(unquote-splicing’ DATUM‘)’. 86 87‘#’’DATUM 88 means ‘(syntax’ DATUM‘)’. 89 90‘#‘’DATUM 91 means ‘(quasisyntax’ DATUM‘)’. 92 93‘#,’DATUM 94 means ‘(unsyntax’ DATUM‘)’. This abbreviation is currently only 95 recognized when nested inside an explicit ‘#‘’DATUM form, because 96 of a conflict with SRFI-10 named constructors. 97 98‘#,@’DATUM 99 means ‘(unsyntax-splicing’ DATUM‘)’. 100 101DATUM1‘:’DATUM2 102 means ‘($lookup$’ DATUM1 ‘(quasiquote’ DATUM2‘))’. *Note Colon 103 notation::. 104 105‘[’EXPRESSION ...‘]’ 106 means ‘($bracket-list$’ EXPRESSION ...‘)’. 107 108OPERATOR‘[’EXPRESSION ...‘]’ 109 means ‘($bracket-apply$’ OPERATOR EXPRESSION ...‘)’. 110 111 112File: kawa.info, Node: Hash-prefixed forms, Next: Primitive expression syntax, Prev: Datum syntax, Up: Syntax 113 1147.5 Hash-prefixed forms 115======================= 116 117A number of different special forms are indicated by an initial hash 118(number) symbols (‘#’). Here is a table summarizing them. 119 120 Case is ignored for the character followed the ‘#’. Thus ‘#x’ and 121‘#X’ are the same. 122 123‘#:’KEYWORD 124 Guile-style *note keyword: Keywords. syntax. 125‘#\’ 126 *note Character literals: meta-character. 127‘#!’ 128 *Note Special named constants::. 129‘#‘’DATUM 130 Equivalent to ‘(quasisyntax DATUM)’. Convenience syntax for 131 syntax-case macros. 132‘#’’DATUM 133 Equivalent to ‘(syntax DATUM)’. Convenience syntax for syntax-case 134 macros. 135‘#,’DATUM 136 Equivalent to ‘(unsyntax DATUM)’. Currently only recognized when 137 inside a ‘#`TEMPLATE’ form. Convenience syntax for syntax-case 138 macros. 139‘#,(’NAME DATUM ...‘)’ 140 Special named constructors. This syntax is deprecated, because it 141 conflicts with ‘unsyntax’. It is only recognized when _not_ in a 142 ‘#`TEMPLATE’ form. 143‘#,@’DATUM 144 Equivalent to ‘(unsyntax-splicing DATUM)’. 145‘#(’ 146 A vector. 147‘#|’ 148 Start of nested-comment. 149‘#/’REGEX‘/’ 150 *Note Regular expressions::. 151‘#<’ 152 *Note XML literals::. 153‘#;’DATUM 154 A datum comment - the DATUM is ignored. (An INTERLEXEME-SPACE may 155 appear before the DATUM.) 156‘#’NUMBER‘=’DATUM 157 A reference definition, allowing cyclic and shared structure. 158 Equivalent to the DATUM, but also defines an association between 159 the integer NUMBER and that DATUM, which can be used by a 160 subsequent ‘#NUMBER#’ form. 161‘#’NUMBER‘#’ 162 A back-reference, allowing cyclic and shared structure. 163‘#’R‘a’DATUM 164 An *note array literal: array-literals, for a multi-dimensional 165 array of rank R. 166‘#b’ 167 A binary (base-2) number. 168‘#d’ 169 A decimal (base-10) number. 170‘#e’ 171 A prefix to treat the following number as exact. 172‘#f’ 173‘#false’ 174 The standard boolean false object. 175‘#f’N‘(’NUMBER ...‘)’ 176 A uniform vector of floating-point numbers. The parameter N is a 177 precision, which can be 32 or 64. *Note Uniform vectors::. 178‘#i’ 179 A prefix to treat the following number as inexact. 180‘#o’ 181 An octal (base-8) number. 182‘#’BASE‘r’ 183 A number in the specified BASE (radix). 184‘#s’N‘(’NUMBER ...‘)’ 185 A uniform vector of signed integers. The parameter N is a 186 precision, which can be 8, 16, 32, or 64. *Note Uniform vectors::. 187‘#t’ 188‘#true’ 189 The standard boolean true object. 190‘#u’N‘(’NUMBER ...‘)’ 191 A uniform vector of unsigned integers. The parameter N is a 192 precision, which can be 8, 16, 32, or 64. *Note Uniform vectors::. 193‘#x’ 194 A hexadecimal (base-16) number. 195 196 The follow named constructor forms are supported: 197 198‘#,(path’ PATH‘)’ 199‘#,(filepath’ PATH‘)’ 200‘#,(URI’ PATH‘)’ 201‘#,(symbol’ LOCAL-NAME [URI [PREFIX]]‘)’ 202‘#,(symbol’ LOCAL-NAME NAMESPACE‘)’ 203‘#,(namespace’ URI [PREFIX]‘)’ 204‘#,(duration’ DURATION‘)’ 205 206 207File: kawa.info, Node: Primitive expression syntax, Next: Colon notation, Prev: Hash-prefixed forms, Up: Syntax 208 2097.6 Primitive expression syntax 210=============================== 211 212 EXPRESSION ::= LITERAL-EXPRESSION | VARIABLE-REFERENCE 213 | PROCEDURE-CALL | TODO 214 2157.6.1 Literal expressions 216------------------------- 217 218 LITERAL-EXPRESSION ::= ‘(quote’ DATUM‘)’ 219 | ‘’’ DATUM 220 | CONSTANT 221 CONSTANT ::= NUMBER | BOOLEAN | CHARACTER | STRING 222 223 ‘(quote DATUM)’ evaluates to DATUM, which may be any external 224representation of a Scheme object. This notation is used to include 225literal constants in Scheme code. 226 (quote a) ⇒ a 227 (quote #(a b c)) ⇒ #(a b c) 228 (quote (+ 1 2)) ⇒ (+ 1 2) 229 230 ‘(quote DATUM)’ may be abbreviated as ‘'DATUM’. The two notations 231are equivalent in all respects. 232 ’a ⇒ a 233 ’#(a b c) ⇒ #(a b c) 234 ’() ⇒ () 235 ’(+ 1 2) ⇒ (+ 1 2) 236 ’(quote a) ⇒ (quote a) 237 ’’a ⇒ (quote a) 238 239 Numerical constants, string constants, character constants, 240bytevector constants, and boolean constants evaluate to themselves; they 241need not be quoted. 242 243 145932 ⇒ 145932 244 #t ⇒ #t 245 "abc" ⇒ "abc" 246 247 Note that *note keywords: Keywords. need to be quoted, unlike some 248other Lisp/Scheme dialect, including Common Lisp, and earlier versions 249of Kawa. (Kawa currently evaluates a non-quoted keyword as itself, but 250that will change.) 251 2527.6.2 Variable references 253------------------------- 254 255 VARIABLE-REFERENCE ::= IDENTIFIER 256 An expression consisting of a variable is a variable reference if it 257is not a macro use (see below). The value of the variable reference is 258the value stored in the location to which the variable is bound. It is 259a syntax violation to reference an unbound variable. 260 261 The following example assumes the base library has been imported: 262 263 (define x 28) 264 x ⇒ 28 265 2667.6.3 Procedure calls 267--------------------- 268 269 PROCEDURE-CALL ::= ‘(’OPERATOR OPERAND ...) 270 OPERATOR ::= EXPRESSION 271 OPERAND ::= EXPRESSION 272 | KEYWORD EXPRESSION 273 | ‘@’ EXPRESSION 274 | ‘@:’ EXPRESSION 275 276 A procedure call consists of expressions for the procedure to be 277called and the arguments to be passed to it, with enclosing parentheses. 278A form in an expression context is a procedure call if OPERATOR is not 279an identifier bound as a syntactic keyword. 280 281 When a procedure call is evaluated, the operator and operand 282expressions are evaluated (in an unspecified order) and the resulting 283procedure is passed the resulting arguments. 284 285 (+ 3 4) ⇒ 7 286 ((if #f + *) 3 4) ⇒ 12 287 288 The syntax KEYWORD EXPRESSION is a “keyword argument”. This is a 289mechanism for specifying arguments using a name rather than position, 290and is especially useful for procedures with many optional paramaters. 291Note that KEYWORD must be literal, and cannot be the result from 292evaluating a non-literal expression. (This is a change from previous 293versions of Kawa, and is different from Common Lisp and some other 294Scheme dialects.) 295 296 An expression prefixed by ‘@’ or ‘@:’ is a splice argument. The 297following expression must evaluate to an “argument list” (see *note 298Application and Arguments Lists:: for details); each element in the 299argument becomes a separate argument when call the OPERATOR. (This is 300very similar to the “spread” operator is EcmaScript 6.) 301 302 303File: kawa.info, Node: Colon notation, Next: Bodies, Prev: Primitive expression syntax, Up: Syntax 304 3057.7 Property access using colon notation 306======================================== 307 308The “colon notation” accesses named parts (properties) of a value. It 309is used to get and set fields, call methods, construct compound symbols, 310and more. Evaluating the form ‘OWNER:PROPERTY’ evaluates the ‘OWNER’ 311then it extracts the named ‘PROPERTY’ of the result. 312 313 PROPERTY-ACCESS-ABBREVIATION ::= PROPERTY-OWNER-EXPRESSION‘:’PROPERTY-NAME 314 PROPERTY-OWNER-EXPRESSION ::= EXPRESSION 315 PROPERTY-NAME ::= IDENTIFIER | ‘,’EXPRESSION 316 317 The PROPERTY-NAME is usually a literal name, but it can be an 318unquoted EXPRESSION (i.e. following a ‘,’), in which case the name is 319evaluated at run-time. No separators are allowed on either side of the 320colon. 321 322 The input syntax ‘OWNER:PART’ is translated by the Scheme reader to 323the internal representation ‘($lookup$ OWNER (quasiquote PART))’. 324 3257.7.1 Part lookup rules 326----------------------- 327 328Evaluation proceeds as follows. First PROPERTY-OWNER-EXPRESSION is 329evaluated to yield an OWNER object. Evaluating the PROPERTY-NAME yields 330a PART name, which is a simple symbol: Either the literal IDENTIFIER, or 331the result of evaluating the property-name EXPRESSION. If the 332EXPRESSION evaluates to a string, it is converted to a symbol, as if 333using ‘string->symbol’. 334 335 • If the OWNER implements ‘gnu.mapping.HasNamedParts’, then the 336 result is that of invoking the ‘get’ method of the OWNER with the 337 PART name as a parameter. 338 339 As a special case of this rule, if OWNER is a 340 ‘gnu.mapping.Namespace’, then the result is the *note compound 341 symbol in that namespace: Namespaces. 342 • If OWNER is a ‘java.lang.Class’ or a ‘gnu.bytecode.ObjectType’, the 343 result is the static member named PART (i.e. a static field, 344 method, or member class). 345 • If OWNER is a ‘java.lang.Package’ object, we get the member class 346 or sub-package named PART. 347 • Otherwise, we look for a named member (instance member or field). 348 349 Note you can’t use colon notation to invoke instance methods of a 350 ‘Class’, because it will match a previous rule. For example if you 351 want to invoke the ‘getDeclaredMethod’ method of the 352 ‘java.util.List’ , you can’t write 353 ‘(java.util.List:getDeclaredMethod’ because that will look for a 354 static method in ‘java.util.List’. Instead, use the ‘invoke’ or 355 ‘invoke-sttic’ method. For example: ‘(invoke java.util.List 356 'getDeclaredMethod)’. 357 358 If the colon form is on the left-hand-side of an assignment (‘set!’), 359then the named part is modified as appropriate. 360 3617.7.2 Specific cases 362-------------------- 363 364Some of these are deprecated; more compact and readable forms are 365usually preferred. 366 3677.7.2.1 Invoking methods 368........................ 369 370 ‘(’INSTANCE‘:’METHOD-NAME ARG ...‘)’ 371 ‘(’CLASS‘:’METHOD-NAME INSTANCE ARG ...‘)’ 372 ‘(’CLASS‘:’METHOD-NAME ARG ...‘)’ 373 ‘(*:’METHOD-NAME INSTANCE ARG ...‘)’ 374 375 For details *note Method operations::. 376 3777.7.2.2 Accessing fields 378........................ 379 380 CLASS‘:’FIELD-NAME 381 INSTANCE‘:’FIELD-NAME 382 ‘(’PREFIX‘:.’FIELD-NAME INSTANCE‘)’ 383 384 For details *note Field operations::. 385 3867.7.2.3 Type literal 387.................... 388 389 ‘(’TYPE‘:<>)’ 390 Returns the TYPE. Deprecated; usually you can just write: 391 TYPE 392 3937.7.2.4 Type cast 394................. 395 396 ‘(’TYPE‘:’‘@’ EXPRESSION‘)’ 397 Performs a cast. Deprecated; usually you can just write: 398 ->TYPE 399 4007.7.2.5 Type test 401................. 402 403 ‘(’TYPE‘:instanceof?’ EXPRESSION‘)’ 404 405 Deprecated; usually you can just write: 406 (TYPE? EXPRESSION) 407 4087.7.2.6 New object construction 409............................... 410 411 ‘(’TYPE‘:new’ ARG ...‘)’ 412 413 Deprecated; usually you can just write: 414 ‘(’TYPE ARG ...‘)’ 415 4167.7.2.7 Getting array length 417............................ 418 419 EXPRESSION‘:length’ 420 ‘(’EXPRESSION‘:.length)’ 421 422 423File: kawa.info, Node: Bodies, Next: Syntax and conditional compilation, Prev: Colon notation, Up: Syntax 424 4257.8 Programs and Bodies 426======================= 427 428Program units 429------------- 430 431A PROGRAM-UNIT consists of a sequence of definitions and expressions. 432 433 PROGRAM-UNIT ::= LIBRARY-DEFINITION^{+} [STATEMENTS] 434 | STATEMENTS 435 STATEMENTS ::= STATEMENT^{+} 436 STATEMENT ::= DEFINITION | EXPRESSION | ‘(begin’ STATEMENT^{*} ‘)’ 437 438 Typically a PROGRAM-UNIT corresponds to a single source file (i.e.a 439named file in the file system). Evaluating a PROGRAM-UNIT first 440requires the Kawa processor to analyze the whole PROGRAM-UNIT to 441determine which names are defined by the definitions, and then evaluates 442each STATEMENT in order in the context of the defined names. The value 443of an EXPRESSION is normally discarded, but may be printed out instead, 444depending on the evaluating context. 445 446 The read-eval-print-loop (REPL) reads one or more lines until it gets 447a valid PROGRAM-UNIT, and evaluates it as above, except that the values 448of expressions are printed to the console (as if using the ‘display’ 449function). Then the REPL reads and evaluates another PROGRAM-UNIT, and 450so on. A definition in an earlier PROGRAM-UNIT is remembered and is 451visible in a later PROGRAM-UNIT unles it is overridden. 452 453 A comment in the first 2 lines of a source file may contain an 454encoding specification. This can be used to tell the reader what kind 455of character set encoding is used for the file. This only works for a 456character encoding that is compatible with ASCII (in the sense that if 457the high-order bit is clear then it’s an ASCII character), and that are 458no non-ASCI characters in the lines upto and including the encoding 459specification. A basic example is: 460 ;; -*- coding: utf-8 -*- 461 In general any string that matches the following regular expression 462works: 463 coding[:=]\s*([-a-zA-Z0-9]+) 464 465Libraries 466--------- 467 468A PROGRAM-UNIT may contain LIBRARY-DEFINITIONS. In addition, any 469STATEMENTS in PROGRAM-UNIT comprise an “implicit library”, in that it 470can be given a name, and referenced from other libraries. Certain names 471defined in the PROGRAM-UNIT can be exported, and then they can be 472imported by other libraries. For more information *note Module 473classes::. 474 475 It is recommended but not required that: 476 • There should be at most one LIBRARY-DEFINITION in a PROGRAM-UNIT. 477 • The LIBRARY-NAME of the LIBRARY-DEFINITION should match the name of 478 the source file. For example: 479 (define-library (foo bar) ...) 480 should be in a file named ‘foo/bar.scm’. 481 • If there is a LIBRARY-DEFINITION, there should be no extra 482 STATEMENTS - i.e no implicit library definition. (It is disallowed 483 to ‘export’ any definitions from the implicit library if there is 484 also a LIBRARY-DEFINITION.) 485 Following these recommendations makes it easier to locate and 486organize libraries. However, having multiple libraries in a single 487PROGRAM-UNIT is occasionally useful for source distribution and for 488testing. 489 490Bodies 491------ 492 493The BODY of a ‘lambda’, ‘let’, ‘let*’, ‘let-values’, ‘let*-values’, 494‘letrec’, or ‘letrec*’ expression, or that of a definition with a body 495consists of zero or more definitions or expressions followed by a final 496expression. (Standard Scheme requires that all definitions precede all 497expressions.) 498 499 BODY ::= STATEMENT^{*} 500 501 Each identifier defined by a definition is local to the BODY. That 502is, the identifier is bound, and the region of the binding is the entire 503BODY. Example: 504 505 (let ((x 5)) 506 (define foo (lambda (y) (bar x y))) 507 (define bar (lambda (a b) (+ (* a b) a))) 508 (foo (+ x 3))) 509 ⇒ 45 510 511 When ‘begin’, ‘let-syntax’, or ‘letrec-syntax’ forms occur in a body 512prior to the first expression, they are spliced into the body. Some or 513all of the body, including portions wrapped in ‘begin’, ‘let-syntax’, or 514‘letrec-syntax’ forms, may be specified by a macro use. 515 516 An expanded BODY containing variable definitions can be converted 517into an equivalent ‘letrec*’ expression. (If there is a definition 518following expressions you may need to convert the expressions to dummy 519definitions.) For example, the ‘let’ expression in the above example is 520equivalent to 521 522 (let ((x 5)) 523 (letrec* ((foo (lambda (y) (bar x y))) 524 (bar (lambda (a b) (+ (* a b) a)))) 525 (foo (+ x 3)))) 526 527 528File: kawa.info, Node: Syntax and conditional compilation, Next: Macros, Prev: Bodies, Up: Syntax 529 5307.9 Syntax and conditional compilation 531====================================== 532 533Feature testing 534--------------- 535 536 -- Syntax: cond-expand COND-EXPAND-CLAUSE^{*} [‘(else’ 537 command-or-definition*‘)’] 538 COND-EXPAND-CLAUSE ::= ‘(’FEATURE-REQUIREMENT COMMAND-OR-DEFINITION*‘)’ 539 FEATURE-REQUIREMENT ::= FEATURE-IDENTIFIER 540 | ‘(and’ FEATURE-REQUIREMENT^{*}‘)’ 541 | ‘(or’ FEATURE-REQUIREMENT^{*}‘)’ 542 | ‘(not’ FEATURE-REQUIREMENT‘)’ 543 | ‘(library’ LIBRARY-NAME‘)’ 544 FEATURE-IDENTIFIER ::= a symbol which is the name or alias of a SRFI 545 546 The ‘cond-expand’ form tests for the existence of features at 547 macro-expansion time. It either expands into the body of one of 548 its clauses or signals an error during syntactic processing. 549 ‘cond-expand’ expands into the body of the first clause whose 550 feature requirement is currently satisfied; the ‘else’ clause, if 551 present, is selected if none of the previous clauses is selected. 552 553 The implementation has a set of feature identifiers which are 554 “present”, as well as a set of libraries which can be imported. 555 The value of a FEATURE-REQUIREMENT is determined by replacing each 556 FEATURE-IDENTIFIER by ‘#t’ if it is present (and ‘#f’ otherwise); 557 replacing ‘(library LIBRARY-NAME)’ by ‘#t’ if LIBRARY-NAME is 558 importable (and ‘#f’ otherwise); and then evaluating the resulting 559 expression as a Scheme boolean expression under the normal 560 interpretation of ‘and’, ‘or’, and ‘not’. 561 562 Examples: 563 (cond-expand 564 ((and srfi-1 srfi-10) 565 (write 1)) 566 ((or srfi-1 srfi-10) 567 (write 2)) 568 (else)) 569 570 (cond-expand 571 (command-line 572 (define (program-name) (car (argv))))) 573 574 The second example assumes that ‘command-line’ is an alias for some 575 feature which gives access to command line arguments. Note that an 576 error will be signaled at macro-expansion time if this feature is 577 not present. 578 579 You can use ‘java-6’, ‘java-7’, ‘java-8’, or ‘java-9’ to check if 580 the underlying Java is a specific version or newer. For example 581 the name ‘java-7’ matches for either Java 7, Java 8, or newer, as 582 reported by ‘System’ property ‘"java.version"’. 583 584 You can use ‘class-exists:CLASSNAME’ to check if ‘CLASSNAME’ exists 585 at compile-time. The identifier ‘class-exists:org.example.MyClass’ 586 is roughly equivalent to the test ‘(library (org example 587 MyClass))’. (The latter has some special handling for ‘(srfi ...)’ 588 as well as builtin Kawa classes.) 589 590 The feature ‘in-http-server’ is defined in a *note self-configuring 591 web page scripts: Self-configuring page scripts, and more 592 specifically ‘in-servlet’ in a *note servlet container: Servlets. 593 594 -- Procedure: features 595 Returns a list of feature identifiers which ‘cond-expand’ treats as 596 true. This not a complete list - for example 597 ‘class-exists:CLASSNAME’ feature identifiers are not included. It 598 is an error to modify this list. Here is an example of what 599 ‘features’ might return: 600 (features) ⇒ 601 (complex exact-complex full-unicode java-7 java-6 kawa 602 ratios srfi-0 srfi-4 srfi-6 srfi-8 srfi-9 srfi-11 603 srfi-16 srfi-17 srfi-23 srfi-25 srfi-26 srfi-28 srfi-30 604 srfi-39 string-normalize-unicode threads) 605 606File inclusion 607-------------- 608 609 -- Syntax: include path^{+} 610 -- Syntax: include-relative path^{+} 611 -- Syntax: include-ci path^{+} 612 These take one or more path names expressed as string literals, 613 find corresponding files, read the contents of the files in the 614 specified order as if by repeated applications of ‘read’, and 615 effectively replace the ‘include’ with a ‘begin’ form containing 616 what was read from the files. 617 618 You can control the search path used for ‘include’ by setting the 619 ‘kawa.include.path’ property. For example: 620 $ kawa -Dkawa.include.path="|:/opt/kawa-includes" 621 The special ‘"|"’ path element means to search relative to the 622 directory containing the including source file. The default search 623 path is ‘"|:."’ which means to first search the directory 624 containing the including source file, and then search the directory 625 specified by ‘(current-path)’. 626 627 The search path for ‘include-relative’ prepends ‘"|"’ before the 628 search path used by ‘include’, so it always searches first the 629 directory containing the including source file. Note that if the 630 default search path is used then ‘include’ and ‘include-relative’ 631 are equivalent; there is only a difference if the 632 ‘kawa.include.path’ property changes the default. 633 634 Using ‘include-ci’ is like ‘include’, except that it reads each 635 file as if it began with the ‘#!fold-case’ directive. 636 637 638File: kawa.info, Node: Macros, Next: Named quasi-literals, Prev: Syntax and conditional compilation, Up: Syntax 639 6407.10 Macros 641=========== 642 643Libraries and top–level programs can define and use new kinds of derived 644expressions and definitions called _syntactic abstractions_ or _macros_. 645A syntactic abstraction is created by binding a keyword to a _macro 646transformer_ or, simply, _transformer_. 647 648 The transformer determines how a use of the macro (called a _macro 649use_) is transcribed into a more primitive form. 650 651 Most macro uses have the form: 652 653 (KEYWORD DATUM ...) 654where KEYWORD is an identifier that uniquely determines the kind of 655form. This identifier is called the _syntactic keyword_, or simply 656_keyword_. The number of DATUMs and the syntax of each depends on the 657syntactic abstraction. 658 659 Macro uses can also take the form of improper lists, singleton 660identifiers, or ‘set!’ forms, where the second subform of the ‘set!’ is 661the keyword: 662 663 (KEYWORD DATUM ... . DATUM) 664 KEYWORD 665 (set! KEYWORD DATUM) 666 667 The ‘define-syntax’, ‘let-syntax’ and ‘letrec-syntax’ forms create 668bindings for keywords, associate them with macro transformers, and 669control the scope within which they are visible. 670 671 The ‘syntax-rules’ and ‘identifier-syntax’ forms create transformers 672via a pattern language. Moreover, the ‘syntax-case’ form allows 673creating transformers via arbitrary Scheme code. 674 675 Keywords occupy the same name space as variables. That is, within 676the same scope, an identifier can be bound as a variable or keyword, or 677neither, but not both, and local bindings of either kind may shadow 678other bindings of either kind. 679 680 Macros defined using ‘syntax-rules’ and ‘identifier-syntax’ are 681“hygienic” and “referentially transparent” and thus preserve Scheme’s 682lexical scoping. 683 684 • If a macro transformer inserts a binding for an identifier 685 (variable or keyword) not appearing in the macro use, the 686 identifier is in effect renamed throughout its scope to avoid 687 conflicts with other identifiers. 688 689 • If a macro transformer inserts a free reference to an identifier, 690 the reference refers to the binding that was visible where the 691 transformer was specified, regardless of any local bindings that 692 may surround the use of the macro. 693 694 Macros defined using the ‘syntax-case’ facility are also hygienic 695unless ‘datum->syntax’ is used. 696 697 Kawa supports most of the ‘syntax-case’ feature. 698 699 Syntax definitions are valid wherever definitions are. They have the 700following form: 701 702 -- Syntax: define-syntax keyword TRANSFORMER-SPEC 703 The KEYWORD is a identifier, and TRANSFORMER-SPEC is a function 704 that maps syntax forms to syntax forms, usually an instance of 705 ‘syntax-rules’. If the ‘define-syntax’ occurs at the top level, 706 then the top-level syntactic environment is extended by binding the 707 KEYWORD to the specified transformer, but existing references to 708 any top-level binding for KEYWORD remain unchanged. Otherwise, it 709 is an “internal syntax definition”, and is local to the BODY in 710 which it is defined. 711 712 (let ((x 1) (y 2)) 713 (define-syntax swap! 714 (syntax-rules () 715 ((swap! a b) 716 (let ((tmp a)) 717 (set! a b) 718 (set! b tmp))))) 719 (swap! x y) 720 (list x y)) ⇒ (2 1) 721 722 Macros can expand into definitions in any context that permits 723 them. However, it is an error for a definition to define an 724 identifier whose binding has to be known in order to determine the 725 meaning of the definition itself, or of any preceding definition 726 that belongs to the same group of internal definitions. 727 728 -- Syntax: define-syntax-case name ‘(’literals‘)’ ‘(’pattern expr‘)’ 729 ... 730 A convenience macro to make it easy to define ‘syntax-case’-style 731 macros. Defines a macro with the given NAME and list of LITERALS. 732 Each PATTERN has the form of a ‘syntax-rules’-style pattern, and it 733 is matched against the macro invocation syntax form. When a match 734 is found, the corresponding EXPR is evaluated. It must evaluate to 735 a syntax form, which replaces the macro invocation. 736 (define-syntax-case macro-name (literals) 737 (pat1 result1) 738 (pat2 result2)) 739 is equivalent to: 740 (define-syntax macro-name 741 (lambda (form) 742 (syntax-case form (literals) 743 (pat1 result1) 744 (pat2 result2)))) 745 746 -- Syntax: define-macro ‘(’name lambda-list‘)’ form ... 747 _This form is deprecated._ Functionally equivalent to ‘defmacro’. 748 749 -- Syntax: defmacro name lambda-list form ... 750 _This form is deprecated._ Instead of 751 (defmacro (NAME ...) 752 (let ... `(... ,EXP ...))) 753 you should probably do: 754 (define-syntax-case NAME () 755 ((_ ...) (let #`(... #,EXP ...)))) 756 and instead of 757 (defmacro (NAME ... VAR ...) `(... VAR ...)) 758 you should probably do: 759 (define-syntax-case NAME () 760 ((_ ... VAR ...) #`(... VAR ...)) 761 762 Defines an old-style macro a la Common Lisp, and installs ‘(lambda 763 LAMBDA-LIST FORM ...)’ as the expansion function for NAME. When 764 the translator sees an application of NAME, the expansion function 765 is called with the rest of the application as the actual arguments. 766 The resulting object must be a Scheme source form that is futher 767 processed (it may be repeatedly macro-expanded). 768 769 -- Procedure: gentemp 770 Returns a new (interned) symbol each time it is called. The symbol 771 names are implementation-dependent. (This is not directly 772 macro-related, but is often used in conjunction with ‘defmacro’ to 773 get a fresh unique identifier.) 774 775 -- Procedure: expand form 776 The result of evaluating FORM is treated as a Scheme expression, 777 syntax-expanded to internal form, and then converted back to 778 (roughly) the equivalent expanded Scheme form. 779 780 This can be useful for debugging macros. 781 782 To access this function, you must first ‘(require 'syntax-utils)’. 783 (require 'syntax-utils) 784 (expand '(cond ((> x y) 0) (else 1))) ⇒ (if (> x y) 0 1) 785 7867.10.1 Pattern language 787----------------------- 788 789A TRANSFORMER-SPEC is an expression that evaluates to a transformer 790procedure, which takes an input form and returns a resulting form. You 791can do general macro-time compilation with such a procedure, commonly 792using ‘syntax-case’ (which is documented in the R6RS library 793specification). However, when possible it is better to use the simpler 794pattern language of ‘syntax-rules’: 795 796 TRANSFORMER-SPEC ::= 797 ‘(syntax-rules (’ TR-LITERAL^{*} ‘)’ SYNTAX-RULE^{*}‘)’ 798 | ‘(syntax-rules’ ELLIPSIS ‘(’ TR-LITERAL^{*} ‘)’ SYNTAX-RULE^{*}‘)’ 799 | EXPRESSION 800 SYNTAX-RULE ::= ‘(’LIST-PATTERN SYNTAX-TEMPLATE‘)’ 801 TR-LITERAL ::= IDENTIFIER 802 ELLIPSIS ::= IDENTIFIER 803 804 An instance of ‘syntax-rules’ produces a new macro transformer by 805specifying a sequence of hygienic rewrite rules. A use of a macro whose 806keyword is associated with a transformer specified by ‘syntax-rules’ is 807matched against the patterns contained in the SYNTAX-RULEs beginning 808with the leftmost syntax rule . When a match is found, the macro use is 809transcribed hygienically according to the template. The optional 810ELLIPSIS species a symbol used to indicate repetition; it defaults to 811‘...’ (3 periods). 812 813 SYNTAX-PATTERN ::= 814 IDENTIFIER | CONSTANT | LIST-PATTERN | VECTOR-PATTERN 815 LIST-PATTERN ::= ‘(’ SYNTAX-PATTERN^{*} ‘)’ 816 | ‘(’ SYNTAX-PATTERN SYNTAX-PATTERN^{*} ‘.’ SYNTAX-PATTERN ‘)’ 817 | ‘(’ SYNTAX-PATTERN^{*} SYNTAX-PATTERN ELLIPSIS SYNTAX-PATTERN^{*} ‘)’ 818 | ‘(’ SYNTAX-PATTERN^{*} SYNTAX-PATTERN ELLIPSIS SYNTAX-PATTERN^{*} ‘.’ SYNTAX-PATTERN‘)’ 819 VECTOR-PATTERN ::= ‘#(’ SYNTAX-PATTERN^{*} ‘)’ 820 | ‘#(’ SYNTAX-PATTERN^{*} SYNTAX-PATTERN ELLIPSIS SYNTAX-PATTERN^{*} ‘)’ 821 822 An identifier appearing within a pattern can be an underscore (‘_’), 823a literal identifier listed in the list of TR-LITERALs, or the ELLIPSIS. 824All other identifiers appearing within a pattern are pattern variables. 825 826 The outer SYNTAX-LIST of the pattern in a SYNTAX-RULE must start with 827an identifier. It is not involved in the matching and is considered 828neither a pattern variable nor a literal identifier. 829 830 Pattern variables match arbitrary input elements and are used to 831refer to elements of the input in the template. It is an error for the 832same pattern variable to appear more than once in a SYNTAX-PATTERN. 833 834 Underscores also match arbitrary input elements but are not pattern 835variables and so cannot be used to refer to those elements. If an 836underscore appears in the literals list, then that takes precedence and 837underscores in the pattern match as literals. Multiple underscores can 838appear in a SYNTAX-PATTERN. 839 840 Identifiers that appear in ‘(TR-LITERAL^{*})’ are interpreted as 841literal identifiers to be matched against corresponding elements of the 842input. An element in the input matches a literal identifier if and only 843if it is an identifier and either both its occurrence in the macro 844expression and its occurrence in the macro definition have the same 845lexical binding, or the two identifiers are the same and both have no 846lexical binding. 847 848 A subpattern followed by ellipsis can match zero or more elements of 849the input, unless ellipsis appears in the literals, in which case it is 850matched as a literal. 851 852 More formally, an input expression E matches a pattern P if and only 853if: 854 • P is an underscore (‘_’); or 855 • P is a non-literal identifier; or 856 • P is a literal identifier and E is an identifier with the same 857 binding; or 858 • P is a list ‘(’P_{1} ... P_{N}‘)’ and E is a list of N elements 859 that match P_{1} through P_{N}, respectively; or 860 • P is an improper list ‘(’P_{1} ... P_{N} ‘.’ P_{N+1}‘)’ and E is 861 a list or improper list of N or more elements that match P_{1} 862 through P_{N}, respectively, and whose Nth tail matches P_{N+1}; or 863 • P is of the form ‘(’P_{1} ... P_{K} P_{E} ELLIPSIS P_{K+1} ... 864 P_{K+L}‘)’ where E is a proper list of N elements, the first K of 865 which match P_{1} through P_{K}, respectively, whose next N-K-L 866 elements each match P_{E}, and whose remaining L elements match 867 P_{K+1} through P_{K+L}; or 868 • P is of the form ‘(’P_{1} ... P_{K} P_{E} ELLIPSIS P_{K+1} ... 869 P_{K+L} ‘.’ P_{X}‘)’ where E is a list or improper list of N 870 elements, the first K of which match P_{1} through P_{K}, whose 871 next N-K-L elements each match P_{E}, and whose remaining L 872 elements match P_{K+1} through P_{K+L}, and whose Nth and final 873 ‘cdr’ matches P_{X}; or 874 • P is a vector of the form ‘#(’P_{1} ... P_{N}‘)’ and E is a vector 875 of N elements that match P_{1} through P_{N}; or 876 • P is of the form ‘#(’P_{1} ... P_{K} P_{E} ELLIPSIS P_{K+1} ... 877 P_{K+L}‘)’ where E is a vector of N elements the first K of which 878 match P_{1} through P_{K}, whose next N-K-L elements each match 879 P_{E}, and whose remaining L elements match P_{K+1} through 880 P_{K+L}; or 881 • P is a constant and E is equal to P in the sense of the ‘equal?’ 882 procedure. 883 884 It is an error to use a macro keyword, within the scope of its 885binding, in an expression that does not match any of the patterns. 886 SYNTAX-TEMPLATE ::= IDENTIFIER | CONSTANT 887 | ‘(’TEMPLATE-ELEMENT^{*}‘)’ 888 | ‘(’TEMPLATE-ELEMENT TEMPLATE-ELEMENT^{*} ‘.’ SYNTAX-TEMPLATE ‘)’ 889 | ‘(’ ELLIPSIS SYNTAX-TEMPLATE‘)’ 890 TEMPLATE-ELEMENT ::= SYNTAX-TEMPLATE [ELLIPSIS] 891 892 When a macro use is transcribed according to the template of the 893matching SYNTAX-RULE, pattern variables that occur in the template are 894replaced by the elements they match in the input. Pattern variables 895that occur in subpatterns followed by one or more instances of the 896identifier ELLIPSIS are allowed only in subtemplates that are followed 897by as many instances of ELLIPSIS . They are replaced in the output by 898all of the elements they match in the input, distributed as indicated. 899It is an error if the output cannot be built up as specified. 900 901 Identifiers that appear in the template but are not pattern variables 902or the identifier ELLIPSIS are inserted into the output as literal 903identifiers. If a literal identifier is inserted as a free identifier 904then it refers to the binding of that identifier within whose scope the 905instance of ‘syntax-rules’ appears. If a literal identifier is inserted 906as a bound identifier then it is in effect renamed to prevent 907inadvertent captures of free identifiers. 908 909 A template of the form ‘(’ELLIPSIS TEMPLATE‘)’ is identical to 910TEMPLATE, except that ELLIPSES within the template have no special 911meaning. That is, any ELLIPSES contained within TEMPLATE are treated as 912ordinary identifiers. In particular, the template ‘(’ELLIPSIS 913ELLIPSIS‘)’ produces a single ELLIPSIS. This allows syntactic 914abstractions to expand into code containing ellipses. 915 916 (define-syntax be-like-begin 917 (syntax-rules () 918 ((be-like-begin name) 919 (define-syntax name 920 (syntax-rules () 921 ((name expr (... ...)) 922 (begin expr (... ...)))))))) 923 924 (be-like-begin sequence) 925 (sequence 1 2 3 4) ⇒ 4 926 9277.10.2 Identifier predicates 928---------------------------- 929 930 -- Procedure: identifier? OBJ 931 Return ‘#t’ if OBJ is an identifier, i.e., a syntax object 932 representing an identifier, and ‘#f’ otherwise. 933 934 The ‘identifier?’ procedure is often used within a fender to verify 935 that certain subforms of an input form are identifiers, as in the 936 definition of ‘rec’, which creates self–contained recursive 937 objects, below. 938 939 (define-syntax rec 940 (lambda (x) 941 (syntax-case x () 942 ((_ x e) 943 (identifier? #'x) 944 #'(letrec ((x e)) x))))) 945 946 (map (rec fact 947 (lambda (n) 948 (if (= n 0) 949 1 950 (* n (fact (- n 1)))))) 951 '(1 2 3 4 5)) ⇒ (1 2 6 24 120) 952 953 (rec 5 (lambda (x) x)) ⇒ exception 954 955 The procedures ‘bound-identifier=?’ and ‘free-identifier=?’ each take 956two identifier arguments and return ‘#t’ if their arguments are 957equivalent and ‘#f’ otherwise. These predicates are used to compare 958identifiers according to their _intended use_ as free references or 959bound identifiers in a given context. 960 961 -- Procedure: bound-identifier=? ID1 ID2 962 ID1 and ID2 must be identifiers. 963 964 The procedure ‘bound-identifier=?’ returns ‘#t’ if a binding for 965 one would capture a reference to the other in the output of the 966 transformer, assuming that the reference appears within the scope 967 of the binding, and ‘#f’ otherwise. 968 969 In general, two identifiers are ‘bound-identifier=?’ only if both 970 are present in the original program or both are introduced by the 971 same transformer application (perhaps implicitly, see 972 ‘datum->syntax’). 973 974 The ‘bound-identifier=?’ procedure can be used for detecting 975 duplicate identifiers in a binding construct or for other 976 preprocessing of a binding construct that requires detecting 977 instances of the bound identifiers. 978 979 -- Procedure: free-identifier=? ID1 ID2 980 ID1 and ID2 must be identifiers. 981 982 The ‘free-identifier=?’ procedure returns ‘#t’ if and only if the 983 two identifiers would resolve to the same binding if both were to 984 appear in the output of a transformer outside of any bindings 985 inserted by the transformer. (If neither of two like–named 986 identifiers resolves to a binding, i.e., both are unbound, they are 987 considered to resolve to the same binding.) 988 989 Operationally, two identifiers are considered equivalent by 990 ‘free-identifier=?’ if and only the topmost matching substitution 991 for each maps to the same binding or the identifiers have the same 992 name and no matching substitution. 993 994 The ‘syntax-case’ and ‘syntax-rules’ forms internally use 995 ‘free-identifier=?’ to compare identifiers listed in the literals 996 list against input identifiers. 997 998 (let ((fred 17)) 999 (define-syntax a 1000 (lambda (x) 1001 (syntax-case x () 1002 ((_ id) #'(b id fred))))) 1003 (define-syntax b 1004 (lambda (x) 1005 (syntax-case x () 1006 ((_ id1 id2) 1007 #`(list 1008 #,(free-identifier=? #'id1 #'id2) 1009 #,(bound-identifier=? #'id1 #'id2)))))) 1010 (a fred)) 1011 ⇒ (#t #f) 1012 1013 The following definition of unnamed ‘let’ uses ‘bound-identifier=?’ 1014 to detect duplicate identifiers. 1015 1016 (define-syntax let 1017 (lambda (x) 1018 (define unique-ids? 1019 (lambda (ls) 1020 (or (null? ls) 1021 (and (let notmem? ((x (car ls)) (ls (cdr ls))) 1022 (or (null? ls) 1023 (and (not (bound-identifier=? x (car ls))) 1024 (notmem? x (cdr ls))))) 1025 (unique-ids? (cdr ls)))))) 1026 (syntax-case x () 1027 ((_ ((i v) ...) e1 e2 ...) 1028 (unique-ids? #'(i ...)) 1029 #'((lambda (i ...) e1 e2 ...) v ...))))) 1030 1031 The argument ‘#'(i ...)’ to ‘unique-ids?’ is guaranteed to be a 1032 list by the rules given in the description of ‘syntax’ above. 1033 1034 With this definition of ‘let’: 1035 1036 (let ((a 3) (a 4)) (+ a a)) ⇒ syntax error 1037 1038 However, 1039 (let-syntax 1040 ((dolet (lambda (x) 1041 (syntax-case x () 1042 ((_ b) 1043 #'(let ((a 3) (b 4)) (+ a b))))))) 1044 (dolet a)) 1045 ⇒ 7 1046 1047 since the identifier ‘a’ introduced by ‘dolet’ and the identifier 1048 ‘a’ extracted from the input form are not ‘bound-identifier=?’. 1049 1050 Rather than including ‘else’ in the literals list as before, this 1051 version of ‘case’ explicitly tests for ‘else’ using 1052 ‘free-identifier=?’. 1053 1054 (define-syntax case 1055 (lambda (x) 1056 (syntax-case x () 1057 ((_ e0 ((k ...) e1 e2 ...) ... 1058 (else-key else-e1 else-e2 ...)) 1059 (and (identifier? #'else-key) 1060 (free-identifier=? #'else-key #'else)) 1061 #'(let ((t e0)) 1062 (cond 1063 ((memv t '(k ...)) e1 e2 ...) 1064 ... 1065 (else else-e1 else-e2 ...)))) 1066 ((_ e0 ((ka ...) e1a e2a ...) 1067 ((kb ...) e1b e2b ...) ...) 1068 #'(let ((t e0)) 1069 (cond 1070 ((memv t '(ka ...)) e1a e2a ...) 1071 ((memv t '(kb ...)) e1b e2b ...) 1072 ...)))))) 1073 1074 With either definition of ‘case’, ‘else’ is not recognized as an 1075 auxiliary keyword if an enclosing lexical binding for ‘else’ 1076 exists. For example, 1077 1078 (let ((else #f)) 1079 (case 0 (else (write "oops")))) ⇒ syntax error 1080 1081 since ‘else’ is bound lexically and is therefore not the same 1082 ‘else’ that appears in the definition of ‘case’. 1083 10847.10.3 Syntax-object and datum conversions 1085------------------------------------------ 1086 1087 -- Procedure: syntax->datum SYNTAX-OBJECT 1088 -- Deprecated procedure: syntax-object->datum SYNTAX-OBJECT 1089 Strip all syntactic information from a syntax object and returns 1090 the corresponding Scheme datum. 1091 1092 Identifiers stripped in this manner are converted to their symbolic 1093 names, which can then be compared with ‘eq?’. Thus, a predicate 1094 ‘symbolic-identifier=?’ might be defined as follows. 1095 1096 (define symbolic-identifier=? 1097 (lambda (x y) 1098 (eq? (syntax->datum x) 1099 (syntax->datum y)))) 1100 1101 -- Procedure: datum->syntax TEMPLATE-ID DATUM [SRCLOC] 1102 -- Deprecated procedure: datum->syntax-object TEMPLATE-ID DATUM 1103 TEMPLATE-ID must be a template identifier and DATUM should be a 1104 datum value. 1105 1106 The ‘datum->syntax’ procedure returns a syntax-object 1107 representation of DATUM that contains the same contextual 1108 information as TEMPLATE-ID, with the effect that the syntax object 1109 behaves as if it were introduced into the code when TEMPLATE-ID was 1110 introduced. 1111 1112 If SRCLOC is specified (and neither ‘#f’ or ‘#!null’), it specifies 1113 the file position (including line number) for the result. In that 1114 case it should be a syntax object representing a list; otherwise it 1115 is currently ignored, though future extensions may support other 1116 ways of specifying the position. 1117 1118 The ‘datum->syntax’ procedure allows a transformer to “bend” 1119 lexical scoping rules by creating _implicit identifiers_ that 1120 behave as if they were present in the input form, thus permitting 1121 the definition of macros that introduce visible bindings for or 1122 references to identifiers that do not appear explicitly in the 1123 input form. For example, the following defines a ‘loop’ expression 1124 that uses this controlled form of identifier capture to bind the 1125 variable ‘break’ to an escape procedure within the loop body. (The 1126 derived ‘with-syntax’ form is like ‘let’ but binds pattern 1127 variables.) 1128 1129 (define-syntax loop 1130 (lambda (x) 1131 (syntax-case x () 1132 ((k e ...) 1133 (with-syntax 1134 ((break (datum->syntax #'k 'break))) 1135 #'(call-with-current-continuation 1136 (lambda (break) 1137 (let f () e ... (f))))))))) 1138 1139 (let ((n 3) (ls '())) 1140 (loop 1141 (if (= n 0) (break ls)) 1142 (set! ls (cons 'a ls)) 1143 (set! n (- n 1)))) 1144 ⇒ (a a a) 1145 1146 Were ‘loop’ to be defined as: 1147 1148 (define-syntax loop 1149 (lambda (x) 1150 (syntax-case x () 1151 ((_ e ...) 1152 #'(call-with-current-continuation 1153 (lambda (break) 1154 (let f () e ... (f)))))))) 1155 1156 the variable ‘break’ would not be visible in ‘e ...’. 1157 1158 The datum argument DATUM may also represent an arbitrary Scheme 1159 form, as demonstrated by the following definition of ‘include’. 1160 1161 (define-syntax include 1162 (lambda (x) 1163 (define read-file 1164 (lambda (fn k) 1165 (let ((p (open-file-input-port fn))) 1166 (let f ((x (get-datum p))) 1167 (if (eof-object? x) 1168 (begin (close-port p) '()) 1169 (cons (datum->syntax k x) 1170 (f (get-datum p)))))))) 1171 (syntax-case x () 1172 ((k filename) 1173 (let ((fn (syntax->datum #'filename))) 1174 (with-syntax (((exp ...) 1175 (read-file fn #'k))) 1176 #'(begin exp ...))))))) 1177 1178 ‘(include "filename")’ expands into a ‘begin’ expression containing 1179 the forms found in the file named by ‘"filename"’. For example, if 1180 the file ‘flib.ss’ contains: 1181 1182 (define f (lambda (x) (g (* x x)))) 1183 1184 and the file ‘glib.ss’ contains: 1185 1186 (define g (lambda (x) (+ x x))) 1187 1188 the expression: 1189 1190 (let () 1191 (include "flib.ss") 1192 (include "glib.ss") 1193 (f 5)) 1194 1195 evaluates to ‘50’. 1196 1197 The definition of ‘include’ uses ‘datum->syntax’ to convert the 1198 objects read from the file into syntax objects in the proper 1199 lexical context, so that identifier references and definitions 1200 within those expressions are scoped where the ‘include’ form 1201 appears. 1202 1203 Using ‘datum->syntax’, it is even possible to break hygiene 1204 entirely and write macros in the style of old Lisp macros. The 1205 ‘lisp-transformer’ procedure defined below creates a transformer 1206 that converts its input into a datum, calls the programmer’s 1207 procedure on this datum, and converts the result back into a syntax 1208 object scoped where the original macro use appeared. 1209 1210 (define lisp-transformer 1211 (lambda (p) 1212 (lambda (x) 1213 (syntax-case x () 1214 ((kwd . rest) 1215 (datum->syntax #'kwd 1216 (p (syntax->datum x)))))))) 1217 12187.10.4 Signaling errors in macro transformers 1219--------------------------------------------- 1220 1221 -- Syntax: syntax-error message args^{*} 1222 The MESSAGE and ARGS are treated similary as for the ‘error’ 1223 procedure. However, the error is reported when the ‘syntax-error’ 1224 is expanded. This can be used as a ‘syntax-rules’ template for a 1225 pattern that is an invalid use of the macro, which can provide more 1226 descriptive error messages. The MESSAGE should be a string 1227 literal, and the ARGS arbitrary (non-evalualted) expressions 1228 providing additional information. 1229 1230 (define-syntax simple-let 1231 (syntax-rules () 1232 ((_ (head ... ((x . y) val) . tail) 1233 body1 body2 ...) 1234 (syntax-error "expected an identifier but got" (x . y))) 1235 ((_ ((name val) ...) body1 body2 ...) 1236 ((lambda (name ...) body1 body2 ...) 1237 val ...)))) 1238 1239 -- Procedure: report-syntax-error location message 1240 This is a procedure that can be called at macro-expansion time by a 1241 syntax transformer function. (In contrast ‘syntax-error’ is a 1242 syntax form used in the expansion result.) The MESSAGE is reported 1243 as a compile-time error message. The LOCATION is used for the 1244 source location (file name and line/column numbers): In general it 1245 can be a ‘SourceLocator’ value; most commonly it is a syntax object 1246 for a sub-list of the input form that is erroneous. The value 1247 returned by ‘report-syntax-error’ is an instance of ‘ErrorExp’, 1248 which supresses further compilation. 1249 1250 (define-syntax if 1251 (lambda (x) 1252 (syntax-case x () 1253 ((_ test then) 1254 (make-if-exp #'test #'then #!null)) 1255 ((_ test then else) 1256 (make-if-exp #'test #'then #'else)) 1257 ((_ e1 e2 e3 . rest) 1258 (report-syntax-error #'rest 1259 "too many expressions for 'if'")) 1260 ((_ . rest) 1261 (report-syntax-error #'rest 1262 "too few expressions for 'if'"))))) 1263 In the above example, one could use the source form ‘x’ for the 1264 location, but using ‘#'rest’ is more accurate. Note that the 1265 following is incorrect, because ‘e1’ might not be a pair, in which 1266 case we don’t have location information for it (due to a Kawa 1267 limitation): 1268 (syntax-case x () 1269 ... 1270 ((_ e1) 1271 (report-syntax-error 1272 #'e1 ;; poor location specifier 1273 "too few expressions for 'if'"))))) 1274 12757.10.5 Convenience forms 1276------------------------ 1277 1278 -- Syntax: with-syntax ((PATTERN EXPRESSION) ...) BODY 1279 The ‘with-syntax’ form is used to bind pattern variables, just as 1280 ‘let’ is used to bind variables. This allows a transformer to 1281 construct its output in separate pieces, then put the pieces 1282 together. 1283 1284 Each PATTERN is identical in form to a ‘syntax-case’ pattern. The 1285 value of each EXPRESSION is computed and destructured according to 1286 the corresponding PATTERN, and pattern variables within the PATTERN 1287 are bound as with ‘syntax-case’ to the corresponding portions of 1288 the value within BODY. 1289 1290 The ‘with-syntax’ form may be defined in terms of ‘syntax-case’ as 1291 follows. 1292 1293 (define-syntax with-syntax 1294 (lambda (x) 1295 (syntax-case x () 1296 ((_ ((p e0) ...) e1 e2 ...) 1297 (syntax (syntax-case (list e0 ...) () 1298 ((p ...) (let () e1 e2 ...)))))))) 1299 1300 The following definition of ‘cond’ demonstrates the use of 1301 ‘with-syntax’ to support transformers that employ recursion 1302 internally to construct their output. It handles all ‘cond’ clause 1303 variations and takes care to produce one-armed ‘if’ expressions 1304 where appropriate. 1305 1306 (define-syntax cond 1307 (lambda (x) 1308 (syntax-case x () 1309 ((_ c1 c2 ...) 1310 (let f ((c1 #'c1) (c2* #'(c2 ...))) 1311 (syntax-case c2* () 1312 (() 1313 (syntax-case c1 (else =>) 1314 (((else e1 e2 ...) #'(begin e1 e2 ...)) 1315 ((e0) #'e0) 1316 ((e0 => e1) 1317 #'(let ((t e0)) (if t (e1 t)))) 1318 ((e0 e1 e2 ...) 1319 #'(if e0 (begin e1 e2 ...))))) 1320 ((c2 c3 ...) 1321 (with-syntax ((rest (f #'c2 #'(c3 ...)))) 1322 (syntax-case c1 (=>) 1323 ((e0) #'(let ((t e0)) (if t t rest))) 1324 ((e0 => e1) 1325 #'(let ((t e0)) (if t (e1 t) rest))) 1326 ((e0 e1 e2 ...) 1327 #'(if e0 1328 (begin e1 e2 ...) 1329 rest))))))))))) 1330 1331 -- Syntax: quasisyntax TEMPLATE 1332 -- Auxiliary Syntax: unsyntax 1333 -- Auxiliary Syntax: unsyntax-splicing 1334 The ‘quasisyntax’ form is similar to ‘syntax’, but it allows parts 1335 of the quoted text to be evaluated, in a manner similar to the 1336 operation of ‘quasiquote’. 1337 1338 Within a ‘quasisyntax’ TEMPLATE, subforms of ‘unsyntax’ and 1339 ‘unsyntax-splicing’ forms are evaluated, and everything else is 1340 treated as ordinary template material, as with ‘syntax’. 1341 1342 The value of each ‘unsyntax’ subform is inserted into the output in 1343 place of the ‘unsyntax’ form, while the value of each 1344 ‘unsyntax-splicing’ subform is spliced into the surrounding list or 1345 vector structure. Uses of ‘unsyntax’ and ‘unsyntax-splicing’ are 1346 valid only within ‘quasisyntax’ expressions. 1347 1348 A ‘quasisyntax’ expression may be nested, with each ‘quasisyntax’ 1349 introducing a new level of syntax quotation and each ‘unsyntax’ or 1350 ‘unsyntax-splicing’ taking away a level of quotation. An 1351 expression nested within _n_ ‘quasisyntax’ expressions must be 1352 within _n_ _unsyntax_ or ‘unsyntax-splicing’ expressions to be 1353 evaluated. 1354 1355 As noted in ABBREVIATION, ‘#`TEMPLATE’ is equivalent to 1356 ‘(quasisyntax TEMPLATE)’, ‘#,TEMPLATE’ is equivalent to ‘(unsyntax 1357 TEMPLATE)’, and ‘#,@TEMPLATE’ is equivalent to ‘(unsyntax-splicing 1358 TEMPLATE)’. _Note_ that for backwards compatibility, you should 1359 only use ‘#,TEMPLATE’ inside a literal ‘#`TEMPLATE’ form. 1360 1361 The ‘quasisyntax’ keyword can be used in place of ‘with-syntax’ in 1362 many cases. For example, the definition of ‘case’ shown under the 1363 description of ‘with-syntax’ above can be rewritten using 1364 ‘quasisyntax’ as follows. 1365 1366 (define-syntax case 1367 (lambda (x) 1368 (syntax-case x () 1369 ((_ e c1 c2 ...) 1370 #`(let ((t e)) 1371 #,(let f ((c1 #'c1) (cmore #'(c2 ...))) 1372 (if (null? cmore) 1373 (syntax-case c1 (else) 1374 ((else e1 e2 ...) 1375 #'(begin e1 e2 ...)) 1376 (((k ...) e1 e2 ...) 1377 #'(if (memv t '(k ...)) 1378 (begin e1 e2 ...))]) 1379 (syntax-case c1 () 1380 (((k ...) e1 e2 ...) 1381 #`(if (memv t '(k ...)) 1382 (begin e1 e2 ...) 1383 #,(f (car cmore) 1384 (cdr cmore)))))))))))) 1385 1386 _Note:_ Any ‘syntax-rules’ form can be expressed with ‘syntax-case’ 1387 by making the ‘lambda’ expression and ‘syntax’ expressions 1388 explicit, and ‘syntax-rules’ may be defined in terms of 1389 ‘syntax-case’ as follows. 1390 1391 (define-syntax syntax-rules 1392 (lambda (x) 1393 (syntax-case x () 1394 ((_ (lit ...) ((k . p) t) ...) 1395 (for-all identifier? #'(lit ... k ...)) 1396 #'(lambda (x) 1397 (syntax-case x (lit ...) 1398 ((_ . p) #'t) ...)))))) 1399 1400 1401File: kawa.info, Node: Named quasi-literals, Prev: Macros, Up: Syntax 1402 14037.11 Named quasi-literals 1404========================= 1405 1406Traditional Scheme has only a few kinds of values, and thus only a few 1407builtin kinds of literals. Modern Scheme allows defining new types, so 1408it is desirable to have a mechanism for defining literal values for the 1409new types. 1410 1411 Consider the ‘*note URI: URI-type.’ type. You can create a new 1412instance of a ‘URI’ using a constructor function: 1413 (URI "http://example.com/") 1414 This isn’t too bad, though the double-quote characters are an ugly 1415distraction. However, if you need to construct the string it gets 1416messy: 1417 (URI (string-append base-uri "icon.png")) 1418 1419 Instead use can write: 1420 &URI{http://example.com/} 1421 or: 1422 &URI{&[base-uri]icon.png} 1423 1424 This syntax is translated by the Scheme reader to the more familiar 1425but more verbose equivalent forms: 1426 ($construct$:URI "http://example.com/") 1427 ($construct$:URI $<<$ base-uri $>>$ "icon.png") 1428 So for this to work there just needs to be a definition of 1429‘$construct$:URI’, usually a macro. Normal scope rules apply; typically 1430you’d define ‘$construct$:URI’ in a module. 1431 1432 The names ‘$<<$’ and ‘$>>$’ are bound to unique zero-length strings. 1433They are used to allow the implementation of ‘$construct$:URI’ to 1434determine which arguments are literal and which come from escaped 1435expressions. 1436 1437 If you want to define your own ‘$construct$:TAG’, or to read 1438motivation and details, see the SRFI 108 1439(http://srfi.schemers.org/srfi-108/srfi-108.html) specification. 1440 1441 EXTENDED-DATUM-LITERAL ::= 1442 ‘&’ CNAME ‘{’ [INITIAL-IGNORED] NAMED-LITERAL-PART^{*} ‘}’ 1443 | ‘&’ CNAME ‘[’ EXPRESSION^{*} ‘]{’ [INITIAL-IGNORED] NAMED-LITERAL-PART^{*} ‘}’ 1444 CNAME ::= IDENTIFIER 1445 NAMED-LITERAL-PART ::= 1446 any character except ‘&’, ‘{’ or ‘}’ 1447 | ‘{’ NAMED-LITERAL-PART^{+} ‘}’ 1448 | CHAR-REF 1449 | ENTITY-REF 1450 | SPECIAL-ESCAPE 1451 | ENCLOSED-PART 1452 | EXTENDED-DATUM-LITERAL 1453 1454 1455File: kawa.info, Node: Program structure, Next: Control features, Prev: Syntax, Up: Top 1456 14578 Program structure 1458******************* 1459 1460See *note program units:: for some notes on structure of an entire 1461source file. 1462 1463* Menu: 1464 1465* Boolean values:: 1466* Conditionals:: 1467* Variables and Patterns:: 1468* Definitions:: 1469* Local binding constructs:: 1470* Lazy evaluation:: 1471* Repeat forms:: Repeat patterns and expressions 1472* Threads:: 1473* Exceptions:: Exception handling 1474 1475 1476File: kawa.info, Node: Boolean values, Next: Conditionals, Up: Program structure 1477 14788.1 Boolean values 1479================== 1480 1481The standard boolean objects for true and false are written as ‘#t’ and 1482‘#f’. Alternatively, they may be written ‘#true’ and ‘#false’, 1483respectively. 1484 1485 BOOLEAN ::= ‘#t’ | ‘#f’ | ‘#true’ | ‘#false’ 1486 1487 TEST-EXPRESSION ::= EXPRESSION 1488 1489 What really matters, though, are the objects that the Scheme 1490conditional expressions (‘if’, ‘cond’, ‘and’, ‘or’, ‘when’, ‘unless’, 1491‘do’) treat as true or false. The phrase “a true value” (or sometimes 1492just “true”) means any object treated as true by the conditional 1493expressions, and the phrase “a false value” (or “false”) means any 1494object treated as false by the conditional expressions. In this 1495document, TEST-EXPRESSION is an expression that is evaluated, but we 1496only care about whether the result is a true or a false value. 1497 1498 Of all the standard Scheme values, only ‘#f’ counts as false in 1499conditional expressions. All other Scheme values, including ‘#t’, count 1500as true. A TEST-EXPRESSION is an expression evaluated in this manner 1501for whether it is true or false. 1502 1503 In addition the null value ‘#!null’ (in Java written as ‘null’) is 1504also considered false. Also, if you for some strange reason create a 1505fresh ‘java.lang.Boolean’ object whose ‘booleanValue()’ returns ‘false’, 1506that is also considered false. 1507 1508 _Note:_ Unlike some other dialects of Lisp, Scheme distinguishes ‘#f’ 1509and the empty list from each other and from the symbol ‘nil’. 1510 1511 Boolean constants evaluate to themselves, so they do not need to be 1512quoted in programs. 1513 1514 #t ⇒ #t 1515 #true ⇒ #t 1516 #f ⇒ #f 1517 #false ⇒ #f 1518 '#f ⇒ #f 1519 1520 -- Type: boolean 1521 The type of boolean values. As a type conversion, a true value is 1522 converted to ‘#t’, while a false value is converted to ‘#f’. 1523 Represented as a primitive Java ‘boolean’ or ‘kawa.lang.Boolean’ 1524 when converted to an object. 1525 1526 -- Procedure: boolean? obj 1527 The ‘boolean?’ predicate returns ‘#t’ if OBJ is either ‘#t’ or 1528 ‘#f’, and returns ‘#f’ otherwise. 1529 (boolean? #f) ⇒ #t 1530 (boolean? 0) ⇒ #f 1531 (boolean? '()) ⇒ #f 1532 1533 -- Procedure: boolean=? boolean1 boolean2 boolean3 ... 1534 Returns ‘#t’ if all the arguments are booleans and all are ‘#t’ or 1535 all are ‘#f’. 1536 1537 1538File: kawa.info, Node: Conditionals, Next: Variables and Patterns, Prev: Boolean values, Up: Program structure 1539 15408.2 Conditionals 1541================ 1542 1543Kawa Scheme has the usual conditional expression forms, such as ‘if’, 1544‘case’, ‘and’, and ‘or’: 1545 (if (> 3 2) 'yes 'no) ⇒ yes 1546 1547 Kawa also allows you bind variables in the condition, using the ‘?’ 1548operator. 1549 (if (and (? x ::integer (get-value)) (> x 0)) 1550 (* x 10) 1551 'invalid) 1552 In the above, if ‘(get-value)’ evaluates to an integer, that integer 1553is bound to the variable ‘x’, which is visible in both following 1554sub-expression of ‘and’, as well case the true-part of the ‘if’. 1555 1556 Specifically, the first sub-expression of an ‘if’ is a TEST-OR-MATCH, 1557which can be a TEST-EXPRESSION, or a ‘?’ match expression, or a 1558combination using ‘and’: 1559 1560 TEST-OR-MATCH ::= TEST-EXPRESSION 1561 | ‘(?’ PATTERN EXPRESSION ‘)’ 1562 | ‘(and’ TEST-OR-MATCH^{*}‘)’ 1563 1564 A TEST-OR-MATCH is true if every nested TEST-EXPRESSION is true, and 1565every ‘?’ operation succeeds. It produces a set of variable bindings 1566which is the union of the bindings produced by all the PATTERNs. In an 1567‘and’ form, bindings produced by a PATTERN are visible to all subsequent 1568TEST-OR-MATCH sub-expressions. 1569 1570 -- Syntax: ? PATTERN EXPRESSION 1571 The form ‘(? P V)’ informally is true if the value of V matches the 1572 pattern P. Any variables bound in P are in scope in the “true” 1573 path of the containing conditional. 1574 1575 This has the form of an expression, but it can only be used in 1576 places where a TEST-OR-MATCH is required. For example it can be 1577 used as the first clause of an ‘if’ expression, in which case the 1578 scope of the variables bound in the ‘pattern’ includes the second 1579 (CONSEQUENT) sub-expression. On the other hand, a ‘?’ form may not 1580 be used as an argument to a procedure application. 1581 1582 -- Syntax: if TEST-OR-MATCH CONSEQUENT ALTERNATE 1583 -- Syntax: if TEST-OR-MATCH CONSEQUENT 1584 1585 CONSEQUENT ::= EXPRESSION 1586 ALTERNATE ::= EXPRESSION 1587 1588 An ‘if’ expression is evaluated as follows: first, the 1589 TEST-OR-MATCH is evaluated. If it it true, then CONSEQUENT is 1590 evaluated and its values are returned. Otherwise ALTERNATE is 1591 evaluated and its values are returned. If TEST yields ‘#f’ and no 1592 ALTERNATE is specified, then the result of the expression is void. 1593 1594 (if (> 2 3) 'yes 'no) ⇒ no 1595 (if (> 3 2) 1596 (- 3 2) 1597 (+ 3 2)) ⇒ 1 1598 (if #f #f) ⇒ #!void 1599 (if (? x::integer 3) 1600 (+ x 1) 1601 'invalid) ⇒ 4 1602 (if (? x::integer 3.4) 1603 (+ x 1) 1604 'invalid) ⇒ 'invalid 1605 1606 The CONSEQUENT and ALTERNATE expressions are in tail context if the 1607 ‘if’ expression itself is. 1608 1609 -- Syntax: cond COND-CLAUSE^{+} 1610 -- Syntax: cond COND-CLAUSE^{*} ‘(else’ EXPRESSION...‘)’ 1611 1612 COND-CLAUSE ::= ‘(’TEST-OR-MATCH BODY‘)’ 1613 | ‘(’TEST ‘=>’ EXPRESSION‘)’ 1614 1615 A ‘cond’ expression is evaluated by evaluating the TEST-OR-MATCHs 1616 of successive COND-CLAUSEs in order until one of them evaluates to 1617 a true value. When a TEST-OR-MATCH is true value, then the 1618 remaining EXPRESSIONs in its COND-CLAUSE are evaluated in order, 1619 and the results of the last EXPRESSION in the COND-CLAUSE are 1620 returned as the results of the entire ‘cond’ expression. Variables 1621 bound by the TEST-OR-MATCH are visible in BODY. If the selected 1622 COND-CLAUSE contains only the TEST-OR-MATCH and no EXPRESSIONs, 1623 then the value of the last TEST-EXPRESSION is returned as the 1624 result. If the selected COND-CLAUSE uses the ‘=>’ alternate form, 1625 then the EXPRESSION is evaluated. Its value must be a procedure. 1626 This procedure should accept one argument; it is called on the 1627 value of the TEST-EXPRESSION and the values returned by this 1628 procedure are returned by the ‘cond’ expression. 1629 1630 If all TEST-OR-MATCHs evaluate to ‘#f’, and there is no ‘else’ 1631 clause, then the conditional expression returns unspecified values; 1632 if there is an ‘else’ clause, then its EXPRESSIONs are evaluated, 1633 and the values of the last one are returned. 1634 1635 (cond ((> 3 2) 'greater) 1636 ((< 3 2) 'less)) ⇒ greater 1637 1638 (cond ((> 3 3) 'greater) 1639 ((< 3 3) 'less) 1640 (else 'equal)) ⇒ equal 1641 1642 (cond ('(1 2 3) => cadr) 1643 (else #f)) ⇒ 2 1644 1645 For a COND-CLAUSE of one of the following forms: 1646 (TEST EXPRESSION^{*}) 1647 (else EXPRESSION EXPRESSION^{*}) 1648 1649 the last EXPRESSION is in tail context if the ‘cond’ form itself 1650 is. For a COND CLAUSE of the form: 1651 1652 (TEST => EXPRESSION) 1653 1654 the (implied) call to the procedure that results from the 1655 evaluation of EXPRESSION is in tail context if the ‘cond’ form 1656 itself is. 1657 1658 -- Syntax: case CASE-KEY CASE-CLAUSE^{+} 1659 -- Syntax: case CASE-KEY CASE-CLAUSE^{*} CASE-ELSE-CLAUSE 1660 1661 CASE-KEY ::= EXPRESSION 1662 CASE-CLAUSE ::= ‘((’DATUM^{*}‘)’ EXPRESSION^{+}‘)’ 1663 | ‘((’DATUM^{*}‘)’ ‘=>’ EXPRESSION‘)’ 1664 CASE-ELSE-CLAUSE ::= ‘(else’ EXPRESSION^{+}‘)’ 1665 | ‘(else =>’ EXPRESSION‘)’ 1666 1667 Each DATUM is an external representation of some object. Each 1668 DATUM in the entire ‘case’ expression should be distinct. 1669 1670 A ‘case’ expression is evaluated as follows. 1671 1672 1. The CASE-KEY is evaluated and its result is compared using 1673 ‘eqv?’ against the data represented by the DATUMs of each 1674 CASE-CLAUSE in turn, proceeding in order from left to right 1675 through the set of clauses. 1676 1677 2. If the result of evaluating CASE-KEY is equivalent to a datum 1678 of a CASE-CLAUSE, the corresponding EXPRESSIONs are evaluated 1679 from left to right and the results of the last expression in 1680 the CASE-CLAUSE are returned as the results of the ‘case’ 1681 expression. Otherwise, the comparison process continues. 1682 3. If the result of evaluating KEY is different from every datum 1683 in each set, then if there is an CASE-ELSE-CLAUSE its 1684 expressions are evaluated and the results of the last are the 1685 results of the ‘case’ expression; otherwise the result of 1686 ‘case’ expression is unspecified. 1687 1688 If the selected CASE-CLAUSE or CASE-ELSE-CLAUSE uses the ‘=>’ 1689 alternate form, then the EXPRESSION is evaluated. It is an error 1690 if its value is not a procedure accepting one argument. This 1691 procedure is then called on the value of the KEY and the values 1692 returned by this procedure are returned by the ‘case’ expression. 1693 1694 (case (* 2 3) 1695 ((2 3 5 7) 'prime) 1696 ((1 4 6 8 9) 'composite)) ⇒ composite 1697 (case (car '(c d)) 1698 ((a) 'a) 1699 ((b) 'b)) ⇒ unspecified 1700 (case (car '(c d)) 1701 ((a e i o u) 'vowel) 1702 ((w y) 'semivowel) 1703 (else => (lambda (x) x))) ⇒ c 1704 1705 The last EXPRESSION of a CASE CLAUSE is in tail context if the 1706 ‘case’ expression itself is. 1707 1708 -- Syntax: match MATCH-KEY MATCH-CLAUSE^{+} 1709 The ‘match’ form is a generalization of ‘case’ using PATTERNs, 1710 MATCH-KEY ::= EXPRESSION 1711 MATCH-CLAUSE ::= 1712 ‘(’ PATTERN [GUARD] BODY ‘)’ 1713 The MATCH-KEY is evaluated, Then the MATCH-CLAUSEs are tried in 1714 order. The first MATCH-CLAUSE whose PATTERN matches (and the 1715 GUARD, if any, is true), is selected, and the corresponding BODY 1716 evaluated. It is an error if no MATCH-CLAUSE matches. 1717 (match value 1718 (0 (found-zero)) 1719 (x #!if (> x 0) (found-positive x)) 1720 (x #!if (< x 0) (found-negative x)) 1721 (x::symbol (found-symbol x)) 1722 (_ (found-other))) 1723 1724 One ‘case’ feature is not (yet) directly supported by ‘match’: 1725 Matching against a list of values. However, this is easy to 1726 simulate using a guard using ‘memq’, ‘memv’, or ‘member’: 1727 ;; compare similar example under case 1728 (match (car '(c d)) 1729 (x #!if (memv x '(a e i o u)) ’vowel) 1730 (x #!if (memv x '(w y)) ’semivowel) 1731 (x x)) 1732 1733 -- Syntax: and TEST-OR-MATCH^{*} 1734 1735 If there are no TEST-OR-MATCH forms, ‘#t’ is returned. 1736 1737 If the ‘and’ is not in TEST-OR-MATCH context, then the last 1738 sub-expression (if any) must be a TEST-EXPRESSION, and not a ‘?’ 1739 form. In this case the TEST-OR-MATCH expressions are evaluated 1740 from left to right until either one of them is false (a 1741 TEST-EXPRESSION is false or a ‘?’ match fails), or the last 1742 TEST-EXPRESSION is reached. In the former case, the ‘and’ 1743 expression returns ‘#f’ without evaluating the remaining 1744 expressions. In the latter case, the last expression is evaluated 1745 and its values are returned. 1746 1747 If the ‘and’ is in TEST-OR-MATCH context, then the last sub-form 1748 can be ‘?’ form. They are evaluated in order: If one of them is 1749 false, the entire ‘and’ is false; otherwise the ‘and’ is true. 1750 1751 Regardless, any bindings made by earlier ‘?’ forms are visible in 1752 later TEST-OR-MATCH forms. 1753 1754 (and (= 2 2) (> 2 1)) ⇒ #t 1755 (and (= 2 2) (< 2 1)) ⇒ #f 1756 (and 1 2 'c '(f g)) ⇒ (f g) 1757 (and) ⇒ #t 1758 (and (? x ::int 23) (> x 0)) ⇒ #t 1759 1760 The ‘and’ keyword could be defined in terms of ‘if’ using 1761 ‘syntax-rules’ as follows: 1762 1763 (define-syntax and 1764 (syntax-rules () 1765 ((and) #t) 1766 ((and test) test) 1767 ((and test1 test2 ...) 1768 (if test1 (and test2 ...) #t)))) 1769 1770 The last TEST-EXPRESSION is in tail context if the ‘and’ expression 1771 itself is. 1772 1773 -- Syntax: or TEST-EXPRESSION ... 1774 If there are no TEST-EXPRESSIONs, ‘#f’ is returned. Otherwise, the 1775 TEST-EXPRESSIONs are evaluated from left to right until a 1776 TEST-EXPRESSION returns a true value VAL or the last 1777 TEST-EXPRESSION is reached. In the former case, the ‘or’ 1778 expression returns VAL without evaluating the remaining 1779 expressions. In the latter case, the last expression is evaluated 1780 and its values are returned. 1781 1782 (or (= 2 2) (> 2 1)) ⇒ #t 1783 (or (= 2 2) (< 2 1)) ⇒ #t 1784 (or #f #f #f) ⇒ #f 1785 (or '(b c) (/ 3 0)) ⇒ (b c) 1786 1787 The ‘or’ keyword could be defined in terms of ‘if’ using 1788 ‘syntax-rules’ as follows: 1789 1790 (define-syntax or 1791 (syntax-rules () 1792 ((or) #f) 1793 ((or test) test) 1794 ((or test1 test2 ...) 1795 (let ((x test1)) 1796 (if x x (or test2 ...)))))) 1797 1798 The last TEST-EXPRESSION is in tail context if the ‘or’ expression 1799 itself is. 1800 1801 -- Procedure: not test-expression 1802 The ‘not’ procedure returns ‘#t’ if TEST-EXPRESSION is false, and 1803 returns ‘#f’ otherwise. 1804 1805 (not #t) ⇒ #f 1806 (not 3) ⇒ #f 1807 (not (list 3)) ⇒ #f 1808 (not #f) ⇒ #t 1809 (not ’()) ⇒ #f 1810 (not (list)) ⇒ #f 1811 (not ’nil) ⇒ #f 1812 (not #!null) ⇒ #t 1813 1814 -- Syntax: when TEST-EXPRESSION form... 1815 If TEST-EXPRESSION is true, evaluate each FORM in order, returning 1816 the value of the last one. 1817 1818 -- Syntax: unless TEST-EXPRESSION form... 1819 If TEST-EXPRESSION is false, evaluate each FORM in order, returning 1820 the value of the last one. 1821 1822 1823File: kawa.info, Node: Variables and Patterns, Next: Definitions, Prev: Conditionals, Up: Program structure 1824 18258.3 Variables and Patterns 1826========================== 1827 1828An identifier can name either a type of syntax or a location where a 1829value can be stored. An identifier that names a type of syntax is 1830called a “syntactic keyword” (informally called a “macro”), and is said 1831to be “bound” to a transformer for that syntax. An identifier that 1832names a location is called a “variable” and is said to be “bound” to 1833that location. The set of all visible bindings in effect at some point 1834in a program is known as the “environment” in effect at that point. The 1835value stored in the location to which a variable is bound is called the 1836variable’s value. By abuse of terminology, the variable is sometimes 1837said to name the value or to be bound to the value. This is not quite 1838accurate, but confusion rarely results from this practice. 1839 1840 Certain expression types are used to create new kinds of syntax and 1841to bind syntactic keywords to those new syntaxes, while other expression 1842types create new locations and bind variables to those locations. These 1843expression types are called “binding constructs”. Those that bind 1844syntactic keywords are discussed in *note Macros::. The most 1845fundamental of the variable binding constructs is the *note ‘lambda’ 1846expression: meta-lambda-expression, because all other variable binding 1847constructs can be explained in terms of ‘lambda’ expressions. Other 1848binding constructs include the *note ‘define’ family: Definitions, and 1849the *note ‘let’ family: Local binding constructs. 1850 1851 Scheme is a language with block structure. To each place where an 1852identifier is bound in a program there corresponds a “region” of the 1853program text within which the binding is visible. The region is 1854determined by the particular binding construct that establishes the 1855binding; if the binding is established by a ‘lambda’ expression, for 1856example, then its region is the entire ‘lambda’ expression. Every 1857mention of an identifier refers to the binding of the identifier that 1858established the innermost of the regions containing the use. 1859 1860 If there is no binding of the identifier whose region contains the 1861use, then the use refers to the binding for the variable in the global 1862environment, if any; if there is no binding for the identifier, it is 1863said to be “unbound”. 1864 18658.3.1 Patterns 1866-------------- 1867 1868The usual way to bind variables is to match an incoming value against a 1869“pattern”. The pattern contains variables that are bound to some value 1870derived from the value. 1871 (! [x::double y::double] (some-expression)) 1872 In the above example, the pattern ‘[x::double y::double]’ is matched 1873against the incoming value that results from evaluating 1874‘(some-expression)’. That value is required to be a two-element 1875sequence. Then the sub-pattern ‘x::double’ is matched against element 0 1876of the sequence, which means it is coerced to a ‘double’ and then the 1877coerced value is matched against the sub-pattern ‘x’ (which trivially 1878succeeds). Similarly, ‘y::double’ is matched against element 1. 1879 1880 The syntax of patterns is a work-in-progress. (The focus until now 1881has been in designing and implementing how patterns work in general, 1882rather than the details of the pattern syntax.) 1883 1884 PATTERN ::= IDENTIFIER 1885 | ‘_’ 1886 | PATTERN-LITERAL 1887 | ‘’’DATUM 1888 | PATTERN ‘::’ TYPE 1889 | ‘[’ LPATTERN^{*} ‘]’ 1890 LPATTERN ::= PATTERN 1891 | ‘@’ PATTERN 1892 | PATTERN ‘...’ 1893 | GUARD 1894 PATTERN-LITERAL ::= 1895 BOOLEAN | number | CHARACTER | STRING 1896 GUARD ::= ‘#!if’ EXPRESSION 1897 1898 This is how the specific patterns work: 1899 1900IDENTIFIER 1901 This is the simplest and most common form of pattern. The 1902 IDENTIFIER is bound to a new variable that is initialized to the 1903 incoming value. 1904 1905‘_’ 1906 This pattern just discards the incoming value. It is equivalent to 1907 a unique otherwise-unused IDENTIFIER. 1908 1909PATTERN-LITERAL 1910 Matches if the value is ‘equal?’ to the PATTERN-LITERAL. 1911 1912‘’’DATUM 1913 Matches if the value is ‘equal?’ to the quoted DATUM. 1914 1915PATTERN ‘::’ TYPE 1916 The incoming value is coerced to a value of the specified TYPE, and 1917 then the coerced value is matched against the sub-PATTERN. Most 1918 commonly the sub-PATTERN is a plain IDENTIFIER, so the latter match 1919 is trivial. 1920 1921‘[’ LPATTERN^{*} ‘]’ 1922 The incoming value must be a sequence (a list, vector or similar). 1923 In the case where each sub-pattern is a plain PATTERN, then the 1924 number of sub-patterns must match the size of the sequence, and 1925 each sub-pattern is matched against the corresponding element of 1926 the sequence. More generally, each sub-pattern may match zero or 1927 more consequtive elements of the incoming sequence. 1928 1929‘#!if’ EXPRESSION 1930 No incoming value is used. Instead the EXPRESSION is evaluated. 1931 If the result is true, matching succeeds (so far); otherwise the 1932 match fails. This form is called a “guard” 1933 (https://en.wikipedia.org/wiki/Guard_(computer_science)). 1934 1935‘@’ PATTERN 1936 A “splice pattern” may match multiple (zero or more) elements of a 1937 sequence. The PATTERN is matched against the resulting 1938 sub-sequence. 1939 (! [x @r] [2 3 5 7 11]) 1940 This binds ‘x’ to 2 and ‘r’ to ‘[3 5 7 11]’. 1941 1942PATTERN ‘...’ 1943 Similar to ‘@PATTERN’ in that it matches multiple elements of a 1944 sequence. However, each individual element is matched against the 1945 PATTERN, rather than the elements as a sequence. This is a *note 1946 repeat pattern: Repeat forms. 1947 1948 1949File: kawa.info, Node: Definitions, Next: Local binding constructs, Prev: Variables and Patterns, Up: Program structure 1950 19518.4 Definitions 1952=============== 1953 1954A variable definition binds one or more identifiers and specifies an 1955initial value for each of them. The simplest kind of variable 1956definition takes one of the following forms: 1957 1958 -- Syntax: ! PATTERN EXPRESSION 1959 Evaluate EXPRESSION, and match the result against PATTERN. 1960 Defining variables in PATTERN becomes bound in the current 1961 (surrounding) scope. 1962 1963 This is similar to ‘define-constant’ except generalized to a 1964 PATTERN. 1965 1966 (! [x y] (vector 3 4)) 1967 (format "x is ~w and y is ~w" x y) ⇒ "x is 3 and y is 4" 1968 1969 -- Syntax: define name [‘::’ TYPE] EXPRESSION 1970 Evaluate the EXPRESSION, optionally converting it to TYPE, and bind 1971 the NAME to the result. 1972 1973 -- Syntax: define (name FORMAL-ARGUMENTS) (ANNOTATION | 1974 OPTION-PAIR)^{*} OPT-RETURN-TYPE BODY 1975 -- Syntax: define (name ‘.’ REST-ARG) (ANNOTATION | OPTION-PAIR)^{*} 1976 OPT-RETURN-TYPE BODY 1977 1978 Bind the NAME to a function definition. The form: 1979 (define (NAME FORMAL-ARGUMENTS) OPTION-PAIR^{*} OPT-RETURN-TYPE BODY) 1980 is equivalent to: 1981 (define NAME (lambda FORMAL-ARGUMENTS) name: NAME OPTION-PAIR^{*} OPT-RETURN-TYPE BODY)) 1982 while the form: 1983 (define (NAME . REST-ARG) OPTION-PAIR^{*} OPT-RETURN-TYPE BODY) 1984 is equivalent to: 1985 (define NAME (lambda REST-ARG) name: NAME OPTION-PAIR^{*} OPT-RETURN-TYPE BODY)) 1986 1987 You can associate *note annotations: Annotations. with NAME. A 1988 field annotation will be associated with the generated field; a 1989 method annotation will be associated with the generated method(s). 1990 1991 In addition to ‘define’ (which can take an optional type specifier), 1992Kawa has some extra definition forms. 1993 1994 -- Syntax: define-private name [‘::’ TYPE] value 1995 -- Syntax: define-private (name formals) body 1996 Same as ‘define’, except that ‘name’ is not exported. 1997 1998 -- Syntax: define-constant name [‘::’ TYPE] value 1999 -- Syntax: define-early-constant name [:: type] value 2000 Defines NAME to have the given VALUE. The value is readonly, and 2001 you cannot assign to it. (This is not fully enforced.) 2002 2003 If ‘define-early-constant’ is used _or_ the VALUE is a compile-time 2004 constant, then the compiler will create a ‘final’ field with the 2005 given name and type, and evaluate VALUE in the module’s class 2006 initializer (if the definition is static) or constructor (if the 2007 definition is non-static), before other definitions and 2008 expressions. Otherwise, the VALUE is evaluated in the module body 2009 where it appears. 2010 2011 If the VALUE is a compile-time constant, then the definition 2012 defaults to being static. 2013 2014 -- Syntax: define-variable name [‘::’ TYPE] [init] 2015 If INIT is specified and NAME does not have a global variable 2016 binding, then INIT is evaluated, and NAME bound to the result. 2017 Otherwise, the value bound to NAME does not change. (Note that 2018 INIT is not evaluated if NAME does have a global variable binding.) 2019 2020 Also, declares to the compiler that NAME will be looked up in the 2021 per-thread dynamic environment. This can be useful for shutting up 2022 warnings from ‘--warn-undefined-variable’. 2023 2024 This is similar to the Common Lisp ‘defvar’ form. However, the 2025 Kawa version is (currently) only allowed at module level. 2026 2027 For ‘define-namespace’ and ‘define-private-namespace’ see *note 2028Namespaces::. 2029 2030 2031File: kawa.info, Node: Local binding constructs, Next: Lazy evaluation, Prev: Definitions, Up: Program structure 2032 20338.5 Local binding constructs 2034============================ 2035 2036The binding constructs ‘let’, ‘let*’, ‘letrec’, and ‘letrec*’ give 2037Scheme a block structure, like Algol 60. The syntax of these four 2038constructs is identical, but they differ in the regions they establish 2039for their variable bindings. In a ‘let’ expression, the initial values 2040are computed before any of the variables become bound; in a ‘let*’ 2041expression, the bindings and evaluations are performed sequentially; 2042while in ‘letrec’ and ‘letrec*’ expressions, all the bindings are in 2043effect while their initial values are being computed, thus allowing 2044mutually recursive definitions. 2045 2046 -- Syntax: let ‘((’PATTERN INIT‘)’ ...‘)’ BODY 2047 Declare new local variables as found in the PATTERNs. Each PATTERN 2048 is matched against the corresponding INIT. The INITs are evaluated 2049 in the current environment (in left-to-right onder), the VARIABLEs 2050 in the PATTERNSs are bound to fresh locations holding the matched 2051 results, the BODY is evaluated in the extended environment, and the 2052 values of the last expression of body are returned. Each binding 2053 of a variable has BODY as its region. 2054 2055 (let ((x 2) (y 3)) 2056 (* x y)) ⇒ 6 2057 2058 (let ((x 2) (y 3)) 2059 (let ((x 7) 2060 (z (+ x y))) 2061 (* z x))) ⇒ 35 2062 2063 An example with a non-trivial pattern: 2064 2065 (let (([a::double b::integer] (vector 4 5))) 2066 (cons b a)) ⇒ (5 . 4.0) 2067 2068 -- Syntax: let* ‘((’PATTERN init‘)’ ...‘)’ BODY 2069 2070 The ‘let*’ binding construct is similar to ‘let’, but the bindings 2071 are performed sequentially from left to right, and the region of a 2072 VARIABLEs in a PATTERN is that part of the ‘let*’ expression to the 2073 right of the PATTERN. Thus the second pattern is matched in an 2074 environment in which the bindings from the first pattern are 2075 visible, and so on. 2076 2077 (let ((x 2) (y 3)) 2078 (let* ((x 7) 2079 (z (+ x y))) 2080 (* z x))) ⇒ 70 2081 2082 -- Syntax: letrec ‘((’variable [‘::’ TYPE] init‘)’ ...‘)’ BODY 2083 -- Syntax: letrec* ‘((’variable [‘::’ TYPE] init‘)’ ...‘)’ BODY 2084 The VARIABLEs are bound to fresh locations, each VARIABLE is 2085 assigned in left-to-right order to the result of the corresponding 2086 INIT, the BODY is evaluated in the resulting environment, and the 2087 values of the last expression in body are returned. Despite the 2088 left-to-right evaluation and assignment order, each binding of a 2089 VARIABLE has the entire ‘letrec’ or ‘letrec*’ expression as its 2090 region, making it possible to define mutually recursive procedures. 2091 2092 In Kawa ‘letrec’ is defined as the same as ‘letrec*’. In standard 2093 Scheme the order of evaluation of the INITs is undefined, as is the 2094 order of assignments. If the order matters, you should use 2095 ‘letrec*’. 2096 2097 If it is not possible to evaluate each INIT without assigning or 2098 referring to the value of the corresponding VARIABLE or the 2099 variables that follow it, it is an error. 2100 (letrec ((even? 2101 (lambda (n) 2102 (if (zero? n) 2103 #t 2104 (odd? (- n 1))))) 2105 (odd? 2106 (lambda (n) 2107 (if (zero? n) 2108 #f 2109 (even? (- n 1)))))) 2110 (even? 88)) 2111 ⇒ #t 2112 2113 2114File: kawa.info, Node: Lazy evaluation, Next: Repeat forms, Prev: Local binding constructs, Up: Program structure 2115 21168.6 Lazy evaluation 2117=================== 2118 2119“Lazy evaluation” (or call-by-need) delays evaluating an expression 2120until it is actually needed; when it is evaluated, the result is saved 2121so repeated evaluation is not needed. Lazy evaluation 2122(http://en.wikipedia.org/wiki/Lazy_evaluation) is a technique that can 2123make some algorithms easier to express compactly or much more 2124efficiently, or both. It is the normal evaluation mechanism for strict 2125functional (side-effect-free) languages such as Haskell 2126(http://www.haskell.org). However, automatic lazy evaluation is awkward 2127to combine with side-effects such as input-output. It can also be 2128difficult to implement lazy evaluation efficiently, as it requires more 2129book-keeping. 2130 2131 Kawa, like other Schemes, uses “eager evaluation” - an expression is 2132normally evaluated immediately, unless it is wrapped in a special form. 2133Standard Scheme has some basic building blocks for “manual” lazy 2134evaluation, using an explicit ‘delay’ operator to indicate that an 2135expression is to be evaluated lazily, yielding a “promise”, and a 2136‘force’ function to force evaluation of a promise. This functionality 2137is enhanced in SRFI 45 (http://srfi.schemers.org/srfi-45/srfi-45.html), 2138in R7RS-draft (based on SRFI 45), and SRFI 41 2139(http://srfi.schemers.org/srfi-41/srfi-41.html) (lazy lists aka 2140streams). 2141 2142 Kawa makes lazy evaluation easier to use, by “implicit forcing”: The 2143promise is automatically evaluated (forced) when used in a context that 2144requires a normal value, such as arithmetic needing a number. Kawa 2145enhances lazy evaluation in other ways, including support for safe 2146multi-threaded programming. 2147 21488.6.1 Delayed evaluation 2149------------------------ 2150 2151 -- Syntax: delay EXPRESSION 2152 The ‘delay’ construct is used together with the procedure ‘force’ 2153 to implement _lazy evaluation_ or _call by need_. 2154 2155 The result of ‘(delay EXPRESSION)’ is a _promise_ which at some 2156 point in the future may be asked (by the ‘force’ procedure) to 2157 evaluate EXPRESSION, and deliver the resulting value. The effect 2158 of EXPRESSION returning multiple values is unspecified. 2159 2160 -- Syntax: delay-force EXPRESSION 2161 -- Syntax: lazy EXPRESSION 2162 The ‘delay-force’ construct is similar to ‘delay’, but it is 2163 expected that its argument evaluates to a promise. (Kawa treats a 2164 non-promise value as if it were a forced promise.) The returned 2165 promise, when forced, will evaluate to whatever the original 2166 promise would have evaluated to if it had been forced. 2167 2168 The expression ‘(delay-force EXPRESSION)’ is conceptually similar 2169 to ‘(delay (force EXPRESSION))’, with the difference that forcing 2170 the result of ‘delay-force’ will in effect result in a tail call to 2171 ‘(force EXPRESSION)’, while forcing the result of ‘(delay (force 2172 EXPRESSION))’ might not. Thus iterative lazy algorithms that might 2173 result in a long series of chains of ‘delay’ and ‘force’ can be 2174 rewritten using delay-force to prevent consuming unbounded space 2175 during evaluation. 2176 2177 Using ‘delay-force’ or ‘lazy’ is equivalent. The name 2178 ‘delay-force’ is from R7RS; the name ‘lazy’ is from the older 2179 SRFI-45. 2180 2181 -- Procedure: eager obj 2182 Returns a promise that when forced will return OBJ. It is similar 2183 to ‘delay’, but does not delay its argument; it is a procedure 2184 rather than syntax. 2185 2186 The Kawa implementation just returns OBJ as-is. This is because 2187 Kawa treats as equivalent a value and forced promise evaluating to 2188 the value. 2189 2190 -- Procedure: force promise 2191 The ‘force’ procedure forces the value of PROMISE. As a Kawa 2192 extension, if the PROMISE is not a promise (a value that does not 2193 implement ‘gnu.mapping.Lazy’) then the argument is returned 2194 unchanged. If no value has been computed for the promise, then a 2195 value is computed and returned. The value of the promise is cached 2196 (or “memoized”) so that if it is forced a second time, the 2197 previously computed value is returned. 2198 (force (delay (+ 1 2))) ⇒ 3 2199 2200 (let ((p (delay (+ 1 2)))) 2201 (list (force p) (force p))) ⇒ (3 3) 2202 2203 (define integers 2204 (letrec ((next 2205 (lambda (n) 2206 (cons n (delay (next (+ n 1))))))) 2207 (next 0))) 2208 (define head 2209 (lambda (stream) (car (force stream)))) 2210 (define tail 2211 (lambda (stream) (cdr (force stream)))) 2212 2213 (head (tail (tail integers))) ⇒ 2 2214 2215 The following example is a mechanical transformation of a lazy 2216 stream-filtering algorithm into Scheme. Each call to a constructor 2217 is wrapped in ‘delay’, and each argument passed to a deconstructor 2218 is wrapped in ‘force’. The use of ‘(lazy ...)’ instead of ‘(delay 2219 (force ...))’ around the body of the procedure ensures that an 2220 ever-growing sequence of pending promises does not exhaust the 2221 heap. 2222 2223 (define (stream-filter p? s) 2224 (lazy 2225 (if (null? (force s)) 2226 (delay ’()) 2227 (let ((h (car (force s))) 2228 (t (cdr (force s)))) 2229 (if (p? h) 2230 (delay (cons h (stream-filter p? t))) 2231 (stream-filter p? t)))))) 2232 2233 (head (tail (tail (stream-filter odd? integers)))) 2234 ⇒ 5 2235 2236 -- Procedure: force* promise 2237 Does ‘force’ as many times as necessary to produce a non-promise. 2238 (A non-promise is a value that does not implement 2239 ‘gnu.mapping.Lazy’, or if it does implement ‘gnu.mapping.Lazy’ then 2240 forcing the value using the ‘getValue’ method yields the receiver.) 2241 2242 The ‘force*’ function is a Kawa extension. Kawa will add implicit 2243 calls to ‘force*’ in most contexts that need it, but you can also 2244 call it explicitly. 2245 2246 The following examples are not intended to illustrate good 2247programming style, as ‘delay’, ‘lazy’, and ‘force’ are mainly intended 2248for programs written in the functional style. However, they do 2249illustrate the property that only one value is computed for a promise, 2250no matter how many times it is forced. 2251 2252 (define count 0) 2253 (define p 2254 (delay (begin (set! count (+ count 1)) 2255 (if (> count x) 2256 count 2257 (force p))))) 2258 (define x 5) 2259 p ⇒ _a promise_ 2260 (force p) ⇒ 6 2261 p ⇒ _a promise, still_ 2262 (begin (set! x 10) 2263 (force p)) ⇒ 6 2264 22658.6.2 Implicit forcing 2266---------------------- 2267 2268If you pass a promise as an argument to a function like ‘sqrt’ if must 2269first be forced to a number. In general, Kawa does this automatically 2270(implicitly) as needed, depending on the context. For example: 2271 (+ (delay (* 3 7)) 13) ⇒ 34 2272 2273 Other functions, like ‘cons’ have no problems with promises, and 2274automatic forcing would be undesirable. 2275 2276 Generally, implicit forcing happens for arguments that require a 2277specific type, and does not happen for arguments that work on _any_ type 2278(or ‘Object’). 2279 2280 Implicit forcing happens for: 2281 • arguments to arithmetic functions; 2282 • the sequence and the index in indexing operations, like 2283 ‘string-ref’; 2284 • the operands to ‘eqv?’ and ‘equal?’ are forced, though the operands 2285 to ‘eq?’ are not; 2286 • port operands to port functions; 2287 • the value to be emitted by a ‘display’ but _not_ the value to be 2288 emitted by a ‘write’; 2289 • the function in an application. 2290 2291 Type membership tests, such as the ‘instance?’ operation, generally 2292do not force their values. 2293 2294 The exact behavior for when implicit forcing happens is a 2295work-in-progress: There are certainly places where implicit forcing 2296doesn’t happen while it should; there are also likely to be places where 2297implicit forcing happens while it is undesirable. 2298 2299 Most Scheme implementations are such that a forced promise behaves 2300differently from its forced value, but some Scheme implementions are 2301such that there is no means by which a promise can be operationally 2302distinguished from its forced value. Kawa is a hybrid: Kawa tries to 2303minimize the difference between a forced promise and its forced value, 2304and may freely optimize and replace a forced promise with its value. 2305 23068.6.3 Blank promises 2307-------------------- 2308 2309A “blank promise” is a promise that doesn’t (yet) have a value _or_ a 2310rule for calculating the value. Forcing a blank promise will wait 2311forever, until some other thread makes the promise non-blank. 2312 2313 Blank promises are useful as a synchronization mechanism - you can 2314use it to safely pass data from one thread (the producer) to another 2315thread (the consumer). Note that you can only pass one value for a 2316given promise: To pass multiple values, you need multiple promises. 2317 2318 (define p (promise)) 2319 (future ;; Consumer thread 2320 (begin 2321 (do-stuff) 2322 (define v (force promise)) ; waits until promise-set-value! 2323 (do-stuff-with v))) 2324 ;; Producer thread 2325 ... do stuff ... 2326 (promise-set-value! p (calculate-value)) 2327 2328 -- Constructor: promise 2329 Calling ‘promise’ as a zero-argument constructor creates a new 2330 blank promise. 2331 2332 This calls the constructor for ‘gnu.mapping.Promise’. You can also 2333 create a non-blank promise, by setting one of the ‘value’, ‘alias’, 2334 ‘thunk’, or ‘exception’ properties. Doing so is equivalent to 2335 calling ‘promise-set-value!’, ‘promise-set-alias!’, 2336 ‘promise-set-thunk!’, or ‘promise-set-exception!’ on the resulting 2337 promise. For example: ‘(delay exp)’ is equivalent to: 2338 (promise thunk: (lambda() exp)) 2339 2340 The following four procedures require that their first arguments be 2341blank promises. When the procedure returns, the promise is no longer 2342blank, and cannot be changed. This is because a promise is conceptually 2343a placeholder for a single “not-yet-known” value; it is not a location 2344that can be assigned multiple times. The former enables clean and safe 2345(“declarative") use of multiple threads; the latter is much trickier. 2346 2347 -- Procedure: promise-set-value! promise value 2348 Sets the value of the PROMISE to VALUE, which makes the PROMISE 2349 forced. 2350 2351 -- Procedure: promise-set-exception! promise exception 2352 Associate EXCEPTION with the PROMISE. When the PROMISE is forced 2353 the EXCEPTION gets thrown. 2354 2355 -- Procedure: promise-set-alias! promise other 2356 Bind the PROMISE to be an alias of OTHER. Forcing PROMISE will 2357 cause OTHER to be forced. 2358 2359 -- Procedure: promise-set-thunk! promise thunk 2360 Associate THUNK (a zero-argument procedure) with the PROMISE. The 2361 first time the PROMISE is forced will causes the THUNK to be 2362 called, with the result (a value or an exception) saved for future 2363 calls. 2364 2365 -- Procedure: make-promise obj 2366 The ‘make-promise’ procedure returns a promise which, when forced, 2367 will return OBJ. It is similar to ‘delay’, but does not delay its 2368 argument: it is a procedure rather than syntax. If OBJ is already 2369 a promise, it is returned. 2370 2371 Because of Kawa’s implicit forcing, there is seldom a need to use 2372 ‘make-promise’, except for portability. 2373 23748.6.4 Lazy and eager types 2375-------------------------- 2376 2377 -- Type: promise[T] 2378 This parameterized type is the type of promises that evaluate to an 2379 value of type ‘T’. It is equivalent to the Java interface 2380 ‘gnu.mapping.Lazy<T>’. The implementation class for promises is 2381 usually ‘gnu.mapping.Promise’, though there are other classes that 2382 implement ‘Lazy’, most notably ‘gnu.mapping.Future’, used for 2383 futures, which are promises evaluated in a separate thread. 2384 2385 Note the distinction between the types ‘integer’ (the type of actual 2386(eager) integer values), and ‘promise[integer]’ (the type of (lazy) 2387promises that evaluate to integer). The two are compatible: if a 2388‘promise[integer]’ value is provided in a context requiring an ‘integer’ 2389then it is automatically evaluated (forced). If an ‘integer’ value is 2390provided in context requiring a ‘promise[integer]’, that conversion is 2391basically a no-op (though the compiler may wrap the ‘integer’ in a 2392pre-forced promise). 2393 2394 In a fully-lazy language there would be no distinction, or at least 2395the promise type would be the default. However, Kawa is a mostly-eager 2396language, so the eager type is the default. This makes efficient 2397code-generation easier: If an expression has an eager type, then the 2398compiler can generate code that works on its values directly, without 2399having to check for laziness. 2400 2401 2402File: kawa.info, Node: Repeat forms, Next: Threads, Prev: Lazy evaluation, Up: Program structure 2403 24048.7 Repeat patterns and expressions 2405=================================== 2406 2407Many programming languages have some variant of list comprehension 2408syntax (https://en.wikipedia.org/wiki/List_comprehension). Kawa splits 2409this into two separate forms, that can be in separate parts of the 2410program: 2411 • A “repeat pattern” as you might guess repeats a pattern by matching 2412 the pattern once for each element of a sequence. For example, 2413 assume ‘A’ is a some sequence-valued expression. Then: 2414 #|kawa:3|# (! [a::integer ...] A) 2415 Here ‘a::integer ...’ is a REPEAT PATTERN that matches all the 2416 elements pf ‘A’. We call ‘a::integer’ the “repeated pattern” - it 2417 matches an individual element of ‘A’. Any variable defined in a 2418 repeated pattern is a “repeat variable”. In the example, that 2419 would be ‘a’. 2420 • A “repeat expression” creates a sequence by repeating an expression 2421 for each element of the result. 2422 #|kawa:4|# [(* 2 a) ...] 2423 [4 6 10 14 22] 2424 In this case ‘(* 2 a) ...’ is the repeat expression. The “repeated 2425 expression” is ‘(* 2 a)’. The repeated expression is evaluated 2426 once for each element of any contained repeat variable. If there 2427 is more than one repeat variable, they are repeated in parallel, as 2428 many times as the “shortest” repeat variable, similar to the ‘map’ 2429 procedure. (If there is no repeat variable, the repeated 2430 expression is potentially evaluated infinitely many times, which is 2431 not allowed. A planned extension will allow it for lazy repeated 2432 expression.) 2433 2434 The use of ‘...’ for repeat patterns and expressions mirrors exactly 2435their use in ‘syntax-rules’ patterns and templates. 2436 2437 It is an error to use a repeat variable outside of repeat context: 2438 #|kawa:5|# a 2439 /dev/stdin:2:1: using repeat variable 'a' while not in repeat context 2440 2441 The repeat form feature is not yet complete. It is missing 2442functionality such as selecting only some elements from a repeat 2443sequence, lazy sequences, and it could be optimized more. 2444 2445 A repeat variable can be used multiple times in the same repeat 2446expressions, or different repeat expressions: 2447 #|kawa:7|# [a ... a ...] 2448 [2 3 5 7 11 2 3 5 7 11] 2449 #|kawa:8|# [(* a a) ...] 2450 [4 9 25 49 121] 2451 2452 Repeat expressions are useful not just in sequence literals, but in 2453the argument list of a procedure call, where the resulting sequence is 2454spliced into the argument list. This is especially useful for functions 2455that take a variable number of arguments, because that enables a 2456convenient way to do fold/accumulate/reduce 2457(https://en.wikipedia.org/wiki/Fold_(higher-order_function)) operations. 2458For example: 2459 2460 #|kawa:9|# (+ a ...) 2461 28 2462 2463 because 28 is the result of ‘(+ 2 3 5 7 11)’. 2464 2465 An elegant way to implement dot product 2466(https://en.wikipedia.org/wiki/Dot_product): 2467 (define (dot-product [x ...] [y ...]) 2468 (+ (* x y) ...)) 2469 2470 When an ellipse expression references two or more distinct repeat 2471variables then they are processed “in parallel”. That does not 2472(necessarily) imply muliple threads, but that the first element of the 2473repeat result is evaluated using the first element of all the repeat 2474sequences, the second element of the result uses the second element of 2475all the repeat sequences, and so on. 2476 2477Sub-patterns in repeat patterns 2478............................... 2479 2480While the repeated pattern before the ‘...’ is commonly in identifier, 2481it may be a more complex pattern. We showed earlier the repeated 2482pattern with a type specifier, which applies to each element: 2483 #|kawa:11|# (define (isum [x::integer ...]) (+ x ...)) 2484 #|kawa:12|# (isum [4 5 6]) 2485 15 2486 #|kawa:12|# (isum [4 5.1 6]) 2487 Argument #1 (null) to 'isum' has wrong type 2488 at gnu.mapping.CallContext.matchError(CallContext.java:189) 2489 at atInteractiveLevel-6.isum$check(stdin:11) 2490 ... 2491 (The stack trace line number ‘stdin:11’ is that of the ‘isum’ 2492definition.) 2493 2494 You can nest repeat patterns, allowing matching against sequences 2495whose elements are sequences. 2496 #|kawa:31|# (define (fun2 [[x ...] ...] [y ...]) 2497 #|.....32|# [[(+ x y) ...] ...]) 2498 #|kawa:33|# (fun2 [[1 2 3] [10 11 12]] [100 200]) 2499 [[101 102 103] [210 211 212]] 2500 Note that ‘x’ is double-nested, while ‘y’ is singly-nested. 2501 2502 Here each element is constrained to be a pair (a -element sequence): 2503 #|kawa:1|# (! [[x y] ...] [[11 12] [21 22] [31 32]]) 2504 #|kawa:2|# [(+ x y) ...] 2505 #(23 43 63) 2506 #|kawa:3|# [[x ...] [y ...]] 2507 #(#(11 21 31) #(12 22 32)) 2508 2509 2510File: kawa.info, Node: Threads, Next: Exceptions, Prev: Repeat forms, Up: Program structure 2511 25128.8 Threads 2513=========== 2514 2515There is a very preliminary interface to create parallel threads. The 2516interface is similar to the standard ‘delay’/‘force’, where a thread is 2517basically the same as a promise, except that evaluation may be in 2518parallel. 2519 2520 -- Syntax: future expression 2521 Creates a new thread that evaluates EXPRESSION. 2522 2523 (The result extends ‘java.lang.Thread’ and implements 2524 ‘gnu.mapping.Lazy’.) 2525 2526 -- Procedure: force thread 2527 The standard ‘force’ function is generalized to also work on 2528 threads. It waits for the thread’s EXPRESSION to finish executing, 2529 and returns the result. 2530 2531 -- Procedure: runnable function 2532 Creates a new ‘Runnable’ instance from a function. Useful for 2533 passing to Java code that expects a ‘Runnable’. You can get the 2534 result (a value or a thrown exception) using the ‘getResult’ 2535 method. 2536 2537 -- Syntax: synchronized object form ... 2538 Synchronize on the given OBJECT. (This means getting an exclusive 2539 lock on the object, by acquiring its “monitor”.) Then execute the 2540 FORMs while holding the lock. When the FORMs finish (normally or 2541 abnormally by throwing an exception), the lock is released. 2542 Returns the result of the last FORM. Equivalent to the Java 2543 ‘synchronized’ statement, except that it may return a result. 2544 2545 2546File: kawa.info, Node: Exceptions, Prev: Threads, Up: Program structure 2547 25488.9 Exception handling 2549====================== 2550 2551An “exception” is an object used to signal an error or other exceptional 2552situation. The program or run-time system can “throw” the exception 2553when an error is discovered. An exception handler is a program 2554construct that registers an action to handle exceptions when the handler 2555is active. 2556 2557 If an exception is thrown and not handled then the 2558read-eval-print-loop will print a stack trace, and bring you back to the 2559top level prompt. When not running interactively, an unhandled 2560exception will normally cause Kawa to be exited. 2561 2562 In the Scheme exception model (as of R6RS and R7RS), exception 2563handlers are one-argument procedures that determine the action the 2564program takes when an exceptional situation is signaled. The system 2565implicitly maintains a current exception handler in the dynamic 2566environment. The program raises an exception by invoking the current 2567exception handler, passing it an object encapsulating information about 2568the exception. Any procedure accepting one argument can serve as an 2569exception handler and any object can be used to represent an exception. 2570 2571 The Scheme exception model is implemented on top of the Java VM’s 2572native exception model where the only objects that can be thrown are 2573instances of ‘java.lang.Throwable’. Kawa also provides direct access to 2574this native model, as well as older Scheme exception models. 2575 2576 -- Procedure: with-exception-handler handler thunk 2577 It is an error if HANDLER does not accept one argument. It is also 2578 an error if THUNK does not accept zero arguments. The 2579 ‘with-exception-handler’ procedure returns the results of invoking 2580 THUNK. The HANDLER is installed as the current exception handler 2581 in the dynamic environment used for the invocation of THUNK. 2582 2583 (call-with-current-continuation 2584 (lambda (k) 2585 (with-exception-handler 2586 (lambda (x) 2587 (display "condition: ") 2588 (write x) 2589 (newline) 2590 (k 'exception)) 2591 (lambda () 2592 (+ 1 (raise ’an-error)))))) 2593 ⇒ exception 2594 and prints condition: an-error 2595 2596 (with-exception-handler 2597 (lambda (x) 2598 (display "something went wrong\n")) 2599 (lambda () 2600 (+ 1 (raise ’an-error)))) 2601 prints something went wrong 2602 2603 After printing, the second example then raises another exception. 2604 2605 _Performance note:_ The THUNK is inlined if it is a lambda 2606 expression. However, the HANDLER cannot be inlined even if it is a 2607 lambda expression, because it could be called by 2608 ‘raise-continuable’. Using the ‘guard’ form is usually more 2609 efficient. 2610 2611 -- Procedure: raise obj 2612 Raises an exception by invoking the current exception handler on 2613 OBJ. The handler is called with the same dynamic environment as 2614 that of the call to raise, except that the current exception 2615 handler is the one that was in place when the handler being called 2616 was installed. If the handler returns, then OBJ is re-raised in 2617 the same dynamic environment as the handler. 2618 2619 If OBJ is an instance of ‘java.lang.Throwable’, then ‘raise’ has 2620 the same effect as ‘primitive-throw’. 2621 2622 -- Procedure: raise-continuable obj 2623 Raises an exception by invoking the current exception handler on 2624 OBJ. The handler is called with the same dynamic environment as 2625 the call to ‘raise-continuable’, except that: (1) the current 2626 exception handler is the one that was in place when the handler 2627 being called was installed, and (2) if the handler being called 2628 returns, then it will again become the current exception handler. 2629 If the handler returns, the values it returns become the values 2630 returned by the call to ‘raise-continuable’. 2631 2632 (with-exception-handler 2633 (lambda (con) 2634 (cond 2635 ((string? con) 2636 (display con)) 2637 (else 2638 (display "a warning has been issued"))) 2639 42) 2640 (lambda () 2641 (+ (raise-continuable "should be a number") 2642 23))) 2643 prints: should be a number 2644 ⇒ 65 2645 2646 -- Syntax: guard VARIABLE COND-CLAUSE^{+} BODY 2647 The BODY is evaluated with an exception handler that binds the 2648 raised object to VARIABLE and, within the scope of that binding, 2649 evaluates the clauses as if they were the clauses of a ‘cond’ 2650 expression. That implicit ‘cond’ expression is evaluated with the 2651 continuation and dynamic environment of the ‘guard’ expression. If 2652 every cond-clause’s test evaluates to ‘#f’ and there is no ‘else’ 2653 clause, then ‘raise-continuable’ is invoked on the raised object 2654 within the dynamic environment of the original call to ‘raise’ or 2655 ‘raise-continuable’, except that the current exception handler is 2656 that of the ‘guard’ expression. 2657 2658 (guard (condition 2659 ((assq 'a condition) => cdr) 2660 ((assq 'b condition))) 2661 (raise (list (cons 'a 42)))) 2662 ⇒ 42 2663 2664 (guard (condition 2665 ((assq 'a condition) => cdr) 2666 ((assq 'b condition))) 2667 (raise (list (cons 'b 23)))) 2668 ⇒ (b . 23) 2669 2670 _Performance note:_ Using ‘guard’ is moderately efficient: there is 2671 some overhead compared to using native exception handling, but both 2672 the BODY and the handlers in the COND-CLAUSE are inlined. 2673 2674 -- Procedure: dynamic-wind in-guard thunk out-guard 2675 All three arguments must be 0-argument procedures. First calls 2676 IN-GUARD, then THUNK, then OUT-GUARD. The result of the expression 2677 is that of THUNK. If THUNK is exited abnormally (by throwing an 2678 exception or invoking a continuation), OUT-GUARD is called. 2679 2680 If the continuation of the dynamic-wind is re-entered (which is not 2681 yet possible in Kawa), the IN-GUARD is called again. 2682 2683 This function was added in R5RS. 2684 2685 -- Procedure: read-error? obj 2686 Returns #t if OBJ is an object raised by the ‘read’ procedure. 2687 (That is if OBJ is a ‘gnu.text.SyntaxException’.) 2688 2689 -- Procedure: file-error? obj 2690 Returns #t if OBJ is an object raised by inability to open an input 2691 or output port on a file. (This includes 2692 ‘java.io.FileNotFoundException’ as well as certain other 2693 exceptions.) 2694 26958.9.1 Simple error objects 2696-------------------------- 2697 2698 -- Procedure: error message obj ... 2699 Raises an exception as if by calling ‘raise’ on a newly allocated 2700 “simple error object”, which encapsulates the information provided 2701 by MESSAGE (which should a string), as well as any OBJ arguments, 2702 known as the irritants. 2703 2704 The string representation of a simple error object is as if calling 2705 ‘(format "#<ERROR ~a~{ ~w~}>" MESSAGE IRRITANTS)’. (That is the 2706 MESSAGE is formatted as if with ‘display’ while each irritant OBJ 2707 is formatted as if with ‘write’.) 2708 2709 This procedure is part of SRFI-23, and R7RS. It differs from (and 2710 is incompatible with) R6RS’s ‘error’ procedure. 2711 2712 -- Procedure: error-object? obj 2713 Returns ‘#t’ if OBJ is a simple error object. Specifically, that 2714 OBJ is an instance of ‘kawa.lang.NamedException’. Otherwise, it 2715 returns ‘#f’. 2716 2717 -- Procedure: error-object-message error-object 2718 Returns the message encapsulated by error-object, which must be a 2719 simple error object. 2720 2721 -- Procedure: error-object-irritants error-object 2722 Returns a list of the irritants (other arguments) encapsulated by 2723 error-object, which must be a simple error object. 2724 27258.9.2 Named exceptions 2726---------------------- 2727 2728These functions associate a symbol with exceptions and handlers: A 2729handler catches an exception if the symbol matches. 2730 2731 -- Procedure: catch key thunk handler 2732 Invoke THUNK in the dynamic context of HANDLER for exceptions 2733 matching KEY. If thunk throws to the symbol KEY, then HANDLER is 2734 invoked this way: 2735 2736 (handler key args ...) 2737 2738 KEY may be a symbol. The THUNK takes no arguments. If THUNK 2739 returns normally, that is the return value of ‘catch’. 2740 2741 Handler is invoked outside the scope of its own ‘catch’. If 2742 HANDLER again throws to the same key, a new handler from further up 2743 the call chain is invoked. 2744 2745 If the key is ‘#t’, then a throw to _any_ symbol will match this 2746 call to ‘catch’. 2747 2748 -- Procedure: throw key arg ... 2749 Invoke the catch form matching KEY, passing the ARGs to the current 2750 HANDLER. 2751 2752 If the key is a symbol it will match catches of the same symbol or 2753 of ‘#t’. 2754 2755 If there is no handler at all, an error is signaled. 2756 27578.9.3 Native exception handling 2758------------------------------- 2759 2760 -- Procedure: primitive-throw exception 2761 Throws the EXCEPTION, which must be an instance of a sub-class of 2762 ‘java.lang.Throwable’. 2763 2764 -- Syntax: try-finally body handler 2765 Evaluate BODY, and return its result. However, before it returns, 2766 evaluate HANDLER. Even if BODY returns abnormally (by throwing an 2767 exception), HANDLER is evaluated. 2768 2769 (This is implemented just like Java’s ‘try’-‘finally’. However, 2770 the current implementation does not duplicate the HANDLER.) 2771 2772 -- Syntax: try-catch body handler ... 2773 Evaluate BODY, in the context of the given HANDLER specifications. 2774 Each HANDLER has the form: 2775 VAR TYPE EXP ... 2776 If an exception is thrown in BODY, the first HANDLER is selected 2777 such that the thrown exception is an instance of the HANDLER’s 2778 TYPE. If no HANDLER is selected, the exception is propagated 2779 through the dynamic execution context until a matching HANDLER is 2780 found. (If no matching HANDLER is found, then an error message is 2781 printed, and the computation terminated.) 2782 2783 Once a HANDLER is selected, the VAR is bound to the thrown 2784 exception, and the EXP in the HANDLER are executed. The result of 2785 the ‘try-catch’ is the result of BODY if no exception is thrown, or 2786 the value of the last EXP in the selected HANDLER if an exception 2787 is thrown. 2788 2789 (This is implemented just like Java’s ‘try’-‘catch’.) 2790 2791 2792File: kawa.info, Node: Control features, Next: Symbols and namespaces, Prev: Program structure, Up: Top 2793 27949 Control features 2795****************** 2796 2797* Menu: 2798 2799* Mapping functions:: 2800* Multiple values:: 2801 2802 2803File: kawa.info, Node: Mapping functions, Next: Multiple values, Up: Control features 2804 28059.1 Mapping functions 2806===================== 2807 2808The procedures ‘string-for-each’ and ‘string-map’ are documented under 2809*note Strings::. 2810 2811 The procedure ‘string-cursor-for-each’ is documented under *note 2812String Cursor API::. 2813 2814 -- Procedure: map PROC sequence_{1} sequence_{2} ... 2815 -- Procedure: for-each PROC sequence_{1} sequence_{2} ... 2816 The ‘map’ procedure applies PROC element-wise to the elements of 2817 the SEQUENCEs and returns a list of the results, in order. The 2818 dynamic order in which PROC is applied to the elements of the 2819 SEQUENCEs is unspecified. 2820 2821 The ‘for-each’ procedure does the same, but is executed for the 2822 side-effects of PROC, whose result (if any) is discarded. Unlike 2823 ‘map’, ‘for-each’ is guaranteed to call PROC on the elements of the 2824 SEQUENCESs in order from the first element(s) to the last. The 2825 value returned by ‘for-each’ is the void value. 2826 2827 Each SEQUENCE must be a generalized sequence. (Traditionally, 2828 these arguments were restricted to lists, but Kawa allows 2829 sequences, including vectors, Java arrays, and strings.) If more 2830 than one SEQUENCE is given and not all SEQUENCEs have the same 2831 length, the procedure terminates when the shortest SEQUENCE runs 2832 out. The SEQUENCEs can be infinite (for example circular lists), 2833 but it is an error if all of them are infinite. 2834 2835 The PROC must be a procedure that accepts as many arguments as 2836 there are SEQUENCE arguments. It is an error for PROC to mutate 2837 any of the SEQUENCEs. In the case of ‘map’, PROC must return a 2838 single value. 2839 2840 (map cadr '((a b) (d e) (g h))) 2841 ⇒ (b e h) 2842 2843 (map (lambda (n) (expt n n)) 2844 '(1 2 3 4 5)) 2845 ⇒ (1 4 27 256 3125) 2846 2847 (map + ’(1 2 3) ’(4 5 6 7)) ⇒ (5 7 9) 2848 2849 (let ((count 0)) 2850 (map (lambda (ignored) 2851 (set! count (+ count 1)) 2852 count) 2853 '(a b))) 2854 ⇒ (1 2) or (2 1) 2855 2856 The result of ‘map’ is a list, even if the arguments are non-lists: 2857 (map + 2858 #(3 4 5) 2859 (float[] 0.5 1.5)) 2860 ⇒ (3.5 5.5) 2861 2862 To get a vector result, use ‘vector-map’. 2863 2864 (let ((v (make-vector 5))) 2865 (for-each (lambda (i) 2866 (vector-set! v i (* i i))) 2867 '(0 1 2 3 4)) 2868 v) 2869 ⇒ #(0 1 4 9 16) 2870 2871 A string is considered a sequence of ‘character’ values (not 16-bit 2872 ‘char’ values): 2873 2874 (let ((v (make-vector 10 #\-))) 2875 (for-each (lambda (i ch) 2876 (vector-set! v i ch)) 2877 [0 <: ] 2878 "Smile ��!") 2879 v) 2880 ⇒ #(#\S #\m #\i #\l #\e #\space #\x1f603 #\! #\- #\-) 2881 2882 _Performance note:_ These procedures are pretty well optimized. 2883 For each SEQUENCE the compiler will by default create an iterator. 2884 However, if the type of the SEQUENCE is known, the compiler will 2885 inline the iteration code. 2886 2887 -- Procedure: vector-map PROC SEQUENCE1 SEQUENCE2 ... 2888 Same as the ‘map’ procedure, except the result is a vector. 2889 (Traditionally, these arguments were restricted to vectors, but 2890 Kawa allows sequences, including lists, Java arrays, and strings.) 2891 2892 (vector-map cadr '#((a b) (d e) (g h))) 2893 ⇒ #(b e h) 2894 2895 (vector-map (lambda (n) (expt n n)) 2896 '#(1 2 3 4 5)) 2897 ⇒ #(1 4 27 256 3125) 2898 2899 (vector-map + '#(1 2 3) ’#(4 5 6 7)) 2900 ⇒ #(5 7 9) 2901 2902 (let ((count 0)) 2903 (vector-map 2904 (lambda (ignored) 2905 (set! count (+ count 1)) 2906 count) 2907 '#(a b))) 2908 ⇒ #(1 2) or #(2 1) 2909 2910 -- Procedure: vector-for-each PROC VECTOR1 VECTOR2 ... 2911 Mostly the same as ‘for-each’, however the arguments should be 2912 generalized vectors. Specifically, they should implement 2913 ‘java.util.List’ (which both regular vectors and uniform vectors 2914 do). The VECTORS should also be efficiently indexable. 2915 2916 (Traditionally, these arguments were restricted to vectors, but 2917 Kawa allows sequences, including lists, Java arrays, and strings.) 2918 2919 (let ((v (make-list 5))) 2920 (vector-for-each 2921 (lambda (i) (list-set! v i (* i i))) 2922 '#(0 1 2 3 4)) 2923 v) 2924 ⇒ (0 1 4 9 16) 2925 2926 2927File: kawa.info, Node: Multiple values, Prev: Mapping functions, Up: Control features 2928 29299.2 Multiple values 2930=================== 2931 2932The multiple-value feature was added in R5RS. 2933 2934 -- Procedure: values object ... 2935 Delivers all of its arguments to its continuation. 2936 2937 -- Procedure: call-with-values producer consumer 2938 Calls its PRODUCER argument with no arguments and a continuation 2939 that, when passed some values, calls the CONSUMER procedure with 2940 those values as arguments. 2941 2942 (call-with-values (lambda () (values 4 5)) 2943 (lambda (a b) b)) 2944 ⇒ 5 2945 2946 (call-with-values * -) ⇒ -1 2947 2948 _Performance note:_ If either the PRODUCER or CONSUMER is a 2949 fixed-arity lambda expression, it is inlined. 2950 2951 -- Syntax: define-values FORMALS EXPRESSION 2952 It is an error if a variable appears more than once in the set of 2953 FORMALS. 2954 2955 The EXPRESSION is evaluated, and the FORMALS are bound to the 2956 return values in the same way that the FORMALS in a ‘lambda’ 2957 expression are matched to the arguments in a procedure call. 2958 2959 (define-values (x y) (integer-sqrt 17)) 2960 (list x y) ⇒ (4 1) 2961 (let () 2962 (define-values (x y) (values 1 2)) 2963 (+ x y)) 2964 ⇒ 3 2965 2966 -- Syntax: let-values ‘((’FORMALS EXPRESSION‘)’ ...‘)’ BODY 2967 Each FORMALS should be a formal arguments list, as for a ‘lambda’. 2968 2969 The EXPRESSIONs are evaluated in the current environment, the 2970 variables of the FORMALS are bound to fresh locations, the return 2971 values of the EXPRESSIONs are stored in the variables, the BODY is 2972 evaluated in the extended environment, and the values of the last 2973 expression of BODY are returned. The BODY is a "tail body", cf 2974 section 3.5 of the R5RS. 2975 2976 The matching of each FORMALS to values is as for the matching of 2977 FORMALS to arguments in a ‘lambda’ expression, and it is an error 2978 for an EXPRESSION to return a number of values that does not match 2979 its corresponding FORMALS. 2980 (let-values (((a b . c) (values 1 2 3 4))) 2981 (list a b c)) ⇒ (1 2 (3 4)) 2982 2983 (let ((a 'a) (b 'b) (x 'x) (y 'y)) 2984 (let-values (((a b) (values x y)) 2985 ((x y) (values a b))) 2986 (list a b x y))) ⇒ (x y a b) 2987 2988 -- Syntax: let*-values ‘((’FORMALS EXPRESSION‘)’ ...‘)’ BODY 2989 2990 Each FORMALS should be a formal arguments list as for a ‘lambda’ 2991 expression. 2992 2993 ‘let*-values’ is similar to ‘let-values’, but the bindings are 2994 performed sequentially from left to right, and the region of a 2995 binding indicated by (FORMALS EXPRESSION) is that part of the 2996 ‘let*-values’ expression to the right of the binding. Thus the 2997 second binding is done in an environment in which the first binding 2998 is visible, and so on. 2999 (let ((a 'a) (b 'b) (x 'x) (y 'y)) 3000 (let*-values (((a b) (values x y)) 3001 ((x y) (values a b))) 3002 (list a b x y))) ⇒ (x y x y) 3003 3004 -- Syntax: receive FORMALS EXPRESSION BODY 3005 This convenience form (from SRFI-8 3006 (http://srfi.schemers.org/srfi-8/srfi-8.html)) is equivalent to: 3007 (let-values ((FORMALS EXPRESSION)) BODY) 3008 For example: 3009 (receive a (values 1 2 3 4) 3010 (reverse a)) ⇒ (4 3 2 1) 3011 3012 (receive (a b . c) (values 1 2 3 4) 3013 (list a b c)) ⇒ (1 2 (3 4)) 3014 3015 (let ((a 'a) (b 'b) (x 'x) (y 'y)) 3016 (receive (a b) (values x y) 3017 (receive (x y) (values a b) 3018 (list a b x y)))) ⇒ (x y x y) 3019 3020 -- Procedure: values-append arg1 ... 3021 The values resulting from evaluating each argument are appended 3022 together. 3023 3024 3025File: kawa.info, Node: Symbols and namespaces, Next: Procedures, Prev: Control features, Up: Top 3026 302710 Symbols and namespaces 3028************************* 3029 3030An identifier is a name that appears in a program. 3031 3032 A symbol is an object representing a string that cannot be modified. 3033This string is called the symbol’s name. Unlike strings, two symbols 3034whose names are spelled the same way are indistinguishable. A symbol is 3035immutable (unmodifiable) and normally viewed as atomic. Symbols are 3036useful for many applications; for instance, they may be used the way 3037enumerated values are used in other languages. 3038 3039 In addition to the simple symbols of standard Scheme, Kawa also has 3040compound (two-part) symbols. 3041 3042* Menu: 3043 3044* Simple symbols:: 3045* Namespaces:: 3046* Keywords:: 3047* Special named constants:: 3048 3049 3050File: kawa.info, Node: Simple symbols, Next: Namespaces, Up: Symbols and namespaces 3051 305210.1 Simple symbols 3053=================== 3054 3055Simple symbols have no properties other than their name, an immutable 3056string. They have the useful property that two simple symbols are 3057identical (in the sense of ‘eq?’, ‘eqv?’ and ‘equal?’) if and only if 3058their names are spelled the same way. A symbol literal is formed using 3059‘quote’. 3060 3061 -- Procedure: symbol? OBJ 3062 Return ‘#t’ if OBJ is a symbol, ‘#f’ otherwise. 3063 3064 (symbol? 'foo) ⇒ #t 3065 (symbol? (car '(a b))) ⇒ #t 3066 (symbol? "bar") ⇒ #f 3067 (symbol? 'nil) ⇒ #t 3068 (symbol? '()) ⇒ #f 3069 (symbol? #f) ⇒ #f 3070 3071 -- Procedure: symbol->string SYMBOL 3072 Return the name of SYMBOL as an immutable string. 3073 3074 (symbol->string 'flying-fish) ⇒ "flying-fish" 3075 (symbol->string 'Martin) ⇒ "Martin" 3076 (symbol->string (string->symbol "Malvina")) ⇒ "Malvina" 3077 3078 -- Procedure: string->symbol STRING 3079 Return the symbol whose name is STRING. 3080 3081 (eq? 'mISSISSIppi 'mississippi) 3082 ⇒ #f 3083 3084 (string->symbol "mISSISSIppi") 3085 ⇒ the symbol with name "mISSISSIppi" 3086 3087 (eq? 'bitBlt (string->symbol "bitBlt")) 3088 ⇒ #t 3089 3090 (eq? 'JollyWog (string->symbol (symbol->string 'JollyWog))) 3091 ⇒ #t 3092 3093 (string=? "K. Harper, M.D." 3094 (symbol->string (string->symbol "K. Harper, M.D."))) 3095 ⇒ #t 3096 3097 3098File: kawa.info, Node: Namespaces, Next: Keywords, Prev: Simple symbols, Up: Symbols and namespaces 3099 310010.2 Namespaces and compound symbols 3101==================================== 3102 3103Different applications may want to use the same symbol to mean different 3104things. To avoid such “name clashes” we can use “compound symbols”, 3105which have two string parts: a “local name” and a “namespace URI”. The 3106namespace-uri can be any string, but it is recommended that it have the 3107form of an absolute URI 3108(http://en.wikipedia.org/wiki/Uniform_Resource_Identifier). It would be 3109too verbose to write the full URI all the time, so one usually uses a 3110“namespace prefix” (namespace alias) as a short local alias to refer to 3111a namespace URI. 3112 3113 Compound symbols are usually written using the infix colon operator: 3114 PREFIX:LOCAL-NAME 3115 where PREFIX is a namespace alias bound to some (lexically-known) 3116namespace URI. 3117 3118 Compound symbols are used for namespace-aware XML processing. 3119 312010.2.1 Namespace objects 3121------------------------ 3122 3123A “namespace” is a mapping from strings to symbols. The string is the 3124local-name of the resulting symbol. A namespace is similar to a Common 3125Lisp “package”. 3126 3127 A namespace has a namespace-uri, which a string; it is recommended 3128that it have the form of an absolute URI. A namespace may optionally 3129have a prefix, which is a string used when printing out symbols 3130belonging to the namespace. (If you want “equivalent symbols” (i.e. 3131those that have the same local-name and same uri) to be the identical 3132symbol object, then you should use namespaces whose prefix is the empty 3133string.) 3134 3135 -- Constructor: namespace name [prefix] 3136 Return a namespace with the given NAME and PREFIX. If no such 3137 namespace exists, create it. The NAMESPACE-NAME is commonly a URI, 3138 especially when working with XML, in which case it is called a 3139 NAMESPACE-URI. However, any non-empty string is allowed. The 3140 prefix can be a string or a simple symbol. (If a symbol is used, 3141 then the symbol’s local-name is used.) The default for PREFIX is 3142 the empty string. Multiple calls with the same arguments will 3143 yield the same namespace object. 3144 3145 The reader macro ‘#,namespace’ is equivalent to the ‘namespace’ 3146function, but it is invoked at read-time: 3147 #,(namespace "http://www.w3.org/1999/XSL/Transform" xsl) 3148 (eq? #,(namespace "foo") (namespace "foo")) ⇒ #t 3149 3150 The form ‘(,#namespace "" "")’ returns the default “empty namespace”, 3151which is used for simple symbols. 3152 3153 -- Procedure: namespace-uri namespace 3154 Return the namespace-uri of the argument NAMESPACE, as a string. 3155 3156 -- Procedure: namespace-prefix namespace 3157 Return the namespace prefix of the argument NAMESPACE, as a string. 3158 315910.2.2 Compound symbols 3160----------------------- 3161 3162A compound symbol is one that belongs to a namespace other than the 3163default empty namespace, and (normally) has a non-empty namespace uri. 3164(It is possible for a symbol to belong to a non-default namespace and 3165have an empty namespace uri, but that is not recommended.) 3166 3167 -- Constructor: symbol local-name namespace-spec 3168 -- Constructor: symbol local-name [uri [prefix]] 3169 Construct a symbol with the given LOCAL-NAME and namespace. If 3170 NAMESPACE-SPEC is a namespace object, then find (or, if needed, 3171 construct) a symbol with the given LOCAL-NAME belonging to the 3172 namespace. Multiple calls to ‘symbol’ with the same namespace and 3173 LOCAL-NAME will yield the same symbol object. 3174 3175 If uri is a string (optionally followed by a prefix), then: 3176 (symbol lname uri [prefix]) 3177 is equivalent to: 3178 (symbol lname (namespace uri [prefix])) 3179 3180 Using ‘#t’ for the NAMESPACE-SPEC is equivalent to using the empty 3181 namespace ‘#,(namespace "")’. 3182 3183 Using ‘#!null’ or ‘#f’ for the NAMESPACE-SPEC creates an UNINTERNED 3184 symbol, which does not belong to any namespace. 3185 3186 -- Procedure: symbol-local-name symbol 3187 Return the local name of the argument symbol, as an immutable 3188 string. (The string is interned, except in the case of an 3189 uninterned symbol.) 3190 3191 -- Procedure: symbol-prefix symbol 3192 Return the prefix of the argument symbol, as an immutable (and 3193 interned) string. 3194 3195 -- Procedure: symbol-namespace-uri symbol 3196 Return the namespace uri of the argument symbol, as an immutable 3197 (and interned) string. 3198 3199 -- Procedure: symbol-namespace symbol 3200 Return the namespace object (if any) of the argument symbol. 3201 Returns ‘#!null’ if the symbol is uninterned. 3202 3203 -- Procedure: symbol=? SYMBOL1 SYMBOL2 SYMBOL3 ... 3204 Return ‘#t’ if the symbols are equivalent as symbols, i.e., if 3205 their local-names and namespace-uris are the same. They may have 3206 different values of ‘symbol-prefix’ and ‘symbol-namespace’. If a 3207 symbol is uninterned (or is ‘#!null’) then ‘symbol=?’ returns the 3208 same result as ‘eq?’. 3209 3210 Two symbols are ‘equal?’ or ‘eqv?’ if they’re ‘symbol=?’. 3211 321210.2.3 Namespace aliases 3213------------------------ 3214 3215A namespace is usually referenced using a shorter “namespace alias”, 3216which is is a lexical definition that binds a namespace prefix to a 3217namespace object (and thus a namespace uri). This allows using compound 3218symbols as identifiers in Scheme programs. 3219 3220 -- Syntax: define-namespace name namespace-name 3221 Defines NAME as a “namespace prefix” - a lexically scoped 3222 "nickname" for the namespace whose full name is NAMESPACE-NAME, 3223 which should be a non-empty string literal. It is customary for 3224 the string have syntactic form of an absolute URI 3225 (http://en.wikipedia.org/wiki/Uniform_Resource_Identifier), but any 3226 non-empty string is acceptable and is used without further 3227 interpretation. 3228 3229 Any symbols in the scope of this definitions that contain a colon, 3230 and where the part before the colon matches the NAME will be 3231 treated as being in the package/namespace whose global unique name 3232 is the NAMESPACE-NAME. 3233 3234 Has mostly the same effect as: 3235 (define-constant NAME #,(namespace NAMESPACE-NAME) 3236 3237 However, using ‘define-namespace’ (rather than ‘define-constant’) 3238 is recommended if you want to use compound symbols as names of 3239 variables, especially local variables, or if you want to quote 3240 compound symbols. 3241 3242 Note that the prefix is only visible lexically: it is not part of 3243 the namespace, or thus indirectly the symbols, and so is not 3244 available when printing the symbol. You might consider using 3245 ‘define-xml-namespace’ as an alternative. 3246 3247 A namespace is similar to a Common Lisp package, and the 3248 NAMESPACE-NAME is like the name of the package. However, a 3249 namespace alias belongs to the lexical scope, while a Common Lisp 3250 package nickname is global and belongs to the package itself. 3251 3252 If the namespace-name starts with the string ‘"class:"’, then the 3253 NAME can be used for invoking Java methods (*note Method 3254 operations::) and accessing fields (*note Field operations::). 3255 3256 You can use a namespace as an abbreviation or renaming of a class 3257 name, but as a matter of style ‘define-alias’ is preferred. 3258 3259 -- Syntax: define-private-namespace name namespace-name 3260 Same as ‘define-namespace’, but the prefix NAME is local to the 3261 current module. 3262 3263 For example, you might have a set of a geometry definitions defined 3264under the namespace-uri ‘"http://foo.org/lib/geometry"’: 3265 3266 (define-namespace geom "http://foo.org/lib/geometry") 3267 (define (geom:translate x y) 3268 (java.awt.geom.AffineTransform:getTranslateInstance x y)) 3269 (define geom:zero (geom:translate 0 0)) 3270 geom:zero 3271 ⇒ AffineTransform[[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]] 3272 3273 You could have some other definitions for complex math: 3274 (define-namespace complex "http://foo.org/lib/math/complex") 3275 (define complex:zero +0+0i) 3276 3277 You can use a namespace-value directly in a compound name: 3278 (namespace "http://foo.org/lib/geometry"):zero 3279 ⇒ AffineTransform[[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]] 3280 3281 The variation ‘define-xml-namespace’ is used for *note Creating XML 3282nodes::. 3283 3284 -- Syntax: define-xml-namespace prefix "namespace-uri" 3285 Defines a namespace with prefix PREFIX and URI NAMESPACE-URI. This 3286 is similar to ‘define-namespace’ but with two important 3287 differences: 3288 • Every symbol in the namespace automatically maps to an 3289 element-constructor-type, as with the ‘html’ namespace. 3290 • The PREFIX is a component of the namespace object, and hence 3291 indirectly of any symbols belongining to the namespace. 3292 3293 Thus the definition is roughly equivalent to: 3294 (define-constant NAME #,(namespace NAMESPACE-NAME NAME) 3295 along with an infinite set of definitions, for every possible TAG: 3296 (define (name:TAG . rest) (apply make-element 'name:TAG rest)) 3297 3298 $ kawa --output-format xml 3299 #|kawa:1|# (define-xml-namespace na "Namespace1") 3300 #|kawa:2|# (define-xml-namespace nb "Namespace1") 3301 #|kawa:3|# (define xa (na:em "Info")) 3302 #|kawa:4|# xa 3303 <na:em xmlns:na="Namespace1">Info</na:em> 3304 #|kawa:5|# (define xb (nb:em "Info")) 3305 #|kawa:6|# xa 3306 <nb:em xmlns:nb="Namespace1">Info</nb:em> 3307 3308 Note that the prefix is part of the qualified name (it is actually 3309part of the namespace object), and it is used when printing the tag. 3310Two qualified names (symbols) that have the same local-name and the same 3311namespace-name are considered equal, even if they have different prefix. 3312You can think of the prefix as annotation used when printing, but not 3313otherwise part of the “meaning” of a compound symbol. They are the same 3314object if they also have the same prefix. This is an important 3315difference from traditional Lisp/Scheme symbols, but it is how XML 3316QNames work. 3317 #|kawa:7|# (instance? xb na:em) 3318 true 3319 #|kawa:8|# (eq? 'na:em 'nb:em) 3320 false 3321 #|kawa:9|# (equal? 'na:em 'nb:em) 3322 true 3323 #|kawa:10|# (eqv? 'na:em 'nb:em) 3324 true 3325 (Note that ‘#t’ is printed as ‘true’ when using XML formatting.) 3326 3327 The predefined ‘html’ prefix could be defined thus: 3328 (define-xml-namespace html "http://www.w3.org/1999/xhtml") 3329 3330 3331File: kawa.info, Node: Keywords, Next: Special named constants, Prev: Namespaces, Up: Symbols and namespaces 3332 333310.3 Keywords 3334============= 3335 3336Keywords are similar to symbols. They are used mainly for specifying 3337keyword arguments. 3338 3339 Historically keywords have been self-evaluating (you did not need to 3340quote them). This has changed: you must quote a keyword if you want a 3341literal keyword value, and not quote it if it is used as a keyword 3342argument. 3343 3344 KEYWORD ::= IDENTIFIER‘:’ 3345 | ‘#:’IDENTIFIER 3346 3347 The two syntaxes have the same meaning: The former is nicer-looking; 3348the latter is more portable (and required if you use the ‘--r7rs’ 3349command-line flag). 3350 3351 _Details:_ In r7rs and other Scheme standards the colon character 3352 does not have any special meaning, so ‘foo:’ or ‘foo:bar’ are just 3353 regular identifiers. Therefore some other Scheme variants that 3354 have keywords (including Guile and Racket) use the ‘#:’ syntax. 3355 Kawa has some hacks so that _most_ standard Scheme programs that 3356 have colons in identifiers will work. However, for best 3357 compatibility, use the ‘--r7rs’ command-line flag (which turns 3358 colon into a regular character in a symbol), and the ‘#:’ syntax. 3359 3360 A keyword is a single token; therefore no whitespace is allowed 3361between the IDENTIFIER and the colon or after the ‘#:’; these characters 3362are not considered part of the name of the keyword. 3363 3364 -- Procedure: keyword? obj 3365 Return ‘#t’ if OBJ is a keyword, and otherwise returns ‘#f’. 3366 3367 -- Procedure: keyword->string keyword 3368 Returns the name of KEYWORD as a string. The name does not include 3369 the final ‘#\:’. 3370 3371 -- Procedure: string->keyword string 3372 Returns the keyword whose name is STRING. (The STRING does not 3373 include a final ‘#\:’.) 3374 3375 3376File: kawa.info, Node: Special named constants, Prev: Keywords, Up: Symbols and namespaces 3377 337810.4 Special named constants 3379============================ 3380 3381 -- Constant: #!optional 3382 Special self-evaluating literal used in lambda parameter lists 3383 before optional parameters. 3384 3385 -- Constant: #!rest 3386 Special self-evaluating literal used in lambda parameter lists 3387 before the rest parameter. 3388 3389 -- Constant: #!key 3390 Special self-evaluating literal used in lambda parameter lists 3391 before keyword parameters. 3392 3393 -- Constant: #!eof 3394 The end-of-file object. 3395 3396 Note that if the Scheme reader sees this literal at top-level, it 3397 is returned literally. This is indistinguishable from coming to 3398 the end of the input file. If you do not want to end reading, but 3399 want the actual value of ‘#!eof’, you should quote it. 3400 3401 -- Constant: #!void 3402 The void value. Same as ‘(values)’. If this is the value of an 3403 expression in a read-eval-print loop, nothing is printed. 3404 3405 -- Constant: #!null 3406 The Java ‘null’ value. This is not really a Scheme value, but is 3407 useful when interfacing to low-level Java code. 3408 3409 3410File: kawa.info, Node: Procedures, Next: Numbers, Prev: Symbols and namespaces, Up: Top 3411 341211 Procedures 3413************* 3414 3415* Menu: 3416 3417* Application and Arguments Lists:: 3418* Extended formals:: 3419* Procedure properties:: 3420* Generic procedures:: 3421* Partial application:: 3422 3423 3424File: kawa.info, Node: Application and Arguments Lists, Next: Extended formals, Up: Procedures 3425 342611.1 Application and Arguments Lists 3427==================================== 3428 3429When a procedure is called, the actual argument expressions are 3430evaluated, and the resulting values becomes the actual argument list. 3431This is then matched against the formal parameter list in the procedure 3432definition, and (assuming they match) the procedure body is called. 3433 343411.1.1 Arguments lists 3435---------------------- 3436 3437An argument list has three parts: 3438 • Zero or more “prefix arguments”, each of which is a value. These 3439 typically get bound to named required or optional formal 3440 parameters, but can also get bound to patterns. 3441 • Zero or more “keyword arguments”, each of which is a keyword (an 3442 identifier specified with keyword syntax) combined with a value. 3443 These are bound to either named keyword formal parameters, or 3444 bundled in with a rest parameter. 3445 • Zero or more “postfix arguments”, each of which is a value. These 3446 are usually bound to a “rest” formal parameter, which receives any 3447 remaining arguments. 3448 3449 If there are no keyword arguments, then it ambiguous where prefix 3450 arguments end and where postfix arguments start. This is normally 3451 not a problem: the called procedure can split them up however it 3452 wishes. 3453 3454 Note that all keyword arguments have to be grouped together: It is 3455not allowed to have a keyword argument followed by a plain argument 3456followed by a keyword argument. 3457 3458 The argument list is constructed by evaluating each OPERAND of the 3459PROCEDURE-CALL in order: 3460EXPRESSION 3461 The EXPRESSION is evaluated, yielding a single value that becomes a 3462 prefix or postfix argument. 3463KEYWORD EXPRESSION 3464 The EXPRESSION is evaluated. The resulting value combined with the 3465 KEYWORD becomes a keyword argument. 3466‘@’EXPRESSION 3467 The EXPRESSION is evaluated. The result must be a sequence - a 3468 list, vector, or primitive array. The values of the sequence are 3469 appended to the resulting argument list. Keyword arguments are not 3470 allowed. 3471‘@:’EXPRESSION 3472 The EXPRESSION is evaluted. The result can be a sequence; a hash 3473 table (viewed as a collection of (keyword,value) pairs); or an 3474 “explicit argument list” object, which is a sequence of values _or_ 3475 keyword arguments. The values and keyword arguments are appended 3476 to the resulting argument list, though subject to the restriction 3477 that keyword arguments must be adjacent in the resulting argument 3478 list. 3479 348011.1.2 Explicit argument list objects 3481------------------------------------- 3482 3483Sometimes it is useful to create an argument list out of pieces, take 3484argument lists apart, iterate over them, and generally treat an argument 3485list as an actual first-class value. 3486 3487 Explicit argument list objects can take multiple forms. The simplest 3488is a sequence: a list, vector, or primitive array. Each element of the 3489list becomes a value in the resulting argument list. 3490 3491 (define v1 '(a b c)) 3492 (define v2 (int[] 10 11 12 13)) 3493 (list "X" @v1 "Y" @v2 "Z") 3494 ⇒ ("X" a b c "Y" 10 11 12 13 "Z") 3495 3496 Things get more complicated once keywords are involved. An explicit 3497argument list with keywords is only allowed when using the ‘@:’ splicing 3498form, not the ‘@’ form. It can be either a hash table, or the types 3499‘arglist’ or ‘argvector’. 3500 3501 _Design note:_ An argument list with keywords is straightforward in 3502 Common Lisp and some Scheme implementations (including order 3503 versions of Kawa): It’s just a list some of whose ‘car’ cells are 3504 keyword objects. The problem with this model is neither a human or 3505 the compiler can reliably tell when an argument is a keyword, since 3506 any variable might have been assigned a keyword. This limits 3507 performance and error checking. 3508 3509 A hash table (anything the implements ‘java.util.Map’) whose keys are 3510strings or keyword objects is interpreted as a sequence of keyword 3511arguments, using the hash-table keys and values. 3512 3513 -- Type: argvector 3514 -- Constructor: argvector OPERAND^{*} 3515 List of arguments represented as an immutable vector. A keyword 3516 argument takes two elements in this vector: A keyword object, 3517 followed by the value. 3518 3519 (define v1 (argvector 1 2 k1: 10 k2: 11 98 99)) 3520 (v1 4) ⇒ 'k2 3521 (v1 5) ⇒ 11 3522 When ‘v1’ is viewed as a vector it is equivalent to ‘(vector 1 2 3523 'k1: 10 'k2: 11 98 99)’. (Note in this case the keywords need to 3524 be quoted, since the ‘vector’ constructor does not take keyword 3525 arguments.) However, the ‘argvector’ “knows” which arguments are 3526 actually keyword arguments, and can be examined using the ‘(kawa 3527 arglist)’ library discussed below: 3528 3529 (arglist-key-count (argvector 1 x: 2 3)) ⇒ 1 3530 (arglist-key-count (argvector 1 'x: 2 3)) ⇒ 0 3531 (arglist-key-count (vector 1 'x: 2 3)) ⇒ 0 3532 3533 In this case: 3534 (fun 'a @:v1) 3535 is equivalent to: 3536 (fun 'a 1 2 k1: 10 k2: 11 98 99) 3537 3538 -- Type: arglist 3539 -- Constructor: arglist OPERAND^{*} 3540 Similar to ‘argvector’, but compatible with ‘list’. If there are 3541 no keyword arguments, returns a plain list. If there is at least 3542 one keyword argument creates a special ‘gnu.mapping.ArgListPair’ 3543 object that implements the usual ‘list’ properties but internally 3544 wraps a ‘argvector’. 3545 354611.1.3 Argument list library 3547---------------------------- 3548 3549 (import (kawa arglist)) 3550 3551 In the following, ARGS is an ‘arglist’ or ‘argvector’ (or in general 3552any object that implement ‘gnu.mapping.ArgList’). Also, ARGS can be any 3553sequence, in which case it behaves like an ‘argvector’ that has no 3554keyword arguments. 3555 3556 -- Procedure: arglist-walk args proc 3557 Call PROC once, in order, for each argument in ARGS. The PROC is 3558 called with two arguments, corresponding to ‘(arglist-key-ref ARGS 3559 I)’ and ‘(arglist-arg-ref ARGS I)’ for each I from 0 up to 3560 ‘(arglist-arg-count ARGS)’ (exclusive). I.e. the first argument 3561 is either ‘#!null’ or the keyword (as a string); the second 3562 argument is the corresponding argument value. 3563 3564 (define (print-arguments args #!optional (out (current-output-port))) 3565 (arglist-walk args 3566 (lambda (key value) 3567 (if key (format out "key: ~a value: ~w~%" key value) 3568 (format out "value: ~w~%" value))))) 3569 3570 -- Procedure: arglist-key-count args 3571 Return the number of keyword arguments. 3572 3573 -- Procedure: arglist-key-start args 3574 Number of prefix arguments, which is the number of arguments before 3575 the first keyword argument. 3576 3577 -- Procedure: arglist-arg-count args 3578 Return the number of arguments. The count includes the number of 3579 keyword arguments, but not the actual keywords. 3580 (arglist-arg-count (arglist 10 11 k1: -1 19)) ⇒ 4 3581 3582 -- Procedure: arglist-arg-ref args index 3583 Get the INDEX’th argument value. The INDEX counts keyword argument 3584 values, but not the keywords themselves. 3585 (arglist-arg-ref (arglist 10 11 k1: -1 19) 2) ⇒ -1 3586 (arglist-arg-ref (arglist 10 11 k1: -1 19) 3) ⇒ 19 3587 3588 -- Procedure: arglist-key-ref args index 3589 The INDEX counts arguments like ‘arglist-arg-ref’ does. If this is 3590 a keyword argument, return the corresponding keyword (as a string); 3591 otherwise, return ‘#!null’ (which counts as false). 3592 (arglist-key-ref (argvector 10 11 k1: -1 k2: -2 19) 3) ⇒ "k2" 3593 (arglist-key-ref (argvector 10 11 k1: -1 k2: -2 19) 4) ⇒ #!null 3594 3595 -- Procedure: arglist-key-index args key 3596 Search for a keyword matching KEY (which must be an interned 3597 string). If there is no such keyword, return -1. Otherwise return 3598 the keyword’s index as an argument to ‘arglist-key-ref’. 3599 3600 -- Procedure: arglist-key-value args key default 3601 Search for a keyword matching KEY (which must be an interned 3602 string). If there is no such keyword, return the DEFAULT. 3603 Otherwise return the corresponding keyword argument’s value. 3604 360511.1.4 Apply procedures 3606----------------------- 3607 3608 -- Procedure: apply proc argi^{*} argrest 3609 ARGREST must be a sequence (list, vector, or string) or a primitive 3610 Java array. (This is an extension over standard Scheme, which 3611 requires that ARGS be a list.) Calls the PROC (which must be a 3612 procedure), using as arguments the ARGI... values plus all the 3613 elements of ARGREST. 3614 3615 Equivalent to: ‘(’PROC ARGI^{*} ‘@’ARGREST‘)’. 3616 3617 -- Syntax: constant-fold proc arg1 ... 3618 Same as ‘(PROC ARG1 ...)’, unless PROC and all the following 3619 arguments are compile-time constants. (That is: They are either 3620 constant, or symbols that have a global binding and no lexical 3621 binding.) In that case, PROC is applied to the arguments at 3622 compile-time, and the result replaces the ‘constant-fold’ form. If 3623 the application raises an exception, a compile-time error is 3624 reported. For example: 3625 (constant-fold vector 'a 'b 'c) 3626 is equivalent to ‘(quote #(a b c))’, assuming ‘vector’ has not been 3627 re-bound. 3628 3629 3630File: kawa.info, Node: Extended formals, Next: Procedure properties, Prev: Application and Arguments Lists, Up: Procedures 3631 363211.2 Lambda Expressions and Formal Parameters 3633============================================= 3634 3635A ‘lambda’ expression evaluates to a procedure. The environment in 3636effect when the ‘lambda’ expression was evaluated is remembered as part 3637of the procedure. When the procedure is later called with some actual 3638arguments, the environment in which the ‘lambda’ expression was 3639evaluated will be extended by binding the variables in the formal 3640argument list to fresh locations, and the corresponding actual argument 3641values will be stored in those locations. (A “fresh location” is one 3642that is distinct from every previously existing location.) Next, the 3643expressions in the body of the lambda expression will be evaluated 3644sequentially in the extended environment. The results of the last 3645expression in the body will be returned as the results of the procedure 3646call. 3647 3648 (lambda (x) (+ x x)) ⇒ _a procedure_ 3649 ((lambda (x) (+ x x)) 4) ⇒ 8 3650 3651 (define reverse-subtract 3652 (lambda (x y) (- y x))) 3653 (reverse-subtract 7 10) ⇒ 3 3654 3655 (define add4 3656 (let ((x 4)) 3657 (lambda (y) (+ x y)))) 3658 (add4 6) ⇒ 10 3659 3660 The formal arguments list of a lambda expression has some extensions 3661over standard Scheme: Kawa borrows the extended formal argument list of 3662DSSSL, and allows you to declare the type of the parameter. More 3663generally, you can use *note patterns: Variables and Patterns. 3664 3665 LAMBDA-EXPRESSION ::= ‘(lambda’ FORMALS OPTION-PAIR^{*} OPT-RETURN-TYPE BODY‘)’ 3666 OPT-RETURN-TYPE ::= [‘::’ TYPE] 3667 FORMALS ::= ‘(’FORMAL-ARGUMENTS‘)’ | REST-ARG 3668 3669 An OPT-RETURN-TYPE specifies the return type of the procedure: The 3670result of evaluating the BODY is coerced to the specified TYPE. 3671 3672 _Deprecated_: If the first form of the function body is an unbound 3673identifier of the form ‘<TYPE>’ (that is the first character is ‘<’ and 3674the last is ‘>’), then that is another way to specify the function’s 3675return type. 3676 3677 See *note properties: Procedure properties. for how to set and use an 3678OPTION-PAIR. 3679 3680 The *note ‘define’: Definitions. form has a short-hand that combines 3681a lambda definition with binding the lambda to a variable: 3682 (define (NAME FORMAL-ARGUMENTS) OPT-RETURN-TYPE BODY) 3683 3684 FORMAL-ARGUMENTS ::= REQUIRED-OR-GUARD^{*} [‘#!optional’ OPTIONAL-ARG ...] REST-KEY-ARGS 3685 REST-KEY-ARGS ::= [‘#!rest’ REST-ARG] [‘#!key’ KEY-ARG ...] [GUARD] 3686 | [‘#!key’ KEY-ARG ...] [REST-PARAMETER] [GUARD] 3687 | ‘.’ REST-ARG 3688 3689 When the procedure is applied to an *note argument list::, the latter 3690is matched against formal parameters. This may involve some complex 3691rules and pattern matching. 3692 3693Required parameters 3694................... 3695 3696 REQUIRED-OR-GUARD ::= REQUIRED-ARG | GUARD 3697 REQUIRED-ARG ::= PATTERN 3698 | ‘(’ PATTERN ‘::’ TYPE‘)’ 3699 3700 The REQUIRED-ARGs are matched against the actual (pre-keyword) 3701arguments in order, starting with the first actual argument. It is an 3702error if there are fewer pre-keyword arguments then there are 3703REQUIRED-ARGs. While a PATTERN is most commonly an identifier, more 3704complicated patterns are possible, thus more (or fewer) variables may be 3705bound than there are arguments. 3706 3707 Note a PATTERN may include an OPT-TYPE-SPECIFIER. For example: 3708 (define (isquare x::integer) 3709 (* x x)) 3710 In this case the actual argument is coerced to an ‘integer’ and then 3711the result matched against the pattern ‘x’. This is how parameter types 3712are specified. 3713 3714 The PATTERN may be enclosed in parentheses for clarify (just like for 3715optional parameters), but in that case the type specifier is required to 3716avoid ambiguity. 3717 3718Optional parameters 3719................... 3720 3721 OPTIONAL-ARG ::= VARIABLE OPT-TYPE-SPECIFIER 3722 | ‘(’ PATTERN OPT-TYPE-SPECIFIER [INITIALIZER [SUPPLIED-VAR]]‘)’ 3723 SUPPLIED-VAR ::= VARIABLE 3724 3725 Next the OPTIONAL-ARGs are bound to remaining pre-keyword arguments. 3726If there are fewer remaining pre-keyword arguments than there are 3727OPTIONAL-ARGs, then the remaining VARIABLEs are bound to the 3728corresponding INITIALIZER. If no INITIALIZER was specified, it defaults 3729to ‘#f’. (TODO: If a TYPE is specified the default for INITIALIZER is 3730the default value of the TYPE.) The INITIALIZER is evaluated in an 3731environment in which all the previous formal parameters have been bound. 3732If a SUPPLIED-VAR is specified, it has type boolean, and is set to true 3733if there was an actual corresponding argument, and false if the 3734initializer was evaluated. 3735 3736Keyword parameters 3737.................. 3738 3739 KEY-ARG ::= VARIABLE OPT-TYPE-SPECIFIER 3740 | ‘(’ VARIABLE OPT-TYPE-SPECIFIER [INITIALIZER [SUPPLIED-VAR]] ‘)’ 3741 3742 Keyword parameters follow ‘#!key’. For each VARIABLE if there is an 3743actual keyword parameter whose keyword matches VARIABLE, then VARIABLE 3744is bound to the corresponding value. If there is no matching artual 3745argument, then the INITIALIZER is evaluated and bound to the argument. 3746If INITIALIZER is not specified, it defaults to ‘#f’. The INITIALIZER 3747is evaluated in an environment in which all the previous formal 3748parameters have been bound. 3749 3750 (define (fun x #!key (foo 1) (bar 2) (baz 3)) 3751 (list x foo bar baz)) 3752 (fun 9 baz: 10 foo: 11) ⇒ (9 11 2 10) 3753 3754 The following cause a match failure, _unless_ there is a rest 3755parameter: 3756 • There may not be extra non-keyword arguments (prefix or postfix) 3757 beyond those matched by required and optional parameters. 3758 • There may not be any duplicated keyword arguments. 3759 • All keyowrds in the actual argument list must match one of the 3760 keyword formal parameters. 3761 3762 It is not recommended to use both keyword parameters and a rest 3763parameter that can match keyword arguments. Currently, the rest 3764parameter will include any arguments that match the explicit keyword 3765parameters, as well any that don’t, though this may change. 3766 3767 On the other hand, it is fine to have both keyword parameters and a 3768rest parameter does not accept keywords. In that case the rest 3769parameter will match any “postfix” arguments: 3770 3771 #|kawa:8|# (define (fun x #!key k1 k2 #!rest r) 3772 (format "x:~w k1:~w k2:~w r:~w" x k1 k2 r)) 3773 (fun 3 k2: 12 100 101) ⇒ x:3 k1:#f k2:12 r:(100 101) 3774 3775 The SUPPLIED-VAR argument is as for optional arguments. 3776 3777 _Performance note:_ Keyword parameters are implemented very 3778efficiently and compactly when explicit in the code. The parameters are 3779sorted by the compiler, and the actual keyword arguemnts at the call 3780state are also sorted at compile-time. So keyword matching just 3781requires a fast linear scan comparing the two sorted lists. This 3782implementation is also very compact, compared to say a hash table. 3783 3784 If a TYPE is specified, the corresponding actual argument (or the 3785INITIALIZER default value) is coerced to the specified TYPE. In the 3786function body, the parameter has the specified type. 3787 3788Rest parameters 3789............... 3790 3791A “rest parameter” matches any arguments not matched by other 3792parameters. You can write it using any of the following ways: 3793 3794 REST-PARAMETER ::= 3795 ‘#!rest’ REST-ARG [‘::’ TYPE] 3796 | ‘@’REST-ARG 3797 | ‘@:’REST-ARG 3798 REST-ARG ::= VARIABLE 3799 3800 In addition, if FORMALS is just a REST-ARG identifier, or a 3801FORMAL-ARGUMENTS ends with ‘. REST-ARG’ (i.e. is a dotted list) that is 3802equivalent to using ‘#!rest’. 3803 3804 These forms are similar but differ in the type of the REST-ARG and 3805whether keywords are allowed (as part of the REST-ARG): 3806 3807 • If ‘#!rest’ REST-ARG is used with no TYPE specifier (or a TYPE 3808 specifier of ‘list’) then REST-ARG is a list. Keywords are not 3809 allowed if ‘#!key’ has been seen. (For backward compatibility, it 3810 is allowed to have extra keywords if ‘#!rest’ is followed by 3811 ‘!key’.) If there are any keywords, then REST-ARG is more 3812 specifically an ‘arglist’. 3813 • If ‘#!rest’ REST-ARG is used with TYPE specifier that is a Java 3814 array (for example ‘#!rest r::string[]’ then REST-ARG has that 3815 type. Each argument must be compatible with the element type of 3816 the array. Keywords are not allowed (even if TYPE is ‘object[]’). 3817 3818 The generated method will be compiled like a Java varargs methods 3819 if possible (i.e. no non-trivial patterns or keyword paremeters). 3820 • Using ‘@’REST-ARG is equivalent to ‘#!rest REST-ARG::object[]’: 3821 Keywords are not allowed; the type of REST-ARG is a Java array; the 3822 method is compiled like a Java varargs method. 3823 3824 • For ‘@:’REST-ARG then REST-ARG is a vector, specifically an 3825 ‘argvector’. Keywords are allowed. 3826 3827Guards (conditional expressions) 3828................................ 3829 3830A GUARD is evaluated when it appears in the formal parameter list. If 3831it evaluates to false, then matching fails. Guards can appears before 3832or after required arguments, or at the very end, after all other formal 3833parameters. 3834 3835 3836File: kawa.info, Node: Procedure properties, Next: Generic procedures, Prev: Extended formals, Up: Procedures 3837 383811.3 Procedure properties 3839========================= 3840 3841You can associate arbitrary “properties” with any procedure. Each 3842property is a (KEY, VALUE)-pair. Usually the KEY is a symbol, but it 3843can be any object. 3844 3845 The preferred way to set a property is using an OPTION-PAIR in a 3846LAMBDA-EXPRESSION. For example, to set the ‘setter’ property of a 3847procedure to ‘my-set-car’ do the following: 3848 (define my-car 3849 (lambda (arg) setter: my-set-car (primitive-car arg))) 3850 3851 The system uses certain internal properties: ‘'name’ refers to the 3852name used when a procedure is printed; ‘'emacs-interactive’ is used to 3853implement Emacs ‘interactive’ specification; ‘'setter’ is used to 3854associate a ‘setter’ procedure. 3855 3856 -- Procedure: procedure-property proc key [default] 3857 Get the property value corresponding to the given KEY. If PROC has 3858 no property with the given KEY, return DEFAULT (which defaults to 3859 ‘#f’) instead. 3860 3861 -- Procedure: set-procedure-property! proc key value 3862 Associate the given VALUE with the KEY property of PROC. 3863 3864 To change the print name of the standard ‘+’ procedure (probably not 3865a good idea!), you could do: 3866 (set-procedure-property! + 'name 'PLUS) 3867 Note this _only_ changes the name property used for printing: 3868 + ⇒ #<procedure PLUS> 3869 (+ 2 3) ⇒ 5 3870 (PLUS 3 4) ⇒ ERROR 3871 3872 As a matter of style, it is cleaner to use the ‘define-procedure’ 3873form, as it is a more declarative interface. 3874 3875 -- Syntax: define-procedure name [propname: propvalue] ... method ... 3876 Defines NAME as a compound procedure consisting of the specified 3877 METHODs, with the associated properties. Applying NAME select the 3878 "best" METHOD, and applies that. See the following section on 3879 generic procedures. 3880 3881 For example, the standard ‘vector-ref’ procedure specifies one 3882 method, as well as the ‘setter’ property: 3883 (define-procedure vector-ref 3884 setter: vector-set! 3885 (lambda (vector::vector k ::int) 3886 (invoke vector 'get k))) 3887 3888 You can also specify properties in the lambda body: 3889 3890 (define (vector-ref vector::vector k ::int) 3891 setter: vector-set! 3892 (invoke vector 'get k)) 3893 389411.3.1 Standard properties 3895-------------------------- 3896 3897‘name’ 3898 The name of a procedure (as a symbol), which is used when the 3899 procedure is printed. 3900‘setter’ 3901 Set the setter procedure associated with the procedure. 3902‘validate-apply’ 3903‘validate-xapply’ 3904 Used during the validation phase of the compiler. 3905‘compile-apply’ 3906 Used during the bytecode-generation phase of the compiler: If we 3907 see a call to a known function with this property, we can emit 3908 custom bytecode for the call. 3909 3910 3911File: kawa.info, Node: Generic procedures, Next: Partial application, Prev: Procedure properties, Up: Procedures 3912 391311.4 Generic (dynamically overloaded) procedures 3914================================================ 3915 3916A “generic procedure” is a collection of “method procedures”. (A 3917"method procedure" is not the same as a Java method, but the terms are 3918related.) You can call a generic procedure, which selects the "closest 3919match" among the component method procedures: I.e. the most specific 3920method procedure that is applicable given the actual arguments. 3921 3922 *Warning:* The current implementation of selecting the "best" 3923 method is not reliable if there is more than one method. It can 3924 select depending on argument count, and it can select between 3925 primitive Java methods. However, selecting between different 3926 Scheme procedures based on parameter types should be considered 3927 experimental. The main problem is we can’t determine the most 3928 specific method, so Kawa just tries the methods in order. 3929 3930 -- Procedure: make-procedure [keyword: value]... method... 3931 Create a generic procedure given the specific methods. You can 3932 also specify property values for the result. 3933 3934 The KEYWORDs specify how the arguments are used. A ‘method:’ 3935 keyword is optional and specifies that the following argument is a 3936 method. A ‘name:’ keyword specifies the name of the resulting 3937 procedure, when used for printing. Unrecognized keywords are used 3938 to set the procedure properties of the result. 3939 (define plus10 (make-procedure foo: 33 name: 'Plus10 3940 method: (lambda (x y) (+ x y 10)) 3941 method: (lambda () 10))) 3942 3943 3944File: kawa.info, Node: Partial application, Prev: Generic procedures, Up: Procedures 3945 394611.5 Partial application 3947======================== 3948 3949 -- Syntax: cut slot-or-expr slot-or-expr* [‘<...>’] 3950 where each SLOT-OR-EXPR is either an EXPRESSION or the literal 3951 symbol ‘<>’. 3952 3953 It is frequently necessary to specialize some of the parameters of 3954 a multi-parameter procedure. For example, from the binary 3955 operation ‘cons’ one might want to obtain the unary operation 3956 ‘(lambda (x) (cons 1 x))’. This specialization of parameters is 3957 also known as “partial application”, “operator section”, or 3958 “projection”. The macro ‘cut’ specializes some of the parameters 3959 of its first argument. The parameters that are to show up as 3960 formal variables of the result are indicated by the symbol ‘<>’, 3961 pronouced as "slot". In addition, the symbol ‘<...>’, pronounced 3962 as "rest-slot", matches all residual arguments of a variable 3963 argument procedure. 3964 3965 A ‘cut’-expression is transformed into a LAMBDA EXPRESSION with as 3966 many formal variables as there are slots in the list SLOT-OR-EXPR*. 3967 The body of the resulting LAMBDA EXPRESSION calls the first 3968 SLOT-OR-EXPR with arguments from the SLOT-OR-EXPR* list in the 3969 order they appear. In case there is a rest-slot symbol, the 3970 resulting procedure is also of variable arity, and the body calls 3971 the first SLOT-OR-EXPR with remaining arguments provided to the 3972 actual call of the specialized procedure. 3973 3974 Here are some examples: 3975 3976 ‘(cut cons (+ a 1) <>)’ is the same as 3977 ‘(lambda (x2) (cons (+ a 1) x2))’ 3978 3979 ‘(cut list 1 <> 3 <> 5)’ is the same as 3980 ‘(lambda (x2 x4) (list 1 x2 3 x4 5))’ 3981 3982 ‘(cut list)’ is the same as ‘(lambda () (list))’ 3983 3984 ‘(cut list 1 <> 3 <...>)’ is the same as 3985 ‘(lambda (x2 . xs) (apply list 1 x2 3 xs))’ 3986 3987 The first argument can also be a slot, as one should expect in 3988 Scheme: ‘(cut <> a b)’ is the same as ‘(lambda (f) (f a b))’ 3989 3990 -- Syntax: cute slot-or-expr slot-or-expr* [‘<...>’] 3991 The macro ‘cute’ (a mnemonic for "cut with evaluated non-slots") is 3992 similar to ‘cut’, but it evaluates the non-slot expressions at the 3993 time the procedure is specialized, not at the time the specialized 3994 procedure is called. 3995 3996 For example ‘(cute cons (+ a 1) <>)’ is the same as 3997 ‘(let ((a1 (+ a 1))) (lambda (x2) (cons a1 x2)))’ 3998 3999 As you see from comparing this example with the first example 4000 above, the ‘cute’-variant will evaluate ‘(+ a 1)’ once, while the 4001 ‘cut’-variant will evaluate it during every invocation of the 4002 resulting procedure. 4003 4004 4005File: kawa.info, Node: Numbers, Next: Characters and text, Prev: Procedures, Up: Top 4006 400712 Quantities and Numbers 4008************************* 4009 4010Kawa supports the full Scheme set of number operations with some 4011extensions. 4012 4013 Kawa converts between Scheme number types and Java number types as 4014appropriate. 4015 4016* Menu: 4017 4018* Numerical types:: 4019* Arithmetic operations:: 4020* Numerical input and output:: 4021* Quaternions:: 4022* Quantities:: 4023* Logical Number Operations:: 4024* Performance of numeric operations:: 4025 4026 4027File: kawa.info, Node: Numerical types, Next: Arithmetic operations, Up: Numbers 4028 402912.1 Numerical types 4030==================== 4031 4032Mathematically, numbers are arranged into a tower of subtypes in which 4033each level is a subset of the level before it: number; complex number; 4034real number; rational number; integer. 4035 4036 For example, ‘3’ is an integer. Therefore ‘3’ is also a rational, a 4037real, and a complex number. The same is true of the Scheme numbers that 4038model 3. For Scheme numbers, these types are defined by the predicates 4039‘number?’, ‘complex?’, ‘real?’, ‘rational?’, and ‘integer?’. 4040 4041 There is no simple relationship between a number’s type and its 4042representation inside a computer. Although most implementations of 4043Scheme will offer at least two different representations of 3, these 4044different representations denote the same integer. 4045 4046 Scheme’s numerical operations treat numbers as abstract data, as 4047independent of their representation as possible. Although an 4048implementation of Scheme may use multiple internal representations of 4049numbers, this ought not to be apparent to a casual programmer writing 4050simple programs. 4051 4052 -- Type: number 4053 The type of Scheme numbers. 4054 4055 -- Type: quantity 4056 The type of quantities optionally with units. This is a sub-type 4057 of ‘number’. 4058 4059 -- Type: complex 4060 The type of complex numbers. This is a sub-type of ‘quantity’. 4061 4062 -- Type: real 4063 The type of real numbers. This is a sub-type of ‘complex’. 4064 4065 -- Type: rational 4066 The type of exact rational numbers. This is a sub-type of ‘real’. 4067 4068 -- Type: integer 4069 The type of exact Scheme integers. This is a sub-type of 4070 ‘rational’. 4071 4072 Kawa allows working with expressions of “primitive” types, which are 4073supported by the JVM without object allocation, and using builtin 4074arithmetic. Using these types may be much faster, assuming the compiler 4075is able to infer that the variable or expression has primitive type. 4076 4077 -- Type: long 4078 -- Type: int 4079 -- Type: short 4080 -- Type: byte 4081 These are fixed-sized primitive signed exact integer types, of 4082 respectively 64, 32, 18, and 8 bits. If a value of one of these 4083 types needs to be converted to an object, the standard classes 4084 ‘java.lang.Long’, ‘java.lang.Integer’, ‘java.lang.Short’, or 4085 ‘java.lang.Byte’, respectively, are used. 4086 4087 -- Type: ulong 4088 -- Type: uint 4089 -- Type: ushort 4090 -- Type: ubyte 4091 These are fixed-sized primitive unsigned exact integer types, of 4092 respectively 64, 32, 18, and 8 bits. These are presented at 4093 runtime using the corresponding signed types (‘long’, ‘int’, 4094 ‘short’, or ‘byte’). However, for arithmetic the Kawa compiler 4095 generates code to perform the “mathematically correct” result, 4096 truncated to an unsigned result rather than signed. If a value of 4097 one of these types needs to be converted to an object, the classes 4098 ‘gnu.math.ULong’, ‘gnu.math.UInt’, ‘gnu.math.UShort’, or 4099 ‘gnu.math.UByte’ is used. 4100 4101 -- Type: double 4102 -- Type: float 4103 These are fixed-size primitive inexact floating-point real types, 4104 using the standard 64-bit or 32-bit IEEE representation. If a 4105 value of one of these types needs to be converted to an object, the 4106 standard classes ‘java.lang.Double’, or ‘java.lang.Float’ is used. 4107 410812.1.1 Exactness 4109---------------- 4110 4111It is useful to distinguish between numbers that are represented exactly 4112and those that might not be. For example, indexes into data structures 4113must be known exactly, as must some polynomial coefficients in a 4114symbolic algebra system. On the other hand, the results of measurements 4115are inherently inexact, and irrational numbers may be approximated by 4116rational and therefore inexact approximations. In order to catch uses 4117of inexact numbers where exact numbers are required, Scheme explicitly 4118distinguishes exact from inexact numbers. This distinction is 4119orthogonal to the dimension of type. 4120 4121 A Scheme number is “exact” if it was written as an exact constant or 4122was derived from exact numbers using only exact operations. A number is 4123“inexact” if it was written as an inexact constant, if it was derived 4124using inexact ingredients, or if it was derived using inexact 4125operations. Thus inexactness is a contagious property of a number. In 4126particular, an “exact complex number” has an exact real part and an 4127exact imaginary part; all other complex numbers are “inexact complex 4128numbers”. 4129 4130 If two implementations produce exact results for a computation that 4131did not involve inexact intermediate results, the two ultimate results 4132will be mathematically equal. This is generally not true of 4133computations involving inexact numbers since approximate methods such as 4134floating-point arithmetic may be used, but it is the duty of the 4135implementation to make the result as close as practical to the 4136mathematically ideal result. 4137 4138 Rational operations such as ‘+’ should always produce exact results 4139when given exact arguments. If the operation is unable to produce an 4140exact result, then it may either report the violation of an 4141implementation restriction or it may silently coerce its result to an 4142inexact value. 4143 4144 Except for ‘exact’, the operations described in this section must 4145generally return inexact results when given any inexact arguments. An 4146operation may, however, return an exact result if it can prove that the 4147value of the result is unaffected by the inexactness of its arguments. 4148For example, multiplication of any number by an exact zero may produce 4149an exact zero result, even if the other argument is inexact. 4150 4151 Specifically, the expression ‘(* 0 +inf.0)’ may return ‘0’, or 4152‘+nan.0’, or report that inexact numbers are not supported, or report 4153that non-rational real numbers are not supported, or fail silently or 4154noisily in other implementation-specific ways. 4155 4156 The procedures listed below will always return exact integer results 4157provided all their arguments are exact integers and the mathematically 4158expected results are representable as exact integers within the 4159implementation: ‘-’, ‘*’, ‘+’, ‘abs’, ‘ceiling’, ‘denominator’, 4160‘exact-integer-sqrt’, ‘expt’, ‘floor’, ‘floor/’, ‘floor-quotient’, 4161‘floor-remainder’, ‘gcd’, ‘lcm’, ‘max’, ‘min’, ‘modulo’, ‘numerator’, 4162‘quotient’, ‘rationalize’, ‘remainder’, ‘square’, ‘truncate’, 4163‘truncate/’, ‘truncate-quotient’, ‘truncate-remainder’. 4164 416512.1.2 Numerical promotion and conversion 4166----------------------------------------- 4167 4168When combining two values of different numeric types, the values are 4169converted to the first line in the following that subsumes (follows) 4170both types. The computation is done using values of that type, and so 4171is the result. For example adding a ‘long’ and a ‘float’ converts the 4172former to the latter, yielding a ‘float’. 4173 4174 Note that ‘short’, ‘byte’, ‘ushort’, ‘ubyte’ are converted to ‘int’ 4175regardless, even in the case of a single-operand operation, such as 4176unary negation. Another exception is trancendental functions (such as 4177‘cos’), where integer operands are converted to ‘double’. 4178 4179 • ‘int’ subsumes ‘short’, ‘byte’, ‘ushort’, ‘ubyte’. 4180 • ‘uint’ 4181 • ‘long’ 4182 • ‘ulong’ 4183 • ‘java.lang.BigInteger’ 4184 • ‘integer’ (i.e. ‘gnu.math.IntNum’) 4185 • ‘rational’ (i.e. ‘gnu.math.RatNum’) 4186 • ‘float’ 4187 • ‘double’ 4188 • ‘gnu.math.FloNum’ 4189 • ‘real’ (i.e. ‘gnu.math.RealNum’) 4190 • ‘number’ 4191 • ‘complex’ 4192 • ‘quantity’ 4193 4194 When comparing a primitive signed integer value with a primitive 4195unsigned integer (for example ‘<’ applied to a ‘int’ and a ‘ulong’) the 4196mathemically correct result is computed, as it converting both operands 4197to ‘integer’. 4198 4199 4200File: kawa.info, Node: Arithmetic operations, Next: Numerical input and output, Prev: Numerical types, Up: Numbers 4201 420212.2 Arithmetic operations 4203========================== 4204 4205 -- Procedure: real-valued? OBJ 4206 -- Procedure: rational-valued? OBJ 4207 -- Procedure: integer-valued? OBJ 4208 These numerical type predicates can be applied to any kind of 4209 argument. The ‘real-valued?’ procedure returns ‘#t’ if the object 4210 is a number object and is equal in the sense of ‘=’ to some real 4211 number object, or if the object is a NaN, or a complex number 4212 object whose real part is a NaN and whose imaginary part is zero in 4213 the sense of ‘zero?’. The ‘rational-valued?’ and ‘integer-valued?’ 4214 procedures return ‘#t’ if the object is a number object and is 4215 equal in the sense of ‘=’ to some object of the named type, and 4216 otherwise they return ‘#f’. 4217 4218 (real-valued? +nan.0) ⇒ #t 4219 (real-valued? +nan.0+0i) ⇒ #t 4220 (real-valued? -inf.0) ⇒ #t 4221 (real-valued? 3) ⇒ #t 4222 (real-valued? -2.5+0.0i) ⇒ #t 4223 4224 (real-valued? -2.5+0i) ⇒ #t 4225 (real-valued? -2.5) ⇒ #t 4226 (real-valued? #e1e10) ⇒ #t 4227 4228 (rational-valued? +nan.0) ⇒ #f 4229 (rational-valued? -inf.0) ⇒ #f 4230 (rational-valued? 6/10) ⇒ #t 4231 (rational-valued? 6/10+0.0i) ⇒ #t 4232 (rational-valued? 6/10+0i) ⇒ #t 4233 (rational-valued? 6/3) ⇒ #t 4234 4235 (integer-valued? 3+0i) ⇒ #t 4236 (integer-valued? 3+0.0i) ⇒ #t 4237 (integer-valued? 3.0) ⇒ #t 4238 (integer-valued? 3.0+0.0i) ⇒ #t 4239 (integer-valued? 8/4) ⇒ #t 4240 4241 _Note:_ These procedures test whether a given number object 4242 can be coerced to the specified type without loss of numerical 4243 accuracy. Specifically, the behavior of these predicates 4244 differs from the behavior of ‘real?’, ‘rational?’, and 4245 ‘integer?’ on complex number objects whose imaginary part is 4246 inexact zero. 4247 4248 _Note:_ The behavior of these type predicates on inexact 4249 number objects is unreliable, because any inaccuracy may 4250 affect the result. 4251 4252 -- Procedure: exact-integer? z 4253 Returns ‘#t’ if Z is both exact and an integer; otherwise returns 4254 ‘#f’. 4255 (exact-integer? 32) ⇒ #t 4256 (exact-integer? 32.0) ⇒ #t 4257 (exact-integer? 32/5) ⇒ #f 4258 4259 -- Procedure: finite? Z 4260 Returns ‘#t’ if Z is finite real number (i.e. an infinity and not 4261 a NaN), or if Z is a complex number whose real and imaginary parts 4262 are both finite. 4263 (finite? 3) ⇒ #t 4264 (finite? +inf.0) ⇒ #f 4265 (finite? 3.0+inf.0i) ⇒ #f 4266 4267 -- Procedure: infinite? Z 4268 Return ‘#t’ if Z is an infinite real number (‘+int.0’ or ‘-inf.0’), 4269 or if Z is a complex number where either real or imaginary parts or 4270 both are infinite. 4271 (infinite? 5.0) ⇒ #f 4272 (infinite? +inf.0) ⇒ #t 4273 (infinite? +nan.0) ⇒ #f 4274 (infinite? 3.0+inf.0i) ⇒ #t 4275 4276 -- Procedure: nan? Z 4277 For a real numer returns whether its is a NaN; for a complex number 4278 if the real or imaginary parts or both is a NaN. 4279 (nan? +nan.0) ⇒ #t 4280 (nan? 32) ⇒ #f 4281 (nan? +nan.0+5.0i) ⇒ #t 4282 (nan? 1+2i) ⇒ #f 4283 4284 -- Procedure: + Z ... 4285 -- Procedure: * Z ... 4286 These procedures return the sum or product of their arguments. 4287 4288 (+ 3 4) ⇒ 7 4289 (+ 3) ⇒ 3 4290 (+) ⇒ 0 4291 (+ +inf.0 +inf.0) ⇒ +inf.0 4292 (+ +inf.0 -inf.0) ⇒ +nan.0 4293 4294 (* 4) ⇒ 4 4295 (*) ⇒ 1 4296 (* 5 +inf.0) ⇒ +inf.0 4297 (* -5 +inf.0) ⇒ -inf.0 4298 (* +inf.0 +inf.0) ⇒ +inf.0 4299 (* +inf.0 -inf.0) ⇒ -inf.0 4300 (* 0 +inf.0) ⇒ +nan.0 4301 (* 0 +nan.0) ⇒ +nan.0 4302 (* 1.0 0) ⇒ 0.0 4303 4304 For any real number object X that is neither infinite nor NaN: 4305 4306 (+ +inf.0 X) ⇒ +inf.0 4307 (+ -inf.0 X) ⇒ -inf.0 4308 4309 For any real number object X: 4310 4311 (+ +nan.0 X) ⇒ +nan.0 4312 4313 For any real number object X that is not an exact 0: 4314 4315 (* +nan.0 X) ⇒ +nan.0 4316 4317 The behavior of ‘-0.0’ is illustrated by the following examples: 4318 4319 (+ 0.0 -0.0) ⇒ 0.0 4320 (+ -0.0 0.0) ⇒ 0.0 4321 (+ 0.0 0.0) ⇒ 0.0 4322 (+ -0.0 -0.0) ⇒ -0.0 4323 4324 -- Procedure: - Z 4325 -- Procedure: - Z1 Z2 Z3 ... 4326 With two or more arguments, this procedures returns the difference 4327 of its arguments, associating to the left. With one argument, 4328 however, it returns the negation (additive inverse) of its 4329 argument. 4330 4331 (- 3 4) ⇒ -1 4332 (- 3 4 5) ⇒ -6 4333 (- 3) ⇒ -3 4334 (- +inf.0 +inf.0) ⇒ +nan.0 4335 4336 The behavior of ‘-0.0’ is illustrated by the following examples: 4337 4338 (- 0.0) ⇒ -0.0 4339 (- -0.0) ⇒ 0.0 4340 (- 0.0 -0.0) ⇒ 0.0 4341 (- -0.0 0.0) ⇒ -0.0 4342 (- 0.0 0.0) ⇒ 0.0 4343 (- -0.0 -0.0) ⇒ 0.0 4344 4345 -- Procedure: / Z 4346 -- Procedure: / Z1 Z2 Z3 ... 4347 If all of the arguments are exact, then the divisors must all be 4348 nonzero. With two or more arguments, this procedure returns the 4349 quotient of its arguments, associating to the left. With one 4350 argument, however, it returns the multiplicative inverse of its 4351 argument. 4352 4353 (/ 3 4 5) ⇒ 3/20 4354 (/ 3) ⇒ 1/3 4355 (/ 0.0) ⇒ +inf.0 4356 (/ 1.0 0) ⇒ +inf.0 4357 (/ -1 0.0) ⇒ -inf.0 4358 (/ +inf.0) ⇒ 0.0 4359 (/ 0 0) ⇒ exception &assertion 4360 (/ 3 0) ⇒ exception &assertion 4361 (/ 0 3.5) ⇒ 0.0 4362 (/ 0 0.0) ⇒ +nan.0 4363 (/ 0.0 0) ⇒ +nan.0 4364 (/ 0.0 0.0) ⇒ +nan.0 4365 4366 If this procedure is applied to mixed non–rational real and 4367 non–real complex arguments, it either raises an exception with 4368 condition type ‘&implementation-restriction’ or returns an 4369 unspecified number object. 4370 4371 -- Procedure: floor/ x y 4372 -- Procedure: truncate/ x y 4373 -- Procedure: div-and-mod x y 4374 -- Procedure: div0-and-mod0 x y 4375 These procedures implement number–theoretic integer division. They 4376 accept two real numbers X and Y as operands, where Y must be 4377 nonzero. In all cases the result is two values Q (an integer) and 4378 R (a real) that satisfy the equations: 4379 X = Q * Y + R 4380 Q = ROUNDING-OP(X/Y) 4381 The result is inexact if either argument is inexact. 4382 4383 For ‘floor/’ the ROUNDING-OP is the ‘floor’ function (below). 4384 (floor/ 123 10) ⇒ 12 3 4385 (floor/ 123 -10) ⇒ -13 -7 4386 (floor/ -123 10) ⇒ -13 7 4387 (floor/ -123 -10) ⇒ 12 -3 4388 4389 For ‘truncate/’ the ROUNDING-OP is the ‘truncate’ function. 4390 (truncate/ 123 10) ⇒ 12 3 4391 (truncate/ 123 -10) ⇒ -12 3 4392 (truncate/ -123 10) ⇒ -12 -3 4393 (truncate/ -123 -10) ⇒ 12 -3 4394 4395 For ‘div-and-mod’ the ROUNDING-OP is either ‘floor’ (if Y is 4396 positive) or ‘ceiling’ (if Y is negative). We have: 4397 0 <= R < |Y| 4398 (div-and-mod 123 10) ⇒ 12 3 4399 (div-and-mod 123 -10) ⇒ -12 3 4400 (div-and-mod -123 10) ⇒ -13 7 4401 (div-and-mod -123 -10) ⇒ 13 7 4402 4403 For ‘div0-and-mod0’ the ROUNDING-OP is the ‘round’ function, and 4404 ‘r’ lies within a half–open interval centered on zero. 4405 -|Y/2| <= R < |Y/2| 4406 4407 (div0-and-mod0 123 10) ⇒ 12 3 4408 (div0-and-mod0 123 -10) ⇒ -12 3 4409 (div0-and-mod0 -123 10) ⇒ -12 -3 4410 (div0-and-mod0 -123 -10) ⇒ 12 -3 4411 (div0-and-mod0 127 10) ⇒ 13 -3 4412 (div0-and-mod0 127 -10) ⇒ -13 -3 4413 (div0-and-mod0 -127 10) ⇒ -13 3 4414 (div0-and-mod0 -127 -10) ⇒ 13 3 4415 4416 The inconsistent naming is for historical reasons: ‘div-and-mod’ 4417 and ‘div0-and-mod0’ are from R6RS, while ‘floor/’ and ‘truncate/’ 4418 are from R7RS. 4419 4420 -- Procedure: floor-quotient x y 4421 -- Procedure: truncate-quotient x y 4422 -- Procedure: div x y 4423 -- Procedure: div0 x y 4424 These procedures return the quotient part (first value) of 4425 respectively ‘floor/’, ‘truncate/’, ‘div-and-mod’, and 4426 ‘div0-and-mod0’. 4427 4428 -- Procedure: floor-remainder x y 4429 -- Procedure: truncate-remainder x y 4430 -- Procedure: mod x y 4431 -- Procedure: mod0 x y 4432 These procedures return the remainder part (second value) of 4433 respectively ‘floor/’, ‘truncate/’, ‘div-and-mod’, and 4434 ‘div0-and-mod0’. 4435 4436 As a Kawa extension Y may be zero, in which case the result is X: 4437 (mod 123 0) ⇒ 123 ;; Kawa extension 4438 4439 -- Procedure: quotient x y 4440 -- Procedure: remainder x y 4441 -- Procedure: modulo x y 4442 These are equivalent to ‘truncate-quotient’, ‘truncate-remainder’, 4443 and ‘floor-remainder’, respectively. These are provided for 4444 backward compatibility. 4445 (remainder 13 4) ⇒ 1 4446 (remainder -13 4) ⇒ -1 4447 (remainder 13 -4) ⇒ 1 4448 (remainder -13 -4) ⇒ -1 4449 (remainder -13 -4.0) ⇒ -1.0 4450 (modulo 13 4) ⇒ 1 4451 (modulo -13 4) ⇒ 3 4452 (modulo 13 -4) ⇒ -4 4453 (modulo -13 -4) ⇒ -1 4454 4455 -- Procedure: abs X 4456 Returns the absolute value of its argument. 4457 4458 (abs -7) ⇒ 7 4459 (abs -inf.0) ⇒ +inf.0 4460 4461 -- Procedure: gcd N1 ... 4462 -- Procedure: lcm N1 ... 4463 These procedures return the greatest common divisor or least common 4464 multiple of their arguments. The result is always non–negative. 4465 The arguments must be integers; if an argument is inexact, so is 4466 the result. 4467 4468 (gcd 32 -36) ⇒ 4 4469 (gcd) ⇒ 0 4470 (lcm 32 -36) ⇒ 288 4471 (lcm 32.0 -36) ⇒ 288.0 ; inexact 4472 (lcm) ⇒ 1 4473 4474 -- Procedure: numerator Q 4475 -- Procedure: denominator Q 4476 These procedures return the numerator or denominator of their 4477 argument; the result is computed as if the argument was represented 4478 as a fraction in lowest terms. The denominator is always positive. 4479 The denominator of ‘0’ is defined to be ‘1’. The arguments must be 4480 integers; if an argument is inexact, so is the result. 4481 4482 (numerator (/ 6 4)) ⇒ 3 4483 (denominator (/ 6 4)) ⇒ 2 4484 (denominator (inexact (/ 6 4))) ⇒ 2.0 4485 4486 -- Procedure: floor X 4487 -- Procedure: ceiling X 4488 -- Procedure: truncate X 4489 -- Procedure: round X 4490 These procedures return inexact integer objects for inexact 4491 arguments that are not infinities or NaNs, and exact integer 4492 objects for exact rational arguments. 4493 4494 ‘floor’ 4495 Returns the largest integer object not larger than X. 4496 4497 ‘ceiling’ 4498 Returns the smallest integer object not smaller than X. 4499 ‘truncate’ 4500 Returns the integer object closest to X whose absolute value 4501 is not larger than the absolute value of X. 4502 4503 ‘round’ 4504 Returns the closest integer object to X, rounding to even when 4505 X represents a number halfway between two integers. 4506 4507 If the argument to one of these procedures is inexact, then the 4508 result is also inexact. If an exact value is needed, the result 4509 should be passed to the ‘exact’ procedure. 4510 4511 Although infinities and NaNs are not integer objects, these 4512 procedures return an infinity when given an infinity as an 4513 argument, and a NaN when given a NaN. 4514 4515 (floor -4.3) ⇒ -5.0 4516 (ceiling -4.3) ⇒ -4.0 4517 (truncate -4.3) ⇒ -4.0 4518 (round -4.3) ⇒ -4.0 4519 4520 (floor 3.5) ⇒ 3.0 4521 (ceiling 3.5) ⇒ 4.0 4522 (truncate 3.5) ⇒ 3.0 4523 (round 3.5) ⇒ 4.0 4524 4525 (round 7/2) ⇒ 4 4526 (round 7) ⇒ 7 4527 4528 (floor +inf.0) ⇒ +inf.0 4529 (ceiling -inf.0) ⇒ -inf.0 4530 (round +nan.0) ⇒ +nan.0 4531 4532 -- Procedure: rationalize X1 X2 4533 The ‘rationalize’ procedure returns a number object representing 4534 the _simplest_ rational number differing from X1 by no more than 4535 X2. 4536 4537 A rational number _r_1_ is _simpler_ than another rational number 4538 _r_2_ if ‘r_1 = p_1/q_1’ and ‘r_2 = p_2/q_2’ (in lowest terms) and 4539 ‘|p_1| <= |p_2|’ and ‘|q_1| <= |q_2|’. Thus ‘3/5’ is simpler than 4540 ‘4/7’. 4541 4542 Although not all rationals are comparable in this ordering 4543 (consider ‘2/7’ and ‘3/5’) any interval contains a rational number 4544 that is simpler than every other rational number in that interval 4545 (the simpler ‘2/5’ lies between ‘2/7’ and ‘3/5’). 4546 4547 Note that ‘0 = 0/1’ is the simplest rational of all. 4548 (rationalize (exact .3) 1/10) ⇒ 1/3 4549 (rationalize .3 1/10) ⇒ #i1/3 ; approximately 4550 4551 (rationalize +inf.0 3) ⇒ +inf.0 4552 (rationalize +inf.0 +inf.0) ⇒ +nan.0 4553 4554 The first two examples hold only in implementations whose inexact 4555 real number objects have sufficient precision. 4556 4557 -- Procedure: exp Z 4558 -- Procedure: log Z 4559 -- Procedure: log Z1 Z2 4560 -- Procedure: sin Z 4561 -- Procedure: cos Z 4562 -- Procedure: tan Z 4563 -- Procedure: asin Z 4564 -- Procedure: acos Z 4565 -- Procedure: atan Z 4566 -- Procedure: atan X1 X2 4567 These procedures compute the usual transcendental functions. 4568 4569 The ‘exp’ procedure computes the base–E exponential of Z. The 4570 ‘log’ procedure with a single argument computes the natural 4571 logarithm of Z (*not* the base–10 logarithm); ‘(log Z1 Z2)’ 4572 computes the base–Z2 logarithm of Z1. 4573 4574 The ‘asin’, ‘acos’, and ‘atan’ procedures compute arcsine, 4575 arccosine, and arctangent, respectively. The two–argument variant 4576 of ‘atan’ computes: 4577 4578 (angle (make-rectangular X2 X1)) 4579 4580 These procedures may return inexact results even when given exact 4581 arguments. 4582 (exp +inf.0) ⇒ +inf.0 4583 (exp -inf.0) ⇒ 0.0 4584 (log +inf.0) ⇒ +inf.0 4585 (log 0.0) ⇒ -inf.0 4586 (log 0) ⇒ exception &assertion 4587 (log -inf.0) ⇒ +inf.0+3.141592653589793i ; approximately 4588 (atan -inf.0) ⇒ -1.5707963267948965 ; approximately 4589 (atan +inf.0) ⇒ 1.5707963267948965 ; approximately 4590 (log -1.0+0.0i) ⇒ 0.0+3.141592653589793i ; approximately 4591 (log -1.0-0.0i) ⇒ 0.0-3.141592653589793i ; approximately 4592 ; if -0.0 is distinguished 4593 4594 -- Procedure: sinh z 4595 -- Procedure: cosh z 4596 -- Procedure: tanh z 4597 -- Procedure: asinh z 4598 -- Procedure: acosh z 4599 -- Procedure: atanh z 4600 The hyperbolic functions. 4601 4602 -- Procedure: square z 4603 Returns the square of Z. This is equivalent to ‘(* Z Z)’. 4604 (square 42) ⇒ 1764 4605 (square 2.0) ⇒ 4.0 4606 4607 -- Procedure: sqrt Z 4608 Returns the principal square root of Z. For rational Z, the result 4609 has either positive real part, or zero real part and non–negative 4610 imaginary part. The value of ‘(sqrt Z)’ could be expressed as: 4611 4612 e^((log z)/2) 4613 4614 The ‘sqrt’ procedure may return an inexact result even when given 4615 an exact argument. 4616 4617 (sqrt -5) ⇒ 0.0+2.23606797749979i ; approximately 4618 (sqrt +inf.0) ⇒ +inf.0 4619 (sqrt -inf.0) ⇒ +inf.0i 4620 4621 Note that if the argument is a primitive number (such as ‘double’) 4622 or an instance of the corresponding boxed class (such as 4623 ‘java.lang.Double’) then we use the real-number version of ‘sqrt’: 4624 (sqrt (->double -5)) ⇒ NaN 4625 That is, we get different a result for ‘java.lang.Double’ and 4626 ‘gnu.math.DFloNum’, even for arguments that are numerically equal 4627 in the sense of ‘=’. This is so that the compiler can use the 4628 ‘java.lang.Math.sqrt’ method without object allocation when the 4629 argument is a ‘double’ (and because we want ‘double’ and 4630 ‘java.lang.Double’ to behave consistently). 4631 4632 -- Procedure: exact-integer-sqrt K 4633 The ‘exact-integer-sqrt’ procedure returns two non–negative exact 4634 integer objects _s_ and _r_ where ‘K = s^2 + r’ and ‘K < (s+1)^2’. 4635 4636 (exact-integer-sqrt 4) ⇒ 2 0 ; two return values 4637 (exact-integer-sqrt 5) ⇒ 2 1 ; two return values 4638 4639 -- Procedure: expt Z1 Z2 4640 Returns Z1 raised to the power Z2. For nonzero Z1, this is Z1^{Z2} 4641 = E^{Z2 log Z1}. The value of 0^{Z} is 1 if ‘(zero? Z)’, 0 if 4642 ‘(real-part Z)’ is positive, and an error otherwise. Similarly for 4643 0.0^{z}, with inexact results. 4644 4645 4646File: kawa.info, Node: Numerical input and output, Next: Quaternions, Prev: Arithmetic operations, Up: Numbers 4647 464812.3 Numerical input and output 4649=============================== 4650 4651 -- Procedure: number->string z [radix] 4652 4653 The procedure ‘number->string’ takes a number and a radix and 4654 returns as a string an external representation of the given number 4655 in the given radix such that 4656 (let ((number number) 4657 (radix radix)) 4658 (eqv? number 4659 (string->number (number->string number radix) 4660 radix))) 4661 is true. It is an error if no possible result makes this 4662 expression true. 4663 4664 If present, RADIX must be an exact integer in the range 2 to 36, 4665 inclusive. If omitted, RADIX defaults to 10. 4666 4667 If Z is inexact, the RADIX is 10, and the above expression can be 4668 satisfied by a result that contains a decimal point, then the 4669 result contains a decimal point and is expressed using the minimum 4670 number of digits (exclusive of exponent and trailing zeroes) needed 4671 to make the above expression; otherwise the format of the result is 4672 unspecified. 4673 4674 The result returned by ‘number->string’ never contains an explicit 4675 radix prefix. 4676 4677 _Note:_ The error case can occur only when Z is not a complex 4678 number or is a complex number with a non-rational real or imaginary 4679 part. 4680 4681 _Rationale:_ If Z is an inexact number and the RADIX is 10, then 4682 the above expression is normally satisfied by a result containing a 4683 decimal point. The unspecified case allows for infinities, NaNs, 4684 and unusual representations. 4685 4686 -- Procedure: string->number string [radix] 4687 Returns a number of the maximally precise representation expressed 4688 by the given STRING. It is an error if RADIX is not an exact 4689 integer in the range 2 to 26, inclusive. 4690 4691 If supplied, RADIX is a default radix that will be overridden if an 4692 explicit radix prefix is present in the string (e.g. ‘"#o177"’). 4693 If RADIX is not supplied, then the default RADIX is 10. If STRING 4694 is not a syntactically valid notation for a number, or would result 4695 in a number that the implementation cannot represent, then 4696 ‘string->number’ returns ‘#f’. An error is never signaled due to 4697 the content of STRING. 4698 4699 (string->number "100") ⇒ 100 4700 (string->number "100" 16) ⇒ 256 4701 (string->number "1e2") ⇒ 100.0 4702 (string->number "#x100" 10) ⇒ 256 4703 4704 4705File: kawa.info, Node: Quaternions, Next: Quantities, Prev: Numerical input and output, Up: Numbers 4706 470712.4 Quaternions 4708================ 4709 4710Kawa extends the Scheme numeric tower to include quaternions 4711(http://en.wikipedia.org/wiki/Quaternion) as a proper superset of the 4712complex numbers. Quaternions provide a convenient notation to represent 4713rotations in three-dimensional space 4714(http://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation), and are 4715therefore commonly found in applications such as computer graphics, 4716robotics, and spacecraft engineering. The Kawa quaternion API is 4717modeled after this (http://www.ccs.neu.edu/home/dorai/squat/squat.html) 4718with some additions. 4719 4720 A quaternion is a number that can be expressed in the form 4721‘w+xi+yj+zk’, where ‘w’, ‘x’, ‘y’, and ‘z’ are real, and ‘i’, ‘j’, and 4722‘k’ are imaginary units satisfying i^{2} = j^{2} = k^{2} = ijk = -1. 4723The magnitude of a quaternion is defined to be its Euclidean norm when 4724viewed as a point in R^{4}. 4725 4726 The real–part of a quaternion is also called its ‘scalar’, while the 4727i–part, j–part, and k–part taken together are also called its ‘vector’. 4728A quaternion with zero j–part and k–part is an ordinary complex number. 4729(If the i–part is also zero, then it is a real). A quaternion with zero 4730real–part is called a ‘vector quaternion’. 4731 4732 The reader syntax for number literals has been extended to support 4733both rectangular and polar (hyperspherical) notation for quaternions. 4734The rectangular notation is as above, i.e. ‘w+xi+yj+zk’. The polar 4735notation takes the form ‘r@t%u&v’, where ‘r’ is the magnitude, ‘t’ is 4736the first angle, and ‘u’ and ‘v’ are two other angles called the 4737“colatitude” and “longitude”. 4738 4739 The rectangular coordinates and polar coordinates are related by the 4740equations: 4741 W = R * cos T 4742 X = R * sin T * cos U 4743 Y = R * sin T * sin U * cos V 4744 Z = R * sin T * sin U * sin V 4745 With either notation, zero elements may be omitted. 4746 4747 -- Procedure: make-rectangular W X 4748 -- Procedure: make-rectangular W X Y Z 4749 These procedures construct quaternions from Cartesian coordinates. 4750 4751 -- Procedure: make-polar R T 4752 -- Procedure: make-polar R T U V 4753 These procedures construct quaternions from polar coordinates. 4754 4755 -- Procedure: + Q ... 4756 -- Procedure: - Q ... 4757 -- Procedure: * Q ... 4758 -- Procedure: / Q 4759 -- Procedure: / Q1 Q2 Q3 ... 4760 -- Procedure: expt Q1 Q2 4761 -- Procedure: exp Q 4762 -- Procedure: log Q 4763 -- Procedure: sqrt Q 4764 -- Procedure: sin Q 4765 -- Procedure: cos Q 4766 -- Procedure: tan Q 4767 -- Procedure: asin Q 4768 -- Procedure: acos Q 4769 -- Procedure: atan Q 4770 All of the arithmetic and transcendental functions defined for 4771 complex arguments have been extended to support quaternions. 4772 4773 Quaternion multiplication is not commutative, so there are two 4774 possible interpretations of ‘(/ q1 q2)’ which would yield different 4775 results: either ‘(* q1 (/ q2))’, or ‘(* (/ q2) q1)’. Division in 4776 this implementation has been defined such that ‘(/ q1 q2 ...)’ is 4777 equivalent to ‘(* q1 (/ q2) ...)’, but it is recommended to use 4778 reciprocals (unary ‘/’) and multiplication. 4779 4780 -- Procedure: real-part Q 4781 Return the real–part of Q. 4782 4783 (real-part 0) ⇒ 0 4784 (real-part -i) ⇒ 0 4785 (real-part 1+2i-3j+4k) ⇒ 1 4786 4787 -- Procedure: imag-part Q 4788 Return the i–part of Q. 4789 4790 (imag-part 0) ⇒ 0 4791 (imag-part -i) ⇒ -1 4792 (imag-part 1+2i-3j+4k) ⇒ 2 4793 4794 -- Procedure: magnitude Q 4795 Return the Euclidean norm of Q. If Q is ‘a+bi+cj+dk’, then 4796 ‘(magnitude q)’ is ‘(sqrt (apply + (map square (list a b c d))))’ 4797 4798 -- Procedure: angle Q 4799 Return the angle of Q. 4800 480112.4.1 The ‘(kawa quaternions)’ module 4802-------------------------------------- 4803 4804The following additional functionality is made available by doing one 4805of: 4806 (require 'quaternions) ;; or 4807 (import (kawa quaternions)) 4808 4809 -- Alias: quaternion 4810 An alias for ‘gnu.math.Quaternion’, useful for type declarations. 4811 -- Procedure: quaternion? X 4812 Return ‘#t’ if X is a quaternion, i.e. an ordinary number, and 4813 ‘#f’ otherwise. 4814 4815 (quaternion? 0) ⇒ #t 4816 (quaternion? -i) ⇒ #t 4817 (quaternion? 1+2i-3j+4k) ⇒ #t 4818 (quaternion? 10.0m) ⇒ #f 4819 (quaternion? "x") ⇒ #f 4820 4821 -- Procedure: jmag-part Q 4822 Return the j–part of Q. 4823 4824 (jmag-part 0) ⇒ 0 4825 (jmag-part -i) ⇒ 0 4826 (jmag-part 1+2i-3j+4k) ⇒ -3 4827 -- Procedure: kmag-part Q 4828 4829 (kmag-part 0) ⇒ 0 4830 (kmag-part -i) ⇒ 0 4831 (kmag-part 1+2i-3j+4k) ⇒ 4 4832 4833 -- Procedure: complex-part Q 4834 Return the projection of Q into the complex plane: ‘(+ (real-part 4835 q) (* +i (imag-part q)))’ 4836 4837 (complex-part 0) ⇒ 0 4838 (complex-part -i) ⇒ -1i 4839 (complex-part 1+2i-3j+4k) ⇒ 1+2i 4840 -- Procedure: vector-part Q 4841 Return the vector–part of Q. 4842 4843 (vector-part 0) ⇒ 0 4844 (vector-part -i) ⇒ -1i 4845 (vector-part 1+2i-3j+4k) ⇒ +2i-3j+4k 4846 4847 -- Procedure: unit-quaternion Q 4848 Return a quaternion of unit magnitude with the same direction as Q. 4849 If Q is zero, return zero. This is like a 4D version of a signum 4850 function. 4851 4852 (unit-quaternion 0) ⇒ 0 4853 (unit-quaternion -i) ⇒ -1i 4854 (unit-quaternion 1+2i-3j+4k) ⇒ 0.18257418583505536+0.3651483716701107i-0.5477225575051661j+0.7302967433402214k 4855 4856 -- Procedure: unit-vector Q 4857 Return the vector–part of Q, scaled to have magnitude 1. If the 4858 vector–part is zero, then return zero. 4859 4860 (unit-vector 0) ⇒ 0 4861 (unit-vector -i) ⇒ -1i 4862 (unit-vector 1+2i-3j+4k) ⇒ +0.3713906763541037i-0.5570860145311556j+0.7427813527082074k 4863 4864 -- Procedure: colatitude Q 4865 Return the colatitude of Q. 4866 4867 -- Procedure: longitude Q 4868 Return the longitude of Q. 4869 4870 -- Procedure: vector-quaternion? OBJ 4871 Return ‘#t’ if OBJ is a vector quaternion, i.e. a quaternion with 4872 zero real–part. 4873 4874 -- Procedure: make-vector-quaternion X Y Z 4875 Construct vector quaternion ‘xi+yj+zk’. This is equivalent to 4876 ‘(make-rectangular 0 x y z)’. 4877 4878 -- Procedure: vector-quaternion->list VQ 4879 Return a newly allocated list of the x, y, and z components of VQ. 4880 This is equivalent to ‘(list (imag-part vq) (jmag-part vq) 4881 (kmag-part vq))’. 4882 4883 -- Procedure: dot-product Q1 Q2 4884 For two vector quaternions Q1 = ‘ai+bj+ck’ and Q2 = ‘di+ej+fk’, 4885 return ‘ad + be + cf’. This is equal to the R^3 dot product for 4886 vectors (a,b,c) and (d,e,f), and is also equal to ‘(- (real-part (* 4887 q1 q2)))’. It is an error if either Q1 or Q2 has a non-zero 4888 real–part. 4889 4890 -- Procedure: cross-product Q1 Q2 4891 For two vector quaternions Q1 = ‘ai+bj+ck’ and Q2 = ‘di+ej+fk’, 4892 return the R^3 cross product for vectors (a,b,c) and (d,e,f), which 4893 is equal to ‘(vector-part (* q1 q2))’. It is an error if either Q1 4894 or Q2 has a non-zero real–part. 4895 4896 -- Procedure: conjugate Q 4897 Return ‘(+ (real-part q) (* -1 (vector-part q)))’. 4898 4899 (conjugate 0) ⇒ 0 4900 (conjugate -i) ⇒ +1i 4901 (conjugate 1+2i-3j+4k) ⇒ 1-2i+3j-4k 4902 490312.4.2 The ‘(kawa rotations)’ module 4904------------------------------------ 4905 4906The ‘(kawa rotations)’ library provides a set of functions which use 4907unit quaternions to represent 3D spatial rotations. To use these 4908functions, the library must be imported: 4909 (import (kawa rotations)) 4910 4911 These functions normalize their quaternion inputs as needed to be of 4912length 1. 4913 491412.4.2.1 Rotation Representation Conversions 4915............................................ 4916 4917Conversions to and from several alternate representations of rotations 4918are supported. 4919 4920 The set of unit quaternions provides a double covering of all 4921possible 3D rotations: ‘q’ and ‘-q’ represent the same rotation. Most 4922other representations also have multiple numerical values which map to 4923the same rotation (for example, the rotation about ‘axis-vec’ by ‘angle’ 4924is the same as the rotation about ‘-axis-vec’ by ‘-angle+2pi’). 4925Therefore, these functions do not necessarily act as inverses in the 4926sense of ‘equal?’. Furthermore, rotations involve trigonometric 4927functions, so there will typically be some floating point error: ‘(acos 4928(cos 0.1))’ returns 0.09999999999999945, which is very close to 0.1 but 4929not exact. 4930 4931Rotation Matrices 4932................. 4933 4934 -- Procedure: quaternion->rotation-matrix Q 4935 -- Procedure: rotation-matrix->quaternion M 4936 4937 The ‘quaternion->rotation-matrix’ procedure returns a 3x3 rotation 4938 matrix representing the same rotation as Q. The rotation matrix is 4939 instantiated as a *note SRFI-25 multi-dimensional array: Arrays. 4940 backed by an *note f64vector: Uniform vectors. 4941 4942 The ‘rotation-matrix->quaternion’ procedure performs the reverse 4943 operation, producing an equivalent unit quaternion for the rotation 4944 matrix (multi-dimensional array) M. 4945 4946 (rotation-matrix->quaternion (quaternion->rotation-matrix -1)) ⇒ 1.0 4947 4948Axis-Angle Representation 4949......................... 4950 4951 -- Procedure: rotation-axis Q 4952 -- Procedure: rotation-angle Q 4953 -- Procedure: rotation-axis/angle Q 4954 4955 The ‘rotation-axis’ procedure returns the axis of rotation of the 4956 quaternion Q as a unit-length vector quaternion. If the axis of 4957 rotation is not well-defined (the angle of rotation is 0), then 4958 ‘+i’ is arbitrarily chosen as the axis. 4959 4960 The ‘rotation-angle’ procedure returns the corresponding angle of 4961 rotation. Note that this is not the same as the result of the 4962 ‘angle’ procedure. 4963 4964 The ‘rotation-axis/angle’ procedure returns the rotation axis and 4965 angle as multiple values. 4966 4967 (let* ((q 1/2+1/2i+1/2j+1/2k) 4968 (ar (rotation-angle q)) 4969 (ad (java.lang.Math:toDegrees ar)) 4970 (exact-ad (exact ad))) 4971 (rationalize exact-ad 1/10)) ⇒ 120 4972 4973 -- Procedure: make-axis/angle AXIS-VEC ANGLE 4974 -- Procedure: make-axis/angle AXIS-X AXIS-Y AXIS-Z ANGLE 4975 4976 The ‘make-axis/angle’ procedure returns a quaternion representing 4977 the given axis/angle rotation. The axis is specified as either a 4978 single vector quaternion argument AXIS-VEC, or as three reals 4979 AXIS-X, AXIS-Y, and AXIS-Z. 4980 4981 -- Procedure: rotx ANGLE 4982 -- Procedure: roty ANGLE 4983 -- Procedure: rotz ANGLE 4984 4985 The procedures ‘rotx’, ‘roty’, and ‘rotz’ return quaternions 4986 representing rotations about the X-, Y-, and Z-axes. 4987 4988Intrinsic Angle Sets 4989.................... 4990 4991The intrinsic angle sets represent arbitrary rotations as a sequence of 4992three rotations about coordinate frame axes attached to the rotating 4993body (i.e. the axes rotate with the body). 4994 4995 There are twelve possible angle sets which neatly divide into two 4996groups of six. The six with same first and third axes are also known as 4997“Euler angles”. The six with different first and third axes are also 4998known as “Tait-Bryan angles”. 4999 5000 -- Procedure: intrinsic-xyx Q 5001 -- Procedure: intrinsic-xzx Q 5002 -- Procedure: intrinsic-yxy Q 5003 -- Procedure: intrinsic-yzy Q 5004 -- Procedure: intrinsic-zxz Q 5005 -- Procedure: intrinsic-zyz Q 5006 5007 These functions decompose the rotation represented by Q into Euler 5008 angles of the given set (XYX, XZX, YXY, YZY, ZXZ, or ZYZ) and 5009 returns the three angles as multiple values. The middle angle will 5010 be in the range [0,pi]. If it is on the edges of that range 5011 (within 1.0E-12 of 0 or pi), such that the first and third axes are 5012 colinear, then the first angle will be set to 0. 5013 5014 (intrinsic-zyz (* (rotz 0.3) (roty 0.8) (rotz -0.6))) ⇒ 0.3000000000000001 0.7999999999999999 -0.5999999999999999 5015 5016 -- Alias: euler-xyx 5017 -- Alias: euler-xzx 5018 -- Alias: euler-yxy 5019 -- Alias: euler-yzy 5020 -- Alias: euler-zxz 5021 -- Alias: euler-zyz 5022 Aliases for the corresponding ‘intrinsic-’ procedures. 5023 5024 -- Procedure: intrinsic-xyz Q 5025 -- Procedure: intrinsic-xzy Q 5026 -- Procedure: intrinsic-yxz Q 5027 -- Procedure: intrinsic-yzx Q 5028 -- Procedure: intrinsic-zxy Q 5029 -- Procedure: intrinsic-zyx Q 5030 5031 These functions decompose the rotation represented by Q into 5032 Tait-Bryan angles of the given set (XYZ, XZY, YXZ, YZX, ZXY, or 5033 ZYX) and returns the three angles as multiple values. The middle 5034 angle will be in the range [-pi/2,pi/2]. If it is on the edges of 5035 that range, such that the first and third axes are colinear, then 5036 the first angle will be set to 0. 5037 5038 -- Alias: tait-bryan-xyz 5039 -- Alias: tait-bryan-xzy 5040 -- Alias: tait-bryan-yxz 5041 -- Alias: tait-bryan-yzx 5042 -- Alias: tait-bryan-zxy 5043 -- Alias: tait-bryan-zyx 5044 Aliases for the corresponding ‘intrinsic-’ procedures. 5045 5046 -- Procedure: make-intrinsic-xyx ALPHA BETA GAMMA 5047 -- Procedure: make-intrinsic-xzx ALPHA BETA GAMMA 5048 -- Procedure: make-intrinsic-yxy ALPHA BETA GAMMA 5049 -- Procedure: make-intrinsic-yzy ALPHA BETA GAMMA 5050 -- Procedure: make-intrinsic-zxz ALPHA BETA GAMMA 5051 -- Procedure: make-intrinsic-zyz ALPHA BETA GAMMA 5052 5053 These functions return quaternions representing the given Euler 5054 angle rotations. 5055 5056 -- Alias: make-euler-xyx 5057 -- Alias: make-euler-xzx 5058 -- Alias: make-euler-yxy 5059 -- Alias: make-euler-yzy 5060 -- Alias: make-euler-zxz 5061 -- Alias: make-euler-zyz 5062 Aliases for the corresponding ‘make-intrinsic-’ procedures. 5063 5064 (let-values (((a b c) (euler-xyx (make-euler-xyx 1.0 0.0 2.0)))) 5065 (list a b c)) ⇒ (0.0 0.0 3.0) 5066 5067 -- Procedure: make-intrinsic-xyz ALPHA BETA GAMMA 5068 -- Procedure: make-intrinsic-xzy ALPHA BETA GAMMA 5069 -- Procedure: make-intrinsic-yxz ALPHA BETA GAMMA 5070 -- Procedure: make-intrinsic-yzx ALPHA BETA GAMMA 5071 -- Procedure: make-intrinsic-zxy ALPHA BETA GAMMA 5072 -- Procedure: make-intrinsic-zyx ALPHA BETA GAMMA 5073 5074 These functions return quaternions representing the given 5075 Tait-Bryan angle rotations. 5076 5077 -- Alias: make-tait-bryan-xyz 5078 -- Alias: make-tait-bryan-xzy 5079 -- Alias: make-tait-bryan-yxz 5080 -- Alias: make-tait-bryan-yzx 5081 -- Alias: make-tait-bryan-zxy 5082 -- Alias: make-tait-bryan-zyx 5083 Aliases for the corresponding ‘make-intrinsic-’ procedures. 5084 5085Extrinsic Angle Sets 5086.................... 5087 5088The extrinsic angle sets represent arbitrary rotations as a sequence of 5089three rotations about fixed-frame axes (i.e. the axes do not rotate 5090with the body). 5091 5092 There are twelve possible extrinsic angle sets, and each is the dual 5093of an intrinsic set. The extrinsic rotation about axes ‘A’, ‘B’, and 5094‘C’ by angles ‘a’, ‘b’, and ‘c’ is the same as the intrinsic rotation 5095about axes ‘C’, ‘B’, and ‘A’ by angles ‘c’, ‘b’, and ‘a’, with the order 5096of the three axes reversed. 5097 5098 -- Procedure: extrinsic-xyx Q 5099 -- Procedure: extrinsic-xyz Q 5100 -- Procedure: extrinsic-xzx Q 5101 -- Procedure: extrinsic-zxy Q 5102 -- Procedure: extrinsic-yxy Q 5103 -- Procedure: extrinsic-yxz Q 5104 -- Procedure: extrinsic-yzx Q 5105 -- Procedure: extrinsic-yzy Q 5106 -- Procedure: extrinsic-zxy Q 5107 -- Procedure: extrinsic-zxz Q 5108 -- Procedure: extrinsic-zyx Q 5109 -- Procedure: extrinsic-zyz Q 5110 5111 These functions decompose the rotation represented by Q into 5112 extrinsic angles of the given set and returns the three angles as 5113 multiple values. 5114 5115 -- Procedure: make-extrinsic-xyx GAMMA BETA ALPHA 5116 -- Procedure: make-extrinsic-xyz GAMMA BETA ALPHA 5117 -- Procedure: make-extrinsic-xzx GAMMA BETA ALPHA 5118 -- Procedure: make-extrinsic-xzy GAMMA BETA ALPHA 5119 -- Procedure: make-extrinsic-yxy GAMMA BETA ALPHA 5120 -- Procedure: make-extrinsic-yxz GAMMA BETA ALPHA 5121 -- Procedure: make-extrinsic-yzx GAMMA BETA ALPHA 5122 -- Procedure: make-extrinsic-yzy GAMMA BETA ALPHA 5123 -- Procedure: make-extrinsic-zxy GAMMA BETA ALPHA 5124 -- Procedure: make-extrinsic-zxz GAMMA BETA ALPHA 5125 -- Procedure: make-extrinsic-zyx GAMMA BETA ALPHA 5126 -- Procedure: make-extrinsic-zyz GAMMA BETA ALPHA 5127 5128 These functions return quaternions representing the given extrinsic 5129 angle rotations. 5130 5131 -- Alias: rpy 5132 -- Alias: make-rpy 5133 Aliases for ‘extrinsic-xyz’ and ‘make-extrinsic-xyz’. 5134 5135 (let ((r (make-rpy 0.12 -0.23 0.34))) 5136 (let-values (((a b c) (tait-bryan-zyx r))) 5137 (list a b c))) ⇒ (0.3400000000000001 -0.2300000000000001 0.12000000000000002) 5138 513912.4.2.2 Rotation Operations 5140............................ 5141 5142 -- Procedure: rotate-vector RQ VQ 5143 Applies the rotation represented by quaternion RQ to the vector 5144 represented by vector quaternion VQ, and returns the rotated 5145 vector. This is equivalent to ‘(* rq vq (conjugate rq))’ for 5146 normalized RQ. 5147 5148 (rotate-vector +k +2i) ⇒ -2i 5149 (rotate-vector 1/2+1/2i+1/2j+1/2k +i+2j+3k) ⇒ +3.0i+1.0j+2.0k 5150 5151 -- Procedure: make-rotation-procedure RQ 5152 A partial application of ‘rotate-vector’. Returns a 5153 single-argument procedure which will take a vector quaternion 5154 argument and rotate it by RQ. The returned procedure closes over 5155 both RQ and its conjugate, so this will likely be more efficient 5156 than ‘rotate-vector’ at rotating many vectors by the same rotation. 5157 5158 5159File: kawa.info, Node: Quantities, Next: Logical Number Operations, Prev: Quaternions, Up: Numbers 5160 516112.5 Quantities and Units 5162========================= 5163 5164As a super-class of numbers, Kawa also provides quantities. A 5165“quantity” is a product of a “unit” and a pure number. The number part 5166can be an arbitrary complex number. The unit is a product of integer 5167powers of base units, such as meter or second. 5168 5169 Quantity literals have the following syntax: 5170 QUANTITY ::= OPTIONAL-SIGN DECIMAL UNIT-TERM [‘*’ UNIT-TERM]... [‘/’ UNIT-TERM] 5171 UNIT-TERM ::= UNIT-NAME [‘^’ DIGIT+] 5172 UNIT-NAME ::= LETTER+ 5173 Some examples are ‘10pt’ (10 points), ‘5s’ (5 seconds), and ‘4cm^2’ 5174(4 square centimeters). 5175 5176 Note the QUANTITY syntax is not recognized by the reader. Instead 5177these are read as symbols. Assuming there is no lexical binding the for 5178the symbol, it will be rewritten at compile-time into an expression. 5179For example ‘4cm^2’ is transformed into: 5180 (* 4.0 (expt unit:cm 2)) 5181 5182 -- Procedure: quantity? object 5183 True iff OBJECT is a quantity. Note that all numbers are 5184 quantities, but not the other way round. Currently, there are no 5185 quantities that are not numbers. To distinguish a plain unit-less 5186 number from a quantity, you can use ‘complex?’. 5187 5188 -- Procedure: quantity->number q 5189 Returns the pure number part of the quantity Q, relative to 5190 primitive (base) units. If Q is a number, returns Q. If Q is a 5191 unit, yields the magitude of Q relative to base units. 5192 5193 -- Procedure: quantity->unit q 5194 Returns the unit of the quantity Q. If Q is a number, returns the 5195 empty unit. 5196 5197 -- Procedure: make-quantity x unit 5198 Returns the product of X (a pure number) and UNIT. You can specify 5199 a string instead of UNIT, such as ‘"cm"’ or ‘"s"’ (seconds). 5200 5201 -- Syntax: define-base-unit unit-name dimension 5202 Define UNIT-NAME as a base (primitive) unit, which is used to 5203 measure along the specified DIMENSION. 5204 (define-base-unit dollar "Money") 5205 5206 -- Syntax: define-unit unit-name expression 5207 Define UNIT-NAME as a unit (that can be used in literals) equal to 5208 the quantity EXPRESSION. 5209 (define-unit cent 0.01dollar) 5210 The UNIT-NAME is declared in the ‘unit’ namespace, so the above is 5211 equivalent to: 5212 (define-constant unit:cent (* 0.01 unit:dollar)) 5213 5214Angles 5215------ 5216 5217The following angle units are dimensionless, with no base unit. 5218 5219 Some procedures treat a unit-less real number as if it were in 5220radians (which mathematicians prefer); some procedures (such as 5221‘rotate’) treat a unit-less real number as if it were in degrees (which 5222is common in Web and other standards). 5223 5224 -- Unit: rad 5225 A unit for angles specified in radians. A full circle is 2*pi 5226 radians. Note that ‘(= 1.5 1.5rad)’ is true, while ‘(eqv? 1.5 5227 1.5rad)’ is false. 5228 5229 -- Unit: deg 5230 A unit for angles specified in degrees. A full circle is 360 5231 degrees. 5232 5233 -- Unit: grad 5234 A unit for angles specified in gradians. A full circle is 400 5235 gradians. 5236 5237 5238File: kawa.info, Node: Logical Number Operations, Next: Performance of numeric operations, Prev: Quantities, Up: Numbers 5239 524012.6 Logical Number Operations 5241============================== 5242 5243These functions operate on the 2’s complement binary representation of 5244an exact integer. 5245 5246 -- Procedure: bitwise-not i 5247 Returns the bit-wise logical inverse of the argument. More 5248 formally, returns the exact integer whose two’s complement 5249 representation is the one’s complement of the two’s complement 5250 representation of I. 5251 5252 -- Procedure: bitwise-and i ... 5253 -- Procedure: bitwise-ior i ... 5254 -- Procedure: bitwise-xor i ... 5255 These procedures return the exact integer that is the bit-wise 5256 “and”, “inclusive or”, or “exclusive or” of the two’s complement 5257 representations of their arguments. If they are passed only one 5258 argument, they return that argument. If they are passed no 5259 arguments, they return the integer that acts as identity for the 5260 operation: -1, 0, or 0, respectively. 5261 5262 -- Procedure: bitwise-if i1 i2 i3 5263 5264 Returns the exact integer that is the bit-wise “if” of the twos 5265 complement representations of its arguments, i.e. for each bit, if 5266 it is 1 in i1, the corresponding bit in i2 becomes the value of the 5267 corresponding bit in the result, and if it is 0, the corresponding 5268 bit in i3 becomes the corresponding bit in the value of the result. 5269 This is equivaent to the following computation: 5270 (bitwise-ior (bitwise-and i1 i2) 5271 (bitwise-and (bitwise-not i1) i3)) 5272 5273 -- Procedure: bitwise-bit-count i 5274 If i is non-negative, returns the number of 1 bits in the twos 5275 complement representation of i. Otherwise it returns the result of 5276 the following computation: 5277 (bitwise-not (bitwise-bit-count (bitwise-not i))) 5278 5279 -- Procedure: bitwise-length i 5280 Returns the number of bits needed to represent i if it is positive, 5281 and the number of bits needed to represent ‘(bitwise-not I)’ if it 5282 is negative, which is the exact integer that is the result of the 5283 following computation: 5284 (do ((result 0 (+ result 1)) 5285 (bits (if (negative? i) 5286 (bitwise-not i) 5287 ei) 5288 (bitwise-arithmetic-shift bits -1))) 5289 ((zero? bits) 5290 result)) 5291 This is the number of bits needed to represent I in an unsigned 5292 field. 5293 5294 -- Procedure: bitwise-first-bit-set i 5295 Returns the index of the least significant 1 bit in the twos 5296 complement representation of i. If i is 0, then - 1 is returned. 5297 (bitwise-first-bit-set 0) ⇒ -1 5298 (bitwise-first-bit-set 1) ⇒ 0 5299 (bitwise-first-bit-set -4) ⇒ 2 5300 5301 -- Procedure: bitwise-bit-set? i1 i2 5302 Returns ‘#t’ if the i2’th bit (where I2 must be non-negative) is 1 5303 in the two’s complement representation of I1, and ‘#f’ otherwise. 5304 This is the result of the following computation: 5305 (not (zero? 5306 (bitwise-and 5307 (bitwise-arithmetic-shift-left 1 i2) 5308 i1))) 5309 5310 -- Procedure: bitwise-copy-bit i bitno replacement-bit 5311 Returns the result of replacing the BITNO’th bit of I by 5312 REPLACEMENT-BIT, where BITNO must be non-negative, and 5313 REPLACEMENT-BIT must be either 0 or 1. This is the result of the 5314 following computation: 5315 (let* ((mask (bitwise-arithmetic-shift-left 1 bitno))) 5316 (bitwise-if mask 5317 (bitwise-arithmetic-shift-left replacement-bit bitno) 5318 i)) 5319 5320 -- Procedure: bitwise-bit-field n start end 5321 Returns the integer formed from the (unsigned) bit-field starting 5322 at START and ending just before END. Same as: 5323 (let ((mask 5324 (bitwise-not 5325 (bitwise-arithmetic-shift-left -1 END)))) 5326 (bitwise-arithmetic-shift-right 5327 (bitwise-and N mask) 5328 START)) 5329 5330 -- Procedure: bitwise-copy-bit-field to start end from 5331 Returns the result of replacing in TO the bits at positions from 5332 START (inclusive) to END (exclusive) by the bits in FROM from 5333 position 0 (inclusive) to position END - START (exclusive). Both 5334 START and START must be non-negative, and START must be less than 5335 or equal to START. 5336 5337 This is the result of the following computation: 5338 (let* ((mask1 5339 (bitwise-arithmetic-shift-left -1 start)) 5340 (mask2 5341 (bitwise-not 5342 (bitwise-arithmetic-shift-left -1 end))) 5343 (mask (bitwise-and mask1 mask2))) 5344 (bitwise-if mask 5345 (bitwise-arithmetic-shift-left from 5346 start) 5347 to)) 5348 5349 -- Procedure: bitwise-arithmetic-shift i j 5350 Shifts I by J. It is a “left” shift if ‘J>0’, and a “right” shift 5351 if ‘J<0’. The result is equal to ‘(floor (* I (expt 2 J)))’. 5352 5353 Examples: 5354 (bitwise-arithmetic-shift -6 -1) ⇒-3 5355 (bitwise-arithmetic-shift -5 -1) ⇒ -3 5356 (bitwise-arithmetic-shift -4 -1) ⇒ -2 5357 (bitwise-arithmetic-shift -3 -1) ⇒ -2 5358 (bitwise-arithmetic-shift -2 -1) ⇒ -1 5359 (bitwise-arithmetic-shift -1 -1) ⇒ -1 5360 5361 -- Procedure: bitwise-arithmetic-shift-left i amount 5362 -- Procedure: bitwise-arithmetic-shift-right i amount 5363 The AMOUNT must be non-negative The ‘bitwise-arithmetic-shift-left’ 5364 procedure returns the same result as ‘bitwise-arithmetic-shift’, 5365 and ‘(bitwise-arithmetic-shift-right I AMOUNT)’ returns the same 5366 result as ‘(bitwise-arithmetic-shift I (- AMOUNT))’. 5367 5368 If I is a primitive integer type, then AMOUNT must be less than the 5369 number of bits in the promoted type of I (32 or 64). If the type 5370 is unsigned, an unsigned (logic) shift is done for 5371 ‘bitwise-arithmetic-shift-right’, rather than a signed (arithmetic) 5372 shift. 5373 5374 -- Procedure: bitwise-rotate-bit-field n start end count 5375 Returns the result of cyclically permuting in N the bits at 5376 positions from START (inclusive) to END (exclusive) by COUNT bits 5377 towards the more significant bits, START and END must be 5378 non-negative, and START must be less than or equal to END. This is 5379 the result of the following computation: 5380 (let* ((n ei1) 5381 (width (- end start))) 5382 (if (positive? width) 5383 (let* ((count (mod count width)) 5384 (field0 5385 (bitwise-bit-field n start end)) 5386 (field1 (bitwise-arithmetic-shift-left 5387 field0 count)) 5388 (field2 (bitwise-arithmetic-shift-right 5389 field0 5390 (- width count))) 5391 (field (bitwise-ior field1 field2))) 5392 (bitwise-copy-bit-field n start end field)) 5393 n)) 5394 5395 -- Procedure: bitwise-reverse-bit-field i start end 5396 Returns the result obtained from I by reversing the order of the 5397 bits at positions from START (inclusive) to END (exclusive), where 5398 START and END must be non-negative, and START must be less than or 5399 equal to END. 5400 (bitwise-reverse-bit-field #b1010010 1 4) ⇒ 88 ; #b1011000 5401 5402 -- Procedure: logop op x y 5403 Perform one of the 16 bitwise operations of X and Y, depending on 5404 OP. 5405 5406 -- Procedure: logtest i j 5407 Returns true if the arguments have any bits in common. Same as 5408 ‘(not (zero? (bitwise-and I J)))’, but is more efficient. 5409 541012.6.1 SRFI-60 Logical Number Operations 5411---------------------------------------- 5412 5413Kawa supports SRFI-60 “Integers as Bits” as well, although we generally 5414recommend using the R6RS-compatible functions instead when possible. 5415Unless noted as being a builtin function, to use these you must first 5416‘(require 'srfi-60)’ or ‘(import (srfi :60))’ (or ‘(import (srfi :60 5417integer-bits))’). 5418 5419 -- Procedure: logand i ... 5420 Equivalent to ‘(bitwise-and I ...)’. Builtin. 5421 5422 -- Procedure: logior i ... 5423 Equivalent to ‘(bitwise-ior I ...)’. Builtin. 5424 5425 -- Procedure: logxor i ... 5426 Equivalent to ‘(bitwise-xor I ...)’. Builtin. 5427 5428 -- Procedure: lognot i 5429 Equivalent to ‘(bitwise-not I)’. Builtin. 5430 5431 -- Procedure: bitwise-merge mask i j 5432 Equivalent to ‘(bitwise-if MASK I J)’. 5433 5434 -- Procedure: any-bits-set? i j 5435 Equivalent to ‘(logtest I J)’. 5436 5437 -- Procedure: logcount i 5438 -- Procedure: bit-count i 5439 Count the number of 1-bits in I, if it is non-negative. If I is 5440 negative, count number of 0-bits. Same as ‘(bitwise-bit-count I)’ 5441 if I is non-negative. Builtin as ‘logcount’. 5442 5443 -- Procedure: integer-length i 5444 Equivalent to ‘(bitwise-length I)’. Builtin. 5445 5446 -- Procedure: log2-binary-factors i 5447 -- Procedure: first-set-bit i 5448 Equivalent to ‘(bitwise-first-bit-set I)’. 5449 5450 -- Procedure: logbit? pos i 5451 -- Procedure: bit-set? pos i 5452 Equivalent to ‘(bitwise-bit-set? I POS)’. 5453 5454 -- Procedure: copy-bit bitno i bool 5455 Equivalent to ‘(bitwise-copy-bit I BITNO (if BOOL 1 0))’. 5456 5457 -- Procedure: bit-field n start end 5458 Equivalent to ‘(bitwise-bit-field N START END)’. 5459 5460 -- Procedure: copy-bit-field to from start end 5461 Equivalent to ‘(bitwise-copy-bit-field TO START END FROM)’. 5462 5463 -- Procedure: arithmetic-shift i j 5464 Equivalent to ‘(bitwise-arithmetic-shift I J)’. Builtin. 5465 5466 -- Procedure: ash i j 5467 Alias for ‘arithmetic-shift’. Builtin. 5468 5469 -- Procedure: rotate-bit-field n count start end 5470 Equivalent to ‘(bitwise-rotate-bit-field N START END COUNT)’. 5471 5472 -- Procedure: reverse-bit-field i start end 5473 Equivalent to ‘(bitwise-reverse-bit-field I START END)’. 5474 5475 -- Procedure: integer->list K [LENGTH] 5476 -- Procedure: list->integer LIST 5477 The ‘integer->list’ procedure returns a list of LENGTH booleans 5478 corresponding to the bits of the non-negative integer K, with ‘#t’ 5479 for ‘1’ and ‘#f’ for ‘0’. LENGTH defaults to ‘(bitwise-length K)’. 5480 The list will be in order from MSB to LSB, with the value of ‘(odd? 5481 K)’ in the last car. 5482 5483 The ‘list->integer’ procedure returns the integer corresponding to 5484 the booleans in the list LIST. The ‘integer->list’ and 5485 ‘list->integer’ procedures are inverses so far as ‘equal?’ is 5486 concerned. 5487 5488 -- Procedure: booleans->integer bool1 ... 5489 Returns the integer coded by the BOOL1 ... arguments. Equivalent 5490 to ‘(list->integer (list BOOL1 ...))’. 5491 549212.6.2 Deprecated Logical Number Operations 5493------------------------------------------- 5494 5495This older function is still available, but we recommend using the 5496R6RS-compatible function. 5497 5498 -- Procedure: bit-extract n start end 5499 Equivalent to ‘(bitwise-bit-field N START END)’. 5500 5501 5502File: kawa.info, Node: Performance of numeric operations, Prev: Logical Number Operations, Up: Numbers 5503 550412.7 Performance of numeric operations 5505====================================== 5506 5507Kawa can generally do a pretty good job of generating efficient code for 5508numeric operations, at least when it knows or can figure out the types 5509of the operands. 5510 5511 The basic operations ‘+’, ‘-’, and ‘*’ are compiled to 5512single-instruction bytecode if both operands are ‘int’ or ‘long’. 5513Likewise, if both operands are floating-point (or one is floating-point 5514and the other is rational), then single-instruction ‘double’ or ‘float’ 5515instructions are emitted. 5516 5517 A binary operation involving an infinite-precision ‘integer’ and a 5518fixed-size ‘int’ or ‘long’ is normally evaluated by expanding the latter 5519to ‘integer’ and using ‘integer’ arithmetic. An exception is an integer 5520literal whose value fits in an ‘int’ or ‘long’ - in that case the 5521operation is done using ‘int’ or ‘long’ arithmetic. 5522 5523 In general, integer literals have amorphous type. When used to infer 5524the type of a variable, they have ‘integer’ type: 5525 (let ((v1 0)) 5526 ... v1 has type integer ... ) 5527 However, a literal whose value fits in the ‘int’ or ‘long’ range is 5528implicitly viewed ‘int’ or ‘long’ in certain contexts, primarily method 5529overload resolution and binary arithmetic (as mentioned above). 5530 5531 The comparison functions ‘<’, ‘<=’, ‘=’, ‘>’, and ‘=>’ are also 5532optimized to single instriction operations if the operands have 5533appropriate type. However, the functions ‘zero?’, ‘positive?’, and 5534‘negative?’ have not yet been optimized. Instead of ‘(positive? x)’ 5535write ‘(> x 0)’. 5536 5537 There are a number of integer division and modulo operations. If the 5538operands are ‘int’ or ‘long’, it is faster to use ‘quotient’ and 5539‘remainder’ rather than ‘div’ and ‘mod’ (or ‘modulo’). If you know the 5540first operand is non-negative and the second is positive, then use 5541‘quotient’ and ‘remainder’. (If an operand is an arbitrary-precision 5542‘integer’, then it dosn’t really matter.) 5543 5544 The logical operations ‘bitwise-and’, ‘bitwise-ior’, ‘bitwise-xor’, 5545‘bitwise-not’, ‘bitwise-arithmetic-shift-left’, 5546‘bitwise-arithmetic-shift-right’ are compiled to single bitcode 5547instructions if the operands are ‘int’ or ‘long’. Avoid 5548‘bitwise-arithmetic-shift’ if the sign of the shift is known. If the 5549operands are arbitrary-precision ‘integer’, a library call is needed, 5550but run-time type dispatch is avoided. 5551 5552 5553File: kawa.info, Node: Characters and text, Next: Data structures, Prev: Numbers, Up: Top 5554 555513 Characters and text 5556********************** 5557 5558* Menu: 5559 5560* Characters:: 5561* Character sets:: 5562* Strings:: 5563* String literals:: 5564* Unicode:: Unicode character classes and conversions 5565* Regular expressions:: 5566 5567 5568File: kawa.info, Node: Characters, Next: Character sets, Up: Characters and text 5569 557013.1 Characters 5571=============== 5572 5573Characters are objects that represent human-readable characters such as 5574letters and digits. More precisely, a character represents a Unicode 5575scalar value (http://www.unicode.org/glossary/#unicode_scalar_value). 5576Each character has an integer value in the range ‘0’ to ‘#x10FFFF’ 5577(excluding the range ‘#xD800’ to ‘#xDFFF’ used for Surrogate Code Points 5578(http://www.unicode.org/glossary/#surrogate_code_point)). 5579 5580 _Note:_ Unicode distinguishes between glyphs, which are printed for 5581 humans to read, and characters, which are abstract entities that 5582 map to glyphs (sometimes in a way that’s sensitive to surrounding 5583 characters). Furthermore, different sequences of scalar values 5584 sometimes correspond to the same character. The relationships 5585 among scalar, characters, and glyphs are subtle and complex. 5586 5587 Despite this complexity, most things that a literate human would 5588 call a “character” can be represented by a single Unicode scalar 5589 value (although several sequences of Unicode scalar values may 5590 represent that same character). For example, Roman letters, 5591 Cyrillic letters, Hebrew consonants, and most Chinese characters 5592 fall into this category. 5593 5594 Unicode scalar values exclude the range ‘#xD800’ to ‘#xDFFF’, which 5595 are part of the range of Unicode “code points”. However, the 5596 Unicode code points in this range, the so-called “surrogates”, are 5597 an artifact of the UTF-16 encoding, and can only appear in specific 5598 Unicode encodings, and even then only in pairs that encode scalar 5599 values. Consequently, all characters represent code points, but 5600 the surrogate code points do not have representations as 5601 characters. 5602 5603 -- Type: character 5604 A Unicode code point - normally a Unicode scalar value, but could 5605 be a surrogate. This is implemented using a 32-bit ‘int’. When an 5606 object is needed (i.e. the “boxed” representation), it is 5607 implemented an instance of ‘gnu.text.Char’. 5608 5609 -- Type: character-or-eof 5610 A ‘character’ or the specical ‘#!eof’ value (used to indicate 5611 end-of-file when reading from a port). This is implemented using a 5612 32-bit ‘int’, where the value -1 indicates end-of-file. When an 5613 object is needed, it is implemented an instance of ‘gnu.text.Char’ 5614 or the special ‘#!eof’ object. 5615 5616 -- Type: char 5617 A UTF-16 code unit. Same as Java primitive ‘char’ type. 5618 Considered to be a sub-type of ‘character’. When an object is 5619 needed, it is implemented as an instance of ‘java.lang.Character’. 5620 Note the unfortunate inconsistency (for historical reasons) of 5621 ‘char’ boxed as ‘Character’ vs ‘character’ boxed as ‘Char’. 5622 5623 Characters are written using the notation ‘#\’CHARACTER (which stands 5624for the given CHARACTER; ‘#\x’HEX-SCALAR-VALUE (the character whose 5625scalar value is the given hex integer); or ‘#\’CHARACTER-NAME (a 5626character with a given name): 5627 5628 CHARACTER ::= ‘#\’ANY-CHARACTER 5629 | ‘#\’ CHARACTER-NAME 5630 | ‘#\x’ HEX-SCALAR-VALUE 5631 | ‘#\X’ HEX-SCALAR-VALUE 5632 5633 The following CHARACTER-NAME forms are recognized: 5634‘#\alarm’ 5635 ‘#\x0007’ - the alarm (bell) character 5636‘#\backspace’ 5637 ‘#\x0008’ 5638‘#\delete’ 5639‘#\del’ 5640‘#\rubout’ 5641 ‘#\x007f’ - the delete or rubout character 5642‘#\escape’ 5643‘#\esc’ 5644 ‘#\x001b’ 5645‘#\newline’ 5646‘#\linefeed’ 5647 ‘#\x001a’ - the linefeed character 5648‘#\null’ 5649‘#\nul’ 5650 ‘#\x0000’ - the null character 5651‘#\page’ 5652 ‘#\000c’ - the formfeed character 5653‘#\return’ 5654 ‘#\000d’ - the carriage return character 5655‘#\space’ 5656 ‘#\x0020’ - the preferred way to write a space 5657‘#\tab’ 5658 ‘#\x0009’ - the tab character 5659‘#\vtab’ 5660 ‘#\x000b’ - the vertical tabulation character 5661‘#\ignorable-char’ 5662 A special ‘character’ value, but it is not a Unicode code point. 5663 It is a special value returned when an index refers to the second 5664 ‘char’ (code point) of a surrogate pair, and which should be 5665 ignored. (When writing a ‘character’ to a string or file, it will 5666 be written as one or two ‘char’ values. The exception is 5667 ‘#\ignorable-char’, for which zero ‘char’ values are written.) 5668 5669 -- Procedure: char? OBJ 5670 Return ‘#t’ if OBJ is a character, ‘#f’ otherwise. (The OBJ can be 5671 any character, not just a 16-bit ‘char’.) 5672 5673 -- Procedure: char->integer CHAR 5674 -- Procedure: integer->char SV 5675 SV should be a Unicode scalar value, i.e., a non–negative exact 5676 integer object in ‘[0, #xD7FF] union [#xE000, #x10FFFF]’. (Kawa 5677 also allows values in the surrogate range.) 5678 5679 Given a character, ‘char->integer’ returns its Unicode scalar value 5680 as an exact integer object. For a Unicode scalar value SV, 5681 ‘integer->char’ returns its associated character. 5682 5683 (integer->char 32) ⇒ #\space 5684 (char->integer (integer->char 5000)) ⇒ 5000 5685 (integer->char #\xD800) ⇒ throws ClassCastException 5686 5687 _Performance note:_ A call to ‘char->integer’ is compiled as 5688 casting the argument to a ‘character’, and then re-interpreting 5689 that value as an ‘int’. A call to ‘integer->char’ is compiled as 5690 casting the argument to an ‘int’, and then re-interpreting that 5691 value as an ‘character’. If the argument is the right type, no 5692 code is emitted: the value is just re-interpreted as the result 5693 type. 5694 5695 -- Procedure: char=? CHAR1 CHAR2 CHAR3 ... 5696 -- Procedure: char<? CHAR1 CHAR2 CHAR3 ... 5697 -- Procedure: char>? CHAR1 CHAR2 CHAR3 ... 5698 -- Procedure: char<=? CHAR1 CHAR2 CHAR3 ... 5699 -- Procedure: char>=? CHAR1 CHAR2 CHAR3 ... 5700 These procedures impose a total ordering on the set of characters 5701 according to their Unicode scalar values. 5702 5703 (char<? #\z #\ß) ⇒ #t 5704 (char<? #\z #\Z) ⇒ #f 5705 5706 _Performance note:_ This is compiled as if converting each argument 5707 using ‘char->integer’ (which requires no code) and the using the 5708 corresponing ‘int’ comparison. 5709 5710 -- Procedure: digit-value char 5711 This procedure returns the numeric value (0 to 9) of its argument 5712 if it is a numeric digit (that is, if ‘char-numeric?’ returns 5713 ‘#t’), or ‘#f’ on any other character. 5714 5715 (digit-value #\3) ⇒ 3 5716 (digit-value #\x0664) ⇒ 4 5717 (digit-value #\x0AE6) ⇒ 0 5718 (digit-value #\x0EA6) ⇒ #f 5719 5720 5721File: kawa.info, Node: Character sets, Next: Strings, Prev: Characters, Up: Characters and text 5722 572313.2 Character sets 5724=================== 5725 5726Sets of characters are useful for text-processing code, including 5727parsing, lexing, and pattern-matching. SRFI 14 5728(http://srfi.schemers.org/srfi-14/srfi-14.html) specifies a ‘char-set’ 5729type for such uses. Some examples: 5730 5731 (import (srfi :14 char-sets)) 5732 (define vowel (char-set #\a #\e #\i #\o #\u)) 5733 (define vowely (char-set-adjoin vowel #\y)) 5734 (char-set-contains? vowel #\y) ⇒ #f 5735 (char-set-contains? vowely #\y) ⇒ #t 5736 5737 See the SRFI 14 specification 5738(http://srfi.schemers.org/srfi-14/srfi-14.html) for details. 5739 5740 -- Type: char-set 5741 The type of character sets. In Kawa ‘char-set’ is a type that can 5742 be used in type specifiers: 5743 (define vowely ::char-set (char-set-adjoin vowel #\y)) 5744 5745 Kawa uses inversion lists 5746(https://en.wikipedia.org/wiki/Inversion_list) for an efficient 5747implementation, using Java ‘int’ arrays to represents character ranges 5748(inversions). The ‘char-set-contains?’ function uses binary search, so 5749it takes time proportional to the logarithm of the number of inversions. 5750Other operations may take time proportional to the number of inversions. 5751 5752 5753File: kawa.info, Node: Strings, Next: String literals, Prev: Character sets, Up: Characters and text 5754 575513.3 Strings 5756============ 5757 5758Strings are sequences of characters. The _length_ of a string is the 5759number of characters that it contains, as an exact non-negative integer. 5760The _valid indices_ of a string are the exact non-negative integers less 5761than the length of the string. The first character of a string has 5762index 0, the second has index 1, and so on. 5763 5764 Strings are _implemented_ as a sequence of 16-bit ‘char’ values, even 5765though they’re semantically a sequence of 32-bit Unicode code points. A 5766character whose value is greater than ‘#xffff’ is represented using two 5767surrogate characters. The implementation allows for natural 5768interoperability with Java APIs. However it does make certain 5769operations (indexing or counting based on character counts) difficult to 5770implement efficiently. Luckily one rarely needs to index or count based 5771on character counts; alternatives are discussed below. 5772 5773 There are different kinds of strings: 5774 • An “istring” is _immutable_: It is fixed, and cannot be modified. 5775 On the other hand, indexing (e.g. ‘string-ref’) is efficient 5776 (constant-time), while indexing of other string implementations 5777 takes time proportional to the index. 5778 5779 String literals are istrings, as are the return values of most of 5780 the procedures in this chapter. 5781 5782 An “istring” is an instance of the ‘gnu.lists.IString’ class. 5783 5784 • An “mstring” is _mutable_: You can replace individual characters 5785 (using ‘string-set!’). You can also change the MSTRING’s length by 5786 inserting or removing characters (using ‘string-append!’ or 5787 ‘string-replace!’). 5788 5789 An “mstring” is an instance of the ‘gnu.lists.FString’ class. 5790 5791 • Any other object that implements the ‘java.lang.CharSequence’ 5792 interface is also a string. This includes standard Java 5793 ‘java.lang.String’ and ‘java.lang.StringBuilder’ objects. 5794 5795 Some of the procedures that operate on strings ignore the difference 5796between upper and lower case. The names of the versions that ignore 5797case end with “‘-ci’” (for “case insensitive”). 5798 5799 _Compatibility:_ Many of the following procedures (for example 5800‘string-append’) return an immutable istring in Kawa, but return a 5801“freshly allocated” mutable string in standard Scheme (include R7RS) as 5802well as most Scheme implementations (including previous versions of 5803Kawa). To get the “compatibility mode” versions of those procedures 5804(which return mstrings), invoke Kawa with one the ‘--r5rs’, ‘--r6rs’, or 5805‘--r7rs’ options, or you can ‘import’ a standard library like ‘(scheme 5806base)’. 5807 5808 -- Type: string 5809 The type of string objects. The underlying type is the interface 5810 ‘java.lang.CharSequence’. Immultable strings are 5811 ‘gnu.lists.IString’ or ‘java.lang.String’, while mutable strings 5812 are ‘gnu.lists.FString’. 5813 581413.3.1 Basic string procedures 5815------------------------------ 5816 5817 -- Procedure: string? OBJ 5818 Return ‘#t’ if OBJ is a string, ‘#f’ otherwise. 5819 5820 -- Procedure: istring? OBJ 5821 Return ‘#t’ if OBJ is a istring (a immutable, 5822 constant-time-indexable string); ‘#f’ otherwise. 5823 5824 -- Constructor: string CHAR ... 5825 Return a string composed of the arguments. This is analogous to 5826 LIST. 5827 5828 _Compatibility:_ The result is an istring, except in compatibility 5829 mode, when it is a new allocated mstring. 5830 5831 -- Procedure: string-length STRING 5832 Return the number of characters in the given STRING as an exact 5833 integer object. 5834 5835 _Performance note:_ If the STRING is not an istring, the calling 5836 ‘string-length’ may take time proportional to the length of the 5837 STRING, because of the need to scan for surrogate pairs. 5838 5839 -- Procedure: string-ref STRING K 5840 K must be a valid index of STRING. The ‘string-ref’ procedure 5841 returns character K of STRING using zero–origin indexing. 5842 5843 _Performance note:_ If the STRING is not an istring, then calling 5844 ‘string-ref’ may take time proportional to K because of the need to 5845 check for surrogate pairs. An alternative is to use 5846 ‘string-cursor-ref’. If iterating through a string, use 5847 ‘string-for-each’. 5848 5849 -- Procedure: string-null? STRING 5850 Is STRING the empty string? Same result as ‘(= (string-length 5851 STRING) 0)’ but executes in O(1) time. 5852 5853 -- Procedure: string-every pred string [start end]) 5854 -- Procedure: string-any pred string [start end]) 5855 5856 Checks to see if every/any character in STRING satisfies PRED, 5857 proceeding from left (index START) to right (index END). These 5858 procedures are short-circuiting: if PRED returns false, 5859 ‘string-every’ does not call PRED on subsequent characters; if PRED 5860 returns true, ‘string-any’ does not call PRED on subsequent 5861 characters. Both procedures are “witness-generating”: 5862 • If ‘string-every’ is given an empty interval (with START = 5863 END), it returns ‘#t’. 5864 • If ‘string-every’ returns true for a non-empty interval (with 5865 START < END), the returned true value is the one returned by 5866 the final call to the predicate on ‘(string-ref STRING (- END 5867 1))’. 5868 • If ‘string-any’ returns true, the returned true value is the 5869 one returned by the predicate. 5870 5871 _Note:_ The names of these procedures do not end with a question 5872 mark. This indicates a general value is returned instead of a 5873 simple boolean (‘#t’ or ‘#f’). 5874 587513.3.2 Immutable String Constructors 5876------------------------------------ 5877 5878 -- Procedure: string-tabulate proc len 5879 5880 Constructs a string of size LEN by calling PROC on each value from 5881 0 (inclusive) to LEN (exclusive) to produce the corresponding 5882 element of the string. The procedure PROC accepts an exact integer 5883 as its argument and returns a character. The order in which PROC 5884 is called on those indexes is not specifified. 5885 5886 _Rationale:_ Although ‘string-unfold’ is more general, 5887 ‘string-tabulate’ is likely to run faster for the common special 5888 case it implements. 5889 5890 -- Procedure: string-unfold stop? mapper successor seed [base 5891 make-final] 5892 -- Procedure: string-unfold-right stop? mapper successor seed [base 5893 make-final] 5894 This is a fundamental and powerful constructor for strings. 5895 • SUCCESSOR is used to generate a series of “seed” values from 5896 the initial seed: SEED, ‘(’SUCCESSOR SEED‘)’, ‘(’SUCCESSOR^{2} 5897 SEED‘)’, ‘(’SUCCESSOR^{3} SEED‘)’, ... 5898 • STOP? tells us when to stop — when it returns true when 5899 applied to one of these seed values. 5900 • MAPPER maps each seed value to the corresponding character(s) 5901 in the result string, which are assembled into that string in 5902 left-to-right order. It is an error for MAPPER to return 5903 anything other than a character or string. 5904 • BASE is the optional initial/leftmost portion of the 5905 constructed string, which defaults to the empty string ‘""’. 5906 It is an error if BASE is anything other than a character or 5907 string. 5908 • MAKE-FINAL is applied to the terminal seed value (on which 5909 STOP? returns true) to produce the final/rightmost portion of 5910 the constructed string. It defaults to ‘(lambda (x) "")’. It 5911 is an error for MAKE-FINAL to return anything other than a 5912 character or string. 5913 5914 ‘string-unfold-right’ is the same as ‘string-unfold’ except the 5915 results of MAPPER are assembled into the string in right-to-left 5916 order, BASE is the optional rightmost portion of the constructed 5917 string, and MAKE-FINAL produces the leftmost portion of the 5918 constructed string. 5919 5920 You can use it ‘string-unfold’ to convert a list to a string, read 5921 a port into a string, reverse a string, copy a string, and so 5922 forth. Examples: 5923 (define (port->string p) 5924 (string-unfold eof-object? values 5925 (lambda (x) (read-char p)) 5926 (read-char p))) 5927 5928 (define (list->string lis) 5929 (string-unfold null? car cdr lis)) 5930 5931 (define (string-tabulate f size) 5932 (string-unfold (lambda (i) (= i size)) f add1 0)) 5933 To map F over a list LIS, producing a string: 5934 (string-unfold null? (compose F car) cdr LIS) 5935 5936 Interested functional programmers may enjoy noting that 5937 ‘string-fold-right’ and ‘string-unfold’ are in some sense inverses. 5938 That is, given operations KNULL?, KAR, KDR, KONS, and KNIL 5939 satisfying 5940 (KONS (KAR x) (KDR x)) = x and (KNULL? KNIL) = #t 5941 then 5942 (string-fold-right KONS KNIL (string-unfold KNULL? KAR KDR X)) = X 5943 and 5944 (string-unfold KNULL? KAR KDR (string-fold-right KONS KNIL STRING)) = STRING. 5945 5946 This combinator pattern is sometimes called an “anamorphism.” 5947 594813.3.3 Selection 5949---------------- 5950 5951 -- Procedure: substring STRING START END 5952 STRING must be a string, and START and END must be exact integer 5953 objects satisfying: 5954 5955 0 <= START <= END <= (string-length STRING) 5956 5957 The ‘substring’ procedure returns a newly allocated string formed 5958 from the characters of STRING beginning with index START 5959 (inclusive) and ending with index END (exclusive). 5960 5961 -- Procedure: string-take string nchars 5962 -- Procedure: string-drop string nchars 5963 -- Procedure: string-take-right string nchars 5964 -- Procedure: string-drop-right string nchars 5965 ‘string-take’ returns an immutable string containing the first 5966 NCHARS of STRING; ‘string-drop’ returns a string containing all but 5967 the first NCHARS of STRING. ‘string-take-right’ returns a string 5968 containing the last NCHARS of STRING; ‘string-drop-right’ returns a 5969 string containing all but the last NCHARS of STRING. 5970 5971 (string-take "Pete Szilagyi" 6) ⇒ "Pete S" 5972 (string-drop "Pete Szilagyi" 6) ⇒ "zilagyi" 5973 5974 (string-take-right "Beta rules" 5) ⇒ "rules" 5975 (string-drop-right "Beta rules" 5) ⇒ "Beta " 5976 It is an error to take or drop more characters than are in the 5977 string: 5978 (string-take "foo" 37) ⇒ error 5979 5980 -- Procedure: string-pad string len [char start end] 5981 -- Procedure: string-pad-right string len [char start end] 5982 Returns an istring of length LEN comprised of the characters drawn 5983 from the given subrange of STRING, padded on the left (right) by as 5984 many occurrences of the character CHAR as needed. If STRING has 5985 more than LEN chars, it is truncated on the left (right) to length 5986 LEN. The CHAR defaults to ‘#\space’ 5987 (string-pad "325" 5) ⇒ " 325" 5988 (string-pad "71325" 5) ⇒ "71325" 5989 (string-pad "8871325" 5) ⇒ "71325" 5990 5991 -- Procedure: string-trim string [pred start end] 5992 -- Procedure: string-trim-right string [pred start end] 5993 -- Procedure: string-trim-both string [pred start end] 5994 Returns an istring obtained from the given subrange of STRING by 5995 skipping over all characters on the left / on the right / on both 5996 sides that satisfy the second argument PRED: PRED defaults to 5997 ‘char-whitespace?’. 5998 (string-trim-both " The outlook wasn't brilliant, \n\r") 5999 ⇒ "The outlook wasn't brilliant," 6000 600113.3.4 String Comparisons 6002------------------------- 6003 6004 -- Procedure: string=? STRING1 STRING2 STRING3 ... 6005 Return ‘#t’ if the strings are the same length and contain the same 6006 characters in the same positions. Otherwise, the ‘string=?’ 6007 procedure returns ‘#f’. 6008 6009 (string=? "Straße" "Strasse") ⇒ #f 6010 6011 -- Procedure: string<? STRING1 STRING2 STRING3 ... 6012 -- Procedure: string>? STRING1 STRING2 STRING3 ... 6013 -- Procedure: string<=? STRING1 STRING2 STRING3 ... 6014 -- Procedure: string>=? STRING1 STRING2 STRING3 ... 6015 These procedures return ‘#t’ if their arguments are (respectively): 6016 monotonically increasing, monotonically decreasing, monotonically 6017 non-decreasing, or monotonically nonincreasing. These predicates 6018 are required to be transitive. 6019 6020 These procedures are the lexicographic extensions to strings of the 6021 corresponding orderings on characters. For example, ‘string<?’ is 6022 the lexicographic ordering on strings induced by the ordering 6023 ‘char<?’ on characters. If two strings differ in length but are 6024 the same up to the length of the shorter string, the shorter string 6025 is considered to be lexicographically less than the longer string. 6026 6027 (string<? "z" "ß") ⇒ #t 6028 (string<? "z" "zz") ⇒ #t 6029 (string<? "z" "Z") ⇒ #f 6030 6031 -- Procedure: string-ci=? STRING1 STRING2 STRING3 ... 6032 -- Procedure: string-ci<? STRING1 STRING2 STRING3 ... 6033 -- Procedure: string-ci>? STRING1 STRING2 STRING3 ... 6034 -- Procedure: string-ci<=? STRING1 STRING2 STRING3 ... 6035 -- Procedure: string-ci>=? STRING1 STRING2 STRING3 ... 6036 These procedures are similar to ‘string=?’, etc., but behave as if 6037 they applied ‘string-foldcase’ to their arguments before invoking 6038 the corresponding procedures without ‘-ci’. 6039 6040 (string-ci<? "z" "Z") ⇒ #f 6041 (string-ci=? "z" "Z") ⇒ #t 6042 (string-ci=? "Straße" "Strasse") ⇒ #t 6043 (string-ci=? "Straße" "STRASSE") ⇒ #t 6044 (string-ci=? "ΧΑΟΣ" "χαοσ") ⇒ #t 6045 604613.3.5 Conversions 6047------------------ 6048 6049 -- Procedure: list->string LIST 6050 The ‘list->string’ procedure returns an istring formed from the 6051 characters in LIST, in order. It is an error if any element of 6052 LIST is not a character. 6053 6054 _Compatibility:_ The result is an istring, except in compatibility 6055 mode, when it is an mstring. 6056 6057 -- Procedure: reverse-list->string LIST 6058 An efficient implementation of ‘(compose list->text reverse)’: 6059 (reverse-list->text '(#\a #\B #\c)) ⇒ "cBa" 6060 This is a common idiom in the epilogue of string-processing loops 6061 that accumulate their result using a list in reverse order. (See 6062 also ‘string-concatenate-reverse’ for the “chunked” variant.) 6063 6064 -- Procedure: string->list STRING [START [END]] 6065 The ‘string->list’ procedure returns a newly allocated list of the 6066 characters of STRING between START and END, in order. The 6067 ‘string->list’ and ‘list->string’ procedures are inverses so far as 6068 ‘equal?’ is concerned. 6069 6070 -- Procedure: vector->string vector [start [end]] 6071 The ‘vector->string’ procedure returns a newly allocated string of 6072 the objects contained in the elements of VECTOR between START and 6073 END. It is an error if any element of VECTOR between START and END 6074 is not a character, or is a character forbidden in strings. 6075 (vector->string #(#\1 #\2 #\3)) ⇒ "123" 6076 (vector->string #(#\1 #\2 #\3 #\4 #\5) 2 4) ⇒ "34" 6077 6078 -- Procedure: string->vector string [start [end]] 6079 The ‘string->vector’ procedure returns a newly created vector 6080 initialized to the elements of the string STRING between START and 6081 END. 6082 (string->vector "ABC") ⇒ #(#\A #\B #\C) 6083 (string->vector "ABCDE" 1 3) ⇒ #(#\B #\C) 6084 6085 -- Procedure: string-upcase STRING 6086 -- Procedure: string-downcase STRING 6087 -- Procedure: string-titlecase STRING 6088 -- Procedure: string-foldcase STRING 6089 These procedures take a string argument and return a string result. 6090 They are defined in terms of Unicode’s locale–independent case 6091 mappings from Unicode scalar–value sequences to scalar–value 6092 sequences. In particular, the length of the result string can be 6093 different from the length of the input string. When the specified 6094 result is equal in the sense of ‘string=?’ to the argument, these 6095 procedures may return the argument instead of a newly allocated 6096 string. 6097 6098 The ‘string-upcase’ procedure converts a string to upper case; 6099 ‘string-downcase’ converts a string to lower case. The 6100 ‘string-foldcase’ procedure converts the string to its case–folded 6101 counterpart, using the full case–folding mapping, but without the 6102 special mappings for Turkic languages. The ‘string-titlecase’ 6103 procedure converts the first cased character of each word, and 6104 downcases all other cased characters. 6105 6106 (string-upcase "Hi") ⇒ "HI" 6107 (string-downcase "Hi") ⇒ "hi" 6108 (string-foldcase "Hi") ⇒ "hi" 6109 6110 (string-upcase "Straße") ⇒ "STRASSE" 6111 (string-downcase "Straße") ⇒ "straße" 6112 (string-foldcase "Straße") ⇒ "strasse" 6113 (string-downcase "STRASSE") ⇒ "strasse" 6114 6115 (string-downcase "Σ") ⇒ "σ" 6116 ; Chi Alpha Omicron Sigma: 6117 (string-upcase "ΧΑΟΣ") ⇒ "ΧΑΟΣ" 6118 (string-downcase "ΧΑΟΣ") ⇒ "χαος" 6119 (string-downcase "ΧΑΟΣΣ") ⇒ "χαοσς" 6120 (string-downcase "ΧΑΟΣ Σ") ⇒ "χαος σ" 6121 (string-foldcase "ΧΑΟΣΣ") ⇒ "χαοσσ" 6122 (string-upcase "χαος") ⇒ "ΧΑΟΣ" 6123 (string-upcase "χαοσ") ⇒ "ΧΑΟΣ" 6124 6125 (string-titlecase "kNock KNoCK") ⇒ "Knock Knock" 6126 (string-titlecase "who's there?") ⇒ "Who's There?" 6127 (string-titlecase "r6rs") ⇒ "R6rs" 6128 (string-titlecase "R6RS") ⇒ "R6rs" 6129 6130 Since these procedures are locale–independent, they may not be 6131 appropriate for some locales. 6132 6133 _Kawa Note:_ The implementation of ‘string-titlecase’ does not 6134 correctly handle the case where an initial character needs to be 6135 converted to multiple characters, such as “LATIN SMALL LIGATURE FL” 6136 which should be converted to the two letters ‘"Fl"’. 6137 6138 _Compatibility:_ The result is an istring, except in compatibility 6139 mode, when it is an mstring. 6140 6141 -- Procedure: string-normalize-nfd STRING 6142 -- Procedure: string-normalize-nfkd STRING 6143 -- Procedure: string-normalize-nfc STRING 6144 -- Procedure: string-normalize-nfkc STRING 6145 These procedures take a string argument and return a string result, 6146 which is the input string normalized to Unicode normalization form 6147 D, KD, C, or KC, respectively. When the specified result is equal 6148 in the sense of ‘string=?’ to the argument, these procedures may 6149 return the argument instead of a newly allocated string. 6150 6151 (string-normalize-nfd "\xE9;") ⇒ "\x65;\x301;" 6152 (string-normalize-nfc "\xE9;") ⇒ "\xE9;" 6153 (string-normalize-nfd "\x65;\x301;") ⇒ "\x65;\x301;" 6154 (string-normalize-nfc "\x65;\x301;") ⇒ "\xE9;" 6155 615613.3.6 Searching and matching 6157----------------------------- 6158 6159 -- Procedure: string-prefix-length string_{1} string_{2} [start_{1} 6160 end_{1} start_{2} end_{2}] 6161 -- Procedure: string-suffix-length string_{1} string_{2} [start_{1} 6162 end_{1} start_{2} end_{2}] 6163 Return the length of the longest common prefix/suffix of STRING_{1} 6164 and STRING_{2}. For prefixes, this is equivalent to their 6165 “mismatch index” (relative to the start indexes). 6166 6167 The optional START/END indexes restrict the comparison to the 6168 indicated substrings of STRING_{1} and STRING_{2}. 6169 6170 -- Procedure: string-prefix? string_{1} string_{2} [start_{1} end_{1} 6171 start_{2} end_{2}] 6172 -- Procedure: string-suffix? string_{1} string_{2} [start_{1} end_{1} 6173 start_{2} end_{2}] 6174 Is STRING_{1} a prefix/suffix of STRING_{2}? 6175 6176 The optional START/END indexes restrict the comparison to the 6177 indicated substrings of STRING_{1} and STRING_{2}. 6178 6179 -- Procedure: string-index string pred [start end] 6180 -- Procedure: string-index-right string pred [start end] 6181 -- Procedure: string-skip string pred [start end] 6182 -- Procedure: string-skip-right string pred [start end] 6183 6184 ‘string-index’ searches through the given substring from the left, 6185 returning the index of the leftmost character satisfying the 6186 predicate PRED. ‘string-index-right’ searches from the right, 6187 returning the index of the rightmost character satisfying the 6188 predicate PRED. If no match is found, these procedures return 6189 ‘#f’. 6190 6191 The START and END arguments specify the beginning and end of the 6192 search; the valid indexes relevant to the search include START but 6193 exclude END. Beware of “fencepost”" errors: when searching 6194 right-to-left, the first index considered is ‘(- END 1)’, whereas 6195 when searching left-to-right, the first index considered is START. 6196 That is, the start/end indexes describe the same half-open interval 6197 ‘[START,END)’ in these procedures that they do in other string 6198 procedures. 6199 6200 The ‘-skip’ functions are similar, but use the complement of the 6201 criterion: they search for the first char that _doesn’t_ satisfy 6202 PRED. To skip over initial whitespace, for example, say 6203 6204 (substring string 6205 (or (string-skip string char-whitespace?) 6206 (string-length string)) 6207 (string-length string)) 6208 6209 These functions can be trivially composed with ‘string-take’ and 6210 ‘string-drop’ to produce ‘take-while’, ‘drop-while’, ‘span’, and 6211 ‘break’ procedures without loss of efficiency. 6212 6213 -- Procedure: string-contains string_{1} string_{2} [start_{1} end_{1} 6214 start_{2} end_{2}] 6215 -- Procedure: string-contains-right string_{1} string_{2} [start_{1} 6216 end_{1} start_{2} end_{2}] 6217 Does the substring of STRING_{1} specified by START_{1} and END_{1} 6218 contain the sequence of characters given by the substring of 6219 STRING_{2} specified by START_{2} and END_{2}? 6220 6221 Returns ‘#f’ if there is no match. If START_{2} = END_{2}, 6222 ‘string-contains’ returns START_{1} but ‘string-contains-right’ 6223 returns END_{1}. Otherwise returns the index in STRING_{1} for the 6224 first character of the first/last match; that index lies within the 6225 half-open interval [START_{1},END_{1}), and the match lies entirely 6226 within the [START_{1},END_{1}) range of STRING_{1}. 6227 6228 (string-contains "eek -- what a geek." "ee" 12 18) ; Searches "a geek" 6229 ⇒ 15 6230 Note: The names of these procedures do not end with a question 6231 mark. This indicates a useful value is returned when there is a 6232 match. 6233 623413.3.7 Concatenation and replacing 6235---------------------------------- 6236 6237 -- Procedure: string-append STRING ... 6238 Returns a string whose characters form the concatenation of the 6239 given strings. 6240 6241 _Compatibility:_ The result is an istring, except in compatibility 6242 mode, when it is an mstring. 6243 6244 -- Procedure: string-concatenate string-list 6245 Concatenates the elements of STRING-LIST together into a single 6246 istring. 6247 6248 _Rationale:_ Some implementations of Scheme limit the number of 6249 arguments that may be passed to an n-ary procedure, so the ‘(apply 6250 string-append STRING-LIST)’ idiom, which is otherwise equivalent to 6251 using this procedure, is not as portable. 6252 6253 -- Procedure: string-concatenate-reverse string-list [final-string 6254 [end]]) 6255 With no optional arguments, calling this procedure is equivalent to 6256 ‘(string-concatenate (reverse STRING-LIST))’. If the optional 6257 argument FINAL-STRING is specified, it is effectively consed onto 6258 the beginning of STRING-LIST before performing the list-reverse and 6259 string-concatenate operations. 6260 6261 If the optional argument END is given, only the characters up to 6262 but not including END in FINAL-STRING are added to the result, thus 6263 producing 6264 (string-concatenate 6265 (reverse (cons (substring final-string 0 end) 6266 string-list))) 6267 For example: 6268 (string-concatenate-reverse '(" must be" "Hello, I") " going.XXXX" 7) 6269 ⇒ "Hello, I must be going." 6270 6271 _Rationale:_ This procedure is useful when constructing procedures 6272 that accumulate character data into lists of string buffers, and 6273 wish to convert the accumulated data into a single string when 6274 done. The optional end argument accommodates that use case when 6275 FINAL-STRING is a bob-full mutable string, and is allowed (for 6276 uniformity) when FINAL-STRING is an immutable string. 6277 6278 -- Procedure: string-join string-list [delimiter [grammar]] 6279 This procedure is a simple unparser; it pastes strings together 6280 using the DELIMITER string, returning an istring. 6281 6282 The STRING-LIST is a list of strings. The DELIMITER is the string 6283 used to delimit elements; it defaults to a single space ‘" "’. 6284 6285 The GRAMMAR argument is a symbol that determines how the DELIMITER 6286 is used, and defaults to ‘'infix’. It is an error for GRAMMAR to 6287 be any symbol other than these four: 6288 ‘'infix’ 6289 An infix or separator grammar: insert the delimiter between 6290 list elements. An empty list will produce an empty string. 6291 ‘'strict-infix’ 6292 Means the same as ‘'infix’ if the string-list is non-empty, 6293 but will signal an error if given an empty list. (This avoids 6294 an ambiguity shown in the examples below.) 6295 ‘'suffix’ 6296 Means a suffix or terminator grammar: insert the DELIMITER 6297 after every list element. 6298 ‘'prefix’ 6299 Means a prefix grammar: insert the DELIMITER before every list 6300 element. 6301 6302 (string-join '("foo" "bar" "baz")) 6303 ⇒ "foo bar baz" 6304 (string-join '("foo" "bar" "baz") "") 6305 ⇒ "foobarbaz" 6306 (string-join '("foo" "bar" "baz") ":") 6307 ⇒ "foo:bar:baz" 6308 (string-join '("foo" "bar" "baz") ":" 'suffix) 6309 ⇒ "foo:bar:baz:" 6310 6311 ;; Infix grammar is ambiguous wrt empty list vs. empty string: 6312 (string-join '() ":") ⇒ "" 6313 (string-join '("") ":") ⇒ "" 6314 6315 ;; Suffix and prefix grammars are not: 6316 (string-join '() ":" 'suffix)) ⇒ "" 6317 (string-join '("") ":" 'suffix)) ⇒ ":" 6318 6319 -- Procedure: string-replace string_{1} string_{2} start_{1} end_{1} 6320 [start_{2} end_{2}] 6321 Returns 6322 (string-append (substring STRING_{1} 0 START_{1}) 6323 (substring STRING_{2} START_{2} END_{2}) 6324 (substring STRING_{1} END_{1} (string-length STRING_{1}))) 6325 That is, the segment of characters in STRING_{1} from START_{1} to 6326 END_{1} is replaced by the segment of characters in STRING_{2} from 6327 START_{2} to END_{2}. If START_{1}=END_{1}, this simply splices 6328 the characters drawn from STRING_{2} into STRING_{1} at that 6329 position. 6330 6331 Examples: 6332 (string-replace "The TCL programmer endured daily ridicule." 6333 "another miserable perl drone" 4 7 8 22) 6334 ⇒ "The miserable perl programmer endured daily ridicule." 6335 6336 (string-replace "It's easy to code it up in Scheme." "lots of fun" 5 9) 6337 ⇒ "It's lots of fun to code it up in Scheme." 6338 6339 (define (string-insert s i t) (string-replace s t i i)) 6340 6341 (string-insert "It's easy to code it up in Scheme." 5 "really ") 6342 ⇒ "It's really easy to code it up in Scheme." 6343 6344 (define (string-set s i c) (string-replace s (string c) i (+ i 1))) 6345 6346 (string-set "String-ref runs in O(n) time." 19 #\1) 6347 ⇒ "String-ref runs in O(1) time." 6348 6349 Also see ‘string-append!’ and ‘string-replace!’ for destructive 6350changes to a mutable string. 6351 635213.3.8 Mapping and folding 6353-------------------------- 6354 6355 -- Procedure: string-fold kons knil string [start end] 6356 -- Procedure: string-fold-right kons knil string [start end] 6357 These are the fundamental iterators for strings. 6358 6359 The ‘string-fold’ procedure maps the KONS procedure across the 6360 given STRING from left to right: 6361 (... (KONS STRING_{2} (KONS STRING_{1} (KONS STRING_{0} KNIL)))) 6362 In other words, string-fold obeys the (tail) recursion 6363 (string-fold KONS KNIL STRING START END) 6364 = (string-fold KONS (KONS STRING_{start} KNIL) START+1 END) 6365 The ‘string-fold-right’ procedure maps KONS across the given string 6366 STRING from right to left: 6367 (KONS STRING_{0} 6368 (... (KONS STRING_{END-3} 6369 (KONS STRING_{END-2} 6370 (KONS STRING_{END-1} 6371 KNIL))))) 6372 obeying the (tail) recursion 6373 (string-fold-right KONS KNIL STRING START END) 6374 = (string-fold-right KONS (KONS STRING_{END-1} KNIL) START END-1) 6375 Examples: 6376 ;;; Convert a string or string to a list of chars. 6377 (string-fold-right cons '() string) 6378 6379 ;;; Count the number of lower-case characters in a string or string. 6380 (string-fold (lambda (c count) 6381 (if (char-lower-case? c) 6382 (+ count 1) 6383 count)) 6384 0 6385 string) 6386 The string-fold-right combinator is sometimes called a 6387 "catamorphism." 6388 6389 -- Procedure: string-for-each PROC STRING1 STRING2 ... 6390 -- Procedure: string-for-each PROC STRING1 [start [end]] 6391 The STRINGs must all have the same length. PROC should accept as 6392 many arguments as there are STRINGs. 6393 6394 The START-END variant is provided for compatibility with the 6395 SRFI-13 version. (In that case START and END count code Unicode 6396 scalar values (‘character’ values), not Java 16-bit ‘char’ values.) 6397 6398 The ‘string-for-each’ procedure applies PROC element–wise to the 6399 characters of the STRINGs for its side effects, in order from the 6400 first characters to the last. PROC is always called in the same 6401 dynamic environment as ‘string-for-each’ itself. 6402 6403 Analogous to ‘for-each’. 6404 6405 (let ((v '())) 6406 (string-for-each 6407 (lambda (c) (set! v (cons (char->integer c) v))) 6408 "abcde") 6409 v) 6410 ⇒ (101 100 99 98 97) 6411 6412 _Performance note:_ The compiler generates efficient code for 6413 ‘string-for-each’. If PROC is a lambda expression, it is inlined. 6414 6415 -- Procedure: string-map PROC STRING1 STRING2 ... 6416 The ‘string-map’ procedure applies PROC element-wise to the 6417 elements of the strings and returns a string of the results, in 6418 order. It is an error if PROC does not accept as many arguments as 6419 there are strings, or return other than a single character or a 6420 string. If more than one string is given and not all strings have 6421 the same length, ‘string-map’ terminates when the shortest string 6422 runs out. The dynamic order in which PROC is applied to the 6423 elements of the strings is unspecified. 6424 6425 (string-map char-foldcase "AbdEgH") ⇒ "abdegh" 6426 (string-map 6427 (lambda (c) (integer->char (+ 1 (char->integer c)))) 6428 "HAL") 6429 ⇒ "IBM" 6430 (string-map 6431 (lambda (c k) 6432 ((if (eqv? k #\u) char-upcase char-downcase) c)) 6433 "studlycaps xxx" 6434 "ululululul") 6435 ⇒ "StUdLyCaPs" 6436 6437 Traditionally the result of PROC had to be a character, but Kawa 6438 (and SRFI-140) allows the result to be a string. 6439 6440 _Performance note:_ The ‘string-map’ procedure has not been 6441 optimized (mainly because it is not very useful): The characters 6442 are boxed, and the PROC is not inlined even if it is a lambda 6443 expression. 6444 6445 -- Procedure: string-map-index proc string [start end] 6446 6447 Calls PROC on each valid index of the specified substring, converts 6448 the results of those calls into strings, and returns the 6449 concatenation of those strings. It is an error for PROC to return 6450 anything other than a character or string. The dynamic order in 6451 which proc is called on the indexes is unspecified, as is the 6452 dynamic order in which the coercions are performed. If any strings 6453 returned by PROC are mutated after they have been returned and 6454 before the call to ‘string-map-index’ has returned, then 6455 ‘string-map-index’ returns a string with unspecified contents; the 6456 STRING-MAP-INDEX procedure itself does not mutate those strings. 6457 6458 -- Procedure: string-for-each-index proc string [start end] 6459 6460 Calls PROC on each valid index of the specified substring, in 6461 increasing order, discarding the results of those calls. This is 6462 simply a safe and correct way to loop over a substring. 6463 6464 Example: 6465 (let ((txt (string->string "abcde")) 6466 (v '())) 6467 (string-for-each-index 6468 (lambda (cur) (set! v (cons (char->integer (string-ref txt cur)) v))) 6469 txt) 6470 v) ⇒ (101 100 99 98 97) 6471 6472 -- Procedure: string-count string pred [start end] 6473 Returns a count of the number of characters in the specified 6474 substring of STRING that satisfy the predicate PRED. 6475 6476 -- Procedure: string-filter pred string [start end] 6477 -- Procedure: string-remove pred string [start end] 6478 Return an immutable string consisting of only selected characters, 6479 in order: ‘string-filter’ selects only the characters that satisfy 6480 PRED; ‘string-remove’ selects only the characters that _not_ 6481 satisfy PRED 6482 648313.3.9 Replication & splitting 6484------------------------------ 6485 6486 -- Procedure: string-repeat string-or-character len 6487 Create an istring by repeating the first argument LEN times. If 6488 the first argument is a character, it is as if it were wrapped with 6489 the ‘string’ constructor. We can define string-repeat in terms of 6490 the more general ‘xsubstring’ procedure: 6491 (define (string-repeat S N) 6492 (let ((T (if (char? S) (string S) S))) 6493 (xsubstring T 0 (* N (string-length T)))) 6494 6495 -- Procedure: xsubstring string [from to [start end]] 6496 This is an extended substring procedure that implements replicated 6497 copying of a substring. The STRING is a string; START and END are 6498 optional arguments that specify a substring of STRING, defaulting 6499 to 0 and the length of STRING. This substring is conceptually 6500 replicated both up and down the index space, in both the positive 6501 and negative directions. For example, if STRING is ‘"abcdefg"’, 6502 START is 3, and END is 6, then we have the conceptual 6503 bidirectionally-infinite string 6504 ... d e f d e f d e f d e f d e f d e f d ... 6505 -9 -8 -7 -6 -5 -4 -3 -2 -1 0 +1 +2 +3 +4 +5 +6 +7 +8 +9 6506 ‘xsubstring’ returns the substring of the STRING beginning at index 6507 FROM, and ending at TO. It is an error if FROM is greater than TO. 6508 6509 If FROM and TO are missing they default to 0 and FROM+(END-START), 6510 respectively. This variant is a generalization of using 6511 ‘substring’, but unlike ‘substring’ never shares substructures that 6512 would retain characters or sequences of characters that are 6513 substructures of its first argument or previously allocated 6514 objects. 6515 6516 You can use ‘xsubstring’ to perform a variety of tasks: 6517 • To rotate a string left: ‘(xsubstring "abcdef" 2 8) ⇒ 6518 "cdefab"’ 6519 • To rotate a string right: ‘(xsubstring "abcdef" -2 4) ⇒ 6520 "efabcd"’ 6521 • To replicate a string: ‘(xsubstring "abc" 0 7) ⇒ "abcabca"’ 6522 6523 Note that 6524 • The FROM/TO arguments give a half-open range containing the 6525 characters from index FROM up to, but not including, index TO. 6526 • The FROM/TO indexes are not expressed in the index space of 6527 STRING. They refer instead to the replicated index space of 6528 the substring defined by STRING, START, and END. 6529 6530 It is an error if START=END, unless FROM=TO, which is allowed as a 6531 special case. 6532 6533 -- Procedure: string-split string delimiter [grammar limit start end] 6534 Returns a list of strings representing the words contained in the 6535 substring of STRING from START (inclusive) to END (exclusive). The 6536 DELIMITER is a string to be used as the word separator. This will 6537 often be a single character, but multiple characters are allowed 6538 for use cases such as splitting on ‘"\r\n"’. The returned list 6539 will have one more item than the number of non-overlapping 6540 occurrences of the DELIMITER in the string. If DELIMITER is an 6541 empty string, then the returned list contains a list of strings, 6542 each of which contains a single character. 6543 6544 The GRAMMAR is a symbol with the same meaning as in the 6545 ‘string-join’ procedure. If it is ‘infix’, which is the default, 6546 processing is done as described above, except an empty string 6547 produces the empty list; if grammar is ‘strict-infix’, then an 6548 empty string signals an error. The values ‘prefix’ and ‘suffix’ 6549 cause a leading/trailing empty string in the result to be 6550 suppressed. 6551 6552 If LIMIT is a non-negative exact integer, at most that many splits 6553 occur, and the remainder of string is returned as the final element 6554 of the list (so the result will have at most limit+1 elements). If 6555 limit is not specified or is #f, then as many splits as possible 6556 are made. It is an error if limit is any other value. 6557 6558 To split on a regular expression, you can use SRFI 115’s 6559 ‘regexp-split’ procedure. 6560 656113.3.10 String mutation 6562----------------------- 6563 6564The following procedures create a mutable string, i.e. one that you can 6565modify. 6566 6567 -- Procedure: make-string [K [CHAR]] 6568 Return a newly allocated mstring of K characters, where K defaults 6569 to 0. If CHAR is given, then all elements of the string are 6570 initialized to CHAR, otherwise the contents of the STRING are 6571 unspecified. 6572 6573 The 1-argument version is deprecated as poor style, except when k 6574 is 0. 6575 6576 _Rationale:_ In many languags the most common pattern for mutable 6577 strings is to allocate an empty string and incrementally append to 6578 it. It seems natural to initialize the string with 6579 ‘(make-string)’, rather than ‘(make-string 0)’. 6580 6581 To return an immutable string that repeats K times a character CHAR 6582 use ‘string-repeat’. 6583 6584 This is as R7RS, except the result is variable-size and we allow 6585 leaving out K when it is zero. 6586 6587 -- Procedure: string-copy STRING [START [END]] 6588 Returns a newly allocated mutable (mstring) copy of the part of the 6589 given STRING between START and END. 6590 6591 The following procedures modify a mutable string. 6592 6593 -- Procedure: string-set! string k char 6594 This procedure stores CHAR in element K of STRING. 6595 6596 (define s1 (make-string 3 #\*)) 6597 (define s2 "***") 6598 (string-set! s1 0 #\?) ⇒ _void_ 6599 s1 ⇒ "?**" 6600 (string-set! s2 0 #\?) ⇒ _error_ 6601 (string-set! (symbol->string 'immutable) 0 #\?) ⇒ _error_ 6602 6603 _Performance note:_ Calling ‘string-set!’ may take time 6604 proportional to the length of the string: First it must scan for 6605 the right position, like ‘string-ref’ does. Then if the new 6606 character requires using a surrogate pair (and the old one doesn’t) 6607 then we have to make room in the string, possibly re-allocating a 6608 new ‘char’ array. Alternatively, if the old character requires 6609 using a surrogate pair (and the new one doesn’t) then following 6610 characters need to be moved. 6611 6612 The function ‘string-set!’ is deprecated: It is inefficient, and it 6613 very seldom does the correct thing. Instead, you can construct a 6614 string with ‘string-append!’. 6615 6616 -- Procedure: string-append! STRING VALUE ... 6617 The STRING must be a mutable string, such as one returned by 6618 ‘make-string’ or ‘string-copy’. The ‘string-append!’ procedure 6619 extends STRING by appending each VALUE (in order) to the end of 6620 STRING. Each ‘value’ should be a character or a string. 6621 6622 _Performance note:_ The compiler converts a call with multiple 6623 VALUEs to multiple ‘string-append!’ calls. If a VALUE is known to 6624 be a ‘character’, then no boxing (object-allocation) is needed. 6625 6626 The following example shows how to efficiently process a string 6627 using ‘string-for-each’ and incrementally “build” a result string 6628 using ‘string-append!’. 6629 6630 (define (translate-space-to-newline str::string)::string 6631 (let ((result (make-string 0))) 6632 (string-for-each 6633 (lambda (ch) 6634 (string-append! result 6635 (if (char=? ch #\Space) #\Newline ch))) 6636 str) 6637 result)) 6638 6639 -- Procedure: string-copy! TO AT FROM [START [END]] 6640 Copies the characters of the string FROM that are between START end 6641 END into the string TO, starting at index AT. The order in which 6642 characters are copied is unspecified, except that if the source and 6643 destination overlap, copying takes place as if the source is first 6644 copied into a temporary string and then into the destination. 6645 (This is achieved without allocating storage by making sure to copy 6646 in the correct direction in such circumstances.) 6647 6648 This is equivalent to (and implemented as): 6649 (string-replace! to at (+ at (- end start)) from start end)) 6650 6651 (define a "12345") 6652 (define b (string-copy "abcde")) 6653 (string-copy! b 1 a 0 2) 6654 b ⇒ "a12de" 6655 6656 -- Procedure: string-replace! DST DST-START DST-END SRC [SRC-START 6657 [SRC-END]] 6658 Replaces the characters of string DST (between DST-START and 6659 DST-END) with the characters of SRC (between SRC-START and 6660 SRC-END). The number of characters from SRC may be different than 6661 the number replaced in DST, so the string may grow or contract. 6662 The special case where DST-START is equal to DST-END corresponds to 6663 insertion; the case where SRC-START is equal to SRC-END corresponds 6664 to deletion. The order in which characters are copied is 6665 unspecified, except that if the source and destination overlap, 6666 copying takes place as if the source is first copied into a 6667 temporary string and then into the destination. (This is achieved 6668 without allocating storage by making sure to copy in the correct 6669 direction in such circumstances.) 6670 6671 -- Procedure: string-fill! STRING FILL [START [END]] 6672 The ‘string-fill!’ procedure stores FILL in the elements of STRING 6673 between START and END. It is an error if FILL is not a character 6674 or is forbidden in strings. 6675 667613.3.11 Strings as sequences 6677---------------------------- 6678 667913.3.11.1 Indexing a string 6680........................... 6681 6682Using function-call syntax with strings is convenient and efficient. 6683However, it has some “gotchas”. 6684 6685 We will use the following example string: 6686 (! str1 "Smile \x1f603;!") 6687 or if you’re brave: 6688 (! str1 "Smile ��!") 6689 6690 This is ‘"Smile "’ followed by an emoticon (“smiling face with open 6691mouth”) followed by ‘"!"’. The emoticon has scalar value ‘\x1f603’ - it 6692is not in the 16-bit Basic Multi-language Plane, and so it must be 6693encoded by a surrogate pair (‘#\xd83d’ followed by ‘#\xde03’). 6694 6695 The number of scalar values (‘character’s) is 8, while the number of 669616-bits code units (‘char’s) is 9. The ‘java.lang.CharSequence:length’ 6697method counts ‘char’s. Both the ‘length’ and the ‘string-length’ 6698procedures count ‘character’s. Thus: 6699 6700 (length str1) ⇒ 8 6701 (string-length str1) ⇒ 8 6702 (str1:length) ⇒ 9 6703 6704 Counting ‘char’s is a constant-time operation (since it is stored in 6705the data structure). Counting ‘character’s depends on the 6706representation used: In geneeral it may take time proportional to the 6707length of the string, since it has to subtract one for each surrogate 6708pair; however the ISTRING type (‘gnu.lists.IString’ class) uses a extra 6709structure so it can count characters in constant-time. 6710 6711 Similarly we can can index the string in 3 ways: 6712 6713 (str1 1) ⇒ #\m :: character 6714 (string-ref str1 1) ⇒ #\m :: character 6715 (str1:charAt 1) ⇒ #\m :: char 6716 6717 Using function-call syntax when the “function” is a string and a 6718single integer argument is the same as using ‘string-ref’. 6719 6720 Things become interesting when we reach the emoticon: 6721 6722 (str1 6) ⇒ #\�� :: character 6723 (str1:charAt 6) ⇒ #\d83d :: char 6724 6725 Both ‘string-ref’ and the function-call syntax return the real 6726character, while the ‘charAt’ methods returns a partial character. 6727 6728 (str1 7) ⇒ #\! :: character 6729 (str1:charAt 7) ⇒ #\de03 :: char 6730 (str1 8) ⇒ throws StringIndexOutOfBoundsException 6731 (str1:charAt 8) ⇒ #\! :: char 6732 673313.3.11.2 Indexing with a sequence 6734.................................. 6735 6736You can index a string with a list of integer indexes, most commonly a 6737range: 6738 (STR [I ...]) 6739 is basically the same as: 6740 (string (STR I) ...) 6741 6742 Generally when working with strings it is best to work with 6743substrings rather than individual characters: 6744 (STR [START <: END]) 6745 6746 This is equivalent to invoking the ‘substring’ procedure: 6747 (substring STR START END) 6748 674913.3.12 String Cursor API 6750------------------------- 6751 6752Indexing into a string (using for example ‘string-ref’) is inefficient 6753because of the possible presence of surrogate pairs. Hence given an 6754index I access normally requires linearly scanning the string until we 6755have seen I characters. 6756 6757 The string-cursor API is defined in terms of abstract “cursor 6758values”, which point to a position in the string. This avoids the 6759linear scan. 6760 6761 Typical usage is: 6762 (let* ((str WHATEVER) 6763 (end (string-cursor-end str))) 6764 (do ((sc::string-cursor (string-cursor-start str) 6765 (string-cursor-next str sc))) 6766 ((string-cursor>=? sc end)) 6767 (let ((ch (string-cursor-ref str sc))) 6768 (DO-SOMETHING-WITH ch)))) 6769 Alternatively, the following may be marginally faster: 6770 (let* ((str WHATEVER) 6771 (end (string-cursor-end str))) 6772 (do ((sc::string-cursor (string-cursor-start str) 6773 (string-cursor-next-quick sc))) 6774 ((string-cursor>=? sc end)) 6775 (let ((ch (string-cursor-ref str sc))) 6776 (if (not (char=? ch #\ignorable-char)) 6777 (DO-SOMETHING-WITH ch))))) 6778 6779 The API is non-standard, but is based on that in Chibi Scheme. 6780 6781 -- Type: string-cursor 6782 An abstract position (index) in a string. Implemented as a 6783 primitive ‘int’ which counts the number of preceding code units 6784 (16-bit ‘char’ values). 6785 6786 -- Procedure: string-cursor-start str 6787 Returns a cursor for the start of the string. The result is always 6788 0, cast to a ‘string-cursor’. 6789 6790 -- Procedure: string-cursor-end str 6791 Returns a cursor for the end of the string - one past the last 6792 valid character. Implemented as ‘(as string-cursor (invoke STR 6793 'length))’. 6794 6795 -- Procedure: string-cursor-ref str cursor 6796 Return the ‘character’ at the CURSOR. If the CURSOR points to the 6797 second ‘char’ of a surrogate pair, returns ‘#\ignorable-char’. 6798 6799 -- Procedure: string-cursor-next string cursor [count] 6800 Return the cursor position COUNT (default 1) character positions 6801 forwards beyond CURSOR. For each COUNT this may add either 1 or 2 6802 (if pointing at a surrogate pair) to the CURSOR. 6803 6804 -- Procedure: string-cursor-next-quiet cursor 6805 Increment cursor by one raw ‘char’ position, even if CURSOR points 6806 to the start of a surrogate pair. (In that case the next 6807 ‘string-cursor-ref’ will return ‘#\ignorable-char’.) Same as ‘(+ 6808 CURSOR 1)’ but with the ‘string-cursor’ type. 6809 6810 -- Procedure: string-cursor-prev string cursor [count] 6811 Return the cursor position COUNT (default 1) character positions 6812 backwards before CURSOR. 6813 6814 -- Procedure: substring-cursor string [start [end]] 6815 Create a substring of the section of STRING between the cursors 6816 START and END. 6817 6818 -- Procedure: string-cursor<? cursor1 cursor2 6819 -- Procedure: string-cursor<=? cursor1 cursor2 6820 -- Procedure: string-cursor=? cursor1 cursor2 6821 -- Procedure: string-cursor>=? cursor1 cursor2 6822 -- Procedure: string-cursor>? cursor1 cursor2 6823 Is the position of CURSOR1 respectively before, before or same, 6824 same, after, or after or same, as CURSOR2. 6825 6826 _Performance note:_ Implemented as the corresponding ‘int’ 6827 comparison. 6828 6829 -- Procedure: string-cursor-for-each proc string [start [end]] 6830 Apply the procedure PROC to each character position in STRING 6831 between the cursors START and END. 6832 6833 6834File: kawa.info, Node: String literals, Next: Unicode, Prev: Strings, Up: Characters and text 6835 683613.4 String literals 6837==================== 6838 6839Kaw support two syntaxes of string literals: The traditional, portable, 6840qdouble-quoted-delimited literals like ‘"this"’; and extended SRFI-109 6841quasi-literals like ‘&{this}’. 6842 684313.4.1 Simple string literals 6844----------------------------- 6845 6846 STRING ::= ‘"’STRING-ELEMENT^{*}‘"’ 6847 STRING-ELEMENT ::= any character other than ‘"’ or ‘\’ 6848 | MNEMONIC-ESCAPE | ‘\"’ | ‘\\’ 6849 | ‘\’INTRALINE-WHITESPACE^{*}LINE-ENDING INTRALINE-WHITESPACE^{*} 6850 | INLINE-HEX-ESCAPE 6851 MNEMONIC-ESCAPE ::= ‘\a’ | ‘\b’ | ‘\t’ | ‘\n’ | ‘\r’ | ... (see below) 6852 6853 A string is written as a sequence of characters enclosed within 6854quotation marks (‘"’). Within a string literal, various escape sequence 6855represent characters other than themselves. Escape sequences always 6856start with a backslash (‘\’): 6857‘\a’ 6858 Alarm (bell), ‘#\x0007’. 6859‘\b’ 6860 Backspace, ‘#\x0008’. 6861‘\e’ 6862 Escape, ‘#\x001B’. 6863‘\f’ 6864 Form feed, ‘#\x000C’. 6865‘\n’ 6866 Linefeed (newline), ‘#\x000A’. 6867‘\r’ 6868 Return, ‘#\x000D’. 6869‘\t’ 6870 Character tabulation, ‘#\x0009’. 6871‘\v’ 6872 Vertical tab, ‘#\x000B’. 6873‘\C-’X 6874‘\^’X 6875 Returns the scalar value of X masked (anded) with ‘#x9F’. An 6876 alternative way to write the Ascii control characters: For example 6877 ‘"\C-m"’ or ‘"\^m"’ is the same as ‘"#\x000D"’ (which the same as 6878 ‘"\r"’). As a special case ‘\^?’ is rubout (delete) (‘\x7f;’). 6879‘\x’ HEX-SCALAR-VALUE‘;’ 6880‘\X’ HEX-SCALAR-VALUE‘;’ 6881 A hex encoding that gives the scalar value of a character. 6882‘\\’ OCT-DIGIT^{+} 6883 At most three octal digits that give the scalar value of a 6884 character. (Historical, for C compatibility.) 6885‘\u’ HEX-DIGIT^{+} 6886 Exactly four hex digits that give the scalar value of a character. 6887 (Historical, for Java compatibility.) 6888‘\M-’X 6889 (Historical, for Emacs Lisp.) Set the meta-bit (high-bit of single 6890 byte) of the following character X. 6891‘\|’ 6892 Vertical line, ‘#\x007c’. (Not useful for string literals, but 6893 useful for symbols.) 6894‘\"’ 6895 Double quote, ‘#\x0022’. 6896‘\\’ 6897 Backslah, ‘#\005C’. 6898‘\’INTRALINE-WHITESPACE^{*}LINE-ENDING INTRALINE-WHITESPACE^{*} 6899 Nothing (ignored). Allows you to split up a long string over 6900 multiple lines; ignoring initial whitespace on the continuation 6901 lines allows you to indent them. 6902 6903 Except for a line ending, any character outside of an escape sequence 6904stands for itself in the string literal. A line ending which is 6905preceded by ‘\’INTRALINE-WHITESPACE^{*} expands to nothing (along with 6906any trailing INTRALINE-WHITESPACE), and can be used to indent strings 6907for improved legibility. Any other line ending has the same effect as 6908inserting a ‘\n’ character into the string. 6909 6910 Examples: 6911 "The word \"recursion\" has many meanings." 6912 "Another example:\ntwo lines of text" 6913 "Here’s text \ 6914 containing just one line" 6915 "\x03B1; is named GREEK SMALL LETTER ALPHA." 6916 691713.4.2 String templates 6918----------------------- 6919 6920The following syntax is a “string template” (also called a string 6921quasi-literal or “here document 6922(http://en.wikipedia.org/wiki/Here_document)”): 6923 &{Hello &[name]!} 6924 Assuming the variable ‘name’ evaluates to ‘"John"’ then the example 6925evaluates to ‘"Hello John!"’. 6926 6927 The Kawa reader converts the above example to: 6928 ($string$ "Hello " $<<$ name $>>$ "!") 6929 See the SRFI-109 (http://srfi.schemers.org/srfi-109/srfi-109.html) 6930specification for details. 6931 6932 EXTENDED-STRING-LITERAL ::= ‘&{’ [INITIAL-IGNORED] STRING-LITERAL-PART^{*} ‘}’ 6933 STRING-LITERAL-PART ::= any character except ‘&’, ‘{’ or ‘}’ 6934 | ‘{’ STRING-LITERAL-PART^{*} ‘}’ 6935 | CHAR-REF 6936 | ENTITY-REF 6937 | SPECIAL-ESCAPE 6938 | ENCLOSED-PART 6939 6940 You can use the plain ‘"STRING"’ syntax for longer multiline strings, 6941but ‘&{STRING}’ has various advantages. The syntax is less error-prone 6942because the start-delimiter is different from the end-delimiter. Also 6943note that nested braces are allowed: a right brace ‘}’ is only an 6944end-delimiter if it is unbalanced, so you would seldom need to escape 6945it: 6946 &{This has a {braced} section.} 6947 ⇒ "This has a {braced} section." 6948 6949 The escape character used for special characters is ‘&’. This is 6950compatible with XML syntax and *note XML literals::. 6951 695213.4.2.1 Special characters 6953........................... 6954 6955 CHAR-REF ::= 6956 ‘&#’ DIGIT^{+} ‘;’ 6957 | ‘&#x’ HEX-DIGIT^{+} ‘;’ 6958 ENTITY-REF ::= 6959 ‘&’ CHAR-OR-ENTITY-NAME ‘;’ 6960 CHAR-OR-ENTITY-NAME ::= TAGNAME 6961 6962 You can the standard XML syntax for character references, using 6963either decimal or hexadecimal values. The following string has two 6964instances of the Ascii escape character, as either decimal 27 or hex 1B: 6965 &{} ⇒ "\e\e" 6966 6967 You can also use the pre-defined XML entity names: 6968 &{& < > " '} ⇒ "& < > \" '" 6969 In addition, ‘{’ ‘}’ can be used for left and right 6970curly brace, though you don’t need them for balanced parentheses: 6971 &{ }_{ / {_} } ⇒ " }_{ / {_} " 6972 6973 You can use the standard XML entity names 6974(http://www.w3.org/2003/entities/2007/w3centities-f.ent). For example: 6975 &{Lærdalsøyri} 6976 ⇒ "Lærdalsøyri" 6977 6978 You can also use the standard R7RS character names ‘null’, ‘alarm’, 6979‘backspace’, ‘tab’, ‘newline’, ‘return’, ‘escape’, ‘space’, and 6980‘delete’. For example: 6981 &{&escape;&space;} 6982 6983 The syntax ‘&NAME;’ is actually syntactic sugar (specifically reader 6984syntax) to the variable reference ‘$entity$:NAME’. Hence you can also 6985define your own entity names: 6986 (define $entity$:crnl "\r\n") 6987 &{&crnl;} ⟹ "\r\n" 6988 698913.4.2.2 Multiline string literals 6990.................................. 6991 6992 INITIAL-IGNORED ::= 6993 INTRALINE-WHITESPACE^{*} LINE-ENDING INTRALINE-WHITESPACE^{*} &| 6994 SPECIAL-ESCAPE ::= 6995 INTRALINE-WHITESPACE^{*} &| 6996 | & NESTED-COMMENT 6997 | &- INTRALINE-WHITESPACE^{*} LINE-ENDING 6998 6999 A line-ending directly in the text is becomes a newline, as in a 7000simple string literal: 7001 (string-capitalize &{one two three 7002 uno dos tres 7003 }) ⇒ "One Two Three\nUno Dos Tres\n" 7004 However, you have extra control over layout. If the string is in a 7005nested expression, it is confusing (and ugly) if the string cannot be 7006indented to match the surrounding context. The indentation marker ‘&|’ 7007is used to mark the end of insignificant initial whitespace. The ‘&|’ 7008characters and all the preceding whitespace are removed. In addition, 7009it also suppresses an initial newline. Specifically, when the initial 7010left-brace is followed by optional (invisible) intraline-whitespace, 7011then a newline, then optional intraline-whitespace (the indentation), 7012and finally the indentation marker ‘&|’ - all of which is removed from 7013the output. Otherwise the ‘&|’ only removes initial 7014intraline-whitespace on the same line (and itself). 7015 7016 (write (string-capitalize &{ 7017 &|one two three 7018 &|uno dos tres 7019 }) out) 7020 ⇒ prints "One Two Three\nUno Dos Tres\n" 7021 7022 As a matter of style, all of the indentation lines should line up. 7023It is an error if there are any non-whitespace characters between the 7024previous newline and the indentation marker. It is also an error to 7025write an indentation marker before the first newline in the literal. 7026 7027 The line-continuation marker ‘&-’ is used to suppress a newline: 7028 &{abc&- 7029 def} ⇒ "abc def" 7030 7031 You can write a ‘#|...|#’-style comment following a ‘&’. This could 7032be useful for annotation, or line numbers: 7033 &{&#|line 1|#one two 7034 &#|line 2|# three 7035 &#|line 3|#uno dos tres 7036 } ⇒ "one two\n three\nuno dos tres\n" 7037 703813.4.2.3 Embedded expressions 7039............................. 7040 7041 ENCLOSED-PART ::= 7042 & ENCLOSED-MODIFIER^{*} [ EXPRESSION^{*} ] 7043 | & ENCLOSED-MODIFIER^{*} ( EXPRESSION^{+} ) 7044 7045 An embedded expression has the form ‘&[EXPRESSION]’. It is 7046evaluated, the result converted to a string (as by ‘display’), and the 7047result added in the result string. (If there are multiple expressions, 7048they are all evaluated and the corresponding strings inserted in the 7049result.) 7050 &{Hello &[(string-capitalize name)]!} 7051 7052 You can leave out the square brackets when the expression is a 7053parenthesized expression: 7054 &{Hello &(string-capitalize name)!} 7055 705613.4.2.4 Formatting 7057................... 7058 7059 ENCLOSED-MODIFIER ::= 7060 ~ FORMAT-SPECIFIER-AFTER-TILDE 7061 7062 Using *note ‘format’: Format. allows finer-grained control over the 7063output, but a problem is that the association between format specifiers 7064and data expressions is positional, which is hard-to-read and 7065error-prone. A better solution places the specifier adjacant to the 7066data expression: 7067 &{The response was &~,2f(* 100.0 (/ responses total))%.} 7068 7069 The following escape forms are equivalent to the corresponding forms 7070withput the ‘~’FMT-SPEC, except the expression(s) are formatted using 7071‘format’: 7072 ‘&~’FMT-SPEC‘[’EXPRESSION^{*}‘]’ 7073 Again using parentheses like this: 7074 ‘&~’FMT-SPEC‘(’EXPRESSION^{+}‘)’ 7075 is equivalent to: 7076 ‘&~’FMT-SPEC‘[(’EXPRESSION^{+}‘)]’ 7077 7078 The syntax of ‘format’ specifications is arcane, but it allows you to 7079do some pretty neat things in a compact space. For example to include 7080‘"_"’ between each element of the array ‘arr’ you can use the ‘~{...~}’ 7081format speciers: 7082 (define arr [5 6 7]) 7083 &{&~{&[arr]&~^_&~}} ⇒ "5_6_7" 7084 7085 If no format is specified for an enclosed expression, the that is 7086equivalent to a ‘~a’ format specifier, so this is equivalent to: 7087 &{&~{&~a[arr]&~^_&~}} ⇒ "5_6_7" 7088 which is in turn equivalent to: 7089 (format #f "~{~a~^_~}" arr) 7090 7091 The fine print that makes this work: If there are multiple 7092expressions in a ‘&[...]’ with no format specifier then there is an 7093implicit ‘~a’ for each expression. On the other hand, if there is an 7094explicit format specifier, it is not repeated for each enclosed 7095expression: it appears exactly once in the effective format string, 7096whether there are zero, one, or many expressions. 7097 7098
