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: Unicode, Next: Regular expressions, Prev: String literals, Up: Characters and text 9 1013.5 Unicode character classes and conversions 11============================================== 12 13Some of the procedures that operate on characters or strings ignore the 14difference between upper case and lower case. These procedures have 15‘-ci’ (for “case insensitive”) embedded in their names. 16 1713.5.1 Characters 18----------------- 19 20 -- Procedure: char-upcase CHAR 21 -- Procedure: char-downcase CHAR 22 -- Procedure: char-titlecase CHAR 23 -- Procedure: char-foldcase CHAR 24 These procedures take a character argument and return a character 25 result. 26 27 If the argument is an upper–case or title–case character, and if 28 there is a single character that is its lower–case form, then 29 ‘char-downcase’ returns that character. 30 31 If the argument is a lower–case or title–case character, and there 32 is a single character that is its upper–case form, then 33 ‘char-upcase’ returns that character. 34 35 If the argument is a lower–case or upper–case character, and there 36 is a single character that is its title–case form, then 37 ‘char-titlecase’ returns that character. 38 39 If the argument is not a title–case character and there is no 40 single character that is its title–case form, then ‘char-titlecase’ 41 returns the upper–case form of the argument. 42 43 Finally, if the character has a case–folded character, then 44 ‘char-foldcase’ returns that character. Otherwise the character 45 returned is the same as the argument. 46 47 For Turkic characters ‘#\x130’ and ‘#\x131’, ‘char-foldcase’ 48 behaves as the identity function; otherwise ‘char-foldcase’ is the 49 same as ‘char-downcase’ composed with ‘char-upcase’. 50 51 (char-upcase #\i) ⇒ #\I 52 (char-downcase #\i) ⇒ #\i 53 (char-titlecase #\i) ⇒ #\I 54 (char-foldcase #\i) ⇒ #\i 55 56 (char-upcase #\ß) ⇒ #\ß 57 (char-downcase #\ß) ⇒ #\ß 58 (char-titlecase #\ß) ⇒ #\ß 59 (char-foldcase #\ß) ⇒ #\ß 60 61 (char-upcase #\Σ) ⇒ #\Σ 62 (char-downcase #\Σ) ⇒ #\σ 63 (char-titlecase #\Σ) ⇒ #\Σ 64 (char-foldcase #\Σ) ⇒ #\σ 65 66 (char-upcase #\ς) ⇒ #\Σ 67 (char-downcase #\ς) ⇒ #\ς 68 (char-titlecase #\ς) ⇒ #\Σ 69 (char-foldcase #\ς) ⇒ #\σ 70 71 _Note:_ ‘char-titlecase’ does not always return a title–case 72 character. 73 74 _Note:_ These procedures are consistent with Unicode’s 75 locale–independent mappings from scalar values to scalar 76 values for upcase, downcase, titlecase, and case–folding 77 operations. These mappings can be extracted from 78 ‘UnicodeData.txt’ and ‘CaseFolding.txt’ from the Unicode 79 Consortium, ignoring Turkic mappings in the latter. 80 81 Note that these character–based procedures are an incomplete 82 approximation to case conversion, even ignoring the user’s 83 locale. In general, case mappings require the context of a 84 string, both in arguments and in result. The ‘string-upcase’, 85 ‘string-downcase’, ‘string-titlecase’, and ‘string-foldcase’ 86 procedures perform more general case conversion. 87 88 -- Procedure: char-ci=? CHAR1 CHAR2 CHAR3 ... 89 -- Procedure: char-ci<? CHAR1 CHAR2 CHAR3 ... 90 -- Procedure: char-ci>? CHAR1 CHAR2 CHAR3 ... 91 -- Procedure: char-ci<=? CHAR1 CHAR2 CHAR3 ... 92 -- Procedure: char-ci>=? CHAR1 CHAR2 CHAR3 ... 93 These procedures are similar to ‘char=?’, etc., but operate on the 94 case–folded versions of the characters. 95 96 (char-ci<? #\z #\Z) ⇒ #f 97 (char-ci=? #\z #\Z) ⇒ #f 98 (char-ci=? #\ς #\σ) ⇒ #t 99 100 -- Procedure: char-alphabetic? CHAR 101 -- Procedure: char-numeric? CHAR 102 -- Procedure: char-whitespace? CHAR 103 -- Procedure: char-upper-case? CHAR 104 -- Procedure: char-lower-case? CHAR 105 -- Procedure: char-title-case? CHAR 106 These procedures return ‘#t’ if their arguments are alphabetic, 107 numeric, whitespace, upper–case, lower–case, or title–case 108 characters, respectively; otherwise they return ‘#f’. 109 110 A character is alphabetic if it has the Unicode “Alphabetic” 111 property. A character is numeric if it has the Unicode “Numeric” 112 property. A character is whitespace if has the Unicode 113 “White_Space” property. A character is upper case if it has the 114 Unicode “Uppercase” property, lower case if it has the “Lowercase” 115 property, and title case if it is in the Lt general category. 116 117 (char-alphabetic? #\a) ⇒ #t 118 (char-numeric? #\1) ⇒ #t 119 (char-whitespace? #\space) ⇒ #t 120 (char-whitespace? #\x00A0) ⇒ #t 121 (char-upper-case? #\Σ) ⇒ #t 122 (char-lower-case? #\σ) ⇒ #t 123 (char-lower-case? #\x00AA) ⇒ #t 124 (char-title-case? #\I) ⇒ #f 125 (char-title-case? #\x01C5) ⇒ #t 126 127 -- Procedure: char-general-category CHAR 128 Return a symbol representing the Unicode general category of CHAR, 129 one of ‘Lu’, ‘Ll’, ‘Lt’, ‘Lm’, ‘Lo’, ‘Mn’, ‘Mc’, ‘Me’, ‘Nd’, ‘Nl’, 130 ‘No’, ‘Ps’, ‘Pe’, ‘Pi’, ‘Pf’, ‘Pd’, ‘Pc’, ‘Po’, ‘Sc’, ‘Sm’, ‘Sk’, 131 ‘So’, ‘Zs’, ‘Zp’, ‘Zl’, ‘Cc’, ‘Cf’, ‘Cs’, ‘Co’, or ‘Cn’. 132 133 (char-general-category #\a) ⇒ Ll 134 (char-general-category #\space) ⇒ Zs 135 (char-general-category #\x10FFFF) ⇒ Cn 136 13713.5.2 Deprecated in-place case modification 138-------------------------------------------- 139 140The following functions are deprecated; they really don’t and cannot do 141the right thing, because in some languages upper and lower case can use 142different number of characters. 143 144 -- Procedure: string-upcase! str 145 _Deprecated:_ Destructively modify STR, replacing the letters by 146 their upper-case equivalents. 147 148 -- Procedure: string-downcase! str 149 _Deprecated:_ Destructively modify STR, replacing the letters by 150 their upper-lower equivalents. 151 152 -- Procedure: string-capitalize! str 153 _Deprecated:_ Destructively modify STR, such that the letters that 154 start a new word are replaced by their title-case equivalents, 155 while non-initial letters are replaced by their lower-case 156 equivalents. 157 158 159File: kawa.info, Node: Regular expressions, Prev: Unicode, Up: Characters and text 160 16113.6 Regular expressions 162======================== 163 164Kawa provides “regular expressions”, which is a convenient mechanism for 165matching a string against a “pattern” and maybe replacing matching 166parts. 167 168 A regexp is a string that describes a pattern. A regexp matcher 169tries to match this pattern against (a portion of) another string, which 170we will call the text string. The text string is treated as raw text 171and not as a pattern. 172 173 Most of the characters in a regexp pattern are meant to match 174occurrences of themselves in the text string. Thus, the pattern “‘abc’” 175matches a string that contains the characters “‘a’”, “‘b’”, “‘c’” in 176succession. 177 178 In the regexp pattern, some characters act as “metacharacters”, and 179some character sequences act as “metasequences”. That is, they specify 180something other than their literal selves. For example, in the pattern 181“‘a.c’”, the characters “‘a’” and “‘c’” do stand for themselves but the 182metacharacter “‘.’” can match any character (other than newline). 183Therefore, the pattern “‘a.c’” matches an “‘a’”, followed by any 184character, followed by a “‘c’”. 185 186 If we needed to match the character “‘.’” itself, we “escape” it, ie, 187precede it with a backslash “‘\’”. The character sequence “‘\.’” is 188thus a metasequence, since it doesn’t match itself but rather just 189“‘.’”. So, to match “‘a’” followed by a literal “‘.’” followed by “‘c’” 190we use the regexp pattern “‘a\.c’”. To write this as a Scheme string 191literal, you need to quote the backslash, so you need to write 192‘"a\\.c"’. Kawa also allows the literal syntax ‘#/a\.c/’, which avoids 193the need to double the backslashes. 194 195 You can choose between two similar styles of regular expressions. 196The two differ slightly in terms of which characters act as 197metacharacters, and what those metacharacters mean: 198 • Functions starting with ‘regex-’ are implemented using the 199 ‘java.util.regex’ package. This is likely to be more efficient, 200 has better Unicode support and some other minor extra features, and 201 literal syntax ‘#/a\.c/’ mentioned above. 202 • Functions starting with ‘pregexp-’ are implemented in pure Scheme 203 using Dorai Sitaram’s “Portable Regular Expressions for Scheme” 204 library. These will be portable to more Scheme implementations, 205 including BRL, and is available on older Java versions. 206 20713.6.1 Java regular expressions 208------------------------------- 209 210The syntax for regular expressions is documented here 211(http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html). 212 213 -- Type: regex 214 A compiled regular expression, implemented as 215 ‘java.util.regex.Pattern’. 216 217 -- Constructor: regex arg 218 Given a regular expression pattern (as a string), compiles it to a 219 ‘regex’ object. 220 221 (regex "a\\.c") 222 This compiles into a pattern that matches an “‘a’”, followed by any 223 character, followed by a “‘c’”. 224 225 The Scheme reader recognizes “‘#/’” as the start of a regular 226expression “pattern literal”, which ends with the next un-escaped “‘/’”. 227This has the big advantage that you don’t need to double the 228backslashes: 229 #/a\.c/ 230 This is equivalent to ‘(regex "a\\.c")’, except it is compiled at 231read-time. If you need a literal “‘/’” in a pattern, just escape it 232with a backslash: “‘#/a\/c/’” matches a “‘a’”, followed by a “‘/’”, 233followed by a “‘c’”. 234 235 You can add single-letter _modifiers_ following the pattern literal. 236The following modifiers are allowed: 237‘i’ 238 The modifier “‘i’” cause the matching to ignore case. For example 239 the following pattern matches “‘a’” or “‘A’”. 240 #/a/i 241‘m’ 242 Enables “metaline” mode. Normally metacharacters “‘^’” and “‘$’’ 243 match at the start end end of the entire input string. In metaline 244 mode “‘^’” and “‘$’” also match just before or after a line 245 terminator. 246 247 Multiline mode can also be enabled by the metasequence “‘(?m)’”. 248‘s’ 249 Enable “singleline” (aka “dot-all”) mode. In this mode the 250 matacharacter “‘.’ matches any character, including a line breaks. 251 This mode be enabled by the metasequence “‘(?s)’”. 252 253 The following functions accept a regex either as a pattern string or 254a compiled ‘regex’ pattern. I.e. the following are all equivalent: 255 (regex-match "b\\.c" "ab.cd") 256 (regex-match #/b\.c/ "ab.cd") 257 (regex-match (regex "b\\.c") "ab.cd") 258 (regex-match (java.util.regex.Pattern:compile "b\\.c") "ab.cd") 259 These all evaluate to the list ‘("b.c")’. 260 261 The following functions must be imported by doing one of: 262 (require 'regex) ;; or 263 (import (kawa regex)) 264 265 -- Procedure: regex-match-positions regex string [start [end]] 266 267 The procedure ‘regex‑match‑position’ takes pattern and a text 268 STRING, and returns a match if the regex matches (some part of) the 269 text string. 270 271 Returns ‘#f’ if the regexp did not match the string; and a list of 272 index pairs if it did match. 273 (regex-match-positions "brain" "bird") ⇒ #f 274 (regex-match-positions "needle" "hay needle stack") 275 ⇒ ((4 . 10)) 276 277 In the second example, the integers 4 and 10 identify the substring 278 that was matched. 4 is the starting (inclusive) index and 10 the 279 ending (exclusive) index of the matching substring. 280 281 (substring "hay needle stack" 4 10) ⇒ "needle" 282 283 In this case the return list contains only one index pair, and that 284 pair represents the entire substring matched by the regexp. When 285 we discuss subpatterns later, we will see how a single match 286 operation can yield a list of submatches. 287 288 ‘regex‑match‑positions’ takes optional third and fourth arguments 289 that specify the indices of the text string within which the 290 matching should take place. 291 292 (regex-match-positions "needle" 293 "his hay needle stack -- my hay needle stack -- her hay needle stack" 294 24 43) 295 ⇒ ((31 . 37)) 296 297 Note that the returned indices are still reckoned relative to the 298 full text string. 299 300 -- Procedure: regex-match regex string [start [end]] 301 The procedure ‘regex‑match’ is called like ‘regex‑match‑positions’ 302 but instead of returning index pairs it returns the matching 303 substrings: 304 (regex-match "brain" "bird") ⇒ #f 305 (regex-match "needle" "hay needle stack") 306 ⇒ ("needle") 307 308 ‘regex‑match’ also takes optional third and fourth arguments, with 309 the same meaning as does ‘regex‑match‑positions’. 310 311 -- Procedure: regex-split regex string 312 Takes two arguments, a REGEX pattern and a text STRING, and returns 313 a list of substrings of the text string, where the pattern 314 identifies the delimiter separating the substrings. 315 (regex-split ":" "/bin:/usr/bin:/usr/bin/X11:/usr/local/bin") 316 ⇒ ("/bin" "/usr/bin" "/usr/bin/X11" "/usr/local/bin") 317 318 (regex-split " " "pea soup") 319 ⇒ ("pea" "soup") 320 321 If the first argument can match an empty string, then the list of 322 all the single-character substrings is returned, plus we get a 323 empty strings at each end. 324 325 (regex-split "" "smithereens") 326 ⇒ ("" "s" "m" "i" "t" "h" "e" "r" "e" "e" "n" "s" "") 327 328 (Note: This behavior is different from ‘pregexp-split’.) 329 330 To identify one-or-more spaces as the delimiter, take care to use 331 the regexp “‘ +’”, not “‘ *’”. 332 (regex-split " +" "split pea soup") 333 ⇒ ("split" "pea" "soup") 334 (regex-split " *" "split pea soup") 335 ⇒ ("" "s" "p" "l" "i" "t" "" "p" "e" "a" "" "s" "o" "u" "p" "") 336 337 -- Procedure: regex‑replace regex string replacement 338 Replaces the matched portion of the text STRING by another a 339 REPLACDEMENT string. 340 (regex-replace "te" "liberte" "ty") 341 ⇒ "liberty" 342 343 Submatches can be used in the replacement string argument. The 344 replacement string can use “‘$N’” as a “backreference” to refer 345 back to the Nth submatch, ie, the substring that matched the Nth 346 subpattern. “‘$0’” refers to the entire match. 347 (regex-replace #/_(.+?)_/ 348 "the _nina_, the _pinta_, and the _santa maria_" 349 "*$1*")) 350 ⇒ "the *nina*, the _pinta_, and the _santa maria_" 351 352 -- Procedure: regex‑replace* regex string replacement 353 Replaces all matches in the text STRING by the REPLACEMENT string: 354 (regex-replace* "te" "liberte egalite fraternite" "ty") 355 ⇒ "liberty egality fratyrnity" 356 (regex-replace* #/_(.+?)_/ 357 "the _nina_, the _pinta_, and the _santa maria_" 358 "*$1*") 359 ⇒ "the *nina*, the *pinta*, and the *santa maria*" 360 361 -- Procedure: regex-quote pattern 362 Takes an arbitrary string and returns a pattern string that 363 precisely matches it. In particular, characters in the input 364 string that could serve as regex metacharacters are escaped as 365 needed. 366 367 (regex-quote "cons") 368 ⇒ "\Qcons\E" 369 ‘regex‑quote’ is useful when building a composite regex from a mix 370 of regex strings and verbatim strings. 371 37213.6.2 Portable Scheme regular expressions 373------------------------------------------ 374 375This provides the procedures ‘pregexp’, ‘pregexp‑match‑positions’, 376‘pregexp‑match’, ‘pregexp‑split’, ‘pregexp‑replace’, ‘pregexp‑replace*’, 377and ‘pregexp‑quote’. 378 379 Before using them, you must require them: 380 (require 'pregexp) 381 382 These procedures have the same interface as the corresponding 383‘regex-’ versions, but take slightly different pattern syntax. The 384replace commands use “‘\’” instead of “‘$’” to indicate substitutions. 385Also, ‘pregexp‑split’ behaves differently from ‘regex‑split’ if the 386pattern can match an empty string. 387 388 See here for details 389(http://www.ccs.neu.edu/home/dorai/pregexp/index.html). 390 391 392File: kawa.info, Node: Data structures, Next: Eval and Environments, Prev: Characters and text, Up: Top 393 39414 Data structures 395****************** 396 397* Menu: 398 399* Sequences:: 400* Lists:: 401* Vectors:: 402* Uniform vectors:: 403* Bytevectors:: 404* Ranges:: 405* Streams:: Lazy lists. 406* Arrays:: Multi-dimensional Arrays 407* Hash tables:: 408 409 410File: kawa.info, Node: Sequences, Next: Lists, Up: Data structures 411 41214.1 Sequences 413============== 414 415A “sequence” is a generalized list, consisting of zero or more values. 416You can choose between a number of different kinds of sequence 417implementations. Scheme traditionally has *note lists: Lists. and *note 418vectors: Vectors. Any Java class that implements ‘java.util.List’ is a 419sequence type. Raw Java arrays can also be viewerd as a sequence, and 420strings can be viewed a sequence (or vector) of characters. Kawa also 421provides *note uniform vectors: Uniform vectors. 422 423 Sequence types differ in their API, but given a sequence type STYPE 424you can construct instances of that type using the syntax: 425 (STYPE V0 V1 .... VN) 426 For example: 427 (bytevector 9 8 7 6) ⇒ #u8(9 8 7 6) 428 429 For a raw Java class name JNAME you may need to use the empty keyword 430‘||:’ to separate constructor parameters (if any) from sequence 431elements, as in: 432 (gnu.lists.U8Vector ||: 9 8 7 6) ⇒ #u8(9 8 7 6) 433 This syntax works with any type with a default constructor and a 4341-argument ‘add’ method; see *note Allocating objects:: for details. 435You can use the same syntax for allocating arrays, though array creation 436supports *note more options: Creating-new-Java-arrays. 437 438 To extract an element from Scheme sequence of type STYPE there is 439usually a function ‘STYPE-ref’. For example: 440 (define vec1 (vector 5 6 7 8)) 441 (vector-ref vec1 2) ⇒ 7 442 443 More concisely, you can use (Kawa-specific) function call syntax: 444 (vec1 3) ⇒ 8 445 446 The index can be another sequence, which creates a new sequence of 447the selected indexes: 448 (vec1 [3 0 2 1]) ⇒ #(8 5 7 6) 449 It is convenient to use a *note “range”: Ranges. to select a 450sub-sequence: 451 (vec1 [1 <=: 3]) ⇒ #(6 7 8) 452 (vec1 [2 <:]) ⇒ #(7 8) 453 454 The same function call syntax also works for raw Java arrays (though 455the index is restricted to an integer, not a sequence or array): 456 (define arr1 (long[] 4 5 6 7)) 457 (arr1 3) ⇒ 7 458 459 To assign to (replace) an element from a sequence of Scheme type 460STYPE there is usually a function ‘STYPE-set!’: 461 (vector-set! vec1 1 9) 462 vec1 ⇒ #(5 9 7 8) 463 464 Again, you can use the function call syntax: 465 (set! (vec1 2) 'x) 466 vec1 ⇒ #(5 9 x 8) 467 468 -- Procedure: length seq 469 Returns the number of elements of the SEQ. 470 471 (length '(a b c)) ⇒ 3 472 (length '(a (b) (c d e))) ⇒ 3 473 (length '()) ⇒ 0 474 (length [3 4 [] 12]) ⇒ 4 475 (length (vector)) ⇒ 0 476 (length (int[] 7 6)) ⇒ 2 477 478 The length of a string is the number of characters (Unicode code 479 points). In contrast, the ‘length’ _method_ (of the ‘CharSequence’ 480 interface) returns the number of 16-bit code points: 481 (length "Hello") ⇒ 5 482 (define str1 "Hello \x1f603;!") 483 (invoke str1 'length) ⇒ 9 484 (length str1) ⇒ 8 ; Used to return 9 in Kawa 2.x. 485 (string-length str1) ⇒ 8 486 487 488File: kawa.info, Node: Lists, Next: Vectors, Prev: Sequences, Up: Data structures 489 49014.2 Lists 491========== 492 493A pair (sometimes called a “dotted pair”) is a record structure with two 494fields called the car and cdr fields (for historical reasons). Pairs 495are created by the procedure ‘cons’. The car and cdr fields are 496accessed by the procedures ‘car’ and ‘cdr’. The car and cdr fields are 497assigned by the procedures ‘set-car!’ and ‘set-cdr!’. 498 499 Pairs are used primarily to represent lists. A “list” can be defined 500recursively as either the empty list or a pair whose cdr is a list. 501More precisely, the set of lists is defined as the smallest set X such 502that: 503 • The empty list is in X. 504 • If LIST is in X, then any pair whose cdr field contains LIST is 505 also in X. 506 507 The objects in the car fields of successive pairs of a list are the 508elements of the list. For example, a two-element list is a pair whose 509car is the first element and whose cdr is a pair whose car is the second 510element and whose cdr is the empty list. The length of a list is the 511number of elements, which is the same as the number of pairs. 512 513 The empty list is a special object of its own type. It is not a 514pair, it has no elements, and its length is zero. 515 516 _Note:_ The above definitions imply that all lists have finite length 517and are terminated by the empty list. 518 519 The most general notation (external representation) for Scheme pairs 520is the “dotted” notation ‘(C1 . C2 )’ where C1 is the value of the car 521field and C2 is the value of the cdr field. For example ‘(4 . 5)’ is a 522pair whose car is 4 and whose cdr is 5. Note that ‘(4 . 5)’ is the 523external representation of a pair, not an expression that evaluates to a 524pair. 525 526 A more streamlined notation can be used for lists: the elements of 527the list are simply enclosed in parentheses and separated by spaces. 528The empty list is written ‘()’. For example, 529 (a b c d e) 530 and 531 (a . (b . (c . (d . (e . ()))))) 532 are equivalent notations for a list of symbols. 533 534 A chain of pairs not ending in the empty list is called an “improper 535list”. Note that an improper list is not a list. The list and dotted 536notations can be combined to represent improper lists: 537 (a b c . d) 538 is equivalent to 539 (a . (b . (c . d))) 540 541 _Needs to finish merging from R7RS!_ 542 543 -- Procedure: make-list k [fill] 544 Returns a newly allocated list of K elements. If a second argument 545 is given, the each element is initialized to FILL. Otherwise the 546 initial contents of each element is unspecified. 547 (make-list 2 3) ⇒ (3 3) 548 54914.2.1 SRFI-1 list library 550-------------------------- 551 552The SRFI-1 List Library (http://srfi.schemers.org/srfi-1/srfi-1.html) is 553available, though not enabled by default. To use its functions you must 554‘(require 'list-lib)’ or ‘(require 'srfi-1)’. 555 (require 'list-lib) 556 (iota 5 0 -0.5) ⇒ (0.0 -0.5 -1.0 -1.5 -2.0) 557 558 -- Procedure: reverse! list 559 The result is a list consisting of the elements of LIST in reverse 560 order. No new pairs are allocated, instead the pairs of LIST are 561 re-used, with ‘cdr’ cells of LIST reversed in place. Note that if 562 LIST was pair, it becomes the last pair of the reversed result. 563 56414.2.2 SRFI-101 Purely Functional Random-Access Pairs and Lists 565--------------------------------------------------------------- 566 567SRFI-101 (http://srfi.schemers.org/srfi-101/srfi-101.html) specifies 568immutable (read-only) lists with fast (logarithmic) indexing and 569functional update (i.e. return a modified list). These are implemented 570by a ‘RAPair’ class which extends the generic ‘pair’ type, which means 571that most code that expects a standard list will work on these lists as 572well. 573 574 575File: kawa.info, Node: Vectors, Next: Uniform vectors, Prev: Lists, Up: Data structures 576 57714.3 Vectors 578============ 579 580Vectors are heterogeneous structures whose elements are indexed by 581integers. A vector typically occupies less space than a list of the 582same length, and the average time needed to access a randomly chosen 583element is typically less for the vector than for the list. 584 585 The _length_ of a vector is the number of elements that it contains. 586This number is a non–negative integer that is fixed when the vector is 587created. The _valid indices_ of a vector are the exact non–negative 588integer objects less than the length of the vector. The first element 589in a vector is indexed by zero, and the last element is indexed by one 590less than the length of the vector. 591 592 Vectors are written using the notation ‘#(OBJ ...)’. For example, a 593vector of length 3 3 containing the number zero in element 0, the list 594‘(2 2 2 2)’ in element 1, and the string ‘"Anna"’ in element 2 can be 595written as following: 596 #(0 (2 2 2 2) "Anna") 597 Note that this is the external representation of a vector. In Kawa, 598a vector datum is self-evaluating, but for style (and compatibility with 599R7RS) is is suggested you quote a vector constant: 600 ’#(0 (2 2 2 2) "Anna") ⇒ #(0 (2 2 2 2) "Anna") 601 602 Compare these different ways of creating a vector: 603‘(vector a b c)’ 604 In this case ‘a’, ‘b’, and ‘c’ are expressions evaluated at 605 run-time and the results used to initialize a newly-allocated 606 3-element vector. 607‘[a b c]’ 608 Same as using vector, but more concise, and results in an immutable 609 (non-modifiable) vector. 610‘#(a b c)’ 611 This is reader syntax and creates a vector literal, at read-time, 612 early in compile-time. The symbols ‘a’, ‘b’, and ‘c’ are not 613 evaluated but instead used literally. 614‘`#(,a ,b ,c)’ 615 This is reader-syntax, using quasi-quotation, so ‘a’, ‘b’, and ‘c’ 616 are expressions evaluated at run-time. This is equivalent to ‘[a b 617 c]’ in that it results in an immutable vector. 618 619 -- Type: vector 620 The type of vector objects. 621 622 -- Constructor: vector OBJ ... 623 Return a newly allocated vector whose elements contain the given 624 arguments. Analogous to ‘list’. 625 626 (vector 'a 'b 'c) ⇒ #(a b c) 627 628 Alternatively, you can use square-bracket syntax, which results in 629 an immutable vector: 630 ['a 'b 'c] ⇒ #(a b c) 631 632 -- Procedure: make-vector K 633 -- Procedure: make-vector K FILL 634 Return a newly allocated vector of K elements. If a second 635 argument is given, then each element is initialized to FILL. 636 Otherwise the initial contents of each element is ‘#!null’. 637 638 -- Procedure: vector? OBJ 639 Return ‘#t’ if OBJ is a vector, ‘#f’ otherwise. 640 641 -- Procedure: vector-length VECTOR 642 Return the number of elements in VECTOR as an exact integer. 643 644 -- Procedure: vector-ref VECTOR K 645 It is an error if K is not a valid index of VECTOR. The 646 ‘vector-ref’ procedure returns the contents of element K of VECTOR. 647 648 (vector-ref '#(1 1 2 3 5 8 13 21) 5) ⇒ 8 649 (vector-ref '#(1 1 2 3 5 8 13 21) 650 (inexact->exact (round (* 2 (acos -1))))) 651 ⇒ 13 652 653 -- Procedure: vector-set! VECTOR K OBJ 654 It is an error if K is not a valid index of VECTOR. The 655 ‘vector-set!’ procedure stores OBJ in element K of VECTOR, and 656 returns no values. 657 658 (let ((vec (vector 0 '(2 2 2 2) "Anna"))) 659 (vector-set! vec 1 '("Sue" "Sue")) 660 vec) 661 ⇒ #(0 ("Sue" "Sue") "Anna") 662 663 (vector-set! '#(0 1 2) 1 "doe") 664 ⇒ error ;; constant vector 665 666 A concise alternative to ‘vector-ref’ and ‘vector-set!’ is to use 667function call syntax. For example: 668 (let ((vec (vector 0 '(2 2 2 2) "Anna"))) 669 (set! (vec 1) '("Sue" "Sue")) 670 (list (vec 2) (vec 1))) 671 ⇒ ("Anna" ("Sue" "Sue")) 672 673 -- Procedure: vector->list VECTOR [START [END]] 674 The ‘vector->list’ procedure returns a newly allocated list of the 675 objects contained in the elements of VECTOR between START and END. 676 677 (vector->list '#(dah dah didah)) ⇒ (dah dah didah) 678 (vector->list '#(dah dah didah) 1 2) ⇒ (dah) 679 680 -- Procedure: list->vector LIST 681 The ‘list->vector’ procedure returns a newly created vector 682 initialized to the elements of the list LIST, in order. 683 (list->vector '(dididit dah)) ⇒ #(dididit dah) 684 685 -- Procedure: vector-copy vector [start [end]] 686 Returns a newly allocated copy of the elements of the given VECTOR 687 between START and END . The elements of the new vector are the 688 same (in the sense of ‘eqv?’) as the elements of the old. 689 690 (define a #(1 8 2 8)) ; a may be immutable 691 (define b (vector-copy a)) 692 (vector-set! b 0 3) ; b is mutable 693 b ⇒ #(3 8 2 8) 694 (define c (vector-copy b 1 3)) 695 c ⇒ #(8 2) 696 697 -- Procedure: vector-copy! to at from [start [end]] 698 Copies the elements of vector from between start and end to vector 699 to, starting at at. The order in which elements are copied is 700 unspecified, except that if the source and destination overlap, 701 copying takes place as if the source is first copied into a 702 temporary vector and then into the destination. This can be 703 achieved without allocating storage by making sure to copy in the 704 correct direction in such circumstances. 705 706 It is an error if AT is less than zero or greater than the length 707 of TO. It is also an error if ‘(- (vector-length TO) AT)’ is less 708 than ‘(- END START)’. 709 710 (define a (vector 1 2 3 4 5)) 711 (define b (vector 10 20 30 40 50)) 712 (vector-copy! b 1 a 0 2) 713 b ⇒ #(10 1 2 40 50) 714 715 -- Procedure: vector-append ARG... 716 Creates a newly allocated vector whose elements are the 717 concatenation of the elements of the given arguments. Each ARG may 718 be a vector or a list. 719 (vector-append #(a b c) #(d e f)) 720 ⇒ #(a b c d e f) 721 722 -- Procedure: vector-fill! VECTOR FILL [START [END]] 723 Stores FILL in in the elements of VECTOR between START and END. 724 (define a (vector 1 2 3 4 5)) 725 (vector-fill! a 'smash 2 4) 726 a ⇒ #(1 2 smash smash 5) 727 728 The procedures ‘vector-map’ and ‘vector-for-each’ are documented in 729*note Mapping functions::. 730 731 732File: kawa.info, Node: Uniform vectors, Next: Bytevectors, Prev: Vectors, Up: Data structures 733 73414.4 Uniform vectors 735==================== 736 737Uniform vectors are vectors whose elements are of the same numeric type. 738The are defined by SRFI-4 (http://srfi.schemers.org/srfi-4/srfi-4.html). 739The type names (such as ‘s8vector’) are a Kawa extension. 740 741 UNIFORM-VECTOR ::= ‘#’ UNIFORM-TAG LIST 742 UNIFORM-TAG ::= ‘f32’ | ‘f64’ 743 | ‘s8’ | ‘s16’ | ‘s32’ | ‘s64’ 744 | ‘u8’ | ‘u16’ | ‘u32’ | ‘u64’ 745 746 This example is a literal for a 5-element vector of unsigned short 747(‘ushort’) values: 748 (define uvec1 #u16(64000 3200 160 8 0)) 749 750 Since a uniform vector is a sequence, you can use function-call 751notation to index one. For example: 752 (uvec1 1) ⇒ 3200 753 In this case the result is a primitive unsigned short (‘ushort’), 754which is converted to a ‘gnu.math.UShort’ if an object is needed. 755 756 -- Type: s8vector 757 The type of uniform vectors where each element can contain a signed 758 8-bit integer. Represented using an array of ‘byte’. 759 760 -- Type: u8vector 761 The type of uniform vectors where each element can contain an 762 unsigned 8-bit integer. Represented using an array of ‘<byte>’, 763 but each element is treated as if unsigned. 764 765 This type is a synonym for ‘bytevector’, which has *note extra 766 functions: Bytevectors. 767 768 -- Type: s16vector 769 The type of uniform vectors where each element can contain a signed 770 16-bit integer. Represented using an array of ‘short’. 771 772 -- Type: u16vector 773 The type of uniform vectors where each element can contain an 774 unsigned 16-bit integer. Represented using an array of ‘short’, 775 but each element is treated as if unsigned. 776 777 -- Type: s32vector 778 The type of uniform vectors where each element can contain a signed 779 32-bit integer. Represented using an array of ‘int’. 780 781 -- Type: u32vector 782 The type of uniform vectors where each element can contain an 783 unsigned 32-bit integer. Represented using an array of ‘int’, but 784 each element is treated as if unsigned. 785 786 -- Type: s64vector 787 The type of uniform vectors where each element can contain a signed 788 64-bit integer. Represented using an array of ‘long’. 789 790 -- Type: u64vector 791 The type of uniform vectors where each element can contain an 792 unsigned 64-bit integer. Represented using an array of ‘long’, but 793 each element is treated as if unsigned. 794 795 -- Type: f32vector 796 The type of uniform vectors where each element can contain a 32-bit 797 floating-point real. Represented using an array of ‘float’. 798 799 -- Type: f64vector 800 The type of uniform vectors where each element can contain a 64-bit 801 floating-point real. Represented using an array of ‘double’. 802 803 -- Procedure: s8vector? value 804 -- Procedure: u8vector? value 805 -- Procedure: s16vector? value 806 -- Procedure: u16vector? value 807 -- Procedure: s32vector? value 808 -- Procedure: u32vector? value 809 -- Procedure: s64vector? value 810 -- Procedure: u64vector? value 811 -- Procedure: f32vector? value 812 -- Procedure: f64vector? value 813 Return true iff VALUE is a uniform vector of the specified type. 814 815 -- Procedure: make-s8vector n [value] 816 -- Procedure: make-u8vector n [value] 817 -- Procedure: make-s16vector n [value] 818 -- Procedure: make-u16vector n [value] 819 -- Procedure: make-s32vector n [value] 820 -- Procedure: make-u32vector n [value] 821 -- Procedure: make-s64vector n [value] 822 -- Procedure: make-u64vector n [value] 823 -- Procedure: make-f32vector n [value] 824 -- Procedure: make-f64vector n [value] 825 Create a new uniform vector of the specified type, having room for 826 N elements. Initialize each element to VALUE if it is specified; 827 zero otherwise. 828 829 -- Constructor: s8vector value ... 830 -- Constructor: u8vector value ... 831 -- Constructor: s16vector value .. 832 -- Constructor: u16vector value ... 833 -- Constructor: s32vector value ... 834 -- Constructor: u32vector value ... 835 -- Constructor: s64vector value ... 836 -- Constructor: u64vector value ... 837 -- Constructor: f32vector value ... 838 -- Constructor: f64vector value ... 839 Create a new uniform vector of the specified type, whose length is 840 the number of VALUEs specified, and initialize it using those 841 VALUEs. 842 843 -- Procedure: s8vector-length v 844 -- Procedure: u8vector-length v 845 -- Procedure: s16vector-length v 846 -- Procedure: u16vector-length v 847 -- Procedure: s32vector-length v 848 -- Procedure: u32vector-length v 849 -- Procedure: s64vector-length v 850 -- Procedure: u64vector-length v 851 -- Procedure: f32vector-length v 852 -- Procedure: f64vector-length v 853 Return the length (in number of elements) of the uniform vector V. 854 855 -- Procedure: s8vector-ref v i 856 -- Procedure: u8vector-ref v i 857 -- Procedure: s16vector-ref v i 858 -- Procedure: u16vector-ref v i 859 -- Procedure: s32vector-ref v i 860 -- Procedure: u32vector-ref v i 861 -- Procedure: s64vector-ref v i 862 -- Procedure: u64vector-ref v i 863 -- Procedure: f32vector-ref v i 864 -- Procedure: f64vector-ref v i 865 Return the element at index I of the uniform vector V. 866 867 -- Procedure: s8vector-set! v i x 868 -- Procedure: u8vector-set! v i x 869 -- Procedure: s16vector-set! v i x 870 -- Procedure: u16vector-set! v i x 871 -- Procedure: s32vector-set! v i x 872 -- Procedure: u32vector-set! v i x 873 -- Procedure: s64vector-set! v i x 874 -- Procedure: u64vector-set! v i x 875 -- Procedure: f32vector-set! v i x 876 -- Procedure: f64vector-set! v i x 877 Set the element at index I of uniform vector V to the value X, 878 which must be a number coercible to the appropriate type. 879 880 -- Procedure: s8vector->list v 881 -- Procedure: u8vector->list v 882 -- Procedure: s16vector->list v 883 -- Procedure: u16vector->list v 884 -- Procedure: s32vector->list v 885 -- Procedure: u32vector->list v 886 -- Procedure: s64vector->list v 887 -- Procedure: u64vector->list v 888 -- Procedure: f32vector->list v 889 -- Procedure: f64vector->list v 890 Convert the uniform vetor V to a list containing the elments of V. 891 892 -- Procedure: list->s8vector l 893 -- Procedure: list->u8vector l 894 -- Procedure: list->s16vector l 895 -- Procedure: list->u16vector l 896 -- Procedure: list->s32vector l 897 -- Procedure: list->u32vector l 898 -- Procedure: list->s64vector l 899 -- Procedure: list->u64vector l 900 -- Procedure: list->f32vector l 901 -- Procedure: list->f64vector l 902 Create a uniform vector of the appropriate type, initializing it 903 with the elements of the list L. The elements of L must be numbers 904 coercible the new vector’s element type. 905 90614.4.1 Relationship with Java arrays 907------------------------------------ 908 909Each uniform array type is implemented as an “underlying Java array”, 910and a length field. The underlying type is ‘byte[]’ for ‘u8vector’ or 911‘s8vector’; ‘short[]’ for ‘u16vector’ or ‘u16vector’; ‘int[]’ for 912‘u32vector’ or ‘s32vector’; ‘long[]’ for ‘u64vector’ or ‘s64vector’; 913‘float[]’ for ‘f32vector’; and ‘double[]’ for ‘f32vector’. The length 914field allows a uniform array to only use the initial part of the 915underlying array. (This can be used to support Common Lisp’s fill 916pointer feature.) This also allows resizing a uniform vector. There is 917no Scheme function for this, but you can use the ‘setSize’ method: 918 (invoke some-vector 'setSize 200) 919 920 If you have a Java array, you can create a uniform vector sharing 921with the Java array: 922 (define arr :: byte[] ((primitive-array-new byte) 10)) 923 (define vec :: u8vector (make u8vector arr)) 924 At this point ‘vec’ uses ‘arr’ for its underlying storage, so changes 925to one affect the other. It ‘vec’ is re-sized so it needs a larger 926underlying array, then it will no longer use ‘arr’. 927 928 929File: kawa.info, Node: Bytevectors, Next: Ranges, Prev: Uniform vectors, Up: Data structures 930 93114.5 Bytevectors 932================ 933 934“Bytevectors” represent blocks of binary data. They are fixed-length 935sequences of bytes, where a BYTE is an exact integer in the range [0, 936255]. A bytevector is typically more space-efficient than a vector 937containing the same values. 938 939 The length of a bytevector is the number of elements that it 940contains. This number is a non-negative integer that is fixed when the 941bytevector is created. The valid indexes of a bytevector are the exact 942non-negative integers less than the length of the bytevector, starting 943at index zero as with vectors. 944 945 The ‘bytevector’ type is equivalent to the ‘u8vector’ *note uniform 946vector: Uniform vectors. type, but is specified by the R7RS standard. 947 948 Bytevectors are written using the notation ‘#u8(byte . . . )’. For 949example, a bytevector of length 3 containing the byte 0 in element 0, 950the byte 10 in element 1, and the byte 5 in element 2 can be written as 951following: 952 #u8(0 10 5) 953 Bytevector constants are self-evaluating, so they do not need to be 954quoted in programs. 955 956 -- Type: bytevector 957 The type of bytevector objects. 958 959 -- Constructor: bytevector BYTE ... 960 Return a newly allocated bytevector whose elements contain the 961 given arguments. Analogous to ‘vector’. 962 (bytevector 1 3 5 1 3 5) ⇒ #u8(1 3 5 1 3 5) 963 (bytevector) ⇒ #u8() 964 965 -- Procedure: bytevector? OBJ 966 Return ‘#t’ if OBJ is a bytevector, ‘#f’ otherwise. 967 968 -- Procedure: make-bytevector k 969 -- Procedure: make-bytevector k byte 970 The ‘make-bytevector’ procedure returns a newly allocated 971 bytevector of length K. If BYTE is given, then all elements of the 972 bytevector are initialized to BYTE, otherwise the contents of each 973 element are unspecified. 974 (make-bytevector 2 12) ⇒ #u8(12 12) 975 976 -- Procedure: bytevector-length bytevector 977 Returns the length of BYTEVECTOR in bytes as an exact integer. 978 979 -- Procedure: bytevector-u8-ref bytevector k 980 It is an error if K is not a valid index of BYTEVECTOR. Returns 981 the Kth byte of BYTEVECTOR. 982 (bytevector-u8-ref ’#u8(1 1 2 3 5 8 13 21) 5) 983 ⇒ 8 984 985 -- Procedure: bytevector-u8-set! bytevector k byte 986 It is an error if K is not a valid index of BYTEVECTOR. Stores 987 BYTE as the Kth byte of BYTEVECTOR. 988 (let ((bv (bytevector 1 2 3 4) 989 (bytevector-u8-set! bv 1 3) 990 bv) 991 ⇒ #u8(1 3 3 4) 992 993 -- Procedure: bytevector-copy bytevector [start [end]] 994 Returns a newly allocated bytevector containing the bytes in 995 BYTEVECTOR between START and END. 996 997 (define a #u8(1 2 3 4 5)) 998 (bytevector-copy a 2 4)) 999 ⇒ #u8(3 4) 1000 1001 -- Procedure: bytevector-copy! to at from [start [end]] 1002 Copies the bytes of bytevectorFROM between START and END to 1003 bytevector TO, starting at AT. The order in which bytes are copied 1004 is unspecified, except that if the source and destination overlap, 1005 copying takes place as if the source is first copied into a 1006 temporary bytevector and then into the destination. This is 1007 achieved without allocating storage by making sure to copy in the 1008 correct direction in such circumstances. 1009 1010 It is an error if AT is less than zero or greater than the length 1011 of TO. It is also an error if ‘(- (bytevector-length TO) AT)’ is 1012 less than ‘(- END START)’. 1013 1014 (define a (bytevector 1 2 3 4 5)) 1015 (define b (bytevector 10 20 30 40 50)) 1016 (bytevector-copy! b 1 a 0 2) 1017 b ⇒ #u8(10 1 2 40 50) 1018 1019 -- Procedure: bytevector-append bytevector... 1020 Returns a newly allocated bytevector whose elements are the 1021 concatenation of the elements in the given bytevectors. 1022 1023 (bytevector-append #u8(0 1 2) #u8(3 4 5)) 1024 ⇒ #u8(0 1 2 3 4 5) 1025 102614.5.1 Converting to or from strings 1027------------------------------------ 1028 1029 -- Procedure: utf8->string bytevector [start [end]] 1030 This procedure decodes the bytes of a bytevector between START and 1031 END, interpreting as a UTF-8-encoded string, and returns the 1032 corresponding string. It is an error for BYTEVECTOR to contain 1033 invalid UTF-8 byte sequences. 1034 (utf8->string #u8(#x41)) ⇒ "A" 1035 1036 -- Procedure: utf16->string bytevector [start [end]] 1037 -- Procedure: utf16be->string bytevector [start [end]] 1038 -- Procedure: utf16le->string bytevector [start [end]] 1039 These procedures interpret their <var>bytevector</var> argument as 1040 a UTF-16 encoding of a sequence of characters, and return an 1041 istring containing that sequence. 1042 1043 The bytevector subrange given to ‘utf16->string’ may begin with a 1044 byte order mark (BOM); if so, that BOM determines whether the rest 1045 of the subrange is to be interpreted as big-endian or 1046 little-endian; in either case, the BOM will not become a character 1047 in the returned string. If the subrange does not begin with a BOM, 1048 it is decoded using the same implementation-dependent endianness 1049 used by ‘string->utf16’. 1050 1051 The ‘utf16be->string’ and ‘utf16le->string’ procedures interpret 1052 their inputs as big-endian or little-endian, respectively. If a 1053 BOM is present, it is treated as a normal character and will become 1054 part of the result. 1055 1056 It is an error if ‘(- END START)’ is odd, or if the bytevector 1057 subrange contains invalid UTF-16 byte sequences. 1058 1059 -- Procedure: string->utf8 string [start [end]] 1060 This procedure encodes the characters of a string between START and 1061 END and returns the corresponding bytevector, in UTF-8 encoding. 1062 (string->utf8 "λ") ⇒ " #u8(#xCE #xBB) 1063 1064 -- Procedure: string->utf16 string [start [end]] 1065 -- Procedure: string->utf16be string [start [end]] 1066 -- Procedure: string->utf16le string [start [end]] 1067 These procedures return a newly allocated (unless empty) bytevector 1068 containing a UTF-16 encoding of the given substring. 1069 1070 The bytevectors returned by ‘string->utf16be’ and ‘string->utf16le’ 1071 do not contain a byte-order mark (BOM); ‘string->utf16be’> returns 1072 a big-endian encoding, while ‘string->utf16le’ returns a 1073 little-endian encoding. 1074 1075 The bytevectors returned by ‘string->utf16’ begin with a BOM that 1076 declares an implementation-dependent endianness, and the bytevector 1077 elements following that BOM encode the given substring using that 1078 endianness. 1079 1080 _Rationale:_ These procedures are consistent with the Unicode 1081 standard. Unicode suggests UTF-16 should default to big-endian, 1082 but Microsoft prefers little-endian. 1083 1084 1085File: kawa.info, Node: Ranges, Next: Streams, Prev: Bytevectors, Up: Data structures 1086 108714.6 Ranges 1088=========== 1089 1090A “range” is an immutable sequence of values that increase “linearly” - 1091i.e. by a fixed amount. Most commonly it’s a sequence of consequtive 1092integers. An example of the syntax is ‘[3 <: 7]’ which evaluates to the 1093sequence ‘[3 4 5 6]’. You can specify an explicit increment with a 1094‘by:’ option. There are multiple ways to specify when the sequence 1095stops. For example ‘[3 by 2 <=: 7]’ is the even numbers from 3 up to 7 1096(inclusive, because of the ‘<=’). 1097 1098 Ranges are very useful for loop indexes, or selecting a sub-sequence. 1099If you have a sequence Q and a range R, and you use the syntax ‘(Q R)’ 1100to “apply”Q with the argument R, is result is to select elements of Q 1101with indexes in R. 1102 ("ABCDEFG" [1 by: 2 <: 7]) ⇒ "BDF" 1103 1104 A range can be “unbounded”, or non-finite, if you leave off the end 1105value. For example ‘[3 by: 2]’ is the odd integers starting at 3. 1106 1107 UNBOUNDED-RANGE ::= 1108 ‘[’ START-EXPRESSION ‘by:’ STEP-EXPRESSION ‘]’ 1109 | ‘[’ START-EXPRESSION ‘<:’ ‘]’ 1110 1111 The expression ‘[START by: STEP]’ evaluates to an infinite sequence 1112of values, starting with START, and followed by ‘(+ START STEP)’, ‘(+ 1113START (* 2 STEP))’, and so on. 1114 1115 The syntax ‘[START-EXPRESSION <:]’ is shorthand for 1116‘[START-EXPRESSION by: 1]’. 1117 1118 BOUNDED-RANGE ::= ‘[’ START-EXPRESSION [‘by:’ STEP-EXPRESSION] RANGE-END ‘]’ 1119 RANGE-END ::= ‘<:’ END-EXPRESSION 1120 | ‘<=:’ END-EXPRESSION 1121 | ‘>:’ END-EXPRESSION 1122 | ‘>=:’ END-EXPRESSION 1123 | ‘size:’ SIZE-EXPRESSION 1124 1125 A bounded range takes an initial subsequence of the unbounded range 1126specified by the START-EXPRESSION and optional STEP-EXPRESSION. The 1127different END-EXPRESSION variants provide different ways to specify the 1128initial subsequence. 1129 1130 If ‘size: SIZE’ is specified, then the resulting range is the first 1131SIZE elements of unbounded sequence. 1132 1133 In the ‘<: END’ or ‘<=: END’ cases then the sequence counts up: The 1134STEP must be positive, and defaults to 1. The resulting values are 1135those X such that ‘(< X END)’, or ‘(<= X END)’, respectively. 1136 1137 In the ‘>: END’ or ‘>=: END’ cases then the sequence counts down: The 1138STEP must be negative, and defaults to -1. The resulting values are 1139those X such that ‘(> X END)’, or ‘(>= X END)’, respectively. 1140 1141 The START-EXPRESSION, STEP-EXPRESSION, and SIZE-EXPRESSION must 1142evaluate to real numbers, not necessarily integers. For example: ‘[1 1143by: 0.5 <=: 3.0]’ is ‘[1.0 1.5 2.0 2.5 3.0]’. 1144 1145 The two pseudo-ranges ‘[<:]’ and ‘[>:]’ are useful as array indexes. 1146They mean “all of the valid indexes” of the array being indexed. For 1147increasing index values use ‘[<:]’; for decreasing index values (i.e. 1148reversing) use ‘[>:]’. 1149 1150 1151File: kawa.info, Node: Streams, Next: Arrays, Prev: Ranges, Up: Data structures 1152 115314.7 Streams - lazy lists 1154========================= 1155 1156Streams, sometimes called lazy lists, are a sequential data structure 1157containing elements computed only on demand. A stream is either null or 1158is a pair with a stream in its cdr. Since elements of a stream are 1159computed only when accessed, streams can be infinite. Once computed, 1160the value of a stream element is cached in case it is needed again. 1161 1162 _Note:_ These are not the same as Java 8 streams. 1163 1164 (require 'srfi-41) 1165 (define fibs 1166 (stream-cons 1 1167 (stream-cons 1 1168 (stream-map + 1169 fibs 1170 (stream-cdr fibs))))) 1171 (stream->list 8 fibs) ⇒ (1 1 2 3 5 8 13 21) 1172 1173 See the SRFI 41 specification 1174(http://srfi.schemers.org/srfi-41/srfi-41.html) for details. 1175 1176 The Kawa implementations builds on *note promises: Lazy evaluation. 1177The ‘stream-null’ value is a promise that evaluates to the empty list. 1178The result of ‘stream-cons’ is an eager immutable pair whose ‘car’ and 1179‘cdr’ properties return promises. 1180 1181 1182File: kawa.info, Node: Arrays, Next: Hash tables, Prev: Streams, Up: Data structures 1183 118414.8 Multi-dimensional Arrays 1185============================= 1186 1187Arrays are heterogeneous data structures that generaize vectors to 1188multiple indexes or dimensions. Instead of a single integer index, 1189there are multiple indexes: An index is a vector of integers; the length 1190of a valid index sequence is the rank or the number of dimensions of an 1191array. 1192 1193 Kawa multi-dimensional arrays follows the by SRFI-25 specification 1194(http://srfi.schemers.org/srfi-25/srfi-25.html), with additions from 1195Racket’s math.array (https://docs.racket-lang.org/math/array.html) 1196package and other sources. 1197 1198 An array whose rank is 1, and where the (single) lower bound is 0 is 1199a sequence. Furthermore, if such an array is simple (not created by 1200‘share-array’) it will be implemented using a ‘<vector>’. Uniform 1201vectors and strings are also arrays in Kawa. 1202 1203 A rank-0 array has a single value. It is essentially a box for that 1204value. Functions that require arrays may treat non-arrays as a rank-0 1205array containing that value. 1206 1207 An array of rank 2 is frequently called a “matrix”. 1208 1209 Note that Kawa arrays are distinct from Java (native) arrays. The 1210latter is a simpler one-dimensional vector-like data structure, which is 1211used to implement Kawa arrays and vectors. 1212 1213 -- Procedure: array? obj 1214 Returns ‘#t’ if OBJ is an array, otherwise returns ‘#f’. 1215 121614.8.1 Array shape 1217------------------ 1218 1219The “shape” of an array consists of bounds for each index. 1220 1221 The lower bound B and the upper bound E of a dimension are exact 1222integers with ‘(<= B E)’. A valid index along the dimension is an exact 1223integer I that satisfies both ‘(<= B I)’ and ‘(< I E)’. The length of 1224the array along the dimension is the difference ‘(- E B)’. The size of 1225an array is the product of the lengths of its dimensions. 1226 1227 There is no separate data type for a shape. The canonical 1228representation for a shape (a “canonical shape”) is a rank-2 array where 1229the first index is the dimension (zero-based), and the second index is 0 1230or 1: Elements (I 0) and (I 1) are respectively the lower bound and 1231upper bound of dimension I. 1232 1233 For convenience, the procedures that require a shape can accept a 1234SHAPE-SPECIFIER, as if converted by the procedure ‘->shape’. For 1235example ‘(array-reshape ARRAY SHAPE)’ is equivalent to ‘(array-reshape 1236ARRAY (->shape SHAPE))’. 1237 1238 -- Procedure: ->shape specifier 1239 Convert the shape specifier SPECIFIER to a canonical shape. The 1240 SPECIFIER must be either a canonical shape, or vector with one 1241 element for each dimension, as described below. We use as examples 1242 a 2*3 array with lower bounds 0 and a 3*4 array with lower bounds 1243 1. 1244 • A vector of simple integers. Each integer E is an upper 1245 bound, with a zero lower bound. Equivalent to the range ‘[0 1246 <: E]’. 1247 1248 A specifier for the first examples is ‘#(2 3)’, and the second 1249 is not expressible. 1250 • A vector of lists of length 2. The first element of each list 1251 is the lower bound, and the second is the upper bound. 1252 1253 Examples: ‘#((0 2) (0 3))’ and ‘#((1 3) (1 4))’. 1254 • A vector of simple *note ranges: Ranges, one for each 1255 dimension, all of who are bounded (finite), consist of integer 1256 values, and have a STEP of 1. Each range, which is usually 1257 written as ‘[B <: E]’, expresses the bounds of the 1258 corresponding dimension For the first example you can use ‘[[0 1259 <: 2] [0 <=: 2]]’; for the second you can use ‘[[1 <: 3] [1 1260 size: 4]]’. 1261 • A vector consisting of a mix of integers, length-2 lists, and 1262 ranges. 1263 1264 Examples: ‘#(2 (0 3))’ and ‘['(1 3) [1 size: 4]]’. 1265 • A canonical shape: A rank-2 array S whose own shape is ‘[R 1266 2]’. For each dimension K (where ‘(<= K 0)’ and ‘(< K R)’), 1267 the lower bound B_{K} is ‘(S K 0)’, and the upper bound E_{K} 1268 is ‘(S K 1)’. 1269 1270 Examples: ‘#2a((0 2) (0 3))’ and ‘#2a((1 3) (1 4))’. 1271 1272 -- Procedure: shape bound ... 1273 Returns a shape. The sequence BOUND ... must consist of an even 1274 number of exact integers that are pairwise not decreasing. Each 1275 pair gives the lower and upper bound of a dimension. If the shape 1276 is used to specify the dimensions of an array and BOUND ... is the 1277 sequence B0 E0 ... BK EK ... of N pairs of bounds, then a valid 1278 index to the array is any sequence J0 ... JK ... of N exact 1279 integers where each JK satisfies ‘(<= BK JK)’ and ‘(< JK EK)’. 1280 1281 The shape of a D-dimensional array is a D * 2 array where the 1282 element at K 0 contains the lower bound for an index along 1283 dimension K and the element at K 1 contains the corresponding upper 1284 bound, where K satisfies ‘(<= 0 K)’ and ‘(< K D)’. 1285 1286 ‘(shape @BOUNDS)’ is equivalent to: ‘(array [2 (/ (length BOUNDS) 1287 2)] @BOUNDS)’ 1288 1289 -- Procedure: array-shape array 1290 Return the shape of ARRAY in the canonical (r 2) form. It is an 1291 error to attempt to modify the shape array. 1292 1293 -- Procedure: array-rank array 1294 Returns the number of dimensions of ARRAY. 1295 (array-rank 1296 (make-array (shape 1 2 3 4))) 1297 Returns 2. 1298 1299 -- Procedure: array-start array k 1300 Returns the lower bound (inclusive) for the index along dimension 1301 K. This is most commonly 0. 1302 1303 -- Procedure: array-end array k 1304 Returns the upper bound for the index along dimension K. The bound 1305 is exclusive - i.e. the first integer higher than the last legal 1306 index. 1307 1308 -- Procedure: array-size array 1309 Return the total number of elements of ARRAY. This is the product 1310 of ‘(- (array-end ARRAY K) (array-start ARRAY K))’ for every valid 1311 K. 1312 131314.8.2 Array types 1314------------------ 1315 1316 -- Type: array 1317 -- Type: arrayN 1318 -- Type: array[ETYPE] 1319 -- Type: arrayN[ETYPE] 1320 1321 The type ‘array’ matches all array values. The type ‘arrayN’, 1322 where N is an integer matches array of rank N. For example 1323 ‘array2’ matches rank-2 array - i.e. matrixes. 1324 1325 You can optionally specify the element type ETYPE. This can be a 1326 primitive type. For example a ‘array2[double]’ is a rank-2 array 1327 whose elements are ‘double’ values. 1328 132914.8.3 Array literals and printing 1330---------------------------------- 1331 1332An array literal starts with ‘#’ followed by its rank, followed by a tag 1333that describes the underlying vector (by default ‘a’), optionally 1334followed by information about its shape, and finally followed by the 1335cells, organized into dimensions using parentheses. 1336 1337 For example, ‘#2a((11 12 13) (21 22 23))’ is a rank-2 array (a 1338matrix) whose shape is ‘[2 3]’ or equivalently ‘[[0 <: 2] [0 <: 3]]’. 1339It is pretty-printed as: 1340 ╔#2a:2:3═╗ 1341 ║11│12│13║ 1342 ╟──┼──┼──╢ 1343 ║21│22│23║ 1344 ╚══╧══╧══╝ 1345 1346 ARRAY-LITERAL ::= ARRAY-LITERAL-HEADER DATUM 1347 ARRAY-LITERAL-HEADER ::= ‘#’ RANK VECTAG ARRAY-BOUND^{*} 1348 ARRAY-BOUND ::= [‘@’LOWER]‘:’LENGTH | ‘@’LOWER 1349 VECTAG ::= ‘a’ | UNIFORM-TAG 1350 1351 The VECTAG specifies the type of the elements of the array. 1352 1353 Following the VECTAG you can optionally include information about the 1354shape: For each dimension you can optionally specify the lower bounds 1355(after the character ‘"@"’), followed by the length of the dimension 1356(after the character ‘":"’). The shape information is required if a 1357lower bound is non-zero, or any length is zero. 1358 1359 The DATUM contains the elements in a nested-list format: a rank-1 1360array (i.e. vector) uses a single list, a rank-2 array uses a 1361list-of-lists, and so on. The elements are in lexicographic order. 1362 1363 A uniform u32 array of rank 2 with index ranges 2..3 and 3..4: 1364 #2u32@2@3((1 2) (2 3)) 1365 1366 This syntax follows Common Lisp with Guile extensions 1367(https://www.gnu.org/software/guile/manual/html_node/Array-Syntax.html). 1368(Note that Guile prints rank-0 arrays with an extra set of parentheses. 1369Kawa follows Common Lisp in not doing so.) 1370 1371 When an array is printed with the ‘write’ function, the result is an 1372‘array-literal’. Printing with ‘display’ formats the array in a 1373rectangular grid using the ‘format-array’ procedure. (Note that 1374‘format-array’ is only used when the output is in column 0, because Kawa 1375has very limited support for printing rectangles.) 1376 1377 -- Procedure: format-array value [port] [element-format] 1378 Produce a nice “pretty” display for VALUE, which is usually an 1379 array. 1380 1381 If PORT is an output port, the formatted output is written into 1382 that port. Otherwise, PORT must be a boolean (one of ‘#t’ or 1383 ‘#f’). If the port is ‘#t’, output is to the 1384 ‘(current-output-port)’. If the port is ‘#f’ or no port is 1385 specified, the output is returned as a string. If the port is 1386 specified and is ‘#t’ or an output-port, the result of the 1387 ‘format-array’ procedure is unspecified. (This convention matches 1388 that of the ‘format’ procedure.) 1389 1390 The top line includes an ‘array-literal-header’. The lower bound 1391 are only printed if non-zero. The dimension lengths are printed if 1392 there is room, or if one of them is zero. 1393 #|kawa:34|# (! arr (array [[1 <=: 2] [1 <=: 3]] 1394 #|.....35|# #2a((1 2) (3 4)) 9 #2a((3 4) (5 6)) 1395 #|.....36|# [42 43] #2a:1:3((8 7 6)) #2a((90 91) (100 101)))) 1396 #|kawa:37|# arr 1397 ╔#2a@1:2@1:3════╤═════════╗ 1398 ║#2a═╗ │ 9│#2a═╗ ║ 1399 ║║1│2║ │ │║3│4║ ║ 1400 ║╟─┼─╢ │ │╟─┼─╢ ║ 1401 ║║3│4║ │ │║5│6║ ║ 1402 ║╚═╧═╝ │ │╚═╧═╝ ║ 1403 ╟───────┼───────┼─────────╢ 1404 ║╔#1a:2╗│#2a:1:3│╔#2a:2:2╗║ 1405 ║║42│43║│║8│7│6║│║ 90│ 91║║ 1406 ║╚══╧══╝│╚═╧═╧═╝│╟───┼───╢║ 1407 ║ │ │║100│101║║ 1408 ║ │ │╚═══╧═══╝║ 1409 ╚═══════╧═══════╧═════════╝ 1410 If ELEMENT-FORMAT is specified, it is a format string used for 1411 format each non-array: 1412 #|kawa:38|# (format-array arr "~4,2f") 1413 ╔#2a@1:2@1:3══╤════════════════╤═══════════════╗ 1414 ║╔#2a:2:2══╗ │ 9.00│╔#2a:2:2══╗ ║ 1415 ║║1.00│2.00║ │ │║3.00│4.00║ ║ 1416 ║╟────┼────╢ │ │╟────┼────╢ ║ 1417 ║║3.00│4.00║ │ │║5.00│6.00║ ║ 1418 ║╚════╧════╝ │ │╚════╧════╝ ║ 1419 ╟─────────────┼────────────────┼───────────────╢ 1420 ║╔#1a:2╤═════╗│╔#2a:1:3══╤════╗│╔#2a:2:2══════╗║ 1421 ║║42.00│43.00║│║8.00│7.00│6.00║│║ 90.00│ 91.00║║ 1422 ║╚═════╧═════╝│╚════╧════╧════╝│╟──────┼──────╢║ 1423 ║ │ │║100.00│101.00║║ 1424 ║ │ │╚══════╧══════╝║ 1425 ╚═════════════╧════════════════╧═══════════════╝ 1426 If the rank is more than 2, then each “layer” is printed separated 1427 by double lines. 1428 #|kawa:42|# (array-reshape [1 <=: 24] [3 2 4]) 1429 ╔#3a:3:2:4══╗ 1430 ║ 1│ 2│ 3│ 4║ 1431 ╟──┼──┼──┼──╢ 1432 ║ 5│ 6│ 7│ 8║ 1433 ╠══╪══╪══╪══╣ 1434 ║ 9│10│11│12║ 1435 ╟──┼──┼──┼──╢ 1436 ║13│14│15│16║ 1437 ╠══╪══╪══╪══╣ 1438 ║17│18│19│20║ 1439 ╟──┼──┼──┼──╢ 1440 ║21│22│23│24║ 1441 ╚══╧══╧══╧══╝ 1442 144314.8.4 Array construction 1444------------------------- 1445 1446See also ‘array-reshape’ 1447 1448 -- Procedure: array shape obj ... 1449 Returns a new array whose shape is given by SHAPE and the initial 1450 contents of the elements are OBJ ... in row major order. The 1451 array does not retain a reference to SHAPE. 1452 1453 -- Procedure: make-array shape 1454 -- Procedure: make-array shape value... 1455 Returns a newly allocated array whose shape is given by SHAPE. If 1456 VALUE is provided, then each element is initialized to it. If 1457 there is more than one VALUE, they are used in order, starting over 1458 when the VALUEs are exhausted. If there is no VALUE, the initial 1459 contents of each element is unspecified. (Actually, it is the 1460 ‘#!null’.) The array does not retain a reference to SHAPE. 1461 1462 #|kawa:16|# (make-array [2 4] 1 2 3 4 5) 1463 ╔#2a:2:4╗ 1464 ║1│2│3│4║ 1465 ╟─┼─┼─┼─╢ 1466 ║5│1│2│3║ 1467 ╚═╧═╧═╧═╝ 1468 1469 _Compatibility:_ Guile has an incompatible ‘make-array’ procedure. 1470 1471 -- Procedure: build-array shape getter [setter] 1472 Construct a “virtual array” of the given SHAPE, which uses no 1473 storage for the elements. Instead, elements are calculated 1474 on-demand by calling GETTER, which takes a single argument, an 1475 index vector. 1476 1477 There is no caching or memoization. 1478 1479 #|kawa:1|# (build-array [[10 <: 12] 3] 1480 #|....:2|# (lambda (ind) 1481 #|....:3|# (let ((x (ind 0)) (y (ind 1))) 1482 #|....:4|# (- x y)))) 1483 #2a@10:2:3 1484 ║10│ 9│8║ 1485 ╟──┼──┼─╢ 1486 ║11│10│9║ 1487 ╚══╧══╧═╝ 1488 1489 The resulting array is mutable if a SETTER is provided. The SETTER 1490 takes two arguments: An index vector, and the new value for the 1491 specified element. Below is a simple and space-efficient (but 1492 slow) implementation of sparse arrays: Most element have a default 1493 initial value, but you can override specific elements. 1494 (define (make-sparse-array shape default-value) 1495 (let ((vals '())) ;; association list of (INDEX-VECTOR . VALUE) 1496 (build-array shape 1497 (lambda (I) 1498 (let ((v (assoc I vals))) 1499 (if v (cdr v) 1500 default-value))) 1501 (lambda (I newval) 1502 (let ((v (assoc I vals))) 1503 (if v 1504 (set-cdr! v newval) 1505 (set! vals (cons (cons I newval) vals)))))))) 1506 1507 -- Procedure: index-array shape 1508 Return a new immutable array of the specified SHAPE where each 1509 element is the corresponding row-major index. Same as 1510 ‘(array-reshape [0 <: SIZE] SHAPE)’ where SIZE is the ‘array-size’ 1511 of the resulting array. 1512 1513 #|kawa:1|# (index-array [[1 <: 3] [2 <: 6]]) 1514 #2a@1:2@2:4 1515 ║0│1│2│3║ 1516 ╟─┼─┼─┼─╢ 1517 ║4│5│6│7║ 1518 ╚═╧═╧═╧═╝ 1519 152014.8.5 Array indexing 1521--------------------- 1522 1523If you “call” an array as it it were a function, it is equivalent to 1524using ‘array-index-ref’, which is generalization of ‘array-ref’. For 1525example, given a rank-2 array ARR with integer indexes I and J, the 1526following all get the element of ARR at index ‘[I J]’. 1527 (ARR I J) 1528 (array-index-ref ARR I J) 1529 (array-ref ARR I J) 1530 (array-ref ARR [I J]) 1531 1532 Using function-call notation or ‘array-index-ref’ (but not plain 1533‘array-ref’) you can do generalized APL-style slicing and indirect 1534indexing. See under ‘array-index-ref’ for examples. 1535 1536 -- Procedure: array-ref array k ... 1537 -- Procedure: array-ref array index 1538 Returns the contents of the element of ARRAY at index K .... The 1539 sequence K ... must be a valid index to ARRAY. In the second 1540 form, INDEX must be either a vector (a 0-based 1-dimensional array) 1541 containing K .... 1542 (array-ref (array [2 3] 1543 'uno 'dos 'tres 1544 'cuatro 'cinco 'seis) 1545 1 0) 1546 Returns ‘cuatro’. 1547 (let ((a (array (shape 4 7 1 2) 3 1 4))) 1548 (list (array-ref a 4 1) 1549 (array-ref a (vector 5 1)) 1550 (array-ref a (array (shape 0 2) 1551 6 1)))) 1552 Returns ‘(3 1 4)’. 1553 1554 -- Procedure: array-index-ref array index ... 1555 Generalized APL-style array indexing, where each INDEX can be 1556 either an array or an integer. 1557 1558 If each INDEX is an integer, then the result is the same as 1559 ‘array-ref’. 1560 1561 Otherwise, the result is an immutable array whose rank is the sum 1562 of the ranks of each INDEX. An integer is treated as rank-0 array. 1563 1564 If MARR is the result of ‘(array-index-ref ARR M_{1} M_{2} ...)’ 1565 then: 1566 (MARR I_{11} I_{12} ... I_{21} I_{22} ...) 1567 is defined as: 1568 (ARR (M_{1} I_{11} I_{12} ...) (M_{2} I_{21} I_{22} ...) ...) 1569 Each M_{K} gets as many indexes as its rank. If M_{K} is an 1570 integer, then it we use it directly without any indexing. 1571 1572 Here are some examples, starting with simple indexing. 1573 #|kawa:1|# (define arr (array #2a((1 4) (0 4)) 1574 #|.....2|# 10 11 12 13 20 21 22 23 30 31 32 33)) 1575 #|kawa:3|# arr 1576 ╔#2a@1:3:4══╗ 1577 ║10│11│12│13║ 1578 ╟──┼──┼──┼──╢ 1579 ║20│21│22│23║ 1580 ╟──┼──┼──┼──╢ 1581 ║30│31│32│33║ 1582 ╚══╧══╧══╧══╝ 1583 #|kawa:4|# (arr 2 3) 1584 23 1585 If one index is a vector and the rest are scalar integers, then the 1586 result is a vector: 1587 #|kawa:5|# (arr 2 [3 1]) 1588 #(23 21) 1589 You can select a “sub-matrix” when all indexes are vectors: 1590 #|kawa:6|# (arr [2 1] [3 1 3]) 1591 ╔#2a:2:3═╗ 1592 ║23│21│23║ 1593 ╟──┼──┼──╢ 1594 ║13│11│13║ 1595 ╚══╧══╧══╝ 1596 Using ranges for index vectors selects a rectangular sub-matrix. 1597 #|kawa:7|# (arr [1 <: 3] [1 <: 4]) 1598 ╔#2a:2:3═╗ 1599 ║11│12│13║ 1600 ╟──┼──┼──╢ 1601 ║21│22│23║ 1602 ╚══╧══╧══╝ 1603 You can add new dimensions: 1604 #|kawa:8|# (arr [2 1] #2a((3 1) (3 2))) 1605 #3a╤══╗ 1606 ║23│21║ 1607 ╟──┼──╢ 1608 ║23│22║ 1609 ╠══╪══╣ 1610 ║13│11║ 1611 ╟──┼──╢ 1612 ║13│12║ 1613 ╚══╧══╝ 1614 The pseudo-range ‘[<:]’ can be used to select all the indexes along 1615 a dimension. To select row 2 (1-origin): 1616 #|kawa:9|# (arr 2 [<:]) 1617 #(20 21 22 23) 1618 To reverse the order use ‘[>:]’: 1619 #|kawa:10|# (arr 2 [>:]) 1620 #(23 22 21 20) 1621 To select column 3: 1622 #|kawa:11|# (arr [<:] 3) 1623 #(13 23 33) 1624 If you actually want a column matrix (i.e. with shape ‘[3 1]’ you 1625 can place the index in a single-element vector: 1626 #|kawa:12|# (arr [<:] [3]) 1627 #2a╗ 1628 ║13║ 1629 ╟──╢ 1630 ║23║ 1631 ╟──╢ 1632 ║33║ 1633 ╚══╝ 1634 To expand that column to 5 colums you can repeat the column index: 1635 #|kawa:13|# [3 by: 0 size: 5] 1636 #(3 3 3 3 3) 1637 #|kawa:14|# (arr [<:] [3 by: 0 size: 5]) 1638 ╔#2a:3:5═╤══╤══╗ 1639 ║13│13│13│13│13║ 1640 ╟──┼──┼──┼──┼──╢ 1641 ║23│23│23│23│23║ 1642 ╟──┼──┼──┼──┼──╢ 1643 ║33│33│33│33│33║ 1644 ╚══╧══╧══╧══╧══╝ 1645 164614.8.6 Modifying arrays 1647----------------------- 1648 1649You can use ‘set!’ to modify one or multiple elements. To modify a 1650single element: 1651 (set! (ARR INDEX ...) NEW-VALUE) 1652 is equivalent to 1653 (array-set! ARR INDEX ... NEW-VALUE) 1654 You can set a slice (or all of the elements). In that case: 1655 (set! (ARR INDEX ...) NEW-ARRAY) 1656 is equivalent to: 1657 (array-copy! (array-index-share ARR INDEX ...) NEW-ARRAY) 1658 1659 -- Procedure: array-set! array k ... obj 1660 -- Procedure: array-set! array index obj 1661 Stores OBJ in the element of ARRAY at index K .... Returns the 1662 void value. The sequence K ... must be a valid index to ARRAY. 1663 In the second form, INDEX must be either a vector or a 0-based 1664 1-dimensional array containing K .... 1665 1666 (let ((a (make-array 1667 (shape 4 5 4 5 4 5)))) 1668 (array-set! a 4 4 4 "huuhkaja") 1669 (array-ref a 4 4 4)) 1670 Returns ‘"huuhkaja"’. 1671 1672 _Compatibility:_ SRFI-47, Guile and Scheme-48 have ‘array-set!’ 1673 with a different argument order. 1674 1675 -- Procedure: array-copy! dst src 1676 _Compatibility:_ Guile has a ‘array-copy!’ with the reversed 1677 argument order. 1678 1679 -- Procedure: array-fill! array value 1680 Set all the values ARRAY to VALUE. 1681 168214.8.7 Transformations and views 1683-------------------------------- 1684 1685A view or transform of an array is an array A_{2} whose elements come 1686from some other array A_{1}, given some transform function T that maps 1687A_{2} indexes to A_{1} indexes. Specifically ‘(array-ref A_{2} 1688INDEXES)’ is ‘(array-ref A_{1} (T INDEXES))’. Modifying A_{2} causes 1689A_{1} to be modified; modifying A_{1} may modify A_{2} (depending on the 1690transform function). The shape of A_{2} is in generally different than 1691that of A_{1}. 1692 1693 -- Procedure: array-transform array shape transform 1694 This is a general mechanism for creating a view. The result is a 1695 new array with the given SHAPE. Accessing this new array is 1696 implemented by calling the TRANSFORM function on the index vector, 1697 which must return a new index vector valid for indexing the 1698 original ARRAY. Here is an example (using the same ‘arr’ as in the 1699 ‘array-index-ref’ example): 1700 #|kawa:1|# (define arr (array #2a((1 4) (0 4)) 1701 #|.....2|# 10 11 12 13 20 21 22 23 30 31 32 33)) 1702 #|kawa:14|# (array-transform arr #2a((0 3) (1 3) (0 2)) 1703 #|.....15|# (lambda (ix) (let ((i (ix 0)) (j (ix 1)) (k (ix 2))) 1704 #|.....16|# [(+ i 1) 1705 #|.....17|# (+ (* 2 (- j 1)) k)]))) 1706 #3a:3@1:2:2 1707 ║10│11║ 1708 ╟──┼──╢ 1709 ║12│13║ 1710 ╠══╪══╣ 1711 ║20│21║ 1712 ╟──┼──╢ 1713 ║22│23║ 1714 ╠══╪══╣ 1715 ║30│31║ 1716 ╟──┼──╢ 1717 ║32│33║ 1718 ╚══╧══╝ 1719 1720 The ‘array-transform’ is generalization of ‘share-array’, in that 1721 it does not require the TRANSFORM to be affine. Also note the 1722 different calling conversions for the TRANFORM: ‘array-transform’ 1723 takes a single argument (a vector of indexes), and returns a single 1724 result (a vector of indexes); ‘share-array’ takes one argument for 1725 each index, and returns one value for each index. The difference 1726 is historical. 1727 1728 -- Procedure: array-index-share array index ... 1729 This does the same generalized APL-style indexing as 1730 ‘array-index-ref’. However, the resulting array is a modifiable 1731 view into the argument ARRAY. 1732 1733 -- Procedure: array-reshape array shape 1734 Creates a new array NARRAY of the given SHAPE, such that 1735 ‘(array->vector ARRAY)’ and ‘(array->vector NARRAY)’ are 1736 equivalent. I.e. the I’th element in row-major-order of NARRAY is 1737 the I’th element in row-major-order of ARRAY. Hence ‘(array-size 1738 NARRAY)’ (as specied from the SHAPE) must be equal to ‘(array-size 1739 ARRAY)’. The resulting NARRAY is a view such that modifying ARRAY 1740 also modifies NARRAY and vice versa. 1741 1742 -- Procedure: share-array array shape proc 1743 Returns a new array of SHAPE shape that shares elements of ARRAY 1744 through PROC. The procedure PROC must implement an affine function 1745 that returns indices of ARRAY when given indices of the array 1746 returned by ‘share-array’. The array does not retain a reference 1747 to SHAPE. 1748 (define i_4 1749 (let* ((i (make-array 1750 (shape 0 4 0 4) 1751 0)) 1752 (d (share-array i 1753 (shape 0 4) 1754 (lambda (k) 1755 (values k k))))) 1756 (do ((k 0 (+ k 1))) 1757 ((= k 4)) 1758 (array-set! d k 1)) 1759 i)) 1760 1761 Note: the affinity requirement for PROC means that each value must 1762 be a sum of multiples of the arguments passed to PROC, plus a 1763 constant. 1764 1765 Implementation note: arrays have to maintain an internal index 1766 mapping from indices K1 ... KD to a single index into a backing 1767 vector; the composition of this mapping and PROC can be recognised 1768 as ‘(+ N0 (* N1 K1) ... (* ND KD))’ by setting each index in turn 1769 to 1 and others to 0, and all to 0 for the constant term; the 1770 composition can then be compiled away, together with any complexity 1771 that the user introduced in their procedure. 1772 1773 Here is an example where the ARRAY is a uniform vector: 1774 (share-array 1775 (f64vector 1.0 2.0 3.0 4.0 5.0 6.0) 1776 (shape 0 2 0 3) 1777 (lambda (i j) (+ (* 2 i) j))) 1778 ⇒ #2f64((1.0 2.0 3.0) (4.0 5.0 6.0)) 1779 1780 -- Procedure: array-flatten array 1781 -- Procedure: array->vector array 1782 Return a vector consisting of the elements of the ARRAY in 1783 row-major-order. 1784 1785 The result of ‘array-flatten’ is fresh (mutable) copy, not a view. 1786 The result of ‘array->vector’ is a view: If ARRAY is mutable, then 1787 modifying ARRAY changes the flattened result and vice versa. 1788 1789 If ARRAY is “simple”, ‘array->vector’ returns the original vector. 1790 Specifically, if VEC is a vector then: 1791 (eq? VEC (array->vector (array-reshape VEC SHAPE))) 1792 179314.8.8 Miscellaneous 1794-------------------- 1795 1796 -- Procedure: format-array value [element-format] 1797 1798 1799File: kawa.info, Node: Hash tables, Prev: Arrays, Up: Data structures 1800 180114.9 Hash tables 1802================ 1803 1804A “hashtable” is a data structure that associates keys with values. The 1805hashtable has no intrinsic order for the (key, value) associations it 1806contains, and supports in-place modification as the primary means of 1807setting the contents of a hash table. Any object can be used as a key, 1808provided a “hash function” and a suitable “equivalence function” is 1809available. A hash function is a procedure that maps keys to exact 1810integer objects. 1811 1812 The hashtable provides key lookup and destructive update in amortised 1813constant time, provided that a good hash function is used. A hash 1814function H is acceptable for an equivalence predicate E iff ‘(E OBJ1 1815OBJ2)’ implies ‘(= (H OBJ1) (H OBJ2))’. A hash function H is good for a 1816equivalence predicate E if it distributes the resulting hash values for 1817non-equal objects (by E) as uniformly as possible over the range of hash 1818values, especially in the case when some (non-equal) objects resemble 1819each other by e.g. having common subsequences. This definition is 1820vague but should be enough to assert that e.g. a constant function is 1821not a good hash function. 1822 1823 Kawa provides two complete sets of functions for hashtables: 1824 • The functions specified by R6RS have names starting with 1825 ‘hashtable-’ 1826 • The functions specified by the older SRFI-69 1827 (http://srfi.schemers.org/srfi-69/srfi-69.html) specifiation have 1828 names starting with ‘hash-table-’ 1829 1830 Both interfaces use the same underlying datatype, so it is possible 1831to mix and match from both sets. That datatype implements 1832‘java.util.Map’. Freshly-written code should probably use the R6RS 1833functions. 1834 183514.9.1 R6RS hash tables 1836----------------------- 1837 1838To use these hash table functions in your Kawa program you must first: 1839 1840 (import (rnrs hashtables)) 1841 1842 This section uses the HASHTABLE parameter name for arguments that 1843must be hashtables, and the KEY parameter name for arguments that must 1844be hashtable keys. 1845 1846 -- Procedure: make-eq-hashtable 1847 -- Procedure: make-eq-hashtable K 1848 Return a newly allocated mutable hashtable that accepts arbitrary 1849 objects as keys, and compares those keys with ‘eq?’. If an 1850 argument is given, the initial capacity of the hashtable is set to 1851 approximately K elements. 1852 1853 -- Procedure: make-eqv-hashtable 1854 -- Procedure: make-eqv-hashtable K 1855 Return a newly allocated mutable hashtable that accepts arbitrary 1856 objects as keys, and compares those keys with ‘eqv?’. If an 1857 argument is given, the initial capacity of the hashtable is set to 1858 approximately K elements. 1859 1860 -- Procedure: make-hashtable HASH-FUNCTION EQUIV 1861 -- Procedure: make-hashtable HASH-FUNCTION EQUIV K 1862 HASH-FUNCTION and EQUIV must be procedures. HASH-FUNCTION should 1863 accept a key as an argument and should return a non–negative exact 1864 integer object. EQUIV should accept two keys as arguments and 1865 return a single value. Neither procedure should mutate the 1866 hashtable returned by ‘make-hashtable’. 1867 1868 The ‘make-hashtable’ procedure returns a newly allocated mutable 1869 hashtable using HASH-FUNCTION as the hash function and EQUIV as the 1870 equivalence function used to compare keys. If a third argument is 1871 given, the initial capacity of the hashtable is set to 1872 approximately K elements. 1873 1874 Both HASH-FUNCTION and EQUIV should behave like pure functions on 1875 the domain of keys. For example, the ‘string-hash’ and ‘string=?’ 1876 procedures are permissible only if all keys are strings and the 1877 contents of those strings are never changed so long as any of them 1878 continues to serve as a key in the hashtable. Furthermore, any 1879 pair of keys for which EQUIV returns true should be hashed to the 1880 same exact integer objects by HASH-FUNCTION. 1881 1882 _Note:_ Hashtables are allowed to cache the results of calling 1883 the hash function and equivalence function, so programs cannot 1884 rely on the hash function being called for every lookup or 1885 update. Furthermore any hashtable operation may call the hash 1886 function more than once. 1887 188814.9.1.1 Procedures 1889................... 1890 1891 -- Procedure: hashtable? OBJ 1892 Return ‘#t’ if OBJ is a hashtable, ‘#f’ otherwise. 1893 1894 -- Procedure: hashtable-size HASHTABLE 1895 Return the number of keys contained in HASHTABLE as an exact 1896 integer object. 1897 1898 -- Procedure: hashtable-ref HASHTABLE KEY DEFAULT 1899 Return the value in HASHTABLE associated with KEY. If HASHTABLE 1900 does not contain an association for KEY, DEFAULT is returned. 1901 1902 -- Procedure: hashtable-set! HASHTABLE KEY OBJ 1903 Change HASHTABLE to associate KEY with OBJ, adding a new 1904 association or replacing any existing association for KEY, and 1905 returns unspecified values. 1906 1907 -- Procedure: hashtable-delete! HASHTABLE KEY 1908 Remove any association for KEY within HASHTABLE and returns 1909 unspecified values. 1910 1911 -- Procedure: hashtable-contains? HASHTABLE KEY 1912 Return ‘#t’ if HASHTABLE contains an association for KEY, ‘#f’ 1913 otherwise. 1914 1915 -- Procedure: hashtable-update! HASHTABLE KEY PROC DEFAULT 1916 PROC should accept one argument, should return a single value, and 1917 should not mutate HASHTABLE. 1918 1919 The ‘hashtable-update!’ procedure applies PROC to the value in 1920 HASHTABLE associated with KEY, or to DEFAULT if HASHTABLE does not 1921 contain an association for KEY. The HASHTABLE is then changed to 1922 associate KEY with the value returned by PROC. 1923 1924 The behavior of ‘hashtable-update!’ is equivalent to the following 1925 code, but is may be (and is in Kawa) implemented more efficiently 1926 in cases where the implementation can avoid multiple lookups of the 1927 same key: 1928 1929 (hashtable-set! 1930 hashtable key 1931 (proc (hashtable-ref 1932 hashtable key default))) 1933 1934 -- Procedure: hashtable-copy HASHTABLE 1935 -- Procedure: hashtable-copy HASHTABLE MUTABLE 1936 Return a copy of HASHTABLE. If the MUTABLE argument is provided 1937 and is true, the returned hashtable is mutable; otherwise it is 1938 immutable. 1939 1940 -- Procedure: hashtable-clear! HASHTABLE 1941 -- Procedure: hashtable-clear! HASHTABLE K 1942 Remove all associations from HASHTABLE and returns unspecified 1943 values. 1944 1945 If a second argument is given, the current capacity of the 1946 hashtable is reset to approximately K elements. 1947 1948 -- Procedure: hashtable-keys HASHTABLE 1949 Return a vector of all keys in HASHTABLE. The order of the vector 1950 is unspecified. 1951 1952 -- Procedure: hashtable-entries HASHTABLE 1953 Return two values, a vector of the keys in HASHTABLE, and a vector 1954 of the corresponding values. 1955 1956 Example: 1957 1958 (let ((h (make-eqv-hashtable))) 1959 (hashtable-set! h 1 'one) 1960 (hashtable-set! h 2 'two) 1961 (hashtable-set! h 3 'three) 1962 (hashtable-entries h)) 1963 ⇒ #(1 2 3) #(one two three) ; two return values 1964 1965 the order of the entries in the result vectors is not known. 1966 196714.9.1.2 Inspection 1968................... 1969 1970 -- Procedure: hashtable-equivalence-function HASHTABLE 1971 Return the equivalence function used by HASHTABLE to compare keys. 1972 For hashtables created with ‘make-eq-hashtable’ and 1973 ‘make-eqv-hashtable’, returns ‘eq?’ and ‘eqv?’ respectively. 1974 1975 -- Procedure: hashtable-hash-function HASHTABLE 1976 Return the hash function used by HASHTABLE. For hashtables created 1977 by ‘make-eq-hashtable’ or ‘make-eqv-hashtable’, ‘#f’ is returned. 1978 1979 -- Procedure: hashtable-mutable? HASHTABLE 1980 Return ‘#t’ if HASHTABLE is mutable, otherwise ‘#f’. 1981 198214.9.1.3 Hash functions 1983....................... 1984 1985The ‘equal-hash’, ‘string-hash’, and ‘string-ci-hash’ procedures of this 1986section are acceptable as the hash functions of a hashtable only if the 1987keys on which they are called are not mutated while they remain in use 1988as keys in the hashtable. 1989 1990 -- Procedure: equal-hash OBJ 1991 Return an integer hash value for OBJ, based on its structure and 1992 current contents. This hash function is suitable for use with 1993 ‘equal?’ as an equivalence function. 1994 _Note:_ Like ‘equal?’, the ‘equal-hash’ procedure must always 1995 terminate, even if its arguments contain cycles. 1996 1997 -- Procedure: string-hash STRING 1998 Return an integer hash value for STRING, based on its current 1999 contents. This hash function is suitable for use with ‘string=?’ 2000 as an equivalence function. 2001 2002 -- Procedure: string-ci-hash STRING 2003 Return an integer hash value for STRING based on its current 2004 contents, ignoring case. This hash function is suitable for use 2005 with ‘string-ci=?’ as an equivalence function. 2006 2007 -- Procedure: symbol-hash SYMBOL 2008 Return an integer hash value for SYMBOL. 2009 201014.9.2 SRFI-69 hash tables 2011-------------------------- 2012 2013To use these hash table functions in your Kawa program you must first: 2014 (require 'srfi-69) 2015 or 2016 (require 'hash-table) 2017 or 2018 (import (srfi 69 basic-hash-tables)) 2019 202014.9.2.1 Type constructors and predicate 2021........................................ 2022 2023 -- Procedure: make-hash-table [ equal? [ hash [ size-hint]]] → 2024 hash-table 2025 2026 Create a new hash table with no associations. The EQUAL? parameter 2027 is a predicate that should accept two keys and return a boolean 2028 telling whether they denote the same key value; it defaults to the 2029 ‘equal?’ function. 2030 2031 The HASH parameter is a hash function, and defaults to an 2032 appropriate hash function for the given EQUAL? predicate (see the 2033 Hashing section). However, an acceptable default is not guaranteed 2034 to be given for any equivalence predicate coarser than ‘equal?’, 2035 except for ‘string-ci=?’. (The function ‘hash’ is acceptable for 2036 ‘equal?’, so if you use coarser equivalence than ‘equal?’ other 2037 than ‘string-ci=?’, you must always provide the function hash 2038 yourself.) (An equivalence predicate C1 is coarser than a 2039 equivalence predicate C2 iff there exist values X and Y such that 2040 ‘(and (C1 X Y) (not (C2 X Y)))’.) 2041 2042 The SIZE-HINT parameter can be used to suggested an approriate 2043 initial size. This option is not part of the SRFI-69 specification 2044 (though it is handled by the reference implementation), so 2045 specifying that option might be unportable. 2046 2047 -- Procedure: hash-table? obj → boolean 2048 A predicate to test whether a given object OBJ is a hash table. 2049 2050 -- Procedure: alist->hash-table alist [ equal? [ hash [ size-hint]]] → 2051 hash-table 2052 2053 Takes an association list ALIST and creates a hash table HASH-TABLE 2054 which maps the ‘car’ of every element in ALIST to the ‘cdr’ of 2055 corresponding elements in ALIST. The EQUAL?, HASH, and SIZE-HINT 2056 parameters are interpreted as in ‘make-hash-table’. If some key 2057 occurs multiple times in ALIST, the value in the first association 2058 will take precedence over later ones. (Note: the choice of using 2059 ‘cdr’ (instead of ‘cadr’) for values tries to strike balance 2060 between the two approaches: using CADR would render this procedure 2061 unusable for ‘cdr’ alists, but not vice versa.) 2062 206314.9.2.2 Reflective queries 2064........................... 2065 2066 -- Procedure: hash-table-equivalence-function hash-table 2067 Returns the equivalence predicate used for keys of HASH-TABLE. 2068 2069 -- Procedure: hash-table-hash-function hash-table 2070 Returns the hash function used for keys of HASH-TABLE. 2071 207214.9.2.3 Dealing with single elements 2073..................................... 2074 2075 -- Procedure: hash-table-ref hash-table key [ thunk ] → value 2076 This procedure returns the value associated to KEY in HASH-TABLE. 2077 If no value is associated to KEY and THUNK is given, it is called 2078 with no arguments and its value is returned; if THUNK is not given, 2079 an error is signalled. Given a good hash function, this operation 2080 should have an (amortised) complexity of O(1) with respect to the 2081 number of associations in HASH-TABLE. 2082 2083 -- Procedure: hash-table-ref/default hash-table key default → value 2084 Evaluates to the same value as ‘(hash-table-ref HASH-TABLE KEY 2085 (lambda () DEFAULT))’. Given a good hash function, this operation 2086 should have an (amortised) complexity of O(1) with respect to the 2087 number of associations in hash-table. 2088 2089 -- Procedure: hash-table-set! hash-table key value → void 2090 This procedure sets the value associated to KEY in HASH-TABLE. The 2091 previous association (if any) is removed. Given a good hash 2092 function, this operation should have an (amortised) complexity of 2093 O(1) with respect to the number of associations in hash-table. 2094 2095 -- Procedure: hash-table-delete! hash-table key → void 2096 This procedure removes any association to KEY in HASH-TABLE. It is 2097 not an error if no association for the KEY exists; in this case, 2098 nothing is done. Given a good hash function, this operation should 2099 have an (amortised) complexity of O(1) with respect to the number 2100 of associations in hash-table. 2101 2102 -- Procedure: hash-table-exists? hash-table key → boolean 2103 This predicate tells whether there is any association to KEY in 2104 HASH-TABLE. Given a good hash function, this operation should have 2105 an (amortised) complexity of O(1) with respect to the number of 2106 associations in hash-table. 2107 2108 -- Procedure: hash-table-update! hash-table key function [ thunk ] → 2109 void 2110 Semantically equivalent to, but may be implemented more efficiently 2111 than, the following code: 2112 (hash-table-set! HASH-TABLE KEY 2113 (function (hash-table-ref HASH-TABLE KEY THUNK))) 2114 2115 -- Procedure: hash-table-update!/default hash-table key function 2116 default → void 2117 Behaves as if it evaluates to ‘(hash-table-update! HASH-TABLE KEY 2118 FUNCTION (lambda () DEFAULT))’. 2119 212014.9.2.4 Dealing with the whole contents 2121........................................ 2122 2123 -- Procedure: hash-table-size hash-table → integer 2124 Returns the number of associations in HASH-TABLE. This operation 2125 takes constant time. 2126 2127 -- Procedure: hash-table-keys hash-table → list 2128 Returns a list of keys in HASH-TABLE. The order of the keys is 2129 unspecified. 2130 2131 -- Procedure: hash-table-values hash-table → list 2132 Returns a list of values in HASH-TABLE. The order of the values is 2133 unspecified, and is not guaranteed to match the order of keys in 2134 the result of ‘hash-table-keys’. 2135 2136 -- Procedure: hash-table-walk hash-table proc → void 2137 PROC should be a function taking two arguments, a key and a value. 2138 This procedure calls PROC for each association in HASH-TABLE, 2139 giving the key of the association as key and the value of the 2140 association as value. The results of PROC are discarded. The 2141 order in which PROC is called for the different associations is 2142 unspecified. 2143 2144 -- Procedure: hash-table-fold hash-table f init-value → final-value 2145 This procedure calls F for every association in HASH-TABLE with 2146 three arguments: the key of the association key, the value of the 2147 association value, and an accumulated value, VAL. The VAL is 2148 INIT-VALUE for the first invocation of F, and for subsequent 2149 invocations of F, the return value of the previous invocation of F. 2150 The value FINAL-VALUE returned by ‘hash-table-fold’ is the return 2151 value of the last invocation of F. The order in which F is called 2152 for different associations is unspecified. 2153 2154 -- Procedure: hash-table->alist hash-table → alist 2155 Returns an association list such that the ‘car’ of each element in 2156 ALIST is a key in HASH-TABLE and the corresponding ‘cdr’ of each 2157 element in ALIST is the value associated to the key in HASH-TABLE. 2158 The order of the elements is unspecified. 2159 2160 The following should always produce a hash table with the same 2161 mappings as a hash table H: 2162 (alist->hash-table (hash-table->alist H) 2163 (hash-table-equivalence-function H) 2164 (hash-table-hash-function H)) 2165 2166 -- Procedure: hash-table-copy hash-table → hash-table 2167 Returns a new hash table with the same equivalence predicate, hash 2168 function and mappings as in HASH-TABLE. 2169 2170 -- Procedure: hash-table-merge! hash-table1 hash-table2 → hash-table 2171 Adds all mappings in HASH-TABLE2 into HASH-TABLE1 and returns the 2172 resulting hash table. This function may modify HASH-TABLE1 2173 destructively. 2174 217514.9.2.5 Hash functions 2176....................... 2177 2178The Kawa implementation always calls these hash functions with a single 2179parameter, and expects the result to be within the entire (32-bit 2180signed) ‘int’ range, for compatibility with standard ‘hashCode’ methods. 2181 2182 -- Procedure: hash object [ bound ] → integer 2183 Produces a hash value for object in the range from 0 (inclusive) tp 2184 to BOUND (exclusive). 2185 2186 If BOUND is not given, the Kawa implementation returns a value 2187 within the range ‘(- (expt 2 32))’ (inclusive) to 2188 ‘(- (expt 2 32) 1)’ (inclusive). It does this by calling the 2189 standard ‘hashCode’ method, and returning the result as is. (If 2190 the OBJECT is the Java ‘null’ value, 0 is returned.) This hash 2191 function is acceptable for ‘equal?’. 2192 2193 -- Procedure: string-hash string [ bound ] → integer 2194 The same as ‘hash’, except that the argument string must be a 2195 string. (The Kawa implementation returns the same as the ‘hash’ 2196 function.) 2197 2198 -- Procedure: string-ci-hash string [ bound ] → integer 2199 The same as ‘string-hash’, except that the case of characters in 2200 string does not affect the hash value produced. (The Kawa 2201 implementation returns the same the ‘hash’ function applied to the 2202 lower-cased STRING.) 2203 2204 -- Procedure: hash-by-identity object [ bound ] → integer 2205 The same as ‘hash’, except that this function is only guaranteed to 2206 be acceptable for ‘eq?’. Kawa uses the ‘identityHashCode’ method 2207 of ‘java.lang.System’. 2208 2209 2210File: kawa.info, Node: Eval and Environments, Next: Debugging, Prev: Data structures, Up: Top 2211 221215 Eval and Environments 2213************************ 2214 2215 -- Procedure: environment list^{*} 2216 This procedure returns a specifier for the environment that results 2217 by starting with an empty environment and then importing each LIST, 2218 considered as an IMPORT-SET, into it. The bindings of the 2219 environment represented by the specifier are immutable, as is the 2220 environment itself. See the ‘eval’ function for examples. 2221 2222 -- Procedure: null-environment version 2223 This procedure returns an environment that contains no variable 2224 bindings, but contains (syntactic) bindings for all the syntactic 2225 keywords. 2226 2227 The effect of assigning to a variable in this environment (such as 2228 ‘let’) is undefined. 2229 2230 -- Procedure: scheme-report-environment version 2231 The VERSION must be an exact non-negative inetger corresponding to 2232 a version of one of the RevisedVERSION Reports on Scheme. The 2233 procedure returns an environment that contains exactly the set of 2234 bindings specified in the corresponding report. 2235 2236 This implementation supports VERSION that is 4 or 5. 2237 2238 The effect of assigning to a variable in this environment (such as 2239 ‘car’) is undefined. 2240 2241 -- Procedure: interaction-environment 2242 This procedure return an environment that contains 2243 implementation-defined bindings, as well as top-level user 2244 bindings. 2245 2246 -- Procedure: environment-bound? environment symbol 2247 Return true ‘#t’ if there is a binding for SYMBOL in ENVIRONMENT; 2248 otherwise returns ‘#f’. 2249 2250 -- Procedure: environment-fold environment proc init 2251 Call PROC for each key in the ENVIRONMENT, which may be any 2252 argument to ‘eval’, such as ‘(interaction-environment)’ or a call 2253 to the ‘environment’ procedure. The PROC is called with two 2254 arguments: The binding’s key, and an accumulator value. The INIT 2255 is the initial accumulator value; the result returned by PROC is 2256 used for subsequent accumulator values. The value returned by 2257 ‘environment-fold’ is the final acumulator value. 2258 2259 A key is normally a symbol, but can also be a ‘KeyPair’ object (a 2260 pair of a symbol and a property symbol used to implement Common 2261 Lisp-style property lists). 2262 (environment-fold (environment '(scheme write)) cons '()) 2263 ⇒ (display write-shared write write-simple) 2264 To get all the predefined bindings use ‘(environment '(kawa 2265 base))’. 2266 2267 -- Syntax: fluid-let ((variable init) ...) body ... 2268 Evaluate the INIT expressions. Then modify the dynamic bindings 2269 for the VARIABLES to the values of the INIT expressions, and 2270 evaluate the BODY expressions. Return the result of the last 2271 expression in BODY. Before returning, restore the original 2272 bindings. The temporary bindings are only visible in the current 2273 thread, and its descendent threads. 2274 2275 -- Procedure: base-uri [node] 2276 If NODE is specified, returns the base-URI property of the NODE. 2277 If the NODE does not have the base-URI property, returns ‘#f’. 2278 (The XQuery version returns the empty sequence in that case.) 2279 2280 In the zero-argument case, returns the "base URI" of the current 2281 context. By default the base URI is the current working directory 2282 (as a URL). While a source file is ‘load’ed, the base URI is 2283 temporarily set to the URL of the document. 2284 2285 -- Procedure: eval expression [environment] 2286 This procedure evaluates EXPRESSION in the environment indicated by 2287 ENVIRONMENT. The default for ENVIRONMENT is the result of 2288 ‘(interaction-environment)’. 2289 2290 (eval ’(* 7 3) (environment '(scheme base))) 2291 ⇒ 21 2292 2293 (let ((f (eval '(lambda (f x) (f x x)) 2294 (null-environment 5)))) 2295 (f + 10)) 2296 ⇒ 20 2297 2298 (eval '(define foo 32) (environment '(scheme base))) 2299 ⇒ error is signaled 2300 2301 -- Procedure: load path [environment] 2302 -- Procedure: load-relative path [environment] 2303 The PATH can be an (absolute) URL or a filename of a source file, 2304 which is read and evaluated line-by-line. The PATH can also be a 2305 fully-qualified class name. (Mostly acts like the ‘-f’ 2306 command-line option, but with different error handling.) Since 2307 ‘load’ is a run-time function it doesn’t know about the enclosing 2308 lexical environment, and the latter can’t know about definitions 2309 introduced by ‘load’. For those reasons it is highly recommended 2310 that you use instead use ‘*note require: require.’ or ‘*note 2311 include: include.’. 2312 2313 Evaluation is done in the specified ENVIRONMENT, which defauls to 2314 result of ‘(interaction-environment)’. 2315 2316 The ‘load-relative’ procedure is like ‘load’, except that PATH is a 2317 URI that is relative to the context’s current base URI. 2318 2319* Menu: 2320 2321* Locations:: 2322* Parameter objects:: 2323 2324 2325File: kawa.info, Node: Locations, Next: Parameter objects, Up: Eval and Environments 2326 232715.1 Locations 2328============== 2329 2330A “location” is a place where a value can be stored. An “lvalue” is an 2331expression that refers to a location. (The name "lvalue" refers to the 2332fact that the left operand of ‘set!’ is an lvalue.) The only kind of 2333lvalue in standard Scheme is a “variable”. Kawa also allows “computed 2334lvalues”. These are procedure calls used in "lvalue context", such as 2335the left operand of ‘set!’. 2336 2337 You can only use procedures that have an associated “setter”. In 2338that case, ‘(set! (f arg ...) value)’ is equivalent to ‘((setter f) arg 2339... value)’ Currently, only a few procedures have associated ‘setter’s, 2340and only builtin procedures written in Java can have ‘setter’s. 2341 2342 For example: 2343 (set! (car x) 10) 2344 is equivalent to: 2345 ((setter car) x 10) 2346 which is equivalent to: 2347 (set-car! x 10) 2348 2349 -- Procedure: setter procedure 2350 Gets the "setter procedure" associated with a "getter procedure". 2351 Equivalent to ‘(procedure-property PROCEDURE 'setter)’. By 2352 convention, a setter procedure takes the same parameters as the 2353 "getter" procedure, plus an extra parameter that is the new value 2354 to be stored in the location specified by the parameters. The 2355 expectation is that following ‘((setter PROC) ARGS ... VALUE)’ then 2356 the value of ‘(PROC ARGS ...)’ will be VALUE. 2357 2358 The ‘setter’ of ‘setter’ can be used to set the ‘setter’ property. 2359 For example the Scheme prologue effectively does the following: 2360 (set! (setter vector-set) vector-set!) 2361 2362 Kawa also gives you access to locations as first-class values: 2363 2364 -- Syntax: location lvalue 2365 Returns a location object for the given LVALUE. You can get its 2366 value (by applying it, as if it were a procedure), and you can set 2367 its value (by using ‘set!’ on the application). The LVALUE can be 2368 a local or global variable, or a procedure call using a procedure 2369 that has a ‘setter’. 2370 (define x 100) 2371 (define lx (location x)) 2372 (set! (lx) (cons 1 2)) ;; set x to (1 . 2) 2373 (lx) ;; returns (1 . 2) 2374 (define lc (location (car x))) 2375 (set! (lc) (+ 10 (lc))) 2376 ;; x is now (11 . 2) 2377 2378 -- Syntax: define-alias variable lvalue 2379 Define VARIABLE as an alias for LVALUE. In other words, makes it 2380 so that ‘(location VARIABLE)’ is equivalent to ‘(location LVALUE)’. 2381 This works both top-level and inside a function. 2382 2383 -- Syntax: define-private-alias variable lvalue 2384 Same as ‘define-alias’, but the VARIABLE is local to the current 2385 module. 2386 2387 Some people might find it helpful to think of a location as a 2388settable “thunk”. Others may find it useful to think of the ‘location’ 2389syntax as similar to the C ‘&’ operator; for the ‘*’ indirection 2390operator, Kawa uses procedure application. 2391 2392 You can use ‘define-alias’ to define a shorter type synonym, similar 2393to Java’s ‘import TypeName’ (single-type-import) declaration: 2394 (define-alias StrBuf java.lang.StringBuffer) 2395 2396 2397File: kawa.info, Node: Parameter objects, Prev: Locations, Up: Eval and Environments 2398 239915.2 Parameter objects 2400====================== 2401 2402A parameter object is a procedure that is bound to a location, and may 2403optionally have a conversion procedure. The procedure accepts zero or 2404one argument. When the procedure is called with zero arguments, the 2405content of the location is returned. On a call with one argument the 2406content of the location is updated with the result of applying the 2407parameter object’s conversion procedure to the argument. 2408 2409 Parameter objects are created with the ‘make-parameter’ procedure 2410which takes one or two arguments. The second argument is a one argument 2411conversion procedure. If only one argument is passed to make-parameter 2412the identity function is used as a conversion procedure. A new location 2413is created and asociated with the parameter object. The initial content 2414of the location is the result of applying the conversion procedure to 2415the first argument of make-parameter. 2416 2417 Note that the conversion procedure can be used for guaranteeing the 2418type of the parameter object’s binding and/or to perform some conversion 2419of the value. 2420 2421 The ‘parameterize’ special form, when given a parameter object and a 2422value, binds the parameter object to a new location for the dynamic 2423extent of its body. The initial content of the location is the result 2424of applying the parameter object’s conversion procedure to the value. 2425The ‘parameterize’ special form behaves analogously to ‘let’ when 2426binding more than one parameter object (that is the order of evaluation 2427is unspecified and the new bindings are only visible in the body of the 2428parameterize special form). 2429 2430 When a new thread is created using ‘future’ or ‘runnable’ then the 2431child thread inherits initial values from its parent. Once the child is 2432running, changing the value in the child does not affect the value in 2433the parent or vice versa. (In the past this was not the case: The child 2434would share a location with the parent except within a ‘parameterize’. 2435This was changed to avoid unsafe and inefficient coupling between 2436threads.) 2437 2438 Note that ‘parameterize’ and ‘fluid-let’ have similar binding and 2439sharing behavior. The difference is that ‘fluid-let’ modifies locations 2440accessed by name, while ‘make-parameter’ and ‘parameterize’ create 2441anonymous locations accessed by calling a parameter procedure. 2442 2443 The R5RS procedures ‘current-input-port’ and ‘current-output-port’ 2444are parameter objects. 2445 2446 -- Procedure: make-parameter init [converter] 2447 2448 Returns a new parameter object which is bound in the global dynamic 2449 environment to a location containing the value returned by the call 2450 ‘(CONVERTER INIT)’. If the conversion procedure converter is not 2451 specified the identity function is used instead. 2452 2453 The parameter object is a procedure which accepts zero or one 2454 argument. When it is called with no argument, the content of the 2455 location bound to this parameter object in the current dynamic 2456 environment is returned. When it is called with one argument, the 2457 content of the location is set to the result of the call 2458 ‘(CONVERTER ARG)’, where ARG is the argument passed to the 2459 parameter object, and an unspecified value is returned. 2460 2461 (define radix 2462 (make-parameter 10)) 2463 2464 (define write-shared 2465 (make-parameter 2466 #f 2467 (lambda (x) 2468 (if (boolean? x) 2469 x 2470 (error "only booleans are accepted by write-shared"))))) 2471 2472 (radix) ⇒ 10 2473 (radix 2) 2474 (radix) ⇒ 2 2475 (write-shared 0) gives an error 2476 2477 (define prompt 2478 (make-parameter 2479 123 2480 (lambda (x) 2481 (if (string? x) 2482 x 2483 (with-output-to-string (lambda () (write x))))))) 2484 2485 (prompt) ⇒ "123" 2486 (prompt ">") 2487 (prompt) ⇒ ">" 2488 2489 -- Syntax: parameterize ((expr1 expr2) ...) BODY 2490 The expressions EXPR1 and EXPR2 are evaluated in an unspecified 2491 order. The value of the EXPR1 expressions must be parameter 2492 objects. For each EXPR1 expression and in an unspecified order, 2493 the local dynamic environment is extended with a binding of the 2494 parameter object EXPR1 to a new location whose content is the 2495 result of the call ‘(CONVERTER VAL)’, where VAL is the value of 2496 EXPR2 and CONVERTER is the conversion procedure of the parameter 2497 object. The resulting dynamic environment is then used for the 2498 evaluation of BODY (which refers to the R5RS grammar nonterminal of 2499 that name). The result(s) of the parameterize form are the 2500 result(s) of the BODY. 2501 2502 (radix) ⇒ 2 2503 (parameterize ((radix 16)) (radix)) ⇒ 16 2504 (radix) ⇒ 2 2505 2506 (define (f n) (number->string n (radix))) 2507 2508 (f 10) ⇒ "1010" 2509 (parameterize ((radix 8)) (f 10)) ⇒ "12" 2510 (parameterize ((radix 8) (prompt (f 10))) (prompt)) ⇒ "1010" 2511 2512 2513File: kawa.info, Node: Debugging, Next: Input-Output, Prev: Eval and Environments, Up: Top 2514 251516 Debugging 2516************ 2517 2518 -- Syntax: trace procedure 2519 Cause PROCEDURE to be "traced", that is debugging output will be 2520 written to the standard error port every time PROCEDURE is called, 2521 with the parameters and return value. 2522 2523 Note that Kawa will normally assume that a procedure defined with 2524 the procedure-defining variant of ‘define’ is constant, and so it 2525 might be inlined: 2526 (define (ff x) (list x x)) 2527 (trace ff) ;; probably won't work 2528 (ff 3) ;; not traced 2529 It works if you specify the ‘--no-inline’ flag to Kawa. 2530 Alternatively, you can use the variable-defining variant of 2531 ‘define’: 2532 #|kawa:1|# (define ff (lambda (x) name: 'ff (list x x))) 2533 #|kawa:2|# (trace ff) ;; works 2534 #|kawa:3|# (ff 3) 2535 call to ff (3) 2536 return from ff => (3 3) 2537 (3 3) 2538 Note the use of the ‘name:’ procedure property to give the 2539 anonymous ‘lambda’ a name. 2540 2541 -- Syntax: untrace procedure 2542 Turn off tracing (debugging output) of PROCEDURE. 2543 2544 -- Procedure: disassemble procedure 2545 Returns a string representation of the disassembled bytecode for 2546 PROCEDURE, when known. 2547 2548 2549File: kawa.info, Node: Input-Output, Next: Types, Prev: Debugging, Up: Top 2550 255117 Input, output, and file handling 2552*********************************** 2553 2554Kawa has a number of useful tools for controlling input and output: 2555 2556 A programmable reader. 2557 2558 A powerful pretty-printer. 2559 2560* Menu: 2561 2562* Named output formats:: 2563* Paths:: Paths - file name, URLs, and URIs 2564* Files:: File System Interface 2565* Reading and writing whole files:: 2566* Ports:: 2567* Format:: Formatted Output (Common-Lisp-style) 2568* Pretty-printing:: 2569* Resources:: 2570 2571 2572File: kawa.info, Node: Named output formats, Next: Paths, Up: Input-Output 2573 257417.1 Named output formats 2575========================= 2576 2577The ‘--output-format’ (or ‘--format’) command-line switch can be used to 2578override the default format for how values are printed on the standard 2579output. This format is used for values printed by the read-eval-print 2580interactive interface. It is also used to control how values are 2581printed when Kawa evaluates a file named on the command line (using the 2582‘-f’ flag or just a script name). (It also affects applications 2583compiled with the ‘--main’ flag.) It currently affects how values are 2584printed by a ‘load’, though that may change. 2585 2586 The default format depends on the current programming language. For 2587Scheme, the default is ‘scheme’ for read-eval-print interaction, and 2588‘ignore’ for files that are loaded. 2589 2590 The formats currently supported include the following: 2591‘scheme’ 2592 Values are printed in a format matching the Scheme programming 2593 language, as if using ‘display’. "Groups" or "elements" are 2594 written as lists. 2595‘readable-scheme’ 2596 Like ‘scheme’, as if using ‘write’: Values are generally printed in 2597 a way that they can be read back by a Scheme reader. For example, 2598 strings have quotation marks, and character values are written like 2599 ‘#\A’. 2600‘elisp’ 2601 Values are printed in a format matching the Emacs Lisp programming 2602 language. Mostly the same as ‘scheme’. 2603‘readable-elisp’ 2604 Like ‘elisp’, but values are generally printed in a way that they 2605 can be read back by an Emacs Lisp reader. For example, strings 2606 have quotation marks, and character values are written like ‘?A’. 2607‘clisp’ 2608‘commonlisp’ 2609 Values are printed in a format matching the Common Lisp programming 2610 language, as if written by ‘princ’. Mostly the same as ‘scheme’. 2611‘readable-clisp’ 2612‘readable-commonlisp’ 2613 Like ‘clisp’, but as if written by ‘prin1’: values are generally 2614 printed in a way that they can be read back by a Common Lisp 2615 reader. For example, strings have quotation marks, and character 2616 values are written like ‘#\A’. 2617‘xml’ 2618‘xhtml’ 2619‘html’ 2620 Values are printed in XML, XHTML, or HTML format. This is 2621 discussed in more detail in *note Formatting XML::. 2622‘cgi’ 2623 The output should follow the CGI standards. I.e. assume that this 2624 script is invoked by a web server as a CGI script/program, and that 2625 the output should start with some response header, followed by the 2626 actual response data. To generate the response headers, use the 2627 ‘response-header’ function. If the ‘Content-type’ response header 2628 has not been specified, and it is required by the CGI standard, 2629 Kawa will attempt to infer an appropriate ‘Content-type’ depending 2630 on the following value. 2631‘ignore’ 2632 Top-level values are ignored, instead of printed. 2633 2634 2635File: kawa.info, Node: Paths, Next: Files, Prev: Named output formats, Up: Input-Output 2636 263717.2 Paths - file name, URLs, and URIs 2638====================================== 2639 2640A “Path” is the name of a file or some other “resource”. The path 2641mechanism provides a layer of abstraction, so you can use the same 2642functions on either a filename or a URL/URI. Functions that in standard 2643Scheme take a filename have been generalized to take a path or a path 2644string, as if using the ‘path’ function below. For example: 2645 (open-input-file "http://www.gnu.org/index.html") 2646 (open-input-file (URI "ftp://ftp.gnu.org/README")) 2647 2648 -- Type: path 2649 A general path, which can be a ‘filename’ or a ‘URI’. It can be 2650 either a ‘filename’ or a ‘URI’. Represented using the abstract 2651 Java class ‘gnu.kawa.io.Path’. 2652 2653 Coercing a value to a ‘Path’ is equivalent to calling the ‘path’ 2654 constructor documented below. 2655 2656 -- Constructor: path arg 2657 Coerces the ARG to a ‘path’. If ARG is already a ‘path’, it is 2658 returned unchanged. If ARG is a ‘java.net.URI’, or a 2659 ‘java.net.URL’ then a ‘URI’ value is returned. If ARG is a 2660 ‘java.io.File’, a ‘filepath’ value is returned. Otherwise, ARG can 2661 be a string. A ‘URI’ value is returned if the string starts with a 2662 URI scheme (such as ‘"http:"’), and a ‘filepath’ value is returned 2663 otherwise. 2664 2665 -- Predicate: path? arg 2666 True if ARG is a ‘path’ - i.e. an instance of a 2667 ‘gnu.kawa.io.Path’. 2668 2669 -- Procedure: current-path [new-value] 2670 With no arguments, returns the default directory of the current 2671 thread as a ‘path’. This is used as the base directory for 2672 relative pathnames. The initial value is that of the ‘user.dir’ 2673 property as returned by ‘(java.lang.System:getProperty 2674 "user.dir")’. 2675 2676 If a NEW-VALUE argument is given, sets the default directory: 2677 (current-path "/opt/myApp/") 2678 A string value is automatically converted to a ‘path’, normally a 2679 ‘filepath’. 2680 2681 Alternatively, you can change the default using a setter: 2682 (set! (current-path) "/opt/myApp/") 2683 2684 Since ‘current-path’ is a *note parameter object: Parameter 2685 objects, you can locally change the value using *note 2686 ‘parameterize’: parameterize-syntax. 2687 2688 -- Type: filepath 2689 The name of a local file. Represented using the Java class 2690 ‘gnu.kawa.io.FilePath’, which is a wrapper around ‘java.io.File’. 2691 2692 -- Predicate: filepath? arg 2693 True if ARG is a ‘filepath’ - i.e. an instance of a 2694 ‘gnu.kawa.io.FilePath’. 2695 2696 -- Type: URI 2697 A Uniform Resource Indicator, which is a generalization of the more 2698 familiar URL. The general format is specified by RFC 2396: Uniform 2699 Resource Identifiers (URI): Generic Syntax 2700 (http://www.ietf.org/rfc/rfc2396.txt). Represented using the Java 2701 class ‘gnu.kawa.io.URIPath’, which is a wrapper around 2702 ‘java.net.URI’. A URI can be a URL, or it be a relative URI. 2703 2704 -- Predicate: URI? arg 2705 True if ARG is a ‘URI’ - i.e. an instance of a 2706 ‘gnu.kawa.io.URIPath’. 2707 2708 -- Type: URL 2709 A Uniform Resource Locator - a subtype of ‘URI’. Represented using 2710 the Java class ‘gnu.kawa.io.URLPath’, which is a wrapper around a 2711 ‘java.net.URL’, in addition to extending ‘gnu.kawa.io.URIPath’. 2712 271317.2.1 Extracting Path components 2714--------------------------------- 2715 2716 -- Procedure: path-scheme arg 2717 Returns the “URI scheme” of ARG (coerced to a ‘path’) if it is 2718 defined, or ‘#f’ otherwise. The URI scheme of a ‘filepath’ is 2719 ‘"file"’ if the ‘filepath’ is absolute, and ‘#f’ otherwise. 2720 (path-scheme "http://gnu.org/") ⇒ "http" 2721 2722 -- Procedure: path-authority arg 2723 Returns the authority part of ARG (coerced to a ‘path’) if it is 2724 defined, or ‘#f’ otherwise. The “authority” is usually the 2725 hostname, but may also include user-info or a port-number. 2726 2727 (path-authority "http://me@localhost:8000/home") ⇒ "me@localhost:8000" 2728 2729 -- Procedure: path-host arg 2730 Returns the name name part of ARG (coerced to a ‘path’) if it is 2731 defined, or ‘#f’ otherwise. 2732 2733 (path-host "http://me@localhost:8000/home") ⇒ "localhost" 2734 2735 -- Procedure: path-user-info arg 2736 Returns the “user info” of ARG (coerced to a ‘path’) if it is 2737 specified, or ‘#f’ otherwise. 2738 2739 (path-host "http://me@localhost:8000/home") ⇒ "me" 2740 2741 -- Procedure: path-port arg 2742 Returns the port number of ARG (coerced to a ‘path’) if it is 2743 specified, or ‘-1’ otherwise. Even if there is a default port 2744 associated with a URI scheme (such as 80 for ‘http’), the value -1 2745 is returned unless the port number is _explictly_ specified. 2746 2747 (path-host "http://me@localhost:8000/home") ⇒ 8000 2748 (path-host "http://me@localhost/home") ⇒ -1 2749 2750 -- Procedure: path-file arg 2751 Returns the “path component” of the ARG (coerced to a ‘path’). 2752 (The name ‘path-path’ might be more logical, but it is obviously a 2753 bit awkward.) The path component of a file name is the file name 2754 itself. For a URI, it is the main hierarchical part of the URI, 2755 without schema, authority, query, or fragment. 2756 (path-file "http://gnu.org/home/me.html?add-bug#body") ⇒ "/home/me.html" 2757 2758 -- Procedure: path-directory arg 2759 If ARG (coerced to a ‘path’) is directory, return ARG; otherwise 2760 return the “parent” path, without the final component. 2761 (path-directory "http://gnu.org/home/me/index.html#body") 2762 ⇒ (path "http://gnu.org/home/me/") 2763 (path-directory "http://gnu.org/home/me/") 2764 ⇒ (path "http://gnu.org/home/me/") 2765 ‘(path-directory "./dir")’ ‘⇒’ ‘(path "./dir")’ if ‘dir’ is a 2766 directory, and ‘(path ".")’ otherwise. 2767 2768 -- Procedure: path-parent arg 2769 Returns the “parent directory” of ARG (coerced to a ‘path’). If 2770 ARG is not a directory, same as ‘path-directory ARG’. 2771 (path-parent "a/b/c") ⇒ (path "a/b") 2772 (path-parent "file:/a/b/c") ⇒ (path "file:/a/b/c") 2773 (path-parent "file:/a/b/c/") ⇒ (path "file:/a/b/") 2774 2775 -- Procedure: path-last arg 2776 The last component of path component of ARG (coerced to a ‘path’). 2777 Returns a substring of ‘(path-file ARG)’. If that string ends with 2778 ‘/’ or the path separator, that last character is ignored. Returns 2779 the tail of the path-string, following the last (non-final) ‘/’ or 2780 path separator. 2781 (path-last "http:/a/b/c") ⇒ "c" 2782 (path-last "http:/a/b/c/") ⇒ "c" 2783 (path-last "a/b/c") ⇒ "c" 2784 2785 -- Procedure: path-extension arg 2786 Returns the “extension” of the ARG (coerced to a ‘path’). 2787 (path-extension "http://gnu.org/home/me.html?add-bug#body") ⇒ "html" 2788 (path-extension "/home/.init") ⇒ #f 2789 2790 -- Procedure: path-query arg 2791 Returns the query part of ARG (coerced to a ‘path’) if it is 2792 defined, or ‘#f’ otherwise. The query part of a URI is the part 2793 after ‘?’. 2794 (path-query "http://gnu.org/home?add-bug") ⇒ "add-bug" 2795 2796 -- Procedure: path-fragment arg 2797 Returns the fragment part of ARG (coerced to a ‘path’) if it is 2798 defined, or ‘#f’ otherwise. The fragment of a URI is the part of 2799 after ‘#’. 2800 (path-query "http://gnu.org/home#top") ⇒ "top" 2801 2802 -- Procedure: resolve-uri uri base 2803 Returns a URI unchanged if it is an absolute URI. Otherwise 2804 resolves it against a base URI BASE, which is normally (though not 2805 always) absolute. 2806 2807 This uses the algorithm specifyed by RFC-3986 (assuming BASE is 2808 absolute), unlike the obsolete RFC-2396 algorithm used by 2809 ‘java.net.URI.resolve’. 2810 2811 2812File: kawa.info, Node: Files, Next: Reading and writing whole files, Prev: Paths, Up: Input-Output 2813 281417.3 File System Interface 2815========================== 2816 2817 -- Procedure: file-exists? filename 2818 Returns true iff the file named FILENAME actually exists. This 2819 function is defined on arbitrary ‘path’ values: for URI values we 2820 open a ‘URLConnection’ and invoke ‘getLastModified()’. 2821 2822 -- Procedure: file-directory? filename 2823 Returns true iff the file named FILENAME actually exists and is a 2824 directory. This function is defined on arbitrary ‘path’ values; 2825 the default implementation for non-file objects is to return ‘#t’ 2826 iff the path string ends with the character ‘/’. 2827 2828 -- Procedure: file-readable? filename 2829 Returns true iff the file named FILENAME actually exists and can be 2830 read from. 2831 2832 -- Procedure: file-writable? filename 2833 Returns true iff the file named FILENAME actually exists and can be 2834 writen to. (Undefined if the FILENAME does not exist, but the file 2835 can be created in the directory.) 2836 2837 -- Procedure: delete-file filename 2838 Delete the file named FILENAME. On failure, throws an exception. 2839 2840 -- Procedure: rename-file oldname newname 2841 Renames the file named OLDNAME to NEWNAME. 2842 2843 -- Procedure: copy-file oldname newname-from path-to 2844 Copy the file named OLDNAME to NEWNAME. The return value is 2845 unspecified. 2846 2847 -- Procedure: create-directory dirname 2848 Create a new directory named DIRNAME. Unspecified what happens on 2849 error (such as exiting file with the same name). (Currently 2850 returns ‘#f’ on error, but may change to be more compatible with 2851 scsh.) 2852 2853 -- Procedure: system-tmpdir 2854 Return the name of the default directory for temporary files. 2855 2856 -- Procedure: make-temporary-file [format] 2857 Return a file with a name that does not match any existing file. 2858 Use FORMAT (which defaults to ‘"kawa~d.tmp"’) to generate a unique 2859 filename in ‘(system-tmpdir)’. The implementation is safe from 2860 race conditions, and the returned filename will not be reused by 2861 this JVM. 2862 2863 2864File: kawa.info, Node: Reading and writing whole files, Next: Ports, Prev: Files, Up: Input-Output 2865 286617.4 Reading and writing whole files 2867==================================== 2868 2869The following procedures and syntax allow you to read and write the 2870entire contents of a file, without iterating using a port. 2871 287217.4.1 Reading a file 2873--------------------- 2874 2875For reading the contents of a file in a single operation, you can use 2876the following syntax: 2877 2878 ‘&<{’NAMED-LITERAL-PART+‘}’ 2879 2880 This is equivalent to using the ‘path-data’ function (defined below): 2881 ‘(path-data’ ‘&{’NAMED-LITERAL-PART+‘})’ 2882 2883 For example: 2884 (define dir "/home/me/") 2885 (define help-message &<{&[dir]HELP}) 2886 This binds ‘help-message’ to the contents of the file named ‘HELP’ in 2887the ‘dir’ directory. 2888 288917.4.2 Blobs 2890------------ 2891 2892The content of a file is, in general, a sequence of uninterpreted bytes. 2893Often these bytes represent text in a locale-dependent encoding, but we 2894don’t always know this. Sometimes they’re images, or videos, or 2895word-processor documents. A filename extension or a “magic number” in 2896the file can give you hints, but not certainty as to the type of the 2897data. 2898 2899 A “blob (http://en.wikipedia.org/wiki/Binary_large_object)” is a raw 2900uninterpreted sequence of bytes. It is a ‘bytevector’ that can be 2901automatically converted to other types as needed, specifically to a 2902string or a bytevector. 2903 2904 The ‘&<{..}’ returns a blob. For example, assume the file ‘README’ 2905contains (bytes representing) the text ‘"Check doc directory.\n"’. 2906Then: 2907 #|kawa:1|# (define readme &<{README})) 2908 |kawa:2|# readme:class 2909 class gnu.lists.Blob 2910 #|kawa:3|# (write (->string readme)) 2911 "Check doc directory.\n" 2912 #|kawa:4|# (write (->bytevector readme)) 2913 #u8(67 104 101 99 107 32 100 111 99 32 100 105 114 101 99 116 111 114 121 46 10) 2914 #|kawa:5|# (->bytevector readme):class 2915 class gnu.lists.U8Vector 2916 291717.4.3 Writing to a file 2918------------------------ 2919 2920The ‘&<{..}’ syntax can be used with ‘set!’ to replace the contents of a 2921file: 2922 (set! &<{README} "Check example.com\n") 2923 2924 The new contents must be blob-compatible - i.e. a bytevector or a 2925string. 2926 2927 If you dislike using ‘<’ as an output operator, you can instead using 2928the ‘&>{..}’ operation, which evaluates to a function whose single 2929argument is the new value: 2930 (&>{README} "Check example.com\n") 2931 In general: 2932 &>{NAMED-LITERAL-PART+} 2933 is equivalent to: 2934 (lambda (new-contents) 2935 (set! &<{NAMED-LITERAL-PART+} new-contents)) 2936 2937 You can use ‘&>>’ to append more data to a file: 2938 2939 (&>>{README} "or check example2.com\n") 2940 294117.4.4 Functions 2942---------------- 2943 2944 -- Procedure: path-data path 2945 Reads the contents of the file specified by PATH, where PATH can be 2946 a *note path: Paths. object, or anything that can be converted to a 2947 ‘Path’, including a filename string or a URL. returning the result 2948 as a blob. The result is a _blob_, which is a kind of bytevector 2949 than can be auto-converted to a string or bytevecor as required. 2950 2951 The function ‘path-data’ has a setter, which replaces the contents 2952 with new contents: 2953 (set! &<{file-name} new-contents) 2954 2955 -- Procedure: path-bytes path 2956 Reads the contents of the file specified by PATH, as with the 2957 ‘path-data’ function, but the result is a plain bytevector, rather 2958 than a blob. This functtion also has a setter, which you can use 2959 to replace the file-contents by new bytevector-valued data. 2960 2961 2962File: kawa.info, Node: Ports, Next: Format, Prev: Reading and writing whole files, Up: Input-Output 2963 296417.5 Ports 2965========== 2966 2967Ports represent input and output devices. An input port is a Scheme 2968object that can deliver data upon command, while an output port is a 2969Scheme object that can accept data. 2970 2971 Different “port types” operate on different data: 2972 • A “textual port” supports reading or writing of individual 2973 characters from or to a backing store containing characters using 2974 ‘read-char’ and ‘write-char’ below, and it supports operations 2975 defined in terms of characters, such as ‘read’ and ‘write’. 2976 • A “binary port” supports reading or writing of individual bytes 2977 from or to a backing store containing bytes using ‘read-u8’ and 2978 ‘write-u8’ below, as well as operations defined in terms of bytes 2979 (integers in the range 0 to 255). 2980 2981 All Kawa binary ports created by procedures documented here are 2982 also textual ports. Thus you can either read/write bytes as 2983 described above, or read/write characters whose scalar value is in 2984 the range 0 to 255 (i.e. the Latin-1 character set), using 2985 ‘read-char’ and ‘write-char’. 2986 2987 A native binary port is a ‘java.io.InputStream’ or 2988 ‘java.io.OutputStream’ instance. These are not textual ports. You 2989 can use methods ‘read-u8’ and ‘write-u8’, but not ‘read-char’ and 2990 ‘write-char’ on native binary ports. (The functions ‘input-port?’, 2991 ‘output-port?’, ‘binary-port?’, and ‘port?’ all currently return 2992 false on native binary ports, but that may change.) 2993 2994 -- Procedure: call-with-port port proc 2995 The ‘call-with-port’ procedure calls PROC with port as an argument. 2996 If PROC returns, then the port is closed automatically and the 2997 values yielded by the proc are returned. 2998 2999 If PROC does not return, then the port must not be closed 3000 automatically unless it is possible to prove that the port will 3001 never again be used for a read or write operation. 3002 3003 As a Kawa extension, PORT may be any object that implements 3004 ‘java.io.Closeable’. It is an error if PROC does not accept one 3005 argument. 3006 3007 -- Procedure: call-with-input-file path proc 3008 -- Procedure: call-with-output-file path proc 3009 These procedures obtain a textual port obtained by opening the 3010 named file for input or output as if by ‘open-input-file’ or 3011 ‘open-output-file’. The port and PROC are then passed to a 3012 procedure equivalent to ‘call-with-port’. 3013 3014 It is an error if PROC does not accept one argument. 3015 3016 -- Procedure: input-port? obj 3017 -- Procedure: output-port? obj 3018 -- Procedure: textual-port? obj 3019 -- Procedure: binary-port? obj 3020 -- Procedure: port? obj 3021 These procedures return ‘#t’ if obj is an input port, output port, 3022 textual port, binary port, or any kind of port, respectively. 3023 Otherwise they return ‘#f’. 3024 3025 These procedures currently return ‘#f’ on a native Java streams 3026 (‘java.io.InputStream’ or ‘java.io.OutputStream’), a native reader 3027 (a ‘java.io.Reader’ that is not an ‘gnu.mapping.Inport’), or a 3028 native writer (a ‘java.io.Writer’ that is not an 3029 ‘gnu.mapping.Outport’). This may change if conversions between 3030 native ports and Scheme ports becomes more seamless. 3031 3032 -- Procedure: input-port-open? port 3033 -- Procedure: output-port-open? port 3034 Returns ‘#t’ if PORT is still open and capable of performing input 3035 or output, respectively, and ‘#f’ otherwise. (Not supported for 3036 native binary ports - i.e. ‘java.io.InputStteam’ or 3037 ‘java.io.OutputStream’.) 3038 3039 -- Procedure: current-input-port 3040 -- Procedure: current-output-port 3041 -- Procedure: current-error-port 3042 Returns the current default input port, output port, or error port 3043 (an output port), respectively. (The error port is the port to 3044 which errors and warnings should be sent - the “standard error” in 3045 Unix and C terminology.) These procedures are *note parameter 3046 objects: Parameter objects, which can be overridden with *note 3047 ‘parameterize’: parameterize-syntax. 3048 3049 The initial bindings for ‘(current-output-port)’ and 3050 ‘(current-error-port)’ are hybrid textual/binary ports that wrap 3051 the values of the corresponding ‘java.lang.System’ fields ‘out’, 3052 and ‘err’. The latter, in turn are bound to the standard output 3053 and error streams of the JVM process. This means you can write 3054 binary data to standard output using ‘write-bytevector’ and 3055 ‘write-u8’. 3056 3057 The initial value ‘(current-input-port)’ similarly is a textual 3058 port that wraps the ‘java.lang.System’ field ‘in’, which is bound 3059 to the standard input stream of the JVM process. It is a _hybrid_ 3060 textual/binary port only if there is no console (as determined by 3061 ‘(java.lang.System:console)’ returning ‘#!null’) - i.e. if 3062 standard input is not a tty. 3063 3064 Here is an example that copies standard input to standard output: 3065 (let* ((in (current-input-port)) 3066 (out (current-output-port)) 3067 (blen ::int 2048) 3068 (buf (make-bytevector blen))) 3069 (let loop () 3070 (define n (read-bytevector! buf in)) 3071 (cond ((not (eof-object? n)) 3072 (write-bytevector buf out 0 n) 3073 (loop))))) 3074 3075 -- Procedure: with-input-from-file path thunk 3076 -- Procedure: with-output-to-file path thunk 3077 The file is opened for input or output as if by ‘open-input-file’ 3078 or ‘open-output-file’, and the new port is made to be the value 3079 returned by ‘current-input-port’ or ‘current-output-port’ (as used 3080 by ‘(read)’, ‘(write OBJ)’, and so forth). The thunk is then 3081 called with no arguments. When the THUNK returns, the port is 3082 closed and the previous default is restored. It is an error if 3083 THUNK does not accept zero arguments. Both procedures return the 3084 values yielded by THUNK. If an escape procedure is used to escape 3085 from the continuation of these procedures, they behave exactly as 3086 if the current input or output port had been bound dynamically with 3087 ‘parameterize’. 3088 3089 -- Procedure: open-input-file path 3090 -- Procedure: open-binary-input-file path 3091 Takes a PATH naming an existing file and returns a textual input 3092 port or binary input port that is capable of delivering data from 3093 the file. 3094 3095 The procedure ‘open-input-file’ checks the fluid variable *note 3096 ‘port-char-encoding’: port-char-encoding. to determine how bytes 3097 are decoded into characters. The procedure 3098 ‘open-binary-input-file’ is equivalent to calling ‘open-input-file’ 3099 with ‘port-char-encoding’ set to ‘#f’. 3100 3101 -- Procedure: open-output-file path 3102 -- Procedure: open-binary-output-file path 3103 Takes a PATH naming an output file to be created and returns 3104 respectively a textual output port or binary output port that is 3105 capable of writing data to a new file by that name. If a file with 3106 the given name already exists, the effect is unspecified. 3107 3108 The procedure ‘open-output-file’ checks the fluid variable *note 3109 ‘port-char-encoding’: port-char-encoding. to determine how 3110 characters are encoded as bytes. The procedure 3111 ‘open-binary-output-file’ is equivalent to calling 3112 ‘open-output-file’ with ‘port-char-encoding’ set to ‘#f’. 3113 3114 -- Procedure: close-port port 3115 -- Procedure: close-input-port port 3116 -- Procedure: close-output-port port 3117 Closes the resource associated with PORT, rendering the port 3118 incapable of delivering or accepting data. It is an error to apply 3119 the last two procedures to a port which is not an input or output 3120 port, respectively. (Specifically, ‘close-input-port’ requires a 3121 ‘java.io.Reader’, while ‘close-output-port’ requires a 3122 ‘java.io.Writer’. In contrast ‘close-port’ accepts any object 3123 whose class implements ‘java.io.Closeable’.) 3124 3125 These routines have no effect if the port has already been closed. 3126 312717.5.1 String and bytevector ports 3128---------------------------------- 3129 3130 -- Procedure: open-input-string string 3131 Takes a string and returns a text input port that delivers 3132 characters from the string. The port can be closed by 3133 ‘close-input-port’, though its storage will be reclaimed by the 3134 garbage collector if it becomes inaccessible. 3135 3136 (define p 3137 (open-input-string "(a . (b c . ())) 34")) 3138 3139 (input-port? p) ⇒ #t 3140 (read p) ⇒ (a b c) 3141 (read p) ⇒ 34 3142 (eof-object? (peek-char p)) ⇒ #t 3143 3144 -- Procedure: open-output-string 3145 Returns an textual output port that will accumulate characters for 3146 retrieval by ‘get-output-string’. The port can be closed by the 3147 procedure ‘close-output-port’, though its storage will be reclaimed 3148 by the garbage collector if it becomes inaccessible. 3149 (let ((q (open-output-string)) 3150 (x '(a b c))) 3151 (write (car x) q) 3152 (write (cdr x) q) 3153 (get-output-string q)) ⇒ "a(b c)" 3154 3155 -- Procedure: get-output-string output-port 3156 Given an output port created by ‘open-output-string’, returns a 3157 string consisting of the characters that have been output to the 3158 port so far in the order they were output. If the result string is 3159 modified, the effect is unspecified. 3160 3161 (parameterize 3162 ((current-output-port (open-output-string))) 3163 (display "piece") 3164 (display " by piece ") 3165 (display "by piece.") 3166 (newline) 3167 (get-output-string (current-output-port))) 3168 ⇒ "piece by piece by piece.\n" 3169 3170 -- Procedure: call-with-input-string string proc 3171 Create an input port that gets its data from STRING, call PROC with 3172 that port as its one argument, and return the result from the call 3173 of PROC 3174 3175 -- Procedure: call-with-output-string proc 3176 Create an output port that writes its data to a STRING, and call 3177 PROC with that port as its one argument. Return a string 3178 consisting of the data written to the port. 3179 3180 -- Procedure: open-input-bytevector bytevector 3181 Takes a bytevector and returns a binary input port that delivers 3182 bytes from the bytevector. 3183 3184 -- Procedure: open-output-bytevector 3185 Returns a binary output port that will accumulate bytes for 3186 retrieval by ‘get-output-bytevector’. 3187 3188 -- Procedure: get-output-bytevector port 3189 Returns a bytevector consisting of the bytes that have been output 3190 to the port so far in the order they were output. It is an error 3191 if PORT was not created with ‘open-output-bytevector’. 3192 319317.5.2 Input 3194------------ 3195 3196If PORT is omitted from any input procedure, it defaults to the value 3197returned by ‘(current-input-port)’. It is an error to attempt an input 3198operation on a closed port. 3199 3200 -- Procedure: read [port] 3201 The ‘read’ procedure converts external representations of Scheme 3202 objects into the objects themselves. That is, it is a parser for 3203 the non-terminal DATUM. It returns the next object parsable from 3204 the given textual input port, updating port to point to the first 3205 character past the end of the external representation of the 3206 object. 3207 3208 If an end of file is encountered in the input before any characters 3209 are found that can begin an object, then an end-of-file object is 3210 returned. The port remains open, and further attempts to read will 3211 also return an end-of-file object. If an end of file is 3212 encountered after the beginning of an object’s external 3213 representation, but the external representation is incomplete and 3214 therefore not parsable, an error that satisfies ‘read-error?’ is 3215 signaled. 3216 3217 -- Procedure: read-char [port] 3218 Returns the next character available from the textual input PORT, 3219 updating the port to point to the following character. If no more 3220 characters are available, an end-of-file value is returned. 3221 3222 The result type is ‘character-or-eof’. 3223 3224 -- Procedure: peek-char [port] 3225 Returns the next character available from the textual input PORT, 3226 but _without_ updating the port to point to the following 3227 character. If no more characters are available, an end-of-file 3228 value is returned. 3229 3230 The result type is ‘character-or-eof’. 3231 3232 _Note:_ The value returned by a call to ‘peek-char’ is the same as 3233 the value that would have been returned by a call to ‘read-char’ 3234 with the same PORT. The only difference is that the very next call 3235 to ‘read-char’ or ‘peek-char’ on that PORT will return the value 3236 returned by the preceding call to ‘peek-char’. In particular, a 3237 call to ‘peek-char’ on an interactive port will hang waiting for 3238 input whenever a call to ‘read-char’ would have hung. 3239 3240 -- Procedure: read-line [port [handle-newline]] 3241 Reads a line of input from the textual input PORT. The 3242 HANDLE-NEWLINE parameter determines what is done with terminating 3243 end-of-line delimiter. The default, ‘'trim’, ignores the 3244 delimiter; ‘'peek’ leaves the delimiter in the input stream; 3245 ‘'concat’ appends the delimiter to the returned value; and ‘'split’ 3246 returns the delimiter as a second value. You can use the last 3247 three options to tell if the string was terminated by end-or-line 3248 or by end-of-file. If an end of file is encountered before any end 3249 of line is read, but some characters have been read, a string 3250 containing those characters is returned. (In this case, ‘'trim’, 3251 ‘'peek’, and ‘'concat’ have the same result and effect. The 3252 ‘'split’ case returns two values: The characters read, and the 3253 delimiter is an empty string.) If an end of file is encountered 3254 before any characters are read, an end-of-file object is returned. 3255 For the purpose of this procedure, an end of line consists of 3256 either a linefeed character, a carriage return character, or a 3257 sequence of a carriage return character followed by a linefeed 3258 character. 3259 3260 -- Procedure: eof-object? obj 3261 Returns ‘#t’ if OBJ is an end-of-file object, otherwise returns 3262 ‘#f’. 3263 3264 ‘Performance note’: If OBJ has type ‘character-or-eof’, this is 3265 compiled as an ‘int’ comparison with -1. 3266 3267 -- Procedure: eof-object 3268 Returns an end-of-file object. 3269 3270 -- Procedure: char-ready? [port] 3271 Returns ‘#t’ if a character is ready on the textual input PORT and 3272 returns ‘#f’ otherwise. If char-ready returns ‘#t’ then the next 3273 ‘read-char’ operation on the given PORT is guaranteed not to hang. 3274 If the port is at end of file then ‘char-ready?’ returns ‘#t’. 3275 3276 _Rationale:_ The ‘char-ready?’ procedure exists to make it possible 3277 for a program to accept characters from interactive ports without 3278 getting stuck waiting for input. Any input editors as- sociated 3279 with such ports must ensure that characters whose existence has 3280 been asserted by ‘char-ready?’ cannot be removed from the input. 3281 If ‘char-ready?’ were to return ‘#f’ at end of file, a port at 3282 end-of-file would be indistinguishable from an interactive port 3283 that has no ready characters. 3284 3285 -- Procedure: read-string k [port] 3286 Reads the next K characters, or as many as are available before the 3287 end of file, from the textual input PORT into a newly allocated 3288 string in left-to-right order and returns the string. If no 3289 characters are available before the end of file, an end-of-file 3290 object is returned. 3291 3292 -- Procedure: read-u8 [port] 3293 Returns the next byte available from the binary input PORT, 3294 updating the PORT to point to the following byte. If no more bytes 3295 are available, an end-of-file object is returned. 3296 3297 -- Procedure: peek-u8 [port] 3298 Returns the next byte available from the binary input PORT, but 3299 _without_ updating the PORT to point to the following byte. If no 3300 more bytes are available, an end-of-file object is returned. 3301 3302 -- Procedure: u8-ready? [port] 3303 Returns ‘#t’ if a byte is ready on the binary input PORT and 3304 returns ‘#f’ otherwise. If ‘u8-ready?’ returns ‘#t’ then the next 3305 ‘read-u8’ operation on the given port is guaranteed not to hang. 3306 If the port is at end of file then ‘u8-ready?’ returns ‘#t’. 3307 3308 -- Procedure: read-bytevector k [port] 3309 Reads the next K bytes, or as many as are available before the end 3310 of file, from the binary input PORT into a newly allocated 3311 bytevector in left-to-right order and returns the bytevector. If 3312 no bytes are available before the end of file, an end-of-file 3313 object is returned. 3314 3315 -- Procedure: read-bytevector! bytevector [port [start [end]]] 3316 Reads the next END − START bytes, or as many as are available 3317 before the end of file, from the binary input PORT into BYTEVECTOR 3318 in left-to-right order beginning at the START position. If END is 3319 not supplied, reads until the end of BYTEVECTOR has been reached. 3320 If START is not supplied, reads beginning at position 0. Returns 3321 the number of bytes read. If no bytes are available, an 3322 end-of-file object is returned. 3323 332417.5.3 Output 3325------------- 3326 3327If PORT is omitted from any output procedure, it defaults to the value 3328returned by ‘(current-output-port)’. It is an error to attempt an 3329output operation on a closed port. 3330 3331 The return type of these methods is ‘void’. 3332 3333 -- Procedure: write obj [port] 3334 Writes a representation of OBJ to the given textual output PORT. 3335 Strings that appear in the written representation are enclosed in 3336 quotation marks, and within those strings backslash and quotation 3337 mark characters are escaped by backslashes. Symbols that contain 3338 non-ASCII characters are escaped with vertical lines. Character 3339 objects are written using the ‘#\’ notation. 3340 3341 If OBJ contains cycles which would cause an infinite loop using the 3342 normal written representation, then at least the objects that form 3343 part of the cycle must be represented using *note datum labels::. 3344 Datum labels must not be used if there are no cycles. 3345 3346 -- Procedure: write-shared obj [port] 3347 The ‘write-shared’ procedure is the same as ‘write’, except that 3348 shared structure must be represented using datum labels for all 3349 pairs and vectors that appear more than once in the output. 3350 3351 -- Procedure: write-simple obj [port] 3352 The ‘write-simple’ procedure is the same as ‘write’, except that 3353 shared structure is never represented using datum labels. This can 3354 cause write-simple not to terminate if OBJ contains circular 3355 structure. 3356 3357 -- Procedure: display obj [port] 3358 Writes a representation of OBJ to the given textual output port. 3359 Strings that appear in the written representation are output as if 3360 by ‘write-string’ instead of by ‘write’. Symbols are not escaped. 3361 Character objects appear in the representation as if written by 3362 ‘write-char’ instead of by ‘write’. The ‘display’ representation 3363 of other objects is unspecified. 3364 3365 -- Procedure: newline [port] 3366 Writes an end of line to textual output PORT. This is done using 3367 the ‘println’ method of the Java class ‘java.io.PrintWriter’. 3368 3369 -- Procedure: write-char char [port] 3370 Writes the character CHAR (not an external representation of the 3371 character) to the given textual output PORT. 3372 3373 -- Procedure: write-string string [port [start [end]]] 3374 Writes the characters of STRING from START to END in left-to-right 3375 order to the textual output PORT. 3376 3377 -- Procedure: write-u8 byte [port] 3378 Writes the BYTE to the given binary output port. 3379 3380 -- Procedure: write-bytevector bytevector [port [start [end]]] 3381 Writes the bytes of BYTEVECTOR from START to END in left-to-right 3382 order to the binary output PORT. 3383 3384 -- Procedure: flush-output-port [port] 3385 -- Procedure: force-output [port] 3386 Forces any pending output on PORT to be delivered to the output 3387 file or device and returns an unspecified value. If the PORT 3388 argument is omitted it defaults to the value returned by 3389 ‘(current-output-port)’. (The name ‘force-output’ is older, while 3390 R6RS added ‘flush-output-port’. They have the same effect.) 3391 339217.5.4 Prompts for interactive consoles (REPLs) 3393----------------------------------------------- 3394 3395When an interactive input port is used for a read-eval-print-loop (REPL 3396or console) it is traditional for the REPL to print a short “prompt” 3397string to signal that the user is expected to type an expression. These 3398prompt strings can be customized. 3399 3400 -- Variable: input-prompt1 3401 -- Variable: input-prompt2 3402 These are fluid variable whose values are string templates with 3403 placeholders similar to ‘printf’-style format. The placeholders 3404 are expanded (depending on the current state), and the resulting 3405 string printed in front of the input line. 3406 3407 The ‘input-prompt1’ is used normally. For multi-line input 3408 commands (for example if the first line is incomplete), 3409 ‘input-prompt1’ is used for the first line of each command, while 3410 ‘input-prompt2’ is used for subsequent “continuation” lines. 3411 3412 The following placeholders are handled: 3413 ‘%%’ 3414 A literal ‘%’. 3415 ‘%N’ 3416 The current line number. This is ‘(+ 1 (port-line PORT))’. 3417 ‘%’N‘P’C 3418 Insert padding at this possion, repeating the following 3419 character ‘C’ as needed to bring the total number of columns 3420 of the prompt to that specified by the digits ‘N’. 3421 ‘%P’C 3422 Same as ‘%NPC’, but ‘N’ defaults to the number of columns in 3423 the initial prompt from the expansion of ‘input-prompt1’. 3424 This is only meaningful when expanding ‘input-prompt2’ for 3425 continuation lines. 3426 ‘%’‘{’HIDDEN‘%}’ 3427 Same as HIDDEN, but the characters of HIDDEN are assumed to 3428 have zero visible width. Can be used for ANSI escape 3429 sequences (https://en.wikipedia.org/wiki/ANSI_escape_code) to 3430 change color or style: 3431 (set! input-prompt1 "%{\e[48;5;51m%}{Kawa:%N} %{\e[0m%}") 3432 The above changes both the text and the background color (to a 3433 pale blue). 3434 ‘%H’CD 3435 If running under DomTerm, use the characters C and D as a 3436 clickable mini-button to hide/show (fold) the command and its 3437 output. (When output is visible C is displayed; clicking on 3438 it hides the output. When output is hidden D is displayed; 3439 clicking on it shows the output.) Ignored if not running 3440 under DomTerm. 3441 ‘%M’ 3442 Insert a “message” string. Not normally used by Kawa, but 3443 supported by JLine. 3444 3445 These variables can be initialized by the command-line arguments 3446 ‘console:prompt1=PROMPT1’ and ‘console:prompt2=PROMPT2’, 3447 respectively. If these are not specified, languages-specific 3448 defaults are used. For example for Scheme the default value of 3449 ‘input-prompt1’ is ‘"#|%H▼▶kawa:%N|# "’ and ‘input-prompt2’ is 3450 ‘"#|%P.%N| "’. These have the form of Scheme comments, to make it 3451 easier to cut-and-paste. 3452 3453 If ‘input-prompt1’ (respectively ‘input-prompt2’) does not contain 3454 an escape sequence (either ‘"%{’ or the escape character ‘"\e"’) 3455 then ANSI escape sequences are added to to highlight the prompt. 3456 (Under DomTerm this sets the ‘prompt’ style, which can be 3457 customised with CSS but defaults to a light green background; if 3458 using JLine the background is set to light green.) 3459 3460 For greater flexibility, you can also set a prompter procedure. 3461 3462 -- Procedure: set-input-port-prompter! port prompter 3463 Set the prompt procedure associated with PORT to PROMPTER, which 3464 must be a one-argument procedure taking an input port, and 3465 returning a string. The procedure is called before reading the 3466 first line of a command; its return value is used as the first-line 3467 prompt. 3468 3469 The prompt procedure can have side effects. In Bash shell terms: 3470 It combines the features of ‘PROMPT_COMMAND’ and ‘PS1’. 3471 3472 The initial PROMPTER is ‘default-prompter’, which returns the 3473 expansion of ‘input-prompt1’. 3474 3475 -- Procedure: input-port-prompter port 3476 Get the prompt procedure associated with PORT. 3477 3478 -- Procedure: default-prompter port 3479 The default prompt procedure. Normally (i.e. when 3480 ‘input-port-read-state’ is a space) returns ‘input-prompt1’ after 3481 expanding the ‘%’-placeholders. Can also expand ‘input-prompt2’ 3482 when ‘input-port-read-state’ is not whitespace. 3483 348417.5.5 Line numbers and other input port properties 3485--------------------------------------------------- 3486 3487 -- Function: port-column input-port 3488 -- Function: port-line input-port 3489 Return the current column number or line number of INPUT-PORT, 3490 using the current input port if none is specified. If the number 3491 is unknown, the result is ‘#f’. Otherwise, the result is a 3492 0-origin integer - i.e. the first character of the first line is 3493 line 0, column 0. (However, when you display a file position, for 3494 example in an error message, we recommend you add 1 to get 1-origin 3495 integers. This is because lines and column numbers traditionally 3496 start with 1, and that is what non-programmers will find most 3497 natural.) 3498 3499 -- Procedure: set-port-line! port line 3500 Set (0-origin) line number of the current line of PORT to NUM. 3501 3502 -- Procedure: input-port-line-number port 3503 Get the line number of the current line of PORT, which must be a 3504 (non-binary) input port. The initial line is line 1. Deprecated; 3505 replaced by ‘(+ 1 (port-line PORT))’. 3506 3507 -- Procedure: set-input-port-line-number! port num 3508 Set line number of the current line of PORT to NUM. Deprecated; 3509 replaced by ‘(set-port-line! PORT (- NUM 1))’. 3510 3511 -- Procedure: input-port-column-number port 3512 Get the column number of the current line of PORT, which must be a 3513 (non-binary) input port. The initial column is column 1. 3514 Deprecated; replaced by ‘(+ 1 (port-column PORT))’. 3515 3516 -- Procedure: input-port-read-state port 3517 Returns a character indicating the current ‘read’ state of the 3518 PORT. Returns ‘#\Return’ if not current doing a READ, ‘#\"’ if 3519 reading a string; ‘#\|’ if reading a comment; ‘#\(’ if inside a 3520 list; and ‘#\Space’ when otherwise in a ‘read’. The result is 3521 intended for use by prompt prcedures, and is not necessarily 3522 correct except when reading a new-line. 3523 3524 -- Variable: symbol-read-case 3525 A symbol that controls how ‘read’ handles letters when reading a 3526 symbol. If the first letter is ‘U’, then letters in symbols are 3527 upper-cased. If the first letter is ‘D’ or ‘L’, then letters in 3528 symbols are down-cased. If the first letter is ‘I’, then the case 3529 of letters in symbols is inverted. Otherwise (the default), the 3530 letter is not changed. (Letters following a ‘\’ are always 3531 unchanged.) The value of ‘symbol-read-case’ only checked when a 3532 reader is created, not each time a symbol is read. 3533 353417.5.6 Miscellaneous 3535-------------------- 3536 3537 -- Variable: port-char-encoding 3538 Controls how bytes in external files are converted to/from internal 3539 Unicode characters. Can be either a symbol or a boolean. If 3540 ‘port-char-encoding’ is ‘#f’, the file is assumed to be a binary 3541 file and no conversion is done. Otherwise, the file is a text 3542 file. The default is ‘#t’, which uses a locale-dependent 3543 conversion. If ‘port-char-encoding’ is a symbol, it must be the 3544 name of a character encoding known to Java. For all text files 3545 (that is if ‘port-char-encoding’ is not ‘#f’), on input a 3546 ‘#\Return’ character or a ‘#\Return’ followed by ‘#\Newline’ are 3547 converted into plain ‘#\Newline’. 3548 3549 This variable is checked when the file is opened; not when actually 3550 reading or writing. Here is an example of how you can safely 3551 change the encoding temporarily: 3552 (define (open-binary-input-file name) 3553 (fluid-let ((port-char-encoding #f)) (open-input-file name))) 3554 3555 -- Variable: *print-base* 3556 The number base (radix) to use by default when printing rational 3557 numbers. Must be an integer between 2 and 36, and the default is 3558 of course 10. For example setting ‘*print-base*’ to 16 produces 3559 hexadecimal output. 3560 3561 -- Variable: *print-radix* 3562 If true, prints an indicator of the radix used when printing 3563 rational numbers. If ‘*print-base*’ is respectively 2, 8, or 16, 3564 then ‘#b’, ‘#o’ or ‘#x’ is written before the number; otherwise 3565 ‘#Nr’ is written, where ‘N’ is the base. An exception is when 3566 ‘*print-base*’ is 10, in which case a period is written _after_ the 3567 number, to match Common Lisp; this may be inappropriate for Scheme, 3568 so is likely to change. 3569 3570 -- Variable: *print-right-margin* 3571 The right margin (or line width) to use when pretty-printing. 3572 3573 -- Variable: *print-miser-width* 3574 If this an integer, and the available width is less or equal to 3575 this value, then the pretty printer switch to the more “miser” 3576 compact style. 3577 3578 -- Variable: *print-xml-indent* 3579 When writing to XML, controls pretty-printing and indentation. If 3580 the value is ‘'always’ or ‘'yes’ force each element to start on a 3581 new suitably-indented line. If the value is ‘'pretty’ only force 3582 new lines for elements that won’t fit completely on a line. The 3583 the value is ‘'no’ or unset, don’t add extra whitespace. 3584 3585 3586File: kawa.info, Node: Format, Prev: Ports, Up: Input-Output 3587 358817.6 Formatted Output (Common-Lisp-style) 3589========================================= 3590 3591 -- Procedure: format destination fmt . arguments 3592 An almost complete implementation of Common LISP format description 3593 according to the CL reference book ‘Common LISP’ from Guy L. 3594 Steele, Digital Press. Backward compatible to most of the 3595 available Scheme format implementations. 3596 3597 Returns ‘#t’, ‘#f’ or a string; has side effect of printing 3598 according to FMT. If DESTINATION is ‘#t’, the output is to the 3599 current output port and ‘#!void’ is returned. If DESTINATION is 3600 ‘#f’, a formatted string is returned as the result of the call. If 3601 DESTINATION is a string, DESTINATION is regarded as the format 3602 string; FMT is then the first argument and the output is returned 3603 as a string. If DESTINATION is a number, the output is to the 3604 current error port if available by the implementation. Otherwise 3605 DESTINATION must be an output port and ‘#!void’ is returned. 3606 3607 FMT must be a string or an instance of ‘gnu.text.MessageFormat’ or 3608 ‘java.text.MessageFormat’. If FMT is a string, it is parsed as if 3609 by ‘parse-format’. 3610 3611 -- Procedure: parse-format format-string 3612 Parses ‘format-string’, which is a string of the form of a Common 3613 LISP format description. Returns an instance of 3614 ‘gnu.text.ReportFormat’, which can be passed to the ‘format’ 3615 function. 3616 3617 A format string passed to ‘format’ or ‘parse-format’ consists of 3618format directives (that start with ‘~’), and regular characters (that 3619are written directly to the destination). Most of the Common Lisp (and 3620Slib) format directives are implemented. Neither justification, nor 3621pretty-printing are supported yet. 3622 3623 Plus of course, we need documentation for ‘format’! 3624 362517.6.1 Implemented CL Format Control Directives 3626----------------------------------------------- 3627 3628Documentation syntax: Uppercase characters represent the corresponding 3629control directive characters. Lowercase characters represent control 3630directive parameter descriptions. 3631 3632‘~A’ 3633 Any (print as ‘display’ does). 3634 ‘~@A’ 3635 left pad. 3636 ‘~MINCOL,COLINC,MINPAD,PADCHARA’ 3637 full padding. 3638‘~S’ 3639 S-expression (print as ‘write’ does). 3640 ‘~@S’ 3641 left pad. 3642 ‘~MINCOL,COLINC,MINPAD,PADCHARS’ 3643 full padding. 3644 3645‘~C’ 3646 Character. 3647 ‘~@C’ 3648 prints a character as the reader can understand it (i.e. ‘#\’ 3649 prefixing). 3650 ‘~:C’ 3651 prints a character as emacs does (eg. ‘^C’ for ASCII 03). 3652 365317.6.2 Formatting Integers 3654-------------------------- 3655 3656‘~D’ 3657 Decimal. 3658 ‘~@D’ 3659 print number sign always. 3660 ‘~:D’ 3661 print comma separated. 3662 ‘~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHD’ 3663 padding. 3664‘~X’ 3665 Hexadecimal. 3666 ‘~@X’ 3667 print number sign always. 3668 ‘~:X’ 3669 print comma separated. 3670 ‘~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHX’ 3671 padding. 3672‘~O’ 3673 Octal. 3674 ‘~@O’ 3675 print number sign always. 3676 ‘~:O’ 3677 print comma separated. 3678 ‘~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHO’ 3679 padding. 3680‘~B’ 3681 Binary. 3682 ‘~@B’ 3683 print number sign always. 3684 ‘~:B’ 3685 print comma separated. 3686 ‘~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHB’ 3687 padding. 3688‘~NR’ 3689 Radix N. 3690 ‘~N,MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHR’ 3691 padding. 3692‘~@R’ 3693 print a number as a Roman numeral. 3694‘~:@R’ 3695 print a number as an “old fashioned” Roman numeral. 3696‘~:R’ 3697 print a number as an ordinal English number. 3698‘~R’ 3699 print a number as a cardinal English number. 3700‘~P’ 3701 Plural. 3702 ‘~@P’ 3703 prints ‘y’ and ‘ies’. 3704 ‘~:P’ 3705 as ‘~P but jumps 1 argument backward.’ 3706 ‘~:@P’ 3707 as ‘~@P but jumps 1 argument backward.’ 3708 3709 COMMAWIDTH is the number of characters between two comma characters. 3710 371117.6.3 Formatting real numbers 3712------------------------------ 3713 3714‘~F’ 3715 Fixed-format floating-point (prints a flonum like MMM.NNN). 3716 ‘~WIDTH,DIGITS,SCALE,OVERFLOWCHAR,PADCHARF’ 3717 ‘~@F’ 3718 If the number is positive a plus sign is printed. 3719 3720‘~E’ 3721 Exponential floating-point (prints a flonum like MMM.NNN‘E’EE) 3722 ‘~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARE’ 3723 ‘~@E’ 3724 If the number is positive a plus sign is printed. 3725 3726‘~G’ 3727 General floating-point (prints a flonum either fixed or 3728 exponential). 3729 ‘~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARG’ 3730 ‘~@G’ 3731 If the number is positive a plus sign is printed. 3732 A slight difference from Common Lisp: If the number is printed in 3733 fixed form and the fraction is zero, then a zero digit is printed 3734 for the fraction, if allowed by the WIDTH and DIGITS is 3735 unspecified. 3736 3737‘~$’ 3738 Dollars floating-point (prints a flonum in fixed with signs 3739 separated). 3740 ‘~DIGITS,SCALE,WIDTH,PADCHAR$’ 3741 ‘~@$’ 3742 If the number is positive a plus sign is printed. 3743 ‘~:@$’ 3744 A sign is always printed and appears before the padding. 3745 ‘~:$’ 3746 The sign appears before the padding. 3747 374817.6.4 Miscellaneous formatting operators 3749----------------------------------------- 3750 3751‘~%’ 3752 Newline. 3753 ‘~N%’ 3754 print N newlines. 3755‘~&’ 3756 print newline if not at the beginning of the output line. 3757 ‘~N&’ 3758 prints ‘~&’ and then N-1 newlines. 3759‘~|’ 3760 Page Separator. 3761 ‘~N|’ 3762 print N page separators. 3763‘~~’ 3764 Tilde. 3765 ‘~N~’ 3766 print N tildes. 3767‘~’<newline> 3768 Continuation Line. 3769 ‘~:’<newline> 3770 newline is ignored, white space left. 3771 ‘~@’<newline> 3772 newline is left, white space ignored. 3773‘~T’ 3774 Tabulation. 3775 ‘~@T’ 3776 relative tabulation. 3777 ‘~COLNUM,COLINCT’ 3778 full tabulation. 3779‘~?’ 3780 Indirection (expects indirect arguments as a list). 3781 ‘~@?’ 3782 extracts indirect arguments from format arguments. 3783‘~(STR~)’ 3784 Case conversion (converts by ‘string-downcase’). 3785 ‘~:(STR~)’ 3786 converts by ‘string-capitalize’. 3787 ‘~@(STR~)’ 3788 converts by ‘string-capitalize-first’. 3789 ‘~:@(STR~)’ 3790 converts by ‘string-upcase’. 3791‘~*’ 3792 Argument Jumping (jumps 1 argument forward). 3793 ‘~N*’ 3794 jumps N arguments forward. 3795 ‘~:*’ 3796 jumps 1 argument backward. 3797 ‘~N:*’ 3798 jumps N arguments backward. 3799 ‘~@*’ 3800 jumps to the 0th argument. 3801 ‘~N@*’ 3802 jumps to the Nth argument (beginning from 0) 3803‘~[STR0~;STR1~;...~;STRN~]’ 3804 Conditional Expression (numerical clause conditional). 3805 ‘~N[’ 3806 take argument from N. 3807 ‘~@[’ 3808 true test conditional. 3809 ‘~:[’ 3810 if-else-then conditional. 3811 ‘~;’ 3812 clause separator. 3813 ‘~:;’ 3814 default clause follows. 3815‘~{STR~}’ 3816 Iteration (args come from the next argument (a list)). 3817 ‘~N{’ 3818 at most N iterations. 3819 ‘~:{’ 3820 args from next arg (a list of lists). 3821 ‘~@{’ 3822 args from the rest of arguments. 3823 ‘~:@{’ 3824 args from the rest args (lists). 3825‘~^’ 3826 Up and out. 3827 ‘~N^’ 3828 aborts if N = 0 3829 ‘~N,M^’ 3830 aborts if N = M 3831 ‘~N,M,K^’ 3832 aborts if N <= M <= K 3833‘~<’MINCOL 3834 Start justification: spacing is evenly distributed between text 3835 segments with a width of MINCOL. This enables an even right 3836 margin. 3837‘~>’ 3838 End of segments to justify. 3839 384017.6.5 Unimplemented CL Format Control Directives 3841------------------------------------------------- 3842 3843‘~:A’ 3844 print ‘#f’ as an empty list (see below). 3845‘~:S’ 3846 print ‘#f’ as an empty list (see below). 3847‘~:^’ 3848 384917.6.6 Extended, Replaced and Additional Control Directives 3850----------------------------------------------------------- 3851 3852These are not necesasrily implemented in Kawa! 3853 3854‘~I’ 3855 print a R4RS complex number as ‘~F~@Fi’ with passed parameters for 3856 ‘~F’. 3857‘~Y’ 3858 Pretty print formatting of an argument for scheme code lists. 3859‘~K’ 3860 Same as ‘~?.’ 3861‘~!’ 3862 Flushes the output if format DESTINATION is a port. 3863‘~_’ 3864 Print a ‘#\space’ character 3865 ‘~N_’ 3866 print N ‘#\space’ characters. 3867 3868‘~NC’ 3869 Takes N as an integer representation for a character. No arguments 3870 are consumed. N is converted to a character by ‘integer->char’. N 3871 must be a positive decimal number. 3872‘~:S’ 3873 Print out readproof. Prints out internal objects represented as 3874 ‘#<...>’ as strings ‘"#<...>"’ so that the format output can always 3875 be processed by ‘read’. 3876‘~:A’ 3877 Print out readproof. Prints out internal objects represented as 3878 ‘#<...>’ as strings ‘"#<...>"’ so that the format output can always 3879 be processed by ‘read’. 3880‘~F, ~E, ~G, ~$’ 3881 may also print number strings, i.e. passing a number as a string 3882 and format it accordingly. 3883 3884 3885File: kawa.info, Node: Pretty-printing, Next: Resources, Prev: Format, Up: Input-Output 3886 388717.7 Pretty-printing 3888==================== 3889 3890Pretty-printing is displaying a data structure as text, by adding 3891line-breaks and indenttaion so that the visual structure of the output 3892corresponds to the logical structure of data structure. This makes it 3893easier to read and understand. Pretty-printing takes into account the 3894column width of the output so as to avoid using more lines than needed. 3895 3896 Pretty-printing of standard sequences types such as lists and vectors 3897is done by default. For example: 3898 #|kawa:11|# (set! *print-right-margin* 50) 3899 #|kawa:12|# '(ABCDEF (aa bb cc dd) (x123456789 3900 #|.....13|# y123456789 z123456789) ABCDEFG HIJKL) 3901 (ABCDEF (aa bb cc dd) 3902 (x123456789 y123456789 z123456789) ABCDEFG HIJK) 3903 Setting ‘*print-right-margin*’ to 50 causes output to be limited to 390450 columns. Notice the top-level list has to be split, but sub-lists 3905‘(aa bb cc dd)’ and ‘(x123456789 y123456789 z123456789)’ don’t need to 3906be split. 3907 3908 When outputting to a DomTerm REPL, then ‘*print-right-margin*’ is 3909ignored, and the line-breaking is actually handled by DomTerm. If you 3910change the window width, DomTerm will dynamically re-calculate the 3911line-breaks of previous pretten output. This works even in the case of 3912a session saved to an HTML file, as long as JavaScript is enabled. 3913 3914 The concepts and terminology are based on those of Common Lisp 3915(https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node253.html). 3916 391717.7.1 Pretty-printing Scheme forms 3918----------------------------------- 3919 3920Scheme and Lisp code is traditionally pretty-printed slightly 3921differently than plain lists. The ‘pprint’ procedure assumes the 3922argument is a Scheme form, and prints its accordingly. For example the 3923special form ‘(let ...)’ is printed differently from a regular function 3924call ‘(list ...)’. 3925 3926 -- Procedure: pprint obj [out] 3927 Assume OBJ is a Scheme form, and pretty-print it in traditional 3928 Scheme format. For example: 3929 #|kawa:1|# (import (kawa pprint)) 3930 #|kawa:2|# (define fib-form 3931 #|.....3|# '(define (fibonacci n) 3932 #|.....4|# (let loop ((i0 0) (i1 1) (n n)) 3933 #|.....5|# (if (<= n 0) i0 3934 #|.....6|# (loop i1 (+ i0 i1) (- n 1)))))) 3935 #|kawa:7|# (set! *print-right-margin* 80) 3936 #|kawa:8|# (pprint fib-form) 3937 (define (fibonacci n) 3938 (let loop ((i0 0) (i1 1) (n n)) (if (<= n 0) i0 (loop i1 (+ i0 i1) (- n 1))))) 3939 #|kawa:9|# (set! *print-right-margin* 40) 3940 #|kawa:10|# (pprint fib-form) 3941 (define (fibonacci n) 3942 (let loop ((i0 0) (i1 1) (n n)) 3943 (if (<= n 0) 3944 i0 3945 (loop i1 (+ i0 i1) (- n 1))))) 3946 3947 The ‘pprint’ special-cases forms that start with ‘define’, ‘if’, 3948 ‘lambda’, ‘let’, and a few more, and formats them with 3949 “traditional” indentation. However, it is not as complete or 3950 polished as it should be. (It should also use a programmable 3951 dispatch table, rather than having these special cases hard-wired. 3952 That is an improvemet for another day.) 3953 395417.7.2 Generic pretty-printing functions 3955---------------------------------------- 3956 3957The following procedures are used to indicate logical blocks, and 3958optional newlines. 3959 3960 To access them do: 3961 (import (kawa pprint)) 3962 3963 In the following, OUT is the output port, which defaults to 3964‘(current-output-port)’. 3965 3966 -- Syntax: pprint-logical-block OPTIONS STATEMENT^{*} 3967 3968 Evaluate the STATEMENTs within the context of a new “logical 3969 block”. 3970 3971 The OPTIONS are one or more of the following: 3972 ‘prefix:’ PREFIX 3973 ‘per-line:’ PER-LINE-PREFIX 3974 Emit PREFIX or PER-LINE-PREFIX (only one of them can be 3975 specified) before the start of the logical block. If 3976 PER-LINE-PREFIX is provided, it is also print for each line 3977 within the logical block, indented the same. These are 3978 strings and default to ‘""’. 3979 ‘suffix:’ SUFFIX 3980 Emit SUFFIX after the end of the logical block. 3981 ‘out:’ OUT 3982 The output file. 3983 3984 For example to print a list you might do: 3985 (pprint-logical-block prefix: "(" suffix: ")" 3986 print contents of list) 3987 3988 This macro is equivalent to: 3989 (pprint-start-logical-block PREFIX IS-PER-LINE SUFFIX OUT) 3990 (try-finally 3991 (begin STATEMENT^{*}) 3992 (pprint-end-logical-block SUFFIX OUT)) 3993 3994 -- Procedure: pprint-start-logical-block prefix is-per-line suffix out 3995 Start a logical block. The IS-PER-LINE argument is a boolean to 3996 specifiy of PREFIX is a per-line-prefix or a plain prefix. 3997 -- Procedure: pprint-end-logical-block suffix out 3998 End a logical block. 3999 4000 -- Procedure: pprint-newline kind [out] 4001 Print a conditional newline, where KIND is one of the symbols 4002 ‘'fill’, ‘'linear’, ‘'mandatory’, or ‘'miser’. Usually follows 4003 printing of a space, as nothing is printed if the line is not 4004 broken here. 4005 4006 -- Procedure: pprint-ident mode amount [out] 4007 Change how much following lines are indented (with the current 4008 logical block). The AMOUNT is the size of the indentation, in 4009 characters. The MODE is either ‘'current’ (if the AMOUNT is 4010 relative to the current position), or ‘'block’ (if the AMOUNT is 4011 relative to the start (after any PREFIX) of the current logical 4012 block). 4013 4014 4015File: kawa.info, Node: Resources, Prev: Pretty-printing, Up: Input-Output 4016 401717.8 Resources 4018============== 4019 4020A resource is a file or other fixed data that an application may access. 4021Resources are part of the application and are shipped with it, but are 4022stored in external files. Examples are images, sounds, and translation 4023(localization) of messages. In the Java world a resource is commonly 4024bundled in the same jar file as the application itself. 4025 4026 -- Syntax: resource-url resource-name 4027 Returns a ‘URLPath’ you can use as a ‘URL’, or you can pass to it 4028 ‘open-input-file’ to read the resource data. The RESOURCE-NAME is 4029 a string which is passed to the ‘ClassLoader’ of the containing 4030 module. If the module class is in a jar file, things will 4031 magically work if the resource is in the same jar file, and 4032 RESOURCE-NAME is a filename relative to the module class in the 4033 jar. If the module is immediately evaluated, the RESOURCE-NAME is 4034 resolved against the location of the module source file. 4035 4036 -- Syntax: module-uri 4037 Evaluates to a special URI that can be used to access resources 4038 relative to the class of the containing module. The URI has the 4039 form ‘"class-resource://CURRENTCLASS/"’ in compiled code, to allow 4040 moving the classes/jars. The current ‘ClassLoader’ is associated 4041 with the URI, so accessing resources using the URI will use that 4042 ‘ClassLoader’. Therefore you should not create a 4043 ‘"class-resource:"’ URI except by using this function or 4044 ‘resolve-uri’, since that might try to use the wrong ‘ClassLoader’. 4045 4046 The macro ‘resource-url’ works by using ‘module-uri’ and resolving 4047 that to a normal ‘URL’. 4048 4049 -- Syntax: module-class 4050 Evaluates to the containing module class, as a ‘java.lang.Class’ 4051 instance. 4052 4053 4054File: kawa.info, Node: Types, Next: Objects Classes and Modules, Prev: Input-Output, Up: Top 4055 405618 Types 4057******** 4058 4059A “type” is a set of values, plus an associated set of operations valid 4060on those values. Types are useful for catching errors 4061("type-checking"), documenting the programmer’s intent, and to help the 4062compiler generate better code. Types in some languages (such as C) 4063appear in programs, but do not exist at run-time. In such languages, 4064all type-checking is done at compile-time. Other languages (such as 4065standard Scheme) do not have types as such, but they have “predicates”, 4066which allow you to check if a value is a member of certain sets; also, 4067the primitive functions will check at run-time if the arguments are 4068members of the allowed sets. Other languages, including Java and Common 4069Lisp, provide a combination: Types may be used as specifiers to guide 4070the compiler, but also exist as actual run-time values. In Java, for 4071each class, there is a corresponding ‘java.lang.Class’ run-time object, 4072as well as an associated type (the set of values of that class, plus its 4073sub-classes, plus ‘null’). 4074 4075 Kawa, like Java, has first-class types, that is types exist as 4076objects you can pass around at run-time. The most used types correspond 4077to Java classes and primitive types, but Kawa also has other non-Java 4078types. 4079 4080 Type specifiers have a “type expressions”, and a type expression is 4081conceptually an expression that is evaluated to yield a type value. The 4082current Kawa compiler is rather simple-minded, and in many places only 4083allows simple types that the compiler can evaluate at compile-time. 4084More specifically, it only allows simple “type names” that map to 4085primitive Java types or Java classes. 4086 4087 TYPE ::= EXPRESSION 4088 OPT-TYPE-SPECIFIER ::= [‘::’ TYPE] 4089 4090 Various Kawa constructs require or allow a type to be specified. You 4091can use a type specifier most places where you *note define a variable 4092or match a pattern: Variables and Patterns. Types specifiers can appear 4093in other placess, such as procedure return type specifiers. For example 4094in this procedure definition, ‘::vector’ is an argument type specifier 4095(and ‘vec::vector’ is a pattern), while ‘::boolean’ is a return type 4096specifier. 4097 (define (vector-even? vec::vector)::boolean 4098 (not (odd? (vector-length vec)))) 4099 (vector-even? #(3 4 5)) ⇒ #f 4100 (vector-even? (list 3 4 5 6)) ⇒ error 4101 4102* Menu: 4103 4104* Standard Types:: 4105* Parameterized Types:: 4106* Type tests and conversions:: 4107 4108 4109File: kawa.info, Node: Standard Types, Next: Parameterized Types, Up: Types 4110 411118.1 Standard Types 4112=================== 4113 4114These types are predefined with the following names. 4115 4116 Instead of plain ‘TYPENAME’ you can also use the syntax ‘<TYPENAME>’ 4117with angle brackets, but that syntax is no longer recommended, because 4118it doesn’t “fit” as well with some ways type names are used. 4119 4120 To find which Java classes these types map into, look in 4121‘kawa/standard/Scheme.java’. 4122 4123 Note that the value of these variables are instances of 4124‘gnu.bytecode.Type’, not (as you might at first expect) 4125‘java.lang.Class’. 4126 4127 The numeric types (‘number’, ‘quantity’, ‘complex’, ‘real’, 4128‘rational’, ‘integer’, ‘long’, ‘int’, ‘short’, ‘byte’ ‘ulong’, ‘uint’, 4129‘ushort’, ‘ubyte’, ‘double’, ‘float’) are discussed in *note Numerical 4130types::. 4131 4132 The types ‘character’ and ‘char’ are discussed in *note Characters::. 4133 4134 -- Variable: Object 4135 An arbitrary Scheme value - and hence an arbitrary Java object. 4136 4137 -- Variable: symbol 4138 The type of Scheme symbols. (Implemented using the Java class 4139 ‘gnu.mapping.Symbol’.) (_Compatibility:_ Previous versions of Kawa 4140 implemented a simple Scheme symbol using an interned 4141 ‘java.lang.String’.) 4142 4143 -- Variable: keyword 4144 The type of keyword values. *Note Keywords::. 4145 4146 -- Variable: list 4147 The type of Scheme lists (pure and impure, including the empty 4148 list). 4149 4150 -- Variable: pair 4151 The type of Scheme pairs. This is a sub-type of ‘list’. 4152 4153 -- Variable: string 4154 The type of Scheme strings. (Implemented using ‘gnu.lists.IString’ 4155 or ‘java.lang.String’ for immutable strings, and 4156 ‘gnu.lists.FString’ for mutable strings. These all implement the 4157 interface ‘java.lang.CharSequence’. (_Compatibility:_ Previous 4158 versions of Kawa always used ‘gnu.lists.FString’.) 4159 4160 -- Variable: character 4161 The type of Scheme character values. This is a sub-type of 4162 ‘Object’, in contrast to type ‘char’, which is the primitive Java 4163 ‘char’ type. 4164 4165 -- Variable: vector 4166 The type of Scheme vectors. 4167 4168 -- Variable: procedure 4169 The type of Scheme procedures. 4170 4171 -- Variable: input-port 4172 The type of Scheme input ports. 4173 4174 -- Variable: output-port 4175 The type of Scheme output ports. 4176 4177 -- Variable: String 4178 This type name is a special case. It specifies the class 4179 ‘java.lang.String’. However, coercing a value to ‘String’ is done 4180 by invoking the ‘toString’ method on the value to be coerced. Thus 4181 it "works" for all objects. It also works for ‘#!null’. 4182 4183 When Scheme code invokes a Java method, any parameter whose type is 4184 ‘java.lang.String’ is converted as if it was declared as a 4185 ‘String’. 4186 4187 -- Variable: parameter 4188 A parameter object, as created by ‘make-parameter’. This type can 4189 take a type parameter (sic): 4190 (define-constant client ::parameter[Client] (make-parameter #!null)) 4191 This lets Kawa know that reading the parameter (as in ‘(client)’) 4192 returns a value of the specified type (in this case ‘Client’). 4193 4194 More will be added later. 4195 4196 A type specifier can also be one of the primitive Java types. The 4197numeric types ‘long’, ‘int’, ‘short’, ‘byte’, ‘float’, and ‘double’ are 4198converted from the corresponding Scheme number classes. Similarly, 4199‘char’ can be converted to and from Scheme characters. The type 4200‘boolean’ matches any object, and the result is ‘false’ if and only if 4201the actual argument is ‘#f’. (The value ‘#f’ is identical to 4202‘Boolean.FALSE’, and ‘#t’ is identical to ‘Boolean.TRUE’.) The return 4203type ‘void’ indicates that no value is returned. 4204 4205 A type specifier can also be a fully-qualified Java class name (for 4206example ‘java.lang.StringBuffer’). In that case, the actual argument is 4207cast at run time to the named class. Also, ‘java.lang.StringBuffer[]’ 4208represents an array of references to ‘java.lang.StringBuffer’ objects. 4209 4210 -- Variable: dynamic 4211 Used to specify that the type is unknown, and is likely to change 4212 at run-time. Warnings about unknown member names are supressed (a 4213 run-time name lookup is formed). An expression of type ‘dynamic’ 4214 is (statically) compatible with any type. 4215 4216 4217File: kawa.info, Node: Parameterized Types, Next: Type tests and conversions, Prev: Standard Types, Up: Types 4218 421918.2 Parameterized Types 4220======================== 4221 4222Kawa has some basic support for parameterized (generic) types. The 4223syntax: 4224 Type[Arg1 Arg2 ... ArgN] 4225 is more-or-less equivalent to Java’s: 4226 Type<Arg1, Arg2, ..., ArgN> 4227 4228 This is a work-in-progress. You can use this syntax with 4229fully-qualified class names, and also type aliases: 4230 (define v1 ::gnu.lists.FVector[gnu.math.IntNum] [4 5 6]) 4231 (define-alias fv gnu.lists.FVector) 4232 (define v2 ::fv[integer] [5 6 7]) 4233 (define-alias fvi fv[integer]) 4234 (define v3 ::fvi [6 7 8]) 4235 4236 4237File: kawa.info, Node: Type tests and conversions, Prev: Parameterized Types, Up: Types 4238 423918.3 Type tests and conversions 4240=============================== 4241 4242Scheme defines a number of standard type testing predicates. For 4243example ‘(vector? x)’ is ‘#t’ if and only if ‘x’ is a vector. 4244 4245 Kawa generalizes this to arbitrary type names: If T is a type-name 4246(that is in scope at compile-time), then ‘T?’ is a one-argument function 4247that returns ‘#t’ if the argument is an instance of the type ‘T’, and 4248‘#f’ otherwise: 4249 (gnu.lists.FVector? #(123)) ⇒ #t 4250 (let ((iarr (int[] 10))) (int[]? iarr)) ⇒ #t 4251 4252 To convert (coerce) the result of an expression VALUE to a type T use 4253the syntax: ‘(->T VALUE)’. 4254 (->float 12) ⇒ 12.0f0 4255 4256 In general: 4257 (T? X) ⇒ (instance? X T) 4258 (->T X) ⇒ (as T X) 4259 4260 -- Procedure: instance? value type 4261 Returns ‘#t’ iff VALUE is an instance of type TYPE. (Undefined if 4262 TYPE is a primitive type, such as ‘int’.) 4263 4264 -- Procedure: as type value 4265 Converts or coerces VALUE to a value of type TYPE. Throws an 4266 exception if that cannot be done. Not supported for TYPE to be a 4267 primitive type such as ‘int’. 4268 4269 4270File: kawa.info, Node: Objects Classes and Modules, Next: XML tools, Prev: Types, Up: Top 4271 427219 Object, Classes and Modules 4273****************************** 4274 4275Kawa provides various ways to define, create, and access Java objects. 4276Here are the currently supported features. 4277 4278 The Kawa module system is based on the features of the Java class 4279system. 4280 4281* Menu: 4282 4283* Defining new classes:: 4284* Anonymous classes:: 4285* Enumerations:: Enumeration types 4286* Annotations:: 4287* Module classes:: Modules and how they are compiled to classes 4288* Importing:: Importing from a library 4289* Record types:: Defining Record Types 4290* Dynamic records:: Creating New Record Types On-the-fly 4291* Method operations:: Calling Java methods from Scheme 4292* Allocating objects:: 4293* Field operations:: Accessing fields of Java objects 4294* Mangling:: Mapping Scheme names to Java names 4295* Scheme types in Java:: 4296* Array operations:: Using Java arrays 4297* Loading Java functions into Scheme:: 4298* Evaluating Scheme expressions from Java:: 4299 4300 -- Syntax: this 4301 Returns the "this object" - the current instance of the current 4302 class. The current implementation is incomplete, not robust, and 4303 not well defined. However, it will have to do for now. Note: 4304 "‘this’" is a macro, not a variable, so you have to write it using 4305 parentheses: ‘(this)’. A planned extension will allow an optional 4306 class specifier (needed for nested clases). 4307 4308 4309File: kawa.info, Node: Defining new classes, Next: Anonymous classes, Up: Objects Classes and Modules 4310 431119.1 Defining new classes 4312========================= 4313 4314Kawa provides various mechanisms for defining new classes. The 4315‘define-class’ and ‘define-simple-class’ forms will usually be the 4316preferred mechanisms. They have basically the same syntax, but have a 4317couple of differences. ‘define-class’ allows multiple inheritance as 4318well as true nested (first-class) class objects. However, the 4319implementation is more complex: code using it is slightly slower, and 4320the mapping to Java classes is a little less obvious. (Each Scheme 4321class is implemented as a pair of an interface and an implementation 4322class.) A class defined by ‘define-simple-class’ is slightly more 4323efficient, and it is easier to access it from Java code. 4324 4325 The syntax of ‘define-class’ are mostly compatible with that in the 4326Guile and Stk dialects of Scheme. 4327 4328 -- Syntax: define-class CLASS-NAME ‘(’supers ...‘)’ 4329 (ANNOTATION|OPTION-PAIR)^{*} FIELD-OR-METHOD-DECL ... 4330 -- Syntax: define-simple-class CLASS-NAME ‘(’supers ...‘)’ 4331 (ANNOTATION|OPTION-PAIR)^{*} FIELD-OR-METHOD-DECL ... 4332 4333 Defines a new class named CLASS-NAME. If ‘define-simple-class’ is 4334 used, creates a normal Java class named CLASS-NAME in the current 4335 package. (If CLASS-NAME has the form ‘<xyz>’ the Java 4336 implementation type is named ‘xyz’.) For ‘define-class’ the 4337 implementation is unspecified. In most cases, the compiler creates 4338 a class pair, consisting of a Java interface and a Java 4339 implementation class. 4340 CLASS-NAME ::= IDENTIFIER 4341 OPTION-PAIR ::= OPTION-KEYWORD OPTION-VALUE 4342 FIELD-OR-METHOD-DECL ::= FIELD-DECL | METHOD-DECL 4343 434419.1.1 General class properties 4345------------------------------- 4346 4347The class inherits from the classes and interfaces listed in SUPERS. 4348This is a list of names of classes that are in scope (perhaps imported 4349using ‘require’), or names for existing classes or interfaces optionally 4350surrounded by ‘<>’, such as ‘<gnu.lists.Sequence>’. If 4351‘define-simple-class’ is used, at most one of these may be the name of a 4352normal Java class or classes defined using ‘define-simple-class’; the 4353rest must be interfaces or classes defined using ‘define-class’. If 4354‘define-class’ is used, _all_ of the classes listed in SUPERS should be 4355interfaces or classes defined using ‘define-class’. 4356 4357‘interface:’ MAKE-INTERFACE 4358 Specifies whether Kawa generates a Java class, interface, or both. 4359 If MAKE-INTERFACE is ‘#t’, then a Java interface is generated. In 4360 that case all the supertypes must be interfaces, and all the 4361 declared methods must be abstract. If MAKE-INTERFACE is ‘#f’, then 4362 a Java class is generated. If ‘interface:’ is unspecified, the 4363 default is ‘#f’ for ‘define-simple-class’. For ‘define-class’ the 4364 default is to generate an interface, and in addition (if needed) a 4365 helper class that implements the interface. (In that case any 4366 non-abstract methods are compiled to static methods. The methods 4367 that implement the interface are just wrapper methods that call the 4368 real static methods. This allows Kawa to implement true multiple 4369 inheritance.) 4370 4371‘access:’ KIND 4372 Specifies the Java access permission on the class. Can be one of 4373 ‘'public’ (which is the default in Kawa), ‘'package’ (which the 4374 default "unnamed" permission in Java code), ‘'protected’, 4375 ‘'private’, ‘'volatile’, or ‘'transient’. Can also be used to 4376 specify ‘final’, ‘abstract’, or ‘enum’, as in Java. (You don’t 4377 need to explicitly specify the class is ‘abstract’ if any 4378 METHOD-BODY is ‘#!abstract’, or you specify ‘interface: #t’.) The 4379 KIND can also be a list, as for example: 4380 access: '(protected volatile) 4381 4382‘class-name:’ ‘"’CNAME‘"’ 4383 Specifies the Java name of the created class. The NAME specified 4384 after ‘define-class’ or ‘define-simple-class’ is the _Scheme name_, 4385 i.e. the name of a Scheme variable that is bound to the class. 4386 The Java name is by default derived from the Scheme name, but you 4387 can override the default with a ‘class-name:’ specifier. If the 4388 CNAME has no periods, then it is a name in the package of the main 4389 (module) class. If the CNAME starts with a period, then you get a 4390 class nested within the module class. In this case the actual 4391 class name is MODULECLASS‘$’RNAME, where RNAME is CNAME without the 4392 initial period. To force a class in the top-level (unnamed) 4393 package (something not recommended) write a period at the end of 4394 the CNAME. 4395 439619.1.2 Declaring fields 4397----------------------- 4398 4399 FIELD-DECL ::= ‘(’FIELD-NAME (ANNOTATION | OPT-TYPE-SPECIFIER | FIELD-OPTION)*‘)’ 4400 FIELD-NAME ::= IDENTIFIER 4401 FIELD-OPTION ::= KEYWORD EXPRESSION 4402 4403 As a matter of style the following order is suggested, though this 4404not enforced: 4405 ‘(’FIELD-NAME ANNOTATION* OPT-TYPE-SPECIFIER FIELD-OPTION*‘)’ 4406 4407 Each FIELD-DECL declares a instance "slot" (field) with the given 4408FIELD-NAME. By default it is publicly visible, but you can specify a 4409different visiblity with the ‘access:’ specifier. The following 4410FIELD-OPTION KEYWORDs are implemented: 4411‘type:’ TYPE 4412 Specifies that TYPE is the type of (the values of) the field. 4413 Equivalent to ‘:: TYPE’. 4414‘allocation:’ KIND 4415 If KIND is ‘'class’ or ‘'static’ a single slot is shared between 4416 all instances of the class (and its sub-classes). Not yet 4417 implemented for ‘define-class’, only for ‘define-simple-class’. In 4418 Java terms this is a ‘static’ field. 4419 4420 If KIND is ‘'instance’ then each instance has a separate value 4421 "slot", and they are not shared. In Java terms, this is a 4422 non-‘static’ field. This is the default. 4423 4424‘access:’ KIND 4425 Specifies the Java access permission on the field. Can be one of 4426 ‘'private’, ‘'protected’, ‘'public’ (which is the default in Kawa), 4427 or ‘'package’ (which the default "unnamed" permission in Java 4428 code). Can also be used to specify ‘volatile’, ‘transient’, 4429 ‘enum’, or ‘final’, as in Java, or a quoted list with these 4430 symbols. 4431‘init:’ EXPR 4432 An expression used to initialize the slot. The expression is 4433 evaluated in a scope that includes the field and method names of 4434 the current class. 4435‘init-form:’ EXPR 4436 An expression used to initialize the slot. The lexical environment 4437 of the EXPR is that of the ‘define-class’; it does _not_ include 4438 the field and method names of the current class. or 4439 ‘define-simple-class’. 4440‘init-value:’ VALUE 4441 A value expression used to initialize the slot. For now this is 4442 synonymous with INIT-FORM:, but that may change (depending on what 4443 other implementation do), so to be safe only use ‘init-value:’ with 4444 a literal. 4445‘init-keyword:’ ‘NAME:’ 4446 A keyword that that can be used to initialize instance in ‘make’ 4447 calls. For now, this is ignored, and NAME should be the same as 4448 the field’s FIELD-NAME. 4449 4450 The FIELD-NAME can be left out. That indicates a "dummy slot", which 4451is useful for initialization not tied to a specific field. In Java 4452terms this is an instance or static initializer, i.e., a block of code 4453executed when a new instance is created or the class is loaded. 4454 4455 In this example, ‘x’ is the only actual field. It is first 4456initialized to 10, but if ‘(some-condition)’ is true then its value is 4457doubled. 4458 (define-simple-class <my-class> () 4459 (allocation: 'class 4460 init: (perform-actions-when-the-class-is-initizalized)) 4461 (x init: 10) 4462 (init: (if (some-condition) (set! x (* x 2))))) 4463 446419.1.3 Declaring methods 4465------------------------ 4466 4467 METHOD-DECL ::= ‘((’METHOD-NAME FORMAL-ARGUMENTS‘)’ 4468 METHOD-OPTION^{*} [DEPRECATED-RETURN-SPECIFIER] METHOD-BODY‘)’ 4469 METHOD-NAME ::= IDENTIFIER 4470 METHOD-OPTION ::= ANNOTATION | OPT-RETURN-TYPE | OPTION-PAIR 4471 METHOD-BODY ::= BODY | ‘#!abstract’ | ‘#!native’ 4472 DEPRECATED-RETURN-SPECIFIER ::= IDENTIFIER 4473 4474 Each METHOD-DECL declares a method, which is by default public and 4475non-static, and whose name is METHOD-NAME. (If METHOD-NAME is not a 4476valid Java method name, it is mapped to something reasonable. For 4477example ‘foo-bar?’ is mapped to ‘isFooBar’.) The types of the method 4478arguments can be specified in the FORMAL-ARGUMENTS. The return type can 4479be specified by a OPT-RETURN-TYPE, DEPRECATED-RETURN-SPECIFIER, or is 4480otherwise the type of the BODY. Currently, the FORMAL-ARGUMENTS cannot 4481contain optional, rest, or keyword parameters. (The plan is to allow 4482optional parameters, implemented using multiple overloaded methods.) 4483 4484 A METHOD-DECL in a ‘define-simple-class’ can have the following 4485OPTION-KEYWORDs: 4486‘access:’ KIND 4487 Specifies the Java access permission on the method. Can be one of 4488 ‘'private’, ‘'protected’, ‘'public’, or ‘'package’. Can also be 4489 ‘'synchronized’, ‘'final’, ‘'strictfp’, or a quoted list. 4490‘allocation:’ KIND 4491 If KIND is ‘'class’ or ‘'static’ creates a static method. 4492‘throws:’ ( EXCEPTION-CLASS-NAME ... ) 4493 Specifies a list of checked exception that the method may throw. 4494 Equivalent to a ‘throws’ specification in Java code. For example: 4495 (define-simple-class T 4496 (prefix) 4497 ((lookup name) throws: (java.io.FileNotFoundException) 4498 (make java.io.FileReader (string-append prefix name)))) 4499 4500 The scope of the BODY of a method includes the FIELD-DECLs and 4501METHOD-DECLs of the class, including those inherited from superclasses 4502and implemented interfaces. 4503 4504 If the METHOD-BODY is the special form ‘#!abstract’, then the method 4505is abstract. This means the method must be overridden in a subclass, 4506and you’re not allowed to create an instance of the enclosing class. 4507 4508 (define-simple-class Searchable () interface: #t 4509 ((search value) :: boolean #!abstract)) 4510 4511 If the METHOD-BODY is the special form ‘#!native’, then the method is 4512native, implemented using JNI 4513(http://en.wikipedia.org/wiki/Java_Native_Interface). 4514 4515 The special METHOD-NAME ‘*init*’ can be used to name a non-default 4516constructor (only if MAKE-INTERFACE discussed above is ‘#f’). It can be 4517used to initialize a freshly-allocated instance using passed-in 4518parameters. You can call a superclass or a sibling constructor using 4519the ‘invoke-special’ special function. (This is general but admittedly 4520a bit verbose; a more compact form may be added in the future.) See the 4521example below. 4522 452319.1.4 Example 4524-------------- 4525 4526In the following example we define a simple class ‘2d-vector’ and a 4527class ‘3d-vector’ that extends it. (This is for illustration only - 4528defining 3-dimensional points as an extension of 2-dimensional points 4529does not really make sense.) 4530 4531 (define-simple-class 2d-vector () 4532 (x ::double init-keyword: x:) 4533 ;; Alternative type-specification syntax. 4534 (y type: double init-keyword: y:) 4535 (zero-2d :: 2d-vector allocation: 'static 4536 init-value: (2d-vector 0)) 4537 ;; An object initializer (constructor) method. 4538 ((*init* (x0 ::double) (y0 ::double)) 4539 (set! x x0) 4540 (set! y y0)) 4541 ((*init* (xy0 ::double)) 4542 ;; Call above 2-argument constructor. 4543 (invoke-special 2d-vector (this) '*init* xy0 xy0)) 4544 ;; Need a default constructor as well. 4545 ((*init*) #!void) 4546 ((add (other ::2d-vector)) ::2d-vector 4547 ;; Kawa compiles this using primitive Java types! 4548 (2d-vector 4549 x: (+ x other:x) 4550 y: (+ y other:y))) 4551 ((scale (factor ::double)) ::2d-vector 4552 (2d-vector x: (* factor x) y: (* factor y)))) 4553 4554 (define-simple-class 3d-vector (2d-vector) 4555 (z type: double init-value: 0.0 init-keyword: z:) 4556 ;; A constructor which calls the superclass constructor. 4557 ((*init* (x0 ::double) (y0 ::double) (z0 ::double)) 4558 (invoke-special 2d-vector (this) '*init* x0 y0) 4559 (set! z z0)) 4560 ;; Need a default constructor. 4561 ((*init*) #!void) 4562 ((scale (factor ::double)) ::2d-vector 4563 ;; Note we cannot override the return type to 3d-vector 4564 ;; because Kawa doesn't yet support covariant return types. 4565 (3d-vector 4566 x: (* factor x) 4567 y: (* factor (this):y) ;; Alternative syntax. 4568 z: (* factor z)))) 4569 4570 Note we define both explicit non-default constructor methods, and we 4571associate fields with keywords, so they can be named when allocating an 4572object. Using keywords requires a default constructor, and since having 4573non-default constructors suppresses the implicit default constructor we 4574have to explicitly define it. Using both styles of constructors is 4575rather redundant, though. 4576 4577 4578File: kawa.info, Node: Anonymous classes, Next: Enumerations, Prev: Defining new classes, Up: Objects Classes and Modules 4579 458019.2 Anonymous classes 4581====================== 4582 4583 -- Syntax: object ‘(’supers ...‘)’ field-or-method-decl ... 4584 Returns a new instance of an anonymous (inner) class. The syntax 4585 is similar to ‘define-class’. 4586 OBJECT-FIELD-OR-METHOD-DECL ::= OBJECT-FIELD-DECL | METHOD-DECL 4587 OBJECT-FIELD-DECL ::= ‘(’FIELD-NAME (ANNOTATION | OPT-TYPE-SPECIFIER | FIELD-OPTION)* [OBJECT-INIT] ‘)’ 4588 OBJECT-INIT ::= EXPRESSION 4589 4590 Returns a new instance of a unique (anonymous) class. The class 4591 inherits from the list of SUPERS, where at most one of the elements 4592 should be the base class being extended from, and the rest are 4593 interfaces. 4594 4595 This is roughly equivalent to: 4596 (begin 4597 (define-simple-class HNAME (SUPERS ...) FIELD-OR-METHOD-DECL ...) 4598 (make HNAME)) 4599 4600 A FIELD-DECL is as for ‘define-class’, except that we also allow an 4601 abbreviated syntax. Each FIELD-DECL declares a public instance 4602 field. If OBJECT-FINIT is given, it is an expression whose value 4603 becomes the initial value of the field. The OBJECT-INIT is 4604 evaluated at the same time as the ‘object’ expression is evaluated, 4605 in a scope where all the FIELD-NAMEs are visible. 4606 4607 A METHOD-DECL is as for ‘define-class’. 4608 460919.2.1 Lambda as shorthand for anonymous class 4610---------------------------------------------- 4611 4612An anonymous class is commonly used in the Java platform where a 4613function language would use a lambda expression. Examples are call-back 4614handlers, events handlers, and ‘run’ methods. In these cases Kawa lets 4615you use a lambda expression as a short-hand for an anonymous class. For 4616example: 4617 (button:addActionListener 4618 (lambda (e) (do-something))) 4619 is equivalent to: 4620 (button:addActionListener 4621 (object (java.awt.event.ActionListener) 4622 ((actionPerformed (e ::java.awt.event.ActionEvent))::void 4623 (do-something)))) 4624 This is possible when the required type is an interface or abstract 4625class with a Single (exactly one) Abstract Methods. Such a class is 4626sometimes called a “SAM-type”, and the conversion from a lambda 4627expression to an anonymous class is sometimes called “SAM-conversion”. 4628 4629 Note that Kawa can also infer the parameter and return types of a 4630method that overrides a method in a super-class. 4631 4632 4633File: kawa.info, Node: Enumerations, Next: Annotations, Prev: Anonymous classes, Up: Objects Classes and Modules 4634 463519.3 Enumeration types 4636====================== 4637 4638An enumeration type is a set of named atomic enumeration values that are 4639distinct from other values. You define the type using ‘define-enum’, 4640and you reference enumeration values using colon notation: 4641 (define-enum colors (red blue green)) 4642 (define favorite-color colors:green) 4643 Displaying an enum just prints the enum name, but readable output 4644using ‘write’ (or the ‘~s’ ‘format’ specifier) prepends the type name: 4645 (format "~a" favorite-color) ⇒ "green" 4646 (format "~s" favorite-color) ⇒ "colors:green" 4647 The static ‘values’ method returns a Java array of the enumeration 4648values, in declaration order, while ‘ordinal’ yields the index of an 4649enumeration value: 4650 (colors:values) ⇒ [red blue green] 4651 ((colors:values) 1) ⇒ blue 4652 (favorite-color:ordinal) ⇒ 2 4653 If you invoke the enumeration type as a function, it will map the 4654name (as a string) to the corresponding value. (This uses the ‘valueOf’ 4655method.) 4656 (colors "red") ⇒ red 4657 (colors "RED") ⇒ throws IllegalArgumentException 4658 (eq? favorite-color (colors:valueOf "green")) ⇒ #t 4659 4660 Kawa enumerations are based on Java enumerations. Thus the above is 4661similar to a Java5 ‘enum’ declaration, and the type ‘colors’ above 4662extends ‘java.lang.Enum’. 4663 4664 -- Syntax: define-enum enum-type-name OPTION-PAIR... ‘(’enum-value-name 4665 ...‘)’ FIELD-OR-METHOD-DECL... 4666 This declares a new enumeration type ENUM-TYPE-NAME, whose 4667 enumerations values are the ENUM-VALUE-NAME list. You can specify 4668 extra options and members using OPTION-PAIR and 4669 FIELD-OR-METHOD-DECL, which are as in ‘define-simple-class’. (The 4670 DEFINE-ENUM syntax is similar to a ‘define-simple-class’ that 4671 extends ‘java.lang.Enum’.) 4672 4673 (Note that R6RS has a separate Enumerations library ‘(rnrs enum)’. 4674Unfortunately, this is not compatible with standard Java enums. R6RS 4675enums are simple symbols, which means you cannot distinguish two enum 4676values from different enumeration types if they have the same value, nor 4677from a vanilla symbol. That makes them less useful.) 4678 4679 4680File: kawa.info, Node: Annotations, Next: Module classes, Prev: Enumerations, Up: Objects Classes and Modules 4681 468219.4 Annotations of declarations 4683================================ 4684 4685The Java platform lets you associate with each declaration zero or more 4686annotations 4687(http://download.oracle.com/javase/1.5.0/docs/guide/language/annotations.html). 4688They provide an extensible mechanism to associate properties with 4689declarations. Kawa support for annotations is not complete (the most 4690important functionality missing is being able to declare annotation 4691types), but is fairly functional. Here is a simple example illustrating 4692use of JAXB annotations (http://jcp.org/en/jsr/detail?id=222): an 4693‘XmlRootElement’ annotation on a class, and an ‘XmlElement’ annotation 4694on a field: 4695 (import (class javax.xml.bind.annotation XmlRootElement XmlElement)) 4696 (define-simple-class Bib ( ) (@XmlRootElement name: "bib") 4697 (books (@XmlElement name: "book" type: Book) ::java.util.ArrayList)) 4698 (define-simple-class Book () ...) 4699 4700 This tutorial 4701(http://per.bothner.com/blog/2011/Using-JAXB-annotations) explains the 4702JAXB example in depth. 4703 4704 Here is the syntax: 4705 ANNOTATION ::= ‘(@’ANNOTATION-TYPENAME ANNOTATIONS-ELEMENT-VALUES‘)’ 4706 ANNOTATIONS-ELEMENT-VALUES ::= ANNOTATION-ELEMENT-VALUE 4707 | ANNOTATION-ELEMENT-PAIR ... 4708 ANNOTATION-ELEMENT-PAIR ::= KEYWORD ANNOTATION-ELEMENT-VALUE 4709 ANNOTATION-ELEMENT-VALUE ::= EXPRESSION 4710 ANNOTATION-TYPENAME ::= EXPRESSION 4711 4712 An ANNOTATIONS-ELEMENT-VALUES consisting of just a single 4713ANNOTATION-ELEMENT-VALUE is equivalent to an ANNOTATION-ELEMENT-PAIR 4714with a ‘value:’ keyword. 4715 4716 Each KEYWORD must correspond to the name of an element (a 4717zero-argument method) in the annotation type. The corresponding 4718ANNOTATION-ELEMENT-VALUE must be compatible with the element type 4719(return type of the method) of the annotation type. 4720 4721 Allowed element types are of the following kinds: 4722 • Primitive types, where the ANNOTATION-ELEMENT-VALUE must be number 4723 or boolean coercible to the element type. 4724 • Strings, where the ANNOTATION-ELEMENT-VALUE is normally a string 4725 literal. 4726 • Classes, where the ANNOTATION-ELEMENT-VALUE is normally a 4727 classname. 4728 • Enumeration types. The value usually has the form 4729 ‘CLASSNAME:ENUMFIELDNAME’. 4730 • Nested annotation types, where the ANNOTATION-ELEMENT-VALUE must be 4731 a compatible ANNOTATION value. 4732 • An array of one of the allowable types. An array constructor 4733 expression works, but using the square bracket syntax is 4734 recommended. 4735 4736 Annotations are usually used in declarations, where they are required 4737to be “constant-folded” to compile-time constant annotation values. 4738This is so they can be written to class files. However, in other 4739contexts an annotation can be used as an expression with general 4740sub-expressions evaluated at run-time: 4741 (define bk-name "book") 4742 (define be (@XmlElement name: bk-name type: Book)) 4743 (be:name) ⇒ "book" 4744 (This may have limited usefulness: There are some bugs, including 4745lack of support for default values for annotation elements. These bugs 4746can be fixed if someone reports a need for runtime construction of 4747annotation values.) 4748 4749 4750File: kawa.info, Node: Module classes, Next: Importing, Prev: Annotations, Up: Objects Classes and Modules 4751 475219.5 Modules and how they are compiled to classes 4753================================================= 4754 4755Modules provide a way to organize Scheme into reusable parts with 4756explicitly defined interfaces to the rest of the program. A “module” is 4757a set of definitions that the module “exports”, as well as some 4758“actions” (expressions evaluated for their side effect). The top-level 4759forms in a Scheme source file compile a module; the source file is the 4760“module source”. When Kawa compiles the module source, the result is 4761the “module class”. Each exported definition is translated to a public 4762field in the module class. 4763 476419.5.1 Name visibility 4765---------------------- 4766 4767The definitions that a module exports are accessible to other modules. 4768These are the "public" definitions, to use Java terminology. By 4769default, all the identifiers declared at the top-level of a module are 4770exported, except those defined using ‘define-private’. (If compiling 4771with the ‘--main’ flag, then by default no identifiers are exported.) 4772However, a major purpose of using modules is to control the set of names 4773exported. One reason is to reduce the chance of accidental name 4774conflicts between separately developed modules. An even more important 4775reason is to enforce an interface: Client modules should only use the 4776names that are part of a documented interface, and should not use 4777internal implementation procedures (since those may change). 4778 4779 If there is a ‘module-export’ (or ‘export’) declaration in the 4780module, then only those names listed are exported. There can be more 4781than one ‘module-export’, and they can be anywhere in the Scheme file. 4782The recommended style has a single ‘module-export’ near the beginning of 4783the file. 4784 4785 -- Syntax: module-export EXPORT-SPEC^{*} 4786 -- Syntax: export EXPORT-SPEC^{*} 4787 The forms ‘export’ and ‘module-export’ are equivalent. (The older 4788 Kawa name is ‘module-export’; ‘export’ comes from R7RS.) Either 4789 form specifies a list of identifiers which can be made visible to 4790 other libraries or programs. 4791 EXPORT-SPEC ::= IDENTIFIER 4792 | ‘(rename’ IDENTIFIER_{1} IDENTIFIER_{2}‘)’ 4793 In the former variant, an IDENTIFIER names a single binding defined 4794 within or imported into the library, where the external name for 4795 the export is the same as the name of the binding within the 4796 library. A ‘rename’ spec exports the binding defined within or 4797 imported into the library and named by IDENTIFIER_{1}, using 4798 IDENTIFIER_{2} as the external name. 4799 4800 Note that it is an error if there is no definition for IDENTIFIER 4801 (or IDENTIFIER_{1}) in the current module, or if it is defined 4802 using ‘define-private’. 4803 4804 As a matter of style, ‘export’ or ‘module-export’ should appear 4805 after ‘module-name’ but _before_ other commands (including ‘import’ 4806 or ‘require’). (This is a requirement if there are any cycles.) 4807 4808 In this module, ‘fact’ is public and ‘worker’ is private: 4809 (module-export fact) 4810 (define (worker x) ...) 4811 (define (fact x) ...) 4812 4813 Alternatively, you can write: 4814 (define-private (worker x) ...) 4815 (define (fact x) ...) 4816 481719.5.2 R7RS explicit library modules 4818------------------------------------ 4819 4820A R7RS ‘define-library’ form is another way to create a module. The 4821R7RS term “library” is roughly the same as a Kawa module. In Kawa, each 4822source file is a *note “implicit module”: implicit library, which may 4823contain zero or more explicit sub-modules (in the form of 4824‘define-library’) optionally followed by the definitions and expressions 4825of the implicit (file-level) module. 4826 4827 -- Syntax: define-library LIBRARY-NAME LIBRARY-DECLARATION^{*} 4828 LIBRARY-NAME ::= ‘(’ LIBRARY-NAME-PARTS ‘)’ 4829 LIBRARY-NAME-PARTS ::= IDENTIFIER^{+} 4830 4831 A LIBRARY-NAME is a list whose members are identifiers and exact 4832non-negative integers. It is used to identify the library uniquely when 4833importing from other programs or libraries. Libraries whose first 4834identifier is ‘scheme’ are reserved for use by the R7RS report and 4835future versions of that report. Libraries whose first identifier is 4836‘srfi’ are reserved for libraries implementing Scheme Requests for 4837Implementation (http://srfi.schemer.org/). It is inadvisable, but not 4838an error, for identifiers in library names to contain any of the 4839characters ‘|’ ‘\’ ‘?’ ‘*’ ‘<’ ‘"’ ‘:’ ‘>’ ‘+’ ‘[’ ‘]’ ‘/’ ‘.’ or 4840control characters after escapes are expanded. 4841 4842 See *note module-name:: for how a LIBRARY-NAME is mapped to a class 4843name. 4844 4845 LIBRARY-DECLARATION ::= 4846 EXPORT-DECLARATION 4847 | IMPORT-DECLARATION 4848 | ‘(begin’ STATEMENT^{*} ‘)’ 4849 | ‘(include’ FILENAME^{+}‘)’ 4850 | ‘(include-ci’ FILENAME^{+}‘)’ 4851 | ‘(include-library-declarations’ FILENAME^{+}‘)’ 4852 | ‘(cond-expand’ COND-EXPAND-CLAUSE^{*} [‘(else’ command-or-definition*‘)’]‘)’ 4853 | STATEMENT 4854 4855 The ‘begin’, ‘include’, and ‘include-ci’ declarations are used to 4856specify the body of the library. They have the same syntax and 4857semantics as the corresponding expression types. This form of ‘begin’ 4858is analogous to, but not the same as regular ‘begin’. A plain STATEMENT 4859(which is allowed as a Kawa extension) is also part of the body of the 4860library, as if it were wrapped in a ‘begin’). 4861 4862 The ‘include-library-declarations’ declaration is similar to 4863‘include’ except that the contents of the file are spliced directly into 4864the current library definition. This can be used, for example, to share 4865the same ‘export’ declaration among multiple libraries as a simple form 4866of library interface. 4867 4868 The ‘cond-expand’ declaration has the same syntax and semantics as 4869the ‘cond-expand’ expression type, except that it expands to spliced-in 4870library declarations rather than expressions enclosed in ‘begin’. 4871 4872 When a library is loaded, its expressions are executed in textual 4873order. If a library’s definitions are referenced in the expanded form 4874of a program or library body, then that library must be loaded before 4875the expanded program or library body is evaluated. This rule applies 4876transitively. If a library is imported by more than one program or 4877library, it may possibly be loaded additional times. 4878 4879 Similarly, during the expansion of a library ‘(foo)’, if any syntax 4880keywords imported from another library ‘(bar)’ are needed to expand the 4881library, then the library ‘(bar)’ must be expanded and its syntax 4882definitions evaluated before the expansion of ‘(foo)’. 4883 4884 Regardless of the number of times that a library is loaded, each 4885program or library that imports bindings from a library must do so from 4886a single loading of that library, regardless of the number of import 4887declarations in which it appears. That is, ‘(import (only (foo) a’)) 4888followed by ‘(import (only (foo) b))’ has the same effect as ‘(import 4889(only (foo) a b))’. 4890 489119.5.3 How a module becomes a class 4892----------------------------------- 4893 4894If you want to just use a Scheme module as a module (i.e. ‘load’ or 4895‘require’ it), you don’t care how it gets translated into a module 4896class. However, Kawa gives you some control over how this is done, and 4897you can use a Scheme module to define a class which you can use with 4898other Java classes. This style of class definition is an alternative to 4899‘define-class’, which lets you define classes and instances fairly 4900conveniently. 4901 4902 The default name of the module class is the main part of the filename 4903of the Scheme source file (with directories and extensions stripped 4904off). That can be overridden by the ‘-T’ Kawa command-line flag. The 4905package-prefix specified by the ‘-P’ flag is prepended to give the 4906fully-qualified class name. 4907 4908 -- Syntax: module-name name 4909 -- Syntax: module-name <name> 4910 -- Syntax: module-name LIBRARY-NAME 4911 Sets the name of the generated class, overriding the default. If 4912 there is no ‘.’ in the NAME, the package-prefix (specified by the 4913 ‘-P’ Kawa command-line flag) is prepended. 4914 4915 If the form LIBRARY-NAME is used, then the class name is the result 4916 of taking each IDENTIFIER in the LIBRARY-NAME-PARTS, *note 4917 mangling: Mangling. if needed, and concatenating them separated by 4918 periods. For example ‘(org example doc-utils)’ becomes 4919 ‘org.example.doc-utils’. (You can’t reference the class name 4920 ‘doc-utils’ directly in Java, but the JVM has no problems with it. 4921 In Java you can use reflection to access classes with such names.) 4922 4923 As a matter of style, ‘module-name’ should be the first command in 4924 a file (after possible comments). It must appear before a 4925 ‘require’ or ‘import’, in case of cycles. 4926 4927 By default, the base class of the generated module class is 4928unspecified; you cannot count on it being more specific than ‘Object’. 4929However, you can override it with ‘module-extends’. 4930 4931 -- Syntax: module-extends class 4932 Specifies that the class generated from the immediately surrounding 4933 module should extend (be a sub-class of) the class ‘CLASS’. 4934 4935 -- Syntax: module-implements interface ... 4936 Specifies that the class generated from the immediately surrounding 4937 module should implement the interfaces listed. 4938 4939 Note that the compiler does _not_ currently check that all the 4940abstract methods requires by the base class or implemented interfaces 4941are actually provided, and have the correct signatures. This will 4942hopefully be fixed, but for now, if you are forgot a method, you will 4943probably get a verifier error 4944 4945 For each top-level exported definition the compiler creates a 4946corresponding public field with a similar (mangled) name. By default, 4947there is some indirection: The value of the Scheme variable is not that 4948of the field itself. Instead, the field is a ‘gnu.mapping.Location’ 4949object, and the value Scheme variable is defined to be the value stored 4950in the ‘Location’. Howewer, if you specify an explicit type, then the 4951field will have the specified type, instead of being a ‘Location’. The 4952indirection using ‘Location’ is also avoided if you use 4953‘define-constant’. 4954 4955 If the Scheme definition defines a procedure (which is not 4956re-assigned in the module), then the compiler assumes the variable as 4957bound as a constant procedure. The compiler generates one or more 4958methods corresponding to the body of the Scheme procedure. It also 4959generates a public field with the same name; the value of the field is 4960an instance of a subclass of ‘<gnu.mapping.Procedure>’ which when 4961applied will execute the correct method (depending on the actual 4962arguments). The field is used when the procedure used as a value (such 4963as being passed as an argument to ‘map’), but when the compiler is able 4964to do so, it will generate code to call the correct method directly. 4965 4966 You can control the signature of the generated method by declaring 4967the parameter types and the return type of the method. See the applet 4968(*note Applet compilation::) example for how this can be done. If the 4969procedures has optional parameters, then the compiler will generate 4970multiple methods, one for each argument list length. (In rare cases the 4971default expression may be such that this is not possible, in which case 4972an "variable argument list" method is generated instead. This only 4973happens when there is a nested scope _inside_ the default expression, 4974which is very contrived.) If there are ‘#!keyword’ or ‘#!rest’ 4975arguments, the compiler generate a "variable argument list" method. 4976This is a method whose last parameter is either an array or a ‘<list>’, 4977and whose name has ‘$V’ appended to indicate the last parameter is a 4978list. 4979 4980 Top-leval macros (defined using either ‘define-syntax’ or ‘defmacro’) 4981create a field whose type is currently a sub-class of 4982‘kawa.lang.Syntax’; this allows importing modules to detect that the 4983field is a macro and apply the macro at compile time. 4984 4985 Unfortunately, the Java class verifier does not allow fields to have 4986arbitrary names. Therefore, the name of a field that represents a 4987Scheme variable is "mangled" (*note Mangling::) into an acceptable Java 4988name. The implementation can recover the original name of a field ‘X’ 4989as ‘((gnu.mapping.Named) X).getName()’ because all the standard 4990compiler-generated field types implement the ‘Named’ interface. 4991 499219.5.4 Same class for module and defined class 4993---------------------------------------------- 4994 4995You can declare a class using ‘define-simple-class’ with the same name 4996as the module class, for example the following in a file named 4997‘foo.scm’: 4998 (define-simple-class foo ...) 4999 In this case the defined class will serve dual-purpose as the module 5000class. 5001 5002 To avoid confusion, in this case you must not specify 5003‘module-extends’, ‘module-implements’, or ‘(module-static #t)’. Also, 5004the defined class should not have public static members. In that case 5005it works out pretty well: public static members represent bindings 5006exported by the module; other non-private members “belong” to the 5007defined class. 5008 5009 In this case ‘(module-static 'init-run)’ is implied. 5010 501119.5.5 Static vs non-static modules 5012----------------------------------- 5013 5014There are two kinds of module class: A “static module” is a class (or 5015gets compiled to a class) all of whose public fields are static, and 5016that does not have a public constructor. A JVM can only have a single 5017global instance of a static module. An “instance module” has a public 5018default constructor, and usually has at least one non-static public 5019field. There can be multiple instances of an instance module; each 5020instance is called a “module instance”. However, only a single instance 5021of a module can be “registered” in an environment, so in most cases 5022there is only a single instance of instance modules. Registering an 5023instance in an environment means creating a binding mapping a magic name 5024(derived from the class name) to the instance. 5025 5026 In fact, any Java class class that has the properties of either an 5027instance module or a static module, is a module, and can be loaded or 5028imported as such; the class need not have written using Scheme. 5029 5030 You can control whether a module is compiled to a static or a 5031non-static class using either a command-line flag to the compiler, or 5032using the ‘module-static’ special form. 5033 5034‘--module-static’ 5035 Generate a static module (as if ‘(module-static #t)’ were 5036 specified). This is (now) the default. 5037‘--module-nonstatic’ 5038‘--no-module-static’ 5039 Generate a non-static module (as if ‘(module-static #f)’ were 5040 specified). This used to be the default. 5041‘--module-static-run’ 5042 Generate a static module (as if ‘(module-static 'init-run)’ were 5043 specified). 5044 5045 -- Syntax: module-static name ... 5046 -- Syntax: module-static ‘#t’ 5047 -- Syntax: module-static ‘#f’ 5048 -- Syntax: module-static ‘'init-run’ 5049 Control whether the generated fields and methods are static. If 5050 ‘#t’ or ‘'init-run’ is specified, then the module will be a static 5051 module, _all_ definitions will be static. If ‘'init-run’ is 5052 specified, in addition the module body is evaluated in the class’s 5053 static initializer. (Otherwise, it is run the first time it is 5054 ‘require’’d.) Otherwise, the module is an instance module. If 5055 there is a non-empty list of NAMEs then the module is an instance 5056 module, but the NAMEs that are explicitly listed will be compiled 5057 to static fields and methods. If ‘#f’ is specified, then all 5058 exported names will be compiled to non-static (instance) fields and 5059 methods. 5060 5061 By default, if no ‘module-static’ is specified: 5062 1. If there is a ‘module-extends’ or ‘module-implements’ 5063 declaration, or one of the ‘--applet’ or ‘--servlet’ 5064 command-line flags was specified, then ‘(module-static #f)’ is 5065 implied. 5066 2. If one of the command-line flags ‘--no-module-static’, 5067 ‘--module-nonstatic’, ‘--module-static’, or 5068 ‘--module-static-run’ was specified, then the default is ‘#f’, 5069 ‘#f’, ‘#t’, or ‘'init-run’, respectively. 5070 3. If the module class is *note dual-purpose: dual-purpose-class. 5071 then ‘(module-static 'init-run)’ is implied. 5072 4. Otherwise the default is ‘(module-static #t)’. (It used to be 5073 ‘(module-static #f)’ in older Kawa versions.) 5074 5075 The default is ‘(module-static #t)’. It usually produces more 5076 efficient code, and is recommended if a module contains only 5077 procedure or macro definitions. However, a static module means 5078 that all environments in a JVM share the same bindings, which you 5079 may not want if you use multiple top-level environments. 5080 5081 The top-level actions of a module will get compiled to a ‘run’ 5082method. If there is an explicit ‘method-extends’, then the module class 5083will also automatically implement ‘java.lang.Runnable’. (Otherwise, the 5084class does not implement ‘Runnable’, since in that case the ‘run’ method 5085return an ‘Object’ rather than ‘void’. This will likely change.) 5086 508719.5.6 Module options 5088--------------------- 5089 5090Certain compilation options can be be specified _either_ on the 5091command-line when compiling, or in the module itself. 5092 5093 -- Syntax: module-compile-options [key‘:’ value] ... 5094 This sets the value of the ‘key’ option to ‘value’ for the current 5095 module (source file). It takes effect as soon it is seen during 5096 the first macro-expansion pass, and is active thereafter (unless 5097 overridden by ‘with-compile-options’). 5098 5099 The KEY: is one of the supported option names (The ending colon 5100 makes it a Kawa keyword). Valid option keys are: 5101 5102 • ‘main:’ - Generate an application, with a main method. 5103 5104 • ‘full-tailcalls:’ - Use a calling convention that supports 5105 proper tail recursion. 5106 5107 • ‘warn-undefined-variable:’ - Warn if no compiler-visible 5108 binding for a variable. 5109 5110 • ‘warn-unknown-member:’ - Warn if referencing an unknown method 5111 or field. 5112 5113 • ‘warn-invoke-unknown-method:’ - Warn if invoke calls an 5114 unknown method (subsumed by warn-unknown-member). 5115 5116 • ‘warn-unused:’ - Warn if a variable is usused or code never 5117 executed. 5118 5119 • ‘warn-uninitialized:’ - Warn if accessing an uninitialized 5120 variable. 5121 5122 • ‘warn-unreachable:’ - Warn if this code can never be executed. 5123 • ‘warn-void-used:’ - Warn if an expression depends on the value 5124 of a void sub-expression (one that never returns a value). 5125 • ‘warn-as-error:’ - Treat a compilation warning as if it were 5126 an error. 5127 5128 The VALUE must be a literal value: either a boolean (‘#t’ or ‘#f’), 5129 a number, or a string, depending on the KEY. (All the options so 5130 far are boolean options.) 5131 5132 (module-compile-options warn-undefined-variable: #t) 5133 ;; This causes a warning message that y is unknown. 5134 (define (func x) (list x y)) 5135 5136 -- Syntax: with-compile-options [key: value] ... body 5137 Similar to ‘module-compile-options’, but the option is only active 5138 within BODY. 5139 5140 The module option key ‘main:’ has no effect when applied to a 5141 particular body via the ‘with-compile-options’ syntax. 5142 5143 (define (func x) 5144 (with-compile-options warn-invoke-unknown-method: #f 5145 (invoke x 'size))) 5146 5147 5148File: kawa.info, Node: Importing, Next: Record types, Prev: Module classes, Up: Objects Classes and Modules 5149 515019.6 Importing from a library 5151============================= 5152 5153You can import a module into the current namespace with ‘import’ or 5154‘require’. This adds the exported bindings (or a subset of them) to the 5155current lexical scope. It follows that these bindings (which are said 5156to be imported) are determined at compile-time. 5157 5158 -- Syntax: import IMPORT-SET^{*} 5159 An ‘import’ declaration provides a way to import identifiers 5160 exported by a library (module). Each IMPORT-SET names a set of 5161 bindings from a library and possibly specifies local names for the 5162 imported bindings. 5163 IMPORT-SET ::= 5164 CLASSNAME 5165 | LIBRARY-REFERENCE 5166 | ‘(library’ LIBRARY-REFERENCE ‘)’ 5167 | ‘(class’ CLASS-PREFIX IMPORT-ONLY-NAME^{*}‘)’ 5168 | ‘(only’ IMPORT-SET IMPORT-ONLY-NAME^{*}‘)’ 5169 | ‘(except’ IMPORT-SET IDENTIFIER^{*}‘)’ 5170 | ‘(prefix’ IMPORT-SET IDENTIFIER ‘)’ 5171 | ‘(rename’ IMPORT-SET RENAME-PAIR^{*}‘)’ 5172 LIBRARY-REFERENCE ::= ‘(’ LIBRARY-NAME-PARTS [EXPLICIT-SOURCE-NAME]‘)’ 5173 IMPORT-ONLY-NAME ::= IDENTIFIER|RENAME-PAIR 5174 EXPLICIT-SOURCE-NAME ::= STRING 5175 RENAME-PAIR ::= ‘(’ IDENTIFIER_{1} IDENTIFIER_{2}‘)’ 5176 5177 A LIBRARY-REFERENCE is mapped to a class name by concatenating all 5178 the identifiers, separated by dots. For example: 5179 (import (gnu kawa slib srfi37)) 5180 is equivalent to: 5181 (import gnu.kawa.slib.srfi37) 5182 as well as to: 5183 (require gnu.kawa.slib.srfi37) 5184 5185 By default, all of an imported library’s exported bindings are made 5186 visible within an importing library using the names given to the 5187 bindings by the imported library. The precise set of bindings to 5188 be imported and the names of those bindings can be adjusted with 5189 the ‘only’, ‘except’, ‘prefix’, and ‘ rename’ forms as described 5190 below. 5191 5192 • An ‘only’ form produces a subset of the bindings from another 5193 IMPORT-SET, including only the listed IDENTIFIERs. The 5194 included IDENTIFIERs must be in the original IMPORT-SET. If a 5195 RENAME-PAIR is used, then the ‘IDENTIFIER_{1}’ must be in the 5196 original IMPORT-SET, and is renamed to ‘IDENTIFIER_{2}’. For 5197 example: 5198 (import (only (kawa example) A (B1 B2) C (D1 D2))) 5199 is equivalent to: 5200 (import (rename (only (kawa example) A B1 C D1) 5201 (B1 B2) (D1 D2))) 5202 The names ‘A’, ‘B1’, ‘C’, and ‘D1’ must exist in the library 5203 ‘(kawa example)’. The bindings are accessible using the names 5204 ‘A’, ‘B2’, ‘C’, and ‘D2’. 5205 5206 • An ‘except’ form produces a subset of the bindings from 5207 another IMPORT-SET, including all but the listed IDENTIFIERs. 5208 All of the excluded IDENTIFIERs must be in the original 5209 IMPORT-SET. 5210 5211 • A ‘prefix’ form adds the IDENTIFIER prefix to each name from 5212 another IMPORT-SET. 5213 5214 • A ‘rename’ form: 5215 (rename (IDENTIFIER_{1} IDENTIFIER_{2}) ...) 5216 removes the bindings for ‘IDENTIFIER_{1} ...’ to form an 5217 intermediate IMPORT-SET, then adds the bindings back for the 5218 corresponding ‘IDENTIFIER_{2} ...’ to form the final 5219 IMPORT-SET. Each ‘IDENTIFIER_{1}’ must be in the original 5220 IMPORT-SET, each IDENTIFIER_{2} must not be in the 5221 intermediate IMPORT-SET, and the IDENTIFIER_{2}s must be 5222 distinct. 5223 5224 A ‘class’ form is a convenient way to define abbreviations for 5225 class names; it may be more convenient than ‘define-alias’. The 5226 CLASS-PREFIX is concatenated with each IDENTIFIER (with a period in 5227 between) to produce a classname. Each IDENTIFIER becomes an alias 5228 for the class. For example: 5229 (import (class java.util Map (HashMap HMap))) 5230 This defines ‘Map’ as an alias for ‘java.util.Map’, and ‘HMap’ as 5231 an alias for ‘java.util.HashMap’. (You can think of the ‘class’ 5232 form as similar to a ‘only’ form, where the CLASS-PREFIX names a 5233 special kind of library represented of a Java package, and whose 5234 exported bindings are the classes in the package.) 5235 5236 You can combine the ‘class’ form with ‘only’, ‘except’, ‘rename’, 5237 and ‘prefix’, though only ‘prefix’ is likely to be useful. For 5238 example: 5239 (import (prefix (class java.lang Long Short) jl-)) 5240 is equivalent to 5241 (import (class java.lang (Long jl-Long) (Short jl-Short))) 5242 which is equivalent to: 5243 (define-private-alias jl-Short java.lang.Short) 5244 (define-private-alias jl-Long java.lang.Long) 5245 5246 -- Syntax: require ‘’’featureName 5247 -- Syntax: require classname [EXPLICIT-SOURCE-NAME] 5248 -- Syntax: require EXPLICIT-SOURCE-NAME] 5249 Search for a matching module (class), and add the names exported by 5250 that module to the current set of visible names. Normally, the 5251 module is specified using CLASSNAME. 5252 5253 The form ‘require’ has similar functionality as ‘import’, but with 5254 a different syntax, and without options like ‘rename’. 5255 5256 If a ‘"SOURCEPATH"’ is specified then that is used to locate the 5257 source file for the module, and if necessary, compile it. 5258 5259 If a ‘'FEATURENAME’ is specified then the FEATURENAME is looked up 5260 (at compile time) in the "feature table" which yields the 5261 implementing CLASSNAME. 5262 5263 -- Syntax: provide ‘’’featurename 5264 Declare that ‘'FEATURENAME’ is available. A following 5265 ‘cond-expand’ in this scope will match FEATURENAME. 5266 5267 Using ‘require’ and ‘provide’ with FEATURENAMEs is similar to the 5268same-named macros in SLib, Emacs, and Common Lisp. However, in Kawa 5269these are not functions, but instead they are syntax forms that are 5270processed at compile time. That is why only quoted FEATURENAMEs are 5271supported. This is consistent with Kawa emphasis on compilation and 5272static binding. 5273 5274 For some examples, you may want to look in the ‘gnu/kawa/slib’ 5275directory. 5276 527719.6.1 Searching for modules 5278---------------------------- 5279 5280When Kawa sees a ‘import’ or ‘require’ it searches for either a matching 5281source file or a previously-compiled class with a matching name. 5282 5283 For ‘import’ we generate a classname by converting it in the same way 5284‘module-name’ does: taking each identifier in the LIBRARY-NAME-PARTS, 5285mangling if needed, and concatenating the parts separated by periods. 5286 5287 If there is a matching module in any PROGRAM-UNIT that is in the 5288process of being compiled, we use that. This may be a file requested to 5289be compiled with the ‘-C’ command-line switch, or an extra 5290LIBRARY-DEFINITION in a file already parsed. Kawa will attempt to 5291finish compiling the module and load the class, but if there are 5292circular dependencies it will use the uncompiled definitions. 5293 5294 Next Kawa looks for a matching class in the context classpath. 5295(There is special handling if the library-name starts with ‘srfi’, and 5296certain builtin classes will have ‘kawa.lib.’ prepended.) 5297 5298 Kawa also searches for a matching source file, described below. It 5299uses the implicit source name (formed by concatenating the library-name 5300parts, separated by ‘"/"’), as well as any EXPLICIT-SOURCE-NAME. The 5301source file is parsed as a PROGRAM-UNIT. It is an error if the 5302PROGRAM-UNIT does not declare a library (explicit or implicit) with the 5303matching name. 5304 5305 If Kawa finds both a matching source file and a class, it will pick 5306one based on which is newer. 5307 530819.6.2 Searching for source files 5309--------------------------------- 5310 5311The Java property ‘kawa.import.path’ controls how ‘import’ and ‘require’ 5312search for a suitable source file. Example usage: 5313 $ kawa -Dkawa.import.path=".:<foo fo>/opt/fo-libs/*.scm:/usr/local/kawa" 5314 5315 The value of the ‘kawa.import.path’ property is a list of path 5316elements, separated by ‘":"’. Each path element is combined with either 5317the explicit source name or the implicit source name to produce a 5318filename. If a matching file exists, then we have found a source file. 5319 5320 If a path element contains a ‘"*"’ then the ‘"*"’ is replaced by the 5321implicit source name (without an extension). (Any explicit source name 5322is ignored in this case.) For example, for ‘(import (foo bar))’ or 5323‘(require foo.bar)’ the implicit source name is ‘"foo/bar"’. If the 5324path element is ‘"/opt/kawa/*.sc"’ then the resulting filename is 5325‘"/opt/kawa/foo/bar.sc"’. 5326 5327 If there is no ‘"*"’ in the path element, and there is an explicit 5328source, then it is appended to the path element (or replaces the path 5329element if the explicit source is absolute). Otherwise we use the 5330implicit source, followed by the default file extension. (The default 5331file extension is that of the current source if that is a named file; 5332otherwise the default for the current language, which is ‘".scm"’ for 5333Scheme.) 5334 5335 A path element that starts with a selector of the form 5336‘"<LIBRARY-NAME-PARTS>"’ is only applicable if a prefix of the requested 5337module name matches the LIBRARY-NAME-PARTS. If there is ‘"*"’ in the 5338path element, that is replaced by the corresponding rest of the implicit 5339source name. For example if importing ‘(fee fo foo fum’) and the path 5340element is ‘"<fee fo>/opt/fo-libs/*.scm"’ then the resulting filename is 5341‘"/opt/fo-libs/foo/fum.scm"’. If there is a selector but no ‘"*"’, then 5342the rest of the path element following the selector is combined with the 5343explicit or implicit source as if there were no selector (assuming of 5344course that the selector matches). 5345 5346 If the resulting filename is relative, then it is resolved relative 5347to the “current root”. For example the source to a library with the 5348name ‘(x y)’ that compiles to a class ‘x.y’ might be a file named 5349‘/a/b/x/y.scm’. Then the current root would be ‘/a/b/’ - that is the 5350directory that results from removing the library name suffix from the 5351file name. 5352 5353 More generally: assume the current module has N name components. For 5354example the name ‘(x y)’ (with the class name ‘x.y’) has 2 components. 5355The current root is what you get when you take the current file name 5356(say ‘"/a/b/c/d.scm"’), and remove everything after the N’th slash 5357(‘"/"’) from the end (say ‘"c/d.scm"’; what remains (e.g. ‘"/a/b/"’ is 5358the current root. (If the current input source is not a named file, use 5359the value of ‘(current-path)’ with a ‘"/"’ appended.) 5360 5361 The default search path is ‘"."’ - i.e. just search relative to the 5362current root. 5363 536419.6.3 Builtin libraries 5365------------------------ 5366 5367The following libraries are bundled with Kawa: 5368 5369‘(scheme base)’ 5370‘(scheme case-lambda)’ 5371‘(scheme char)’ 5372‘(scheme complex)’ 5373‘(scheme cxr)’ 5374‘(scheme cxr)’ 5375‘(scheme eval)’ 5376‘(scheme inexact)’ 5377‘(scheme lazy)’ 5378‘(scheme load)’ 5379‘(scheme process-context)’ 5380‘(scheme read)’ 5381‘(scheme repl)’ 5382‘(scheme time)’ 5383‘(scheme write)’ 5384‘(scheme r5rs)’ 5385 The above are standard libraries as defined by R7RS. 5386‘(rnrs arithmetic bitwise)’ 5387‘(rnrs hashtables)’ 5388‘(rnrs lists)’ 5389‘(rnrs programs)’ 5390‘(rnrs sorting)’ 5391‘(rnrs unicode)’ 5392 The above are standard libraries as defined by R6RS. 5393‘(kawa reflect)’ 5394 Defines procedures and syntax for acessing Java objects and 5395 members: ‘as’ ‘field’ ‘instance?’ ‘invoke’ ‘invoke-static’ 5396 ‘invoke-special’ ‘make’ ‘primitive-throw’ ‘set-field!’ 5397 ‘set-static-field!’ ‘static-field’ 5398‘(kawa expressions)’ 5399‘(kawa hashtable)’ 5400‘(kawa quaternions)’ 5401‘(kawa rotations)’ 5402‘(kawa regex)’ 5403‘(kawa string-cursors)’ 5404 Various Kawa libraries add details. 5405‘(kawa base)’ 5406 All the bindings by default available to the kawa top-level. 5407 540819.6.4 Importing a SRFI library 5409------------------------------- 5410 5411Importing a supported SRFI numbered N is conventionally doing using a 5412‘(import (srfi N))’ or the older R6RS syntax ‘(import (srfi :N))’ (with 5413a colon, for historical reasons). You can also give it a name, as 5414specified by SRFI 95 (http://srfi.schemers.org/srfi-95/srfi-95.html). 5415For example, any of these work: 5416 (import (srfi 95)) 5417 (import (srfi 95 sorting-and-merging)) 5418 (import (srfi :95)) 5419 (import (srfi :95 sorting-and-merging)) 5420 You can also use ‘(require 'srfi-N)’: 5421 (require 'srfi-95) 5422 542319.6.5 Importing from a plain class 5424----------------------------------- 5425 5426Note you can import from many classes, even if they weren’t compiled 5427from a library-definition. The set of ‘public’ fields in a class are 5428considered as the set of exported definitions, with the names demangled 5429as needed. 5430 5431 The module can be static module (all public fields must be static), 5432or an instance module (it has a public default constructor). 5433 5434 If an imported definition is a non-static field and if no module 5435instance for that class has been registered in the current environment, 5436then a new instance is created and registered (using a "magic" 5437identifier). If the module class either inherits from 5438‘gnu.expr.ModuleBody’ or implements ‘java.lang.Runnable’ then the 5439corresponding ‘run’ method is executed. (This is done _after_ the 5440instance is registered so that cycles can be handled.) These actions 5441(creating, registering, and running the module instance) are done both 5442at compile time and at run time, if necessary. 5443 5444 All the imported fields of the module class are then incorporated in 5445the current set of local visible names in the current module. (This is 5446for both instance and static modules.) This is done at compile time - 5447no new bindings are created at run-time (except for the magic binding 5448used to register the module instance), and the imported bindings are 5449private to the current module. References to the imported bindings will 5450be compiled as field references, using the module instance (except for 5451static fields). 5452 5453 5454File: kawa.info, Node: Record types, Next: Dynamic records, Prev: Importing, Up: Objects Classes and Modules 5455 545619.7 Record types 5457================= 5458 5459The ‘define-record-type’ form can be used for creating new data types, 5460called record types. A predicate, constructor, and field accessors and 5461modifiers are defined for each record type. The ‘define-record-type’ 5462feature is specified by SRFI-9 5463(http://srfi.schemers.org/srfi-9/srfi-9.html), which is implemented by 5464many modern Scheme implementations. 5465 5466 -- Syntax: define-record-type TYPE-NAME (CONSTRUCTOR-NAME FIELD-TAG 5467 ...) PREDICATE-NAME (FIELD-TAG ACCESSOR-NAME [MODIFIER-NAME]) 5468 ... 5469 5470 The form ‘define-record-type’ is generative: each use creates a new 5471 record type that is distinct from all existing types, including 5472 other record types and Scheme’s predefined types. Record-type 5473 definitions may only occur at top-level (there are two possible 5474 semantics for ‘internal’ record-type definitions, generative and 5475 nongenerative, and no consensus as to which is better). 5476 5477 An instance of ‘define-record-type’ is equivalent to the following 5478 definitions: 5479 • The TYPE-NAME is bound to a representation of the record type 5480 itself. 5481 • The CONSTRUCTOR-NAME is bound to a procedure that takes as 5482 many arguments as there are FIELD-TAGs in the 5483 ‘(CONSTRUCTOR-NAME ...)’ subform and returns a new TYPE-NAME 5484 record. Fields whose tags are listed with CONSTRUCTOR-NAME 5485 have the corresponding argument as their initial value. The 5486 initial values of all other fields are unspecified. 5487 • The PREDICATE-NAME is a predicate that returns ‘#t’ when given 5488 a value returned by CONSTRUCTOR-NAME and ‘#f’ for everything 5489 else. 5490 • Each ACCESSOR-NAME is a procedure that takes a record of type 5491 TYPE-NAME and returns the current value of the corresponding 5492 field. It is an error to pass an accessor a value which is 5493 not a record of the appropriate type. 5494 • Each MODIFIER-NAME is a procedure that takes a record of type 5495 TYPE-NAME and a value which becomes the new value of the 5496 corresponding field. The result (in Kawa) is the empty value 5497 ‘#!void’. It is an error to pass a modifier a first argument 5498 which is not a record of the appropriate type. 5499 5500 Set!ing the value of any of these identifiers has no effect on the 5501 behavior of any of their original values. 5502 5503 Here is an example of how you can define a record type named ‘pare’ 5504with two fields ‘x’ and ‘y’: 5505 (define-record-type pare 5506 (kons x y) 5507 pare? 5508 (x kar set-kar!) 5509 (y kdr)) 5510 5511 The above defines ‘kons’ to be a constructor, ‘kar’ and ‘kdr’ to be 5512accessors, ‘set-kar!’ to be a modifier, and ‘pare?’ to be a predicate 5513for ‘pare’s. 5514 (pare? (kons 1 2)) ⇒ #t 5515 (pare? (cons 1 2)) ⇒ #f 5516 (kar (kons 1 2)) ⇒ 1 5517 (kdr (kons 1 2)) ⇒ 2 5518 (let ((k (kons 1 2))) 5519 (set-kar! k 3) 5520 (kar k)) ⇒ 3 5521 5522 Kawa compiles the record type into a nested class. If the 5523‘define-record-type’ appears at module level, the result is a class that 5524is a member of the module class. For example if the above ‘pare’ class 5525is define in a module ‘parelib’, then the result is a class named ‘pare’ 5526with the internal JVM name ‘parelib$pare’. The ‘define-record-type’ can 5527appear inside a procedure, in which case the result is an inner class. 5528 5529 The nested class has a name derived from the TYPE-NAME. If the 5530TYPE-NAME is valid Java class name, that becomes the name of the Java 5531class. If the TYPE-NAME has the form ‘<NAME>’ (for example ‘<pare>’), 5532then NAME is used, if possible, for the Java class name. Otherwise, the 5533name of the Java class is derived by "mangling" the TYPE-NAME. In any 5534case, the package is the same as that of the surrounding module. 5535 5536 Kawa generates efficient code for the resulting functions, without 5537needing to use run-time reflection. 5538 5539 5540File: kawa.info, Node: Dynamic records, Next: Method operations, Prev: Record types, Up: Objects Classes and Modules 5541 554219.8 Creating New Record Types On-the-fly 5543========================================= 5544 5545Calling the ‘make-record-type’ procedure creates a new record data type 5546at run-time, without any compile-time support. It is primarily provided 5547for compatibility; in most cases it is better to use the 5548‘define-record-type’ form (*note Record types::). 5549 5550 -- Procedure: make-record-type type-name field-names 5551 Returns a “record-type descriptor”, a value representing a new data 5552 type disjoint from all others. The TYPE-NAME argument must be a 5553 string, but is only used for debugging purposes (such as the 5554 printed representation of a record of the new type). The 5555 FIELD-NAMES argument is a list of symbols naming the “fields” of a 5556 record of the new type. It is an error if the list contains any 5557 duplicates. 5558 5559 -- Procedure: record-constructor rtd [field-names] 5560 Returns a procedure for constructing new members of the type 5561 represented by RTD. The returned procedure accepts exactly as many 5562 arguments as there are symbols in the given list, FIELD-NAMES; 5563 these are used, in order, as the initial values of those fields in 5564 a new record, which is returned by the constructor procedure. The 5565 values of any fields not named in that list are unspecified. The 5566 FIELD-NAMES argument defaults to the list of field names in the 5567 call to ‘make-record-type’ that created the type represented by 5568 RTD; if the FIELD-NAMES argument is provided, it is an error if it 5569 contains any duplicates or any symbols not in the default list. 5570 5571 -- Procedure: record-predicate rtd 5572 Returns a procedure for testing membership in the type represented 5573 by RTD. The returned procedure accepts exactly one argument and 5574 returns a true value if the argument is a member of the indicated 5575 record type; it returns a false value otherwise. 5576 5577 -- Procedure: record-accessor rtd field-name 5578 Returns a procedure for reading the value of a particular field of 5579 a member of the type represented by RTD. The returned procedure 5580 accepts exactly one argument which must be a record of the 5581 appropriate type; it returns the current value of the field named 5582 by the symbol FIELD-NAME in that record. The symbol FIELD-NAME 5583 must be a member of the list of field-names in the call to 5584 ‘make-record-type’ that created the type represented by RTD. 5585 5586 -- Procedure: record-modifier rtd field-name 5587 Returns a procedure for writing the value of a particular field of 5588 a member of the type represented by RTD. The returned procedure 5589 accepts exactly two arguments: first, a record of the appropriate 5590 type, and second, an arbitrary Scheme value; it modifies the field 5591 named by the symbol FIELD-NAME in that record to contain the given 5592 value. The returned value of the modifier procedure is 5593 unspecified. The symbol FIELD-NAME must be a member of the list of 5594 field-names in the call to ‘make-record-type’ that created the type 5595 represented by RTD. 5596 5597 -- Procedure: record? obj 5598 Returns a true value if OBJ is a record of any type and a false 5599 value otherwise. 5600 5601 -- Procedure: record-type-descriptor record 5602 Returns a record-type descriptor representing the type of the given 5603 record. That is, for example, if the returned descriptor were 5604 passed to ‘record-predicate’, the resulting predicate would return 5605 a true value when passed the given record. 5606 5607 -- Procedure: record-type-name rtd 5608 Returns the type-name associated with the type represented by rtd. 5609 The returned value is ‘eqv?’ to the TYPE-NAME argument given in the 5610 call to ‘make-record-type’ that created the type represented by 5611 RTD. 5612 5613 -- Procedure: record-type-field-names rtd 5614 Returns a list of the symbols naming the fields in members of the 5615 type represented by RTD. The returned value is ‘equal?’ to the 5616 field-names argument given in the call to ‘make-record-type’ that 5617 created the type represented by RTD. 5618 5619 Records are extensions of the class ‘Record’. These procedures use 5620the Java 1.1 reflection facility. 5621 5622 5623File: kawa.info, Node: Method operations, Next: Allocating objects, Prev: Dynamic records, Up: Objects Classes and Modules 5624 562519.9 Calling Java methods from Scheme 5626===================================== 5627 5628You can call a Java method as if it were a Scheme procedure using 5629various mechanisms. 5630 563119.9.1 Calling static methods using colon notation 5632-------------------------------------------------- 5633 5634The easiest way to invoke a static method is to use *note colon 5635notation: Colon notation, specifically: 5636 ‘(’CLASS-EXPRESSION‘:’METHOD-NAME ARGUMENT ...‘)’ 5637 5638 The CLASS-EXPRESSION can be a class in the current lexical scope, 5639such as a class defined using ‘define-simple-class’: 5640 (define-simple-class MyClass () 5641 ((add2 x y) allocation: 'static (+ x y))) 5642 (MyClass:add2 3 4) ⇒ 7 5643 5644 Often CLASS-EXPRESSION is a fully-qualified class name: 5645 (java.lang.Math:sqrt 9.0) ⇒ 3.0 5646 5647 This is only allowed when the name is of a class that exists and is 5648accessible both at compile-time and run-time, and the name is not 5649otherwise lexically bound. 5650 5651 You can also use a defined alias: 5652 (define-alias jlMath java.lang.Math) 5653 (jlMath:sqrt 16.0) ⇒ 4.0 5654 5655 You can even evaluate CLASS-EXPRESSION at run-time (in which case 5656Kawa may have to use slower reflection): 5657 (let ((math java.lang.Math)) (math:sqrt 9.0)) ⇒ 3.0 5658 5659 Here ‘java.lang.Math’ evaluates to a ‘java.lang.Class’ instance for 5660the named class (like Java’s ‘java.lang.Class.class’, again assuming the 5661class exists and is accessible both at compile-time and run-time, and 5662the name is not otherwise lexically bound. 5663 566419.9.2 Calling instance methods using colon notation 5665---------------------------------------------------- 5666 5667The syntax is: 5668 ‘(’INSTANCE‘:’METHOD-NAME ARGUMENT ...‘)’ 5669 This invokes the method named METHOD-NAME with the evaluated INSTANCE 5670as the target object and the evaluated ARGUMENTs as the method 5671arguments. 5672 5673 For example: 5674 ((list 9 8 7):toString) ⇒ "(9 8 7)" 5675 ([5 6 7]:get 2) ⇒ 7 5676 5677 This older syntax is also available: 5678 ‘(*:’METHOD-NAME INSTANCE ARGUMENT ...‘)’ 5679 5680 For example: 5681 (*:toString (list 9 8 7)) 5682 5683 You can also name the class explicitly: 5684 ‘(’CLASS-EXPRESSION‘:’METHOD-NAME INSTANCE ARGUMENT ...‘)’ 5685 For example: 5686 (java.util.List:get [5 6 7] 2) ⇒ 7 5687 Using an explicit class is like coercing the INSTANCE: 5688 ‘(*:’METHOD-NAME ‘(as ’CLASS-EXPRESSION INSTANCE ‘)’ARGUMENT ...‘)’ 5689 5690 Note that for some special values, including ‘java.lang.Class’ 5691instances, you can’t use the compact form of *note colon notation: Colon 5692notation. where the INSTANCE is before the comma: 5693 (java.lang.Integer:getDeclaredField "MAX_VALUE") ⇒ error 5694 This is because in this case we look for a static member of 5695‘java.lang.Integer’ (at least as currently defined and implemented), 5696while we want an instance member of ‘java.lang.Class’. In those cases 5697you can use one of these alternative forms, which all return the same 5698‘java.lang.reflect.Field’ result: 5699 (*:getDeclaredField java.lang.Integer "MAX_VALUE") 5700 (java.lang.Class:getDeclaredField java.lang.Integer "MAX_VALUE") 5701 (invoke java.lang.Integer 'getDeclaredField "MAX_VALUE") 5702 570319.9.3 Method names 5704------------------- 5705 5706The method to invoke is selected using the specified method name and 5707argments. If specified name is not a Java name, it is "mangled" (*note 5708Mangling::) into a valid Java name. All accessible methods whose names 5709match are considered. Methods that match after appending ‘$V’ or ‘$X’ 5710or ‘$V$X’ are also considered. A ‘$V’ suffix matches a variable number 5711of arguments: any excess arguments are collect into an ‘gnu.lists.LList’ 5712or a Java array (depending on the final parameter type). A ‘$X’ 5713specifies that the method expects an extra implicit ‘CallContext’ 5714parameter. In that case the method’s result is written to the 5715‘CallContext’, so the method result type must be ‘void’. 5716 5717 (Kawa may compile a procedure with a ‘#!rest’ or keyword args whose 5718name is ‘FN’ to a method named ‘FN$V’. It adds an implicit parameter 5719for the extra arguments. By default this extra extra parameter is a 5720Scheme list. You can specify a Java array type instead, in which case 5721the method is named ‘FN’ without the ‘$V’, and instead it is marked as a 5722Java-5 varargs method. The array element type must be compatible with 5723all the extra arguments.) 5724 572519.9.4 Invoking a method with the ‘invoke’ function 5726--------------------------------------------------- 5727 5728If you prefer, you can instead use the following functions. (There is 5729also an older deprecated lower-level interface (*note Low-level Method 5730invocation::.) 5731 5732 -- Procedure: invoke-static class name args ... 5733 The CLASS can be a ‘java.lang.Class’, a ‘gnu.bytecode.ClassType’, 5734 or a ‘symbol’ or ‘string’ that names a Java class. The NAME can be 5735 ‘symbol’ or ‘string’ that names one or more methods in the Java 5736 class. 5737 5738 Any accessible methods (static or instance) in the specified CLASS 5739 (or its super-classes) that match "NAME" or "NAME$V" collectively 5740 form a generic procedure. When the procedure is applied to the 5741 argument list, the most specific applicable method is chosen 5742 depending on the argument list; that method is then called with the 5743 given arguments. Iff the method is an instance method, the first 5744 actual argument is used as the ‘this’ argument. If there are no 5745 applicable methods (or no methods at all!), or there is no "best" 5746 method, ‘WrongType’ is thrown. 5747 5748 An example: 5749 (invoke-static java.lang.Thread 'sleep 100) 5750 5751 The behavior of interpreted code and compiled code is not 5752 identical, though you should get the same result either way unless 5753 you have designed the classes rather strangely. The details will 5754 be nailed down later, but the basic idea is that the compiler will 5755 "inline" the ‘invoke-static’ call if it can pick a single "best" 5756 matching method. 5757 5758 -- Procedure: invoke object name args ... 5759 The NAME can be ‘<symbol>’ or ‘<string>’ that names one or more 5760 methods in the Java class. 5761 5762 Any accessible methods (static or instance) in the specified CLASS 5763 (or its super-classes) that match "NAME" or "NAME$V" collectively 5764 form a generic procedure. When the procedure is applied to the 5765 argument list, the most specific applicable method is chosen 5766 depending on the argument list; that method is then called with the 5767 given arguments. Iff the method is an instance method, the OBJECT 5768 is used as the ‘this’ argument; otherwise OBJECT is prepended to 5769 the ARGS list. If there are no applicable methods (or no methods 5770 at all!), or there is no "best" method, ‘WrongType’ is thrown. 5771 5772 The behavior of interpreted code and compiled code is not 5773 indentical, though you should get the same result either way unless 5774 you have designed the classes rather strangely. The details will 5775 be nailed down later, but the basic idea is that the compiler will 5776 "inline" the ‘invoke-static’ call if it can pick a single "best" 5777 matching method. 5778 5779 If the compiler cannot determine the method to call (assuming the 5780 method name is constant), the compiler has to generate code at 5781 run-time to find the correct method. This is much slower, so the 5782 compiler will print a warning. To avoid a waning, you can use a 5783 type declaration, or insert a cast: 5784 (invoke (as java.util.Date my-date) 'setDate cur-date) 5785 or 5786 (let ((my-date ::java.util.Date (calculate-date)) 5787 (cur-date ::int (get-cur-date))) 5788 (invoke my-date 'setDate cur-date)) 5789 5790 -- Procedure: invoke-special class receiver-object name arg ... 5791 The CLASS can be a ‘java.lang.Class’, a ‘gnu.bytecode.ClassType’, 5792 or a ‘symbol’ or ‘string’ that names a Java class. The NAME can be 5793 ‘symbol’ or ‘string’ that names one or more methods in the Java 5794 class. 5795 5796 This procedure is very similar to ‘invoke’ and ‘invoke-static’ and 5797 invokes the specified method, ignoring any methods in subclasses 5798 that might overide it. One interesting use is to invoke a method 5799 in your super-class like the Java language ‘super’ keyword. 5800 5801 Any methods in the specified CLASS that match "NAME" or "NAME$V" 5802 collectively form a generic procedure. That generic procedure is 5803 then applied as in ‘invoke’ using the ‘receiver-object’ and the 5804 arguments (if any). 5805 5806 The compiler must be able to inline this procedure (because you 5807 cannot force a specific method to be called using reflection). 5808 Therefore the CLASS and NAME must resolve at compile-time to a 5809 specific method. 5810 5811 (define-simple-class <MyClass> (<java.util.Date>) 5812 ((get-year) :: <int> 5813 (+ (invoke-special <java.util.Date> (this) 'get-year)) 1900) 5814 ((set-year (year :: <int>)) :: <void> 5815 (invoke-special <java.util.Date> (this) 'set-year (- year 1900)))) 5816 5817 -- Procedure: class-methods class name 5818 Return a generic function containing those methods of CLASS that 5819 match the name NAME, in the sense of ‘invoke-static’. Same as: 5820 (lambda args (apply invoke-static (cons class (cons name args)))) 5821 5822 Some examples using these functions are ‘vectors.scm’ and 5823‘characters.scm’ the directory ‘kawa/lib’ in the Kawa sources. 5824 582519.9.5 Using a namespace prefix 5826------------------------------- 5827 5828_This way of invoking a method is deprecated._ 5829 5830 You can use ‘define-namespace’ to define an alias for a Java class: 5831 (define-namespace Int32 "class:java.lang.Integer") 5832 In this example the name ‘Int32’ is a “namespace alias” for the 5833namespace whose full name is ‘"class:java.lang.Integer"’. The full name 5834should be the 6 characters ‘"class:"’ followed by the fully-qualified 5835name of a Java class. 5836 5837 Instead of a VAMESPACE-URI you can use a variable that names a class, 5838usually of the form ‘<CLASSNAME>’. The following is equivalent to the 5839above: 5840 (define-namespace Int32 <java.lang.Integer>) 5841 However, there is one important difference: The ‘<CLASSNAME>’ is 5842first searched in the lexical scope. It may resolve to a class defined 5843in the current compilation unit (perhaps defined using 5844‘define-simple-class’), or imported from another module, or an alias 5845(such as from ‘define-alias’). Only if ‘<CLASSNAME>’ is _not_ found in 5846the current scope is it tried as the class name CLASSNAME. 5847 5848 You can name a method using a “qualified name” containing a colon. 5849The part of the name before the colon is a namespace alias (in this case 5850‘Int32’), and the part of the name after the colon is the method name. 5851For example: 5852 (Int32:toHexString 255) ⇒ "ff" 5853 This invokes the static method ‘toHexString’ in the Java class 5854‘java.lang.Integer’, passing it the argument ‘255’, and returning the 5855String ‘"ff"’. 5856 5857 The general syntax is 5858 (PREFIX:METHOD-NAME ARG ...) 5859 This invokes the method named METHOD-NAME in the class corresponding 5860to PREFIX, and the ARGs are the method arguments. 5861 5862 You can use the method name ‘new’ to construct new objects: 5863 (Int32:new '|255|) 5864 This is equivalent to the Java expression ‘new Integer("255")’. You 5865can also write: 5866 (Int32:new "255") 5867 5868 You can also call instance methods using a namespace prefix: 5869 (Int32:doubleValue (Int32:new "00255")) 5870 This returns the ‘double’ value ‘255.0’. 5871 5872 As a shorthand, you can use the name of a Java class instead of a 5873namespace alias: 5874 (java.lang.Integer:toHexString 255) 5875 (java.lang.Object:toString some-value) 5876 If Kawa sees a qualified name with a prefix that is not defined _and_ 5877that matches the name of a known class, then Kawa will automatically 5878treat the prefix as a nickname for namespace uri like 5879‘class:java.lang.Integer’. Both conditions should be true at both 5880compile-time and run-time. However, using an explicit 5881‘define-namespace’ is recommended. 5882 5883 As a final shorthand you can use an identifier in handle brackets, 5884such as an existing type alias like ‘<list>’. The following are all 5885equivalent: 5886 (<list>:list3 'a 'b 'c) 5887 This is equivalent to: 5888 (define-namespace PREFIX <list> 5889 (PREFIX:list3 'a 'b 'c) 5890 for some otherwise-unused PREFIX. 5891 5892 5893File: kawa.info, Node: Allocating objects, Next: Field operations, Prev: Method operations, Up: Objects Classes and Modules 5894 589519.10 Allocating objects 5896======================== 5897 5898The recommended way to create an instance of a type T is to “call” T as 5899if it were a function, with the arguments used to initialize the object. 5900If ‘T’ is a class and ‘T’ has a matching constructor, then the arguments 5901will used for constructor arguments: 5902 (java.util.StringTokenizer "this/is/a/test" "/") 5903 (You can think of the type T as being coerced to an 5904instance-constructor function.) 5905 5906 If ‘T’ is a container or collection type, then typically the 5907arguments will be used to specify the child or component values. Many 5908standard Scheme procedures fit this convention. For example in Kawa 5909‘list’ and ‘vector’ evaluate to types, rather than procedures as in 5910standard Scheme, but because types can be used as constructor functions 5911it just works: 5912 (list 'a (+ 3 4) 'c) ⇒ (a 7 c) 5913 (vector 'a 'b 'c) ⇒ #(a b c) 5914 Any class ‘T’ that has a default constructor and an ‘add’ method can 5915be initialized this way. Examples are ‘java.util’ collection classes, 5916and ‘jawa.awt’ and ‘javax.swing’ containers. 5917 (java.util.ArrayList 11 22 33) ⇒ [11, 22, 333] 5918 The above expression is equivalent to: 5919 (let ((tmp (java.util.ArrayList))) 5920 (tmp:add 11) 5921 (tmp:add 22) 5922 (tmp:add 33) 5923 tmp) 5924 5925 Allocating Java arrays (*note Creating-new-Java-arrays::) uses a 5926similar pattern: 5927 (int[] 2 3 5 7 11) 5928 5929 Sometimes you want to set some named property to an initial value. 5930You can do that using a keyword argument. For example: 5931 (javax.swing.JButton text: "Do it!" tool-tip-text: "do it") 5932 5933 This is equivalent to using “setter methods”: 5934 (let ((tmp (javax.swing.JButton))) 5935 (tmp:setText "Do it!") 5936 (tmp:setToolTipText "do it") 5937 tmp) 5938 5939 A keyword argument ‘KEY-NAME’‘:’ can can translated to either a 5940‘setKEYNAME:’ or a ‘addKEYNAME:’ method. The latter makes it convenient 5941to add listeners: 5942 5943 (javax.swing.JButton 5944 text: "Do it!" 5945 action-listener: 5946 (object (java.awt.event.ActionListener) 5947 ((actionPerformed e) (do-the-action)))) 5948 This is equivalent to: 5949 (let ((tmp (javax.swing.JButton))) 5950 (tmp:setText "Do it!") 5951 (tmp:addActionListener 5952 (object (java.awt.event.ActionListener) 5953 ((actionPerformed e) (do-the-action)))) 5954 tmp) 5955 5956 Making use of so-called “SAM-conversion” (*note SAM-conversion::) 5957makes it even more convenient: 5958 (javax.swing.JButton 5959 text: "Do it!" 5960 action-listener: 5961 (lambda (e) (do-the-action))) 5962 5963 The general case allows for a mix of constructor arguments, property 5964keywords, and child values: 5965 CLASS-TYPE CONSTRUCTOR-VALUE... PROPERTY-INITIALIZER... CHILD-VALUE... 5966 CONSTRUCTOR-VALUE ::= EXPRESSION 5967 PROPERTY-INITIALIZER ::= KEYWORD EXPRESSION 5968 CHILD-VALUE ::= EXPRESSION 5969 5970 First an object is constructed with the CONSTRUCTOR-VALUE arguments 5971(if any) passed to the object constructor; then named properties (if 5972any) are used to initialize named properties; and then remaining 5973arguments are used to add child values. 5974 5975 There is an ambiguity if there is no PROPERTY-INITIALIZER - we can’t 5976distinguish between a CONSTRUCTOR-VALUE and a CHILD-VALUE. In that 5977case, if there is a matching constructor method, then all of the 5978arguments are constructor arguments; otherwise, there must a default 5979constructor, and all of the arguments are CHILD-VALUE arguments. 5980 5981 There is a trick you can you if you need both CONSTRUCTOR-VALUE and 5982CHILD-VALUE arguments: separate them with an “empty keyword” ‘||:’. 5983This matches a method named ‘add’, which means that the next argument 5984effectively a CHILD-VALUE - as do all the remaining arguments. Example: 5985 (let ((vec #(1 2 3))) 5986 (java.util.ArrayList vec ||: 4 5 6)) 5987 ⇒ [1, 2, 3, 4, 5, 6] 5988 5989 The compiler rewrites these allocations expression to generated 5990efficient bytecode, assuming that the “function” being applied is a type 5991known by the compiler. Most of the above expressions also work if the 5992type is applied at run-time, in which case Kawa has to use slower 5993reflection: 5994 (define iarr int[]) 5995 (apply iarr (list 3 4 5)) ⇒ [3 4 5] 5996 However ‘addXXX’ methods and SAM-conversion are currently only 5997recognized in the case of a class known at compile-time, not at 5998run-time. 5999 6000 Here is a working Swing demo illustrating many of these techniques: 6001 6002 (import (class javax.swing 6003 JButton Box JFrame)) 6004 (define-simple-class HBox (Box) 6005 ((*init*) (invoke-special Box (this) '*init* 0))) 6006 6007 (define value 0) 6008 6009 (define txt 6010 (javax.swing.JLabel 6011 text: "0")) 6012 6013 (define (set-value i) 6014 (set! value i) 6015 (set! txt:text (number->string i))) 6016 6017 (define fr 6018 (JFrame 6019 title: "Hello!" 6020 (Box 1#|VERTICAL|# ||: 6021 (javax.swing.Box:createGlue) 6022 txt 6023 (javax.swing.Box:createGlue) 6024 (HBox 6025 (JButton ;; uses 1-argument constructor 6026 "Decrement" ;; constructor argument 6027 tool-tip-text: "decrement" 6028 action-listener: (lambda (e) (set-value (- value 1)))) 6029 (javax.swing.Box:createGlue) 6030 (JButton ;; uses 0-argument constructor 6031 text: "Increment" 6032 tool-tip-text: "increment" 6033 action-listener: (lambda (e) (set-value (+ value 1)))))))) 6034 (fr:setSize 200 100) 6035 (set! fr:visible #t) 6036 6037 If you prefer, you can use the older ‘make’ special function: 6038 6039 -- Procedure: make type args ... 6040 Constructs a new object instance of the specified TYPE, which must 6041 be either a ‘java.lang.Class’ or a ‘<gnu.bytecode.ClassType>’. 6042 Equivalent to: 6043 TYPE ARGS ... 6044 6045 Another (semi-deprecated) function is to use the colon notation with 6046the ‘new’ pseudo-function. The following three are all equivalent: 6047 (java.awt.Point:new x: 4 y: 3) 6048 (make java.awt.Point: x: 4 y: 3) 6049 (java.awt.Point x: 4 y: 3) 6050 6051 6052File: kawa.info, Node: Field operations, Next: Mangling, Prev: Allocating objects, Up: Objects Classes and Modules 6053 605419.11 Accessing object fields 6055============================= 6056 605719.11.1 Accessing static fields and properties 6058---------------------------------------------- 6059 6060The recommmended way to access fields uses the *note colon notation: 6061Colon notation. For static fields and properties the following is 6062recommended: 6063 CLASS-EXPRESSION‘:’FIELD-NAME 6064 For example: 6065 java.lang.Integer:MAX_VALUE 6066 6067 A property with a ‘get’ method is equivalent to a field. The 6068following are all equivalent: 6069 java.util.Currency:available-currencies 6070 java.util.Currency:availableCurrencies 6071 (java.util.Currency:getAvailableCurrencies) 6072 6073 Just like for a method call, the CLASS-EXPRESSION can be a class in 6074the current lexical scope, a fully-qualified class name, or more 6075generally an expression that evaluates to a class. 6076 607719.11.2 Accessing instance fields and properties 6078------------------------------------------------ 6079 6080The syntax is: 6081 INSTANCE‘:’FIELD-NAME 6082 6083 The FIELD-NAME can of course be the name of an actual object field, 6084but it can also be the name of a property with a zero-argument ‘get’ 6085method. For example, if ‘cal’ is a ‘java.util-Calendar’ instance, then 6086the following are all equivalent: 6087 cal:time-zone 6088 cal:timeZone 6089 (cal:getTimeZone) 6090 (cal:get-time-zone) 6091 6092 You can use colon notation to assign to a field: 6093 (set! cal:time-zone TimeZone:default) 6094 which is equivalent to: 6095 (cal:setTimeZone (TimeZone:getDefault)) 6096 6097 A Java array only has the ‘length’ field, plus the ‘class’ property: 6098 (int[] 4 5 6):length ⇒ 3 6099 (int[] 4 5 6):class:name ⇒ "int[]" 6100 610119.11.3 Using field and static-field methods 6102-------------------------------------------- 6103 6104The following methods are useful in cases where colon notation is 6105ambiguous, for example where there are both fields and methods with the 6106same name. You might also prefer as a matter of style, to emphasise 6107that a field is being accessed. 6108 6109 -- Procedure: field object fieldname 6110 Get the instance field with the given FIELDNAME from the given 6111 OBJECT. Returns the value of the field, which must be accessible. 6112 This procedure has a ‘setter’, and so can be used as the first 6113 operand to ‘set!’. 6114 6115 The field name is "mangled" (*note Mangling::) into a valid Java 6116 name. If there is no accessible field whose name is ‘"FIELDNAME"’, 6117 we look for a no-argument method whose name is ‘"getFIELDNAME"’ (or 6118 ‘"isFIELDNAME"’ for a boolean property). 6119 6120 If OBJECT is a primitive Java array, then FIELDNAME can only be 6121 ‘'length’, and the result is the number of elements of the array. 6122 6123 -- Procedure: static-field class fieldname 6124 Get the static field with the given FIELDNAME from the given CLASS. 6125 Returns the value of the field, which must be accessible. This 6126 procedure has a ‘setter’, and so can be used as the first operand 6127 to ‘set!’. 6128 6129 If the FIELDNAME is the special name ‘class’, then it returns the 6130 ‘java.lang.Class’ object corresponding to CLASS (which is usually a 6131 ‘gnu.bytecode.ClassType’ object). 6132 6133 Examples: 6134 (static-field java.lang.System 'err) 6135 ;; Copy the car field of b into a. 6136 (set! (field a 'car) (field b 'car)) 6137 6138 -- Procedure: slot-ref object fieldname 6139 A synonym for ‘(field OBJECT FIELDNAME)’. 6140 6141 -- Procedure: slot-set! object fieldname value 6142 A synonym for ‘(set! (field OBJECT FIELDNAME) VALUE)’. 6143 614419.11.4 Older colon-dot notation 6145-------------------------------- 6146 6147There is older syntax where following the colon there is field name a 6148following the colon _and_ a period. 6149 6150 To access an static field named FIELD-NAME use this syntax 6151 (PREFIX:.FIELD-NAME INSTANCE) 6152 The PREFIX can be as discussed in *Note Method operations::. Here 6153are 5 equivalent ways: 6154 (java.lang.Integer:.MAX_VALUE) 6155 (<java.lang.Integer>:.MAX_VALUE) 6156 (define-namespace Int32 <java.lang.Integer>) 6157 (Int32:.MAX_VALUE) 6158 (define-namespace Integer "class:java.lang.Integer") 6159 (Integer:.MAX_VALUE) 6160 (define-alias j.l.Integer java.lang.Integer) 6161 (j.l.Integer:.MAX_VALUE) 6162 You can set a static field using this syntax: 6163 (set! (PREFIX:.FIELD-NAME) NEW-VALUE) 6164 6165 The special field name ‘class’ can be used to extract the 6166‘java.lang.Class’ object for a class-type. For example: 6167 (java.util.Vector:.class) ⇒ class java.util.Vector 6168 6169 To access a instance field named FIELD-NAME use the following syntax. 6170Note the period before the FIELD-NAME. 6171 (*:.FIELD-NAME INSTANCE) 6172 This syntax works with ‘set!’ - to set the field use this syntax: 6173 (set! (*:.FIELD-NAME INSTANCE) NEW-VALUE) 6174 Here is an example: 6175 (define p (list 3 4 5)) 6176 (*:.cdr p) ⇒ (4 5) 6177 (set! (*:.cdr p) (list 6 7)) 6178 p ⇒ (3 6 7) 6179 6180 You can specify an explicit class: 6181 (PREFIX:.FIELD-NAME INSTANCE) 6182 If PREFIX is bound to ‘<CLASS>’, then the above is equivalent to: 6183 (*:.FIELD-NAME (as <CLASS> INSTANCE)) 6184 6185 6186File: kawa.info, Node: Mangling, Next: Scheme types in Java, Prev: Field operations, Up: Objects Classes and Modules 6187 618819.12 Mapping Scheme names to Java names 6189======================================== 6190 6191Programs use "names" to refer to various values and procedures. The 6192definition of what is a "name" is different in different programming 6193languages. A name in Scheme (and other Lisp-like languages) can in 6194principle contain any character (if using a suitable quoting 6195convention), but typically names consist of "words" (one or more 6196letters) separated by hyphens, such as ‘make-temporary-file’. Digits 6197and some special symbols are also used. Traditionally, Scheme is 6198case-insensitive; this means that the names ‘loop’, ‘Loop’, and ‘LOOP’ 6199are all the same name. Kawa is by default case-sensitive, but we 6200recommend that you avoid using upper-case letters as a general rule. 6201 6202 The Java language and the Java virtual machine uses names for 6203classes, variables, fields and methods. Names in the Java language can 6204contain upper- and lower-case letters, digits, and the special symbols 6205‘_’ and ‘$’. The Java virtual machine (JVM) allows most characters, but 6206still has some limitations. 6207 6208 Kawa translates class names, package names, field names, and local 6209variable names using the ”symbolic” convention 6210(https://blogs.oracle.com/jrose/entry/symbolic_freedom_in_the_vm), so 6211most characters are unchanged. For example the Scheme function 6212‘file-exists?’ becomes the field ‘file-exists?’, but ‘dotted.name’ 6213becomes ‘dotted\,name’. Such names may not be valid Java name, so to 6214access them from a Java program you might have to use reflection. 6215 6216 When translating procedure names to method names, Kawa uses a 6217different translation, in order to achieve more “Java-like” names. This 6218means translating a Scheme-style name like ‘make-temporary-file’ to 6219"mixed-case" words, such as ‘makeTemporaryFile’. The basic rule is 6220simple: Hyphens are dropped, and a letter that follows a hyphen is 6221translated to its upper-case (actually "title-case") equivalent. 6222Otherwise, letters are translated as is. 6223 6224 Some special characters are handled specially. A final ‘?’ is 6225replaced by an _initial_ ‘is’, with the following letter converted to 6226titlecase. Thus ‘number?’ is converted to ‘isNumber’ (which fits with 6227Java conventions), and ‘file-exists?’ is converted to ‘isFileExists’ 6228(which doesn’t really). The pair ‘->’ is translated to ‘$To$’. For 6229example ‘list->string’ is translated to ‘list$To$string’. 6230 6231 Some symbols are mapped to a mnemonic sequence, starting with a 6232dollar-sign, followed by a two-character abbreviation. For example, the 6233less-than symbol ‘<’ is mangled as ‘$Ls’. See the source code to the 6234‘mangleName’ method in the ‘gnu.expr.Mangling’ class for the full list. 6235Characters that do not have a mnemonic abbreviation are mangled as ‘$’ 6236followed by a four-hex-digit unicode value. For example ‘Tamil vowel 6237sign ai’ is mangled as ‘$0bc8’. 6238 6239 Note that this mapping may map different Scheme names to the same 6240Java name. For example ‘string?’, ‘String?’, ‘is-string’, ‘is-String’, 6241and ‘isString’ are all mapped to the same Java identifier ‘isString’. 6242Code that uses such "Java-clashing" names is _not_ supported. There is 6243very partial support for renaming names in the case of a clash, and 6244there may be better support in the future. However, some of the nice 6245features of Kawa depend on being able to map Scheme name to Java names 6246naturally, so we urge you to _not_ write code that "mixes" naming 6247conventions by using (say) the names ‘open-file’ and ‘openFile’ to name 6248two different objects. 6249 6250 6251File: kawa.info, Node: Scheme types in Java, Next: Array operations, Prev: Mangling, Up: Objects Classes and Modules 6252 625319.13 Scheme types in Java 6254========================== 6255 6256All Scheme values are implemented by sub-classes of ‘java.lang.Object’. 6257 6258 Scheme symbols are implemented using ‘java.lang.String’. (Don’t be 6259confused by the fact the Scheme sybols are represented using Java 6260Strings, while Scheme strings are represented by ‘gnu.lists.FString’. 6261It is just that the semantics of Java strings match Scheme symbols, but 6262do not match mutable Scheme strings.) Interned symbols are presented as 6263interned Strings. (Note that with JDK 1.1 string literals are 6264automatically interned.) 6265 6266 Scheme integers are implemented by ‘gnu.math.IntNum’. Use the make 6267static function to create a new IntNum from an int or a long. Use the 6268intValue or longValue methods to get the int or long value of an IntNum. 6269 6270 A Scheme "flonum" is implemented by ‘gnu.math.DFloNum’. 6271 6272 A Scheme pair is implemented by ‘gnu.lists.Pair’. 6273 6274 A Scheme vector is implemented by ‘gnu.lists.FVectror’. 6275 6276 Scheme characters are implemented using ‘gnu.text.Char’. 6277 6278 Scheme strings are implemented using ‘gnu.lists.FString’. 6279 6280 Scheme procedures are all sub-classes of ‘gnu.mapping.Procedure’. 6281The "action" of a ‘Procedure’ is invoked by using one of the ‘apply*’ 6282methods: ‘apply0’, ‘apply1’, ‘apply2’, ‘apply3’, ‘apply4’, or ‘applyN’. 6283Various sub-class of ‘Procedure’ provide defaults for the various 6284‘apply*’ methods. For example, a ‘Procedure2’ is used by 2-argument 6285procedures. The ‘Procedure2’ class provides implementations of all the 6286‘apply*’ methods _except_ ‘apply2’, which must be provided by any class 6287that extends ‘Procedure2’. 6288 6289 6290File: kawa.info, Node: Array operations, Next: Loading Java functions into Scheme, Prev: Scheme types in Java, Up: Objects Classes and Modules 6291 629219.14 Using Java Arrays 6293======================= 6294 629519.14.1 Creating new Java arrays 6296-------------------------------- 6297 6298To allocate a Java array you can use the array type specifier as a 6299constructor function. For example, to allocate an array with room for 630010 elements each of each is a primitive ‘int’: 6301 (int[] length: 10) 6302 6303 You can specify the initial elements instead of the length: 6304 (object[] 31 32 33 34) 6305 This creates a 4-length array, initialized to the given values. 6306 6307 Note this is a variation of the generation object-allocation (*note 6308Allocating objects::) pattern. You can explicitly use the ‘make’ 6309function, if you prefer: 6310 (make object[] 31 32 33 34) 6311 6312 If you specify a length, you can also specify initial values for 6313selected elements. If you specify an index, in the form of a literal 6314integer-valued keyword, then following elements are placed starting at 6315that position. 6316 (int[] length: 100 10 12 80: 15 16 50: 13 14) 6317 This creates an array with 100 elements. Most of them are 6318initialized to the default value of zero, but elements with indexes 0, 63191, 50, 51, 80, 81 are initialized to the values 10, 12, 13, 14, 15, 16, 6320respectively. 6321 632219.14.2 Accessing Java array elements 6323------------------------------------- 6324 6325You can access the elements of a Java array by treating it as a 6326one-argument function, where the argument is the index: 6327 (define primes (integer[] 2 3 5 7 11 13)) 6328 (primes 0) ⇒ 2 6329 (primes 5) ⇒ 13 6330 6331 You can set an element by treating the array as a function with a 6332‘setter’: 6333 (set! (primes 0) -2) 6334 (set! (primes 3) -7) 6335 primes ⇒ [-2 3 5 -7 11 13] 6336 6337 To get the number of elements of an array, you can treat it as having 6338a ‘length’ field: 6339 primes:length ⇒ 6 6340 6341 Here is a longer example. This is the actual definition of the 6342standard ‘gcd’ function. Note the ‘args’ variable receives all the 6343arguments on the form of an ‘integer’ array. (This uses the Java5 6344varargs feature.) 6345 (define (gcd #!rest (args ::integer[])) ::integer 6346 (let ((n ::int args:length)) 6347 (if (= n 0) 6348 0 6349 (let ((result ::integer (args 0))) 6350 (do ((i ::int 1 (+ i 1))) 6351 ((>= i n) result) 6352 (set! result (gnu.math.IntNum:gcd result (args i)))))))) 6353 6354 The above example generates good code, thanks to judicious use of 6355casts and type specifications. In general, if Kawa knows that a 6356“function” is an array then it will generate efficient bytecode 6357instructions for array operations. 6358 635919.14.3 Old low-level array macros 6360---------------------------------- 6361 6362The deprecated *note Low-level array macros:: are also supported. 6363 6364 6365File: kawa.info, Node: Loading Java functions into Scheme, Next: Evaluating Scheme expressions from Java, Prev: Array operations, Up: Objects Classes and Modules 6366 636719.15 Loading Java functions into Scheme 6368======================================== 6369 6370When ‘kawa -C’ compiles (*note Files compilation::) a Scheme module it 6371creates a class that implements the ‘java.lang.Runnable’ interface. 6372(Usually it is a class that extends the ‘gnu.expr.ModuleBody’.) It is 6373actually fairly easy to write similar "modules" by hand in Java, which 6374is useful when you want to extend Kawa with new "primitive functions" 6375written in Java. For each function you need to create an object that 6376extends ‘gnu.mapping.Procedure’, and then bind it in the global 6377environment. We will look at these two operations. 6378 6379 There are multiple ways you can create a ‘Procedure’ object. Below 6380is a simple example, using the ‘Procedure1’ class, which is class 6381extending ‘Procedure’ that can be useful for one-argument procedure. 6382You can use other classes to write procedures. For example a 6383‘ProcedureN’ takes a variable number of arguments, and you must define 6384‘applyN(Object[] args)’ method instead of ‘apply1’. (You may notice 6385that some builtin classes extend ‘CpsProcedure’. Doing so allows has 6386certain advantages, including support for full tail-recursion, but it 6387has some costs, and is a bit trickier.) 6388 6389 import gnu.mapping.*; 6390 import gnu.math.*; 6391 public class MyFunc extends Procedure1 6392 { 6393 // An "argument" that is part of each procedure instance. 6394 private Object arg0; 6395 6396 public MyFunc(String name, Object arg0) 6397 { 6398 super(name); 6399 this.arg0 = arg0; 6400 } 6401 6402 public Object apply1 (Object arg1) 6403 { 6404 // Here you can so whatever you want. In this example, 6405 // we return a pair of the argument and arg0. 6406 return gnu.lists.Pair.make(arg0, arg1); 6407 } 6408 } 6409 6410 You can create a ‘MyFunc’ instance and call it from Java: 6411 Procedure myfunc1 = new MyFunc("my-func-1", Boolean.FALSE); 6412 Object aresult = myfunc1.apply1(some_object); 6413 The name ‘my-func-1’ is used when ‘myfunc1’ is printed or when 6414‘myfunc1.toString()’ is called. However, the Scheme variable 6415‘my-func-1’ is still not bound. To define the function to Scheme, we 6416can create a "module", which is a class intended to be loaded into the 6417top-level environment. The provides the definitions to be loaded, as 6418well as any actions to be performed on loading 6419 6420 public class MyModule 6421 { 6422 // Define a function instance. 6423 public static final MyFunc myfunc1 6424 = new MyFunc("my-func-1", IntNum.make(1)); 6425 } 6426 6427 If you use Scheme you can use ‘require’: 6428 #|kawa:1|# (require <MyModule>) 6429 #|kawa:2|# (my-func-1 0) 6430 (1 0) 6431 6432 Note that ‘require’ magically defines ‘my-func-1’ without you telling 6433it to. For each public final field, the name and value of the field are 6434entered in the top-level environment when the class is loaded. (If 6435there are non-static fields, or the class implements ‘Runnable’, then an 6436instance of the object is created, if one isn’t available.) If the 6437field value is a ‘Procedure’ (or implements ‘Named’), then the name 6438bound to the procedure is used instead of the field name. That is why 6439the variable that gets bound in the Scheme environment is ‘my-func-1’, 6440not ‘myfunc1’. 6441 6442 Instead of ‘(require <MyModule>)’, you can do ‘(load "MyModule")’ or 6443‘(load "MyModule.class")’. If you’re not using Scheme, you can use 6444Kawa’s ‘-f’ option: 6445 $ kawa -f MyModule --xquery -- 6446 #|kawa:1|# my-func-1(3+4) 6447 <list>1 7</list> 6448 6449 If you need to do some more complex calculations when a module is 6450loaded, you can put them in a ‘run’ method, and have the module 6451implement ‘Runnable’: 6452 6453 public class MyModule implements Runnable 6454 { 6455 public void run () 6456 { 6457 Interpreter interp = Interpreter.getInterpreter(); 6458 Object arg = Boolean.TRUE; 6459 interp.defineFunction (new MyFunc ("my-func-t", arg)); 6460 System.err.println("MyModule loaded"); 6461 } 6462 } 6463 6464 Loading ‘MyModule’ causes ‘"MyModule loaded"’ to be printed, and 6465‘my-func-t’ to be defined. Using ‘Interpreter’’s ‘defineFunction’ 6466method is recommended because it does the righ things even for languages 6467like Common Lisp that use separate "namespaces" for variables and 6468functions. 6469 6470 A final trick is that you can have a ‘Procedure’ be its own module: 6471 6472 import gnu.mapping.*; 6473 import gnu.math.*; 6474 public class MyFunc2 extends Procedure2 6475 { 6476 public MyFunc(String name) 6477 { 6478 super(name); 6479 } 6480 6481 public Object apply2 (Object arg1, arg2) 6482 { 6483 return gnu.lists.Pair.make(arg1, arg2); 6484 } 6485 6486 public static final MyFunc myfunc1 = new MyFunc("my-func-2); 6487 } 6488 6489 6490File: kawa.info, Node: Evaluating Scheme expressions from Java, Prev: Loading Java functions into Scheme, Up: Objects Classes and Modules 6491 649219.16 Evaluating Scheme expressions from Java 6493============================================= 6494 6495The following methods are recommended if you need to evaluate a Scheme 6496expression from a Java method. (Some details (such as the ‘throws’ 6497lists) may change.) 6498 6499 -- Static method: void Scheme.registerEnvironment () 6500 Initializes the Scheme environment. Maybe needed if you try to 6501 load a module compiled from a Scheme source file. 6502 6503 -- Static method: Object Scheme.eval (InPort PORT, Environment ENV) 6504 Read expressions from PORT, and evaluate them in the ENV 6505 environment, until end-of-file is reached. Return the value of the 6506 last expression, or ‘Interpreter.voidObject’ if there is no 6507 expression. 6508 6509 -- Static method: Object Scheme.eval (String STRING, Environment ENV) 6510 Read expressions from STRING, and evaluate them in the ENV 6511 environment, until the end of the string is reached. Return the 6512 value of the last expression, or ‘Interpreter.voidObject’ if there 6513 is no expression. 6514 6515 -- Static method: Object Scheme.eval (Object SEXPR, Environment ENV) 6516 The SEXPR is an S-expression (as may be returned by ‘read’). 6517 Evaluate it in the ENV environment, and return the result. 6518 6519 For the ‘Environment’ in most cases you could use 6520‘Environment.current()’. Before you start, you need to initialize the 6521global environment, which you can do with 6522 Environment.setCurrent(new Scheme().getEnvironment()); 6523 6524 Alternatively, rather than setting the global environment, you can 6525use this style: 6526 Scheme scm = new Scheme(); 6527 Object x = scm.eval("(+ 3 2)"); 6528 System.out.println(x); 6529 653019.16.1 Using ‘javax.script’ portable Java scripting 6531---------------------------------------------------- 6532 6533Kawa also supports the standard ‘javax.script’ 6534(http://docs.oracle.com/javase/8/docs/api/javax/script/package-summary.html) 6535API. The main advantage of this API is if you want your users to be able 6536to choose between multiple scripting languages. That way you can 6537support Kawa without Kawa-specific programming. 6538 6539 For example the standard JDK tool jrunscript 6540(http://docs.oracle.com/javase/8/docs/technotes/tools/unix/jrunscript.html) 6541provides a read-eval-print-loop for any language that implements the 6542‘javax.script’ API. It knows nothing about Kawa but can still use it: 6543 $ jrunscript -cp kawa.jar -l scheme 6544 scheme> (cadr '(3 4 5)) 6545 4 6546 6547 (Of course the ‘jrunscript’ REPL isn’t as nice as the one that Kawa 6548provides. For example the latter can handle multi-line inputs.) 6549 6550 6551File: kawa.info, Node: XML tools, Next: Miscellaneous, Prev: Objects Classes and Modules, Up: Top 6552 655320 Working with XML and HTML 6554**************************** 6555 6556Kawa has a number of features for working with XML, HTML, and generated 6557web pages. 6558 6559 In Kawa you don’t write XML or HTML directly. Instead you write 6560expressions that evaluate to “node objects” corresponding to elements, 6561attributes, and text. You then write these node objects using either an 6562XML or HTML format. 6563 6564 Many web-page-generating tools require you to work directly with raw 6565HTML, as for example: 6566 (display "<p>Don't use the <code><blink></code> tag.</p>") 6567 6568 In Kawa you would instead do: 6569 (display (html:p "Don't use the " (html:code "<blink>") " tag.")) 6570 6571 The conversion from node objects to XML or HTML is handled by the 6572formatter (or serializer). Some advantages of doing it this way are: 6573 • You don’t have to worry about quoting special characters. Missing 6574 or incorrect quoting is a common source of bugs and security 6575 problems on systems that work directly with text, such as PHP. 6576 • Some errors, such as mismatched element tags, are automatically 6577 avoided. 6578 • The generated XML can be validated as it is generated, or even 6579 using compile-time type-checking. (Kawa doesn’t yet do either.) 6580 • In an application that also reads XML, you can treat XML that is 6581 read in and XML that is generated using the same functions. 6582 6583* Menu: 6584 6585* Formatting XML:: 6586* Creating HTML nodes:: 6587* Creating XML nodes:: 6588* XML literals:: 6589* Server-side scripts:: Writing web-server-side Kawa scripts 6590* Self-configuring page scripts:: 6591* Servlets:: Installing Kawa programs as Servlets 6592* CGI scripts:: Installing Kawa programs as CGI scripts 6593* HTTP requests:: Functions for accessing HTTP requests 6594* HTTP response:: Functions for generating HTTP response 6595* XML beyond Scheme:: Using non-Scheme languages for XML/HTML 6596 6597 6598File: kawa.info, Node: Formatting XML, Next: Creating HTML nodes, Up: XML tools 6599 660020.1 Formatting XML 6601=================== 6602 6603The easiest way to generate HTML or XML output is to run Kawa with the 6604appropriate *note ‘--output-format’ option: Named output formats. 6605 6606 The intentation is that these output modes should be compatible with 6607XSLT 2.0 and XQuery 1.0 Serialization 6608(http://www.w3.org/TR/2006/PR-xslt-xquery-serialization-20061121/). 6609(However, that specifies many options, most of which have not yet been 6610implemented. 6611 6612‘xml’ 6613 Values are printed in XML format. "Groups" or "elements" are 6614 written as using xml element syntax. Plain characters (such as 6615 ‘<’) are escaped (such as ‘<’). 6616‘xhtml’ 6617 Same as ‘xml’, but follows the xhtml compatibility guidelines. 6618‘html’ 6619 Values are printed in HTML format. Mostly same as ‘xml’ format, 6620 but certain elements without body, are written without a closing 6621 tag. For example ‘<img>’ is written without ‘</img>’, which would 6622 be illegal for html, but required for xml. Plain characters (such 6623 as ‘<’) are not escaped inside ‘<script>’ or ‘<style>’ elements. 6624 6625 To illustrate: 6626 $ kawa --output-format html 6627 #|kawa:1|# (html:img src:"img.jpg") 6628 <img src="img.jpg"> 6629 $ kawa --output-format xhtml 6630 #|kawa:1|# (html:img src:"img.jpg") 6631 <img xmlns="http://www.w3.org/1999/xhtml" src="img.jpg" /> 6632 $ kawa --output-format xml 6633 #|kawa:1|# (html:img src:"img.jpg") 6634 <img xmlns="http://www.w3.org/1999/xhtml" src="img.jpg"></img> 6635 And here is the default ‘scheme’ formatting: 6636 $ kawa 6637 #|kawa:1|# (html:img src:"img.jpg") 6638 ({http://www.w3.org/1999/xhtml}img src: img.jpg ) 6639 6640 -- Procedure: as-xml value 6641 Return a value (or multiple values) that when printed will print 6642 VALUE in XML syntax. 6643 (require 'xml) 6644 (as-xml (make-element 'p "Some " (make-element 'em "text") ".")) 6645 prints ‘<p>Some <em>text</em>.</p>’. 6646 6647 -- Procedure: unescaped-data data 6648 Creates a special value which causes ‘data’ to be printed, as is, 6649 without normal escaping. For example, when the output format is 6650 XML, then printing ‘"<?xml?>"’ prints as ‘<?xml?>’, but 6651 ‘(unescaped-data "<?xml?>")’ prints as ‘<?xml?>’. 6652 6653
