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: Top, Next: Installation, Prev: (dir), Up: (dir) 9 10The Kawa Scheme language 11************************ 12 13Kawa is a general-purpose programming language that runs on the Java 14platform. It aims to combine: 15 • the benefits of dynamic scripting languages (non-verbose code with 16 less boiler-plate, fast and easy start-up, a REPL 17 (http://en.wikipedia.org/wiki/Read-eval-print_loop), no required 18 compilation step); with 19 • the benefits of traditional compiled languages (fast execution, 20 static error detection, modularity, zero-overhead Java platform 21 integration). 22 It is an extension of the long-established Scheme 23(http://www.schemers.org/) language, which is in the Lisp family of 24programming languages. Kawa has many *note useful features: Features. 25 26 Kawa is also a useful *note framework: Framework. for implementing 27other programming languages on the Java platform. It has many useful 28utility classes. 29 30 This manual describes version 3.1.1, updated 16 January 2020. See 31the summary of *note recent changes: News. 32 33 The Kawa home page (which is currently just an on-line version of 34this document) is <http://www.gnu.org/software/kawa/>. 35 36 The *note Kawa tutorial: Tutorial. is useful to get stated. While it 37is woefully incomplete, it does link to some other more in-depth (but 38not Kawa-specific) Scheme tutorials. 39 40 For copyright information on the software and documentation, see 41*note License::. 42 43 Various people and orgnizations *note have contributed to Kawa: 44Acknowledgements. 45 46 This package has nothing to do with the defunct Kawa commercial Java 47IDE. 48 49* Menu: 50 51* News:: News - Recent Changes 52* Features:: 53* Community:: 54* Installation:: Building and installing Kawa 55* Tutorial:: Kawa Scheme Tutorial 56* Running:: Invoking, Running, and Using Kawa 57* Syntax:: 58* Program structure:: 59* Control features:: 60* Symbols and namespaces:: 61* Procedures:: 62* Numbers:: Quantities and Numbers 63* Characters and text:: 64* Data structures:: 65* Eval and Environments:: 66* Debugging:: 67* Input-Output:: Input, output, and file handling 68* Types:: 69* Objects Classes and Modules:: 70* XML tools:: XML, HTML, and the web 71* Miscellaneous:: 72* FAQs:: Frequently Asked Questions 73* Framework:: The Kawa language framework 74* License:: 75* Overall Index:: Index of functions, macros, concepts, and more. 76 77 78File: kawa.info, Node: News, Next: Features, Up: Top 79 801 News - Recent Changes 81*********************** 82 83These changes are in more-or-less reverse chronological order, with the 84most recent changes first. 85 86 See also the list of Qexo (XQuery)-specific changes 87(../qexo/news.html). 88 89Kawa 3.1.1 (January 16, 2020) 90----------------------------- 91 92 • Various bug-fixes, mostly related to packaging and 93 ‘--browse-manual’. 94 95Kawa 3.1 (January 7, 2020) 96-------------------------- 97 98 • Updates for Java 9 and newer. 99 • Support justification ~‘<’...‘~>’ in ‘format’ (thanks to Helmut 100 Eller). 101 • Partial (and highly experimental) support for the Language Server 102 Protocol (https://langserver.org) (used by editors and IDEs for 103 on-the-fly syntax checking and more). 104 • Revert 3.0 change in allocating closure objects for inlined 105 functions. 106 • Enhancements to arrays to match SRFI 163 107 (http://srfi.schemers.org/srfi-163/srfi-163.html) and SRFI 164 108 (http://srfi.schemers.org/srfi-163/srfi-164.html): 109 • The type ‘gvector’ is a “generalized vector”. 110 • Add optional port parameter to ‘format-array’. 111 • The ‘build-array’ procedure takes an optional setter 112 procedure. 113 • New procedures ‘array-shape’, ‘->shape’. 114 • In array constructors, index keywords must be all or none: ‘[int[] 115 length: 5 11 22]’ or ‘[int[] length: 5 1: 22 0: 11]’. 116 • Various improvements in the Common Lisp implementation, by Helmut 117 Eller. 118 • New ‘--max-errors’ option. 119 • The classes created by ‘define-record-type’ now extends 120 ‘kawa.lang.Record’, which adds some conveniences, such as printing. 121 • Support for source location ranges with an end position. 122 • Various improvements when running under DomTerm include clickable 123 error message locations. 124 • Many bug-fixes and minor improvements. 125 126Kawa 3.0 (October 2, 2017) 127-------------------------- 128 129 • Binary release are now built for Java 8. The repository source 130 code is now set up for Java 8. (Building for Java 6 or 7 is still 131 supported. Java 5 might also work, but has not been tested 132 recently.) 133 • Tested and updated for Java 9. 134 • Most places where you could declare a new identifier binding have 135 been generalized to accept *note patterns: Variables and Patterns, 136 including literals and boolean GUARDs. 137 138 Related changes: 139 • The form ‘(! PATTERN EXPRESSION)’ creates *note variable 140 bindings: exclam-syntax. by matching the EXPRESSION against 141 the PATTERN. It is like ‘define-constant’ but generalized to 142 patterns. 143 144 • The conditional match form ‘(? PATTERN EXPRESSION)’ is similar 145 to ‘!’ but can only be used *note in conditional context: 146 Conditionals. If the match fails, the condition is false. 147 148 • *note Repeat patterns and forms: Repeat forms. is a powerful 149 experimental feature, similar to list comprehensions. 150 151 • The new form *note ‘match’: def-match. form is a 152 generalization of ‘case’ using patterns. 153 • The internal calling convention used for “apply” (ie. calling 154 an unknown-at-compile-time procedure) has been completely 155 changed. 156 • New types for arguments list (possibly with keywords) *note 157 ‘arglist’ and ‘argvector’: Explicit argument list objects. 158 along with *note an API: Argument list library. for using 159 them. 160 • Major changes to strings: 161 • _Incompatible change:_ String literals are now 162 ‘gnu.lists.IString’ rather than ‘java.lang.String’. The 163 advantage of using ‘gnu.lists.IString’ is that ‘string-ref’ 164 and ‘string-length’ are (roughly) constant-time, rather than 165 having to linearly scan the string. 166 • _Incompatible change:_ The procedures ‘string-append’, 167 ‘string-map’, ‘substring’, ‘list->string’, ‘vector->string’, 168 ‘string-downcase’, ‘string-upcase’, ‘string-foldcase’, 169 ‘string-titlecase’, and the constructor ‘string’ return an 170 immutable string (an ‘IString’). (The function ‘string-copy’ 171 is similar to ‘substring’, but returns a mutable string.) 172 This is a work-in-progress with the goal of implementing 173 SRFI-140 (http://srfi.schemers.org/srfi-140/srfi-140.html): 174 Other procedures will be changed to return immutable strings. 175 176 If you ‘(import (scheme base))’ standard procedures such as 177 ‘string-append’ will return mutable strings; if you ‘(import 178 (kawa base))’ the procedures will return immutable strings. 179 The command-line options ‘--r5rs’ or ‘--r6rs’ or ‘--r7rs’ 180 override the default so these procedures return mutable 181 strings. 182 • _Incompatible change:_ Treating a string as a sequence is now 183 simpler but possibly slower: The I’th element is now the I’th 184 Unicode code point. Indexing with function-call syntax 185 ‘(STRING I)’ is the same as ‘(string-ref STRING I)’ and 186 ‘(length STRING)’ is the same as ‘(string-length STRING)’. 187 This applies to all classes that implement 188 ‘java.lang.CharSequence’. Indexing may be a linear-time 189 operation (thus much slower), unless the string is an 190 ‘IString’ (in which case it is constant-time), 191 • _Incompatible change:_ Before, if a Java parameter type was 192 ‘java.lang.String’ Kawa would accept any value, converting it 193 using Object’s ‘toString’ method. Now Kawa will reject an 194 argument if it is not a ‘java.lang.CharSequence’. 195 • New procedures: ‘istring?’, ‘reverse-list->string’, 196 ‘string-any’, ‘string-concatenate’, 197 ‘string-concatenate-reverse’, ‘string-contains’, 198 ‘string-contains-right’, ‘string-count’, ‘string-drop’, 199 ‘string-drop-right’, ‘string-every’, ‘string-filter’, 200 ‘string-fold’, ‘string-fold-right’, ‘string-for-each-index’, 201 ‘string-index’, ‘string-index-right’, ‘string-join’, 202 ‘string-map-index’, ‘string-null?’, ‘string-prefix?’, 203 ‘string-prefix-length’, ‘string-repeat’, ‘string-remove’, 204 ‘string-replace’, ‘string-skip’, ‘string-skip-right’, 205 ‘string-split’, ‘string-suffix?’, ‘string-suffix-length’, 206 ‘string-tabulate’, ‘string-take’, ‘string-take-right’, 207 ‘string-trim’, ‘string-trim-right’, ‘string-trim-both’, 208 ‘string-unfold’, ‘string-unfold-right’, ‘string->utf16’, 209 ‘string->utf16be’, ‘string->utf16le’, ‘utf16->string’, 210 ‘utf16be->string’, ‘utf16le->string’, ‘xsubstring’. These 211 follow SRFI-140 and return immutable strings. (Some of these 212 had previously been available in SRFI-13, but the older 213 versions return mutable strings.) 214 • _Incompatible change:_ Kawa traditionally followed Java in allowing 215 you to pass an array with the “rest” arguments to a varargs method. 216 For example, you could write: 217 218 (define args (Object[] 3 "cm")) 219 (java.lang.String:format "length:%s%s" args) 220 221 This is no longer allowed. Instead, use the splice operator: 222 223 (java.lang.String:format "length:%s%s" @args) 224 • _Incompatible change:_ You used to be able to write a 225 type-specifier in a formal parameter or return type without using 226 ‘::’, as in: 227 (define (incr (x int)) int (+ x 1)) 228 This is no longer allowed, because it conflicts with the syntax for 229 patterns. Instead you have to write: 230 (define (incr (x ::int)) ::int (+ x 1)) 231 • New type aliases ‘bitvector’ and ‘c16vector’. The latter is a 232 *note uniform vector: Uniform vectors. type for wrapping ‘char[]’ 233 arrays. 234 • You can convert a Java array (for example a ‘int[]’ to the 235 corresponing uniform vector type (for example ‘u32vector’) using 236 the ‘as’ pseudo-function or the corresponding conversion procedure 237 (for example ‘->u32vector’). The result shares storage with the 238 array, so changes in one will update the other. 239 • The expression ‘(module-class)’ evaluates to the containing module 240 class. 241 • Change the *note mangling: Mangling. for field and local variables 242 names to match the Symbolic Freedom 243 (https://blogs.oracle.com/jrose/entry/symbolic_freedom_in_the_vm) 244 style. 245 • Internally, expressions now record their ending position 246 (line/column), in addition to the starting position. 247 • The new procedure ‘environment-fold’ can be used to iterate over 248 the bindings of an environment. 249 • Change in how closure objects are allocated for inlined functions. 250 This sometimes reduces the number of objection allocations and also 251 of helper classes, though in pathological cases it could cause 252 objects to be retained (leak) where it didn’t before. 253 254 • New command-line flag ‘--warn-uninitialized’ (by default on) to 255 control warning about using uninitialized variables. 256 • The pre-defined *note character sets: Character sets. are now based 257 on Java 9’s Unicode 8 support. 258 259Kawa 2.4 (April 30, 2017) 260------------------------- 261 262 • Final 2.x release. Minor updates and fixes. 263 264Kawa 2.3 (January 13, 2017) 265--------------------------- 266 267 • Moved Kawa’s source code repository (version control system) to use 268 git, hosted at GitLab (https://gitlab.com/kashell/Kawa). 269 • Issues (bugs, feature requests, etc) should now be reported using 270 the GitLab Issue Tracker (https://gitlab.com/kashell/Kawa/issues). 271 • New ‘with-docbook-stylesheets’ to make it easier to build the 272 documentation with better functionality and look. 273 • The command-line option ‘console:jline-mouse=yes’ enables moving 274 the input cursor using a mouse click, when using JLine in the REPL 275 on common xterm-like terminals. This is disabled by default 276 because it conflicts with other mouse actions, such as making a 277 selection for copying text. You can press shift to get the 278 terminal’s standard mouse handling. 279 280Kawa 2.2 (November 12, 2016) 281---------------------------- 282 283 • A binary release is no longer just a Kawa ‘.jar’ file, but is now a 284 ‘zip’ archive that also includes shell/batch scripts for running 285 Kawa, useful third-party libraries, and the complete documentation 286 in EPUB format. The archives are named ‘kawa-version.zip’. 287 • The ‘kawa --browse-manual’ switch makes it easy to *note browse the 288 local documentation: browse-manual-option. 289 • The *note ‘(kawa pictures’) library: Composable pictures. lets you 290 create “picture” objects, display them, transform them, combine 291 them, and more. 292 • There is a new *note API for pretty-printing: Pretty-printing. 293 • Basic support for Java 9 (though still some issues). 294 • Generated files like ‘Makefile.in’ and ‘configure’ are no longer in 295 the Subversion source code repository, though they are still 296 included in the distributed ‘kawa-version.tar.gz’ releases. The 297 new top-level script ‘autogen.sh’ should be run before ‘configure’. 298 • Kawa traditionally followed Java in allowing you to pass an array 299 with the "rest" arguments to a varargs method. (A "varargs" method 300 includes Java varargs methods, as well as Kawa methods with a 301 ‘#!rest’ parameter that is explicitly typed to be an array type.) 302 For example, you could write: 303 304 (define args (Object[] 3 "cm")) 305 (java.lang.String:format "length:%s%s" args) 306 307 This is deprecated, and may stop working in a future release. 308 Instead, use the splice operator: 309 310 (java.lang.String:format "length:%s%s" @args) 311 312 • More options for *note range objects: Ranges. For example, you can 313 write ‘[1 by: 2 <=: 9]’. 314 315 • Many enhancements to *note arrays: Arrays. and vectors: 316 317 • Shape specifiers (used when creating an array) can now be one 318 of a rank-2 array of low/high-bounds, as in SRFI-25; a vector 319 of upper bounds; or a vector of ranges. 320 • New type specifiers for array: ‘array’ is any array (i.e. any 321 ‘gnu.lists.Array’); ‘arrayN’ is the same restricted to rank 322 ‘N’; ‘array[etype]’ or ‘arrayN[etype]’ restrict the types of 323 elements to ‘etype’. 324 325 If the ‘etype’ is a primitive type (for example 326 ‘array2[double]’) then indexing is optimized to method calls 327 that avoid object allocation. 328 329 • Generalized array indexing: If A is an array (or a vector), 330 then the expression: 331 ‘(A I J K ...)’ 332 in general evaluates to an array B such that: 333 ‘(B i1 i2 ... j1 j2 ... k1 k2 ... ...)’ is 334 ‘(A (I i1 i2 ..) (J j1 j2 ...) (K k1 k2 ...) ...)’ 335 336 If an index I is an integer, it is treated as a zero-index 337 array - a scalar. 338 339 For example: if ‘(define B (A 2 [4 <: 10]))’ then ‘(B i)’ is 340 ‘(A 2 (+ i 4))’. 341 342 • The procedure ‘array-index-ref’ is does the above indexing 343 explicitly: ‘(array-index-ref A I J K ...)’ is ‘(A I J K 344 ...)’. The result is a read-only snapshot. 345 • The procedure ‘array-index-share’ is like ‘array-index-ref’ 346 but creates a modifiable view into argument array. 347 • ‘(build-array shape procedure)’ is a general constructor for 348 lazy arrays: If ‘A’ is the result, then ‘(A i j k ...)’ is 349 ‘(procedure [I J K ...])’. 350 • ‘array-transform’ creates a view, with a mapping of the 351 indexes. 352 • Other new procedures (like those in the Racket math package): 353 ‘array-size’, ‘array-fill!’, ‘array-copy!’, ‘array-transform’, 354 ‘array-reshape’, ‘array-flatten’, ‘array->vector’, 355 ‘index-array’, ‘build-array’. 356 • Add Common Lisp array reader syntax (‘#rankA’) with Guile 357 extensions 358 (https://www.gnu.org/software/guile/manual/html_node/Array-Syntax.html), 359 including reader sypport for multi-dimensional uniform 360 (primitive) arrays. This is also used when printing arrays. 361 • New ‘format-array’ procedure print an array a tabular 362 2-dimensional (APL-like) format. This format is used by 363 default in the top-level of the REPL. 364 365 • Print bit-vectors using the Common Lisp (and Guile) reader syntax. 366 For example ‘#*1100110’. Enhanced the reader to read this format. 367 368 • Various REPL enhancements and new features: 369 370 • The ‘-w’ switch to create a new REPL window can be followed by 371 various sub-options to control _how_ and where the window is 372 created. For example ‘-wbrowser’ creates a new window using 373 your default web browser. 374 • Prompts are now normally specified using ‘printf’-style 375 templates. The normal prompt template is specified by the 376 ‘input-prompt1’ variable, while continuation lines use 377 ‘input-prompt2’. These can be initialized by command-line 378 options ‘console:prompt1’ and ‘console:prompt2’, or otherwise 379 use language-specific defaults. You can still use 380 ‘set-input-port-prompter!’ to set a more general 381 prompt-procedure, but it is now only called for the initial 382 line of a command, not continuation lines. 383 • The new ‘--with-jline3’ configure option builds support for 384 the JLine (version 3) (https://github.com/jline/jline3) 385 library for handling console input, similar to GNU readline. 386 • Context-dependent command-completion (tab-completion) works 387 when using JLine. 388 389 • Various REPL enhancements when using DomTerm (http://domterm.org/). 390 • If you “print” an XML/HTML node, it gets inserted into the 391 DomTerm objects. You print images, tables, fancy text, and 392 more. 393 • If you “print” a picture object or a ‘BuferredImage’ the 394 picture is shown in the DomTerm console. 395 • You can load or modify styles with the 396 ‘domterm-load-stylesheet’ procedure. 397 • When pretty-printing, calculation of line-breaks and 398 indentation is handled by DomTerm. If you change the window 399 width, DomTerm will dynamically re-calculate the line-breaks 400 of previous pretten output. This works even in the case of a 401 session saved to an HTML file, as long as JavaScript is 402 enabled. 403 • Hide/show buttons are emitted as part of the default prompt. 404 • Multiple literals that have the same value (as in ‘equal?’) get 405 compiled to the same object. 406 • The syntax ‘&<[expr]’ is now equivalent to ‘&<{&[expr]}’, assuming 407 ‘expr’ is an expression that evaluates to a string that named an 408 existing file. That file is read is the result is the contents of 409 the file (as if by ‘(path-data expr)’). 410 411Kawa 2.1 (October 26, 2015) 412--------------------------- 413 414Lots of little changes, and some big changes to sequences and strings. 415 416 • Enhancements to the Kawa tutorial. 417 • Added ‘parameter’ as a new typename, for Scheme parameter objects. 418 It can be parameterized (for example ‘parameter[string]’) for 419 better type inference when "calling" (reading) the parameter. 420 • We now define “interactive mode” as a REPL or a source module that 421 uses the default global top-level environment _or_ a source module 422 imported/required by a interactive module. Interactive mode 423 attempts to support dynamic re-definition and re-loading of 424 function and other definitions. This is a work-in-progres; 425 interactive mode currently uses extra indirection to support 426 re-definitions (at a slight performance cost). 427 • Various changes and fixes in Path/URI handling. Most 428 significantly, the resolve argorithm used by ‘resolve-uri’ was 429 re-written to use the algorithm from RFC-3986, rather than the 430 obsolete RFC-2396 algorithm used by ‘java.net.URI.resolve’. 431 • Change to mangle class and package name in Symbolic Freedom 432 (https://blogs.oracle.com/jrose/entry/symbolic_freedom_in_the_vm) 433 style. This means that class names and class filenames usually 434 match the source file, even if special charaters are used, except 435 for a small number of disallowed characters. Note this is 436 currently _only_ used for class and package names. 437 • Allow ‘'synchronized’ and ‘'strictfp’ as access flags for methods. 438 • You can now have a type-specifier for ‘define-variable’. 439 440 • Better support for forward references between macros. 441 442 • Added unsigned primitive integer types ‘ubyte’, ‘ushort’, ‘uint’, 443 and ‘ulong’. These are represented at run-time by the 444 corresponding signed types, but Kawa generates code to do unsigned 445 arithmethic and comparisons. Corresponding boxed classes are 446 ‘gnu.math.UByte’, ‘gnu.math.UShort’, ‘gnu.math.UInt’, and 447 ‘gnu.math.ULong’. 448 449 • Improvements and unification of sequences and strings: 450 451 • The new ‘sequence’ type generalizes lists, vectors, arrays, 452 strings, and more. It is implemented as the ‘java.util.List’ 453 interface, but strings (‘java.lang.CharSequence’) and Java 454 arrays are compatible with ‘sequence’ and converted as needed. 455 • The ‘length’ function is generalized to arbitrary sequences. 456 (For strings it uses the ‘CharSequence.length’ method, which 457 returns the number of (16-bit) code units. This is different 458 from the ‘string-length’ function, which returns the number of 459 Unicode code points.) 460 • A new pseudo-character value ‘#\ignorable-char’ is introduced. 461 It is ignored in string-construction contexts. 462 • The function-call syntax for indexing works for all sequences. 463 If the sequence is a string, the result is the Unicode 464 (20-bit) scalar value at the specified index. If index 465 references the trailing surrogate of a surrogate pair the 466 result is ‘#\ignorable-char’. This allows efficient indexing 467 of strings: Handing of surrogate pairs are handled 468 automatically as long as ‘#\ignorable-char’ is skipped. 469 • Indexing of uniform vector types (such as ‘s64vector’ or 470 ‘f64vector’ or ‘u16vector’) now return the “standard” 471 primitive type (such as ‘long’ or ‘double’) or the new 472 unsigned primitive (such as ‘ushort’). This improves 473 performance (since we can generally use primitive types), and 474 improves compatibility with Java arrays. Specifically, 475 ‘s64vector’ now implements ‘Sequence<Long>’, and thus 476 ‘java.util.List<Long>’ Note that indexing a ‘f64vector’ 477 returns a ‘double’ which as an object is a ‘java.lang.Double’, 478 not the Kawa floating-point type ‘gnu.math.DFloNum’. The 479 result is usually the same, but ‘eqv?’ might return a 480 different result than previously. 481 • The arguments to ‘map’, ‘for-each’, and ‘vector-for-each’ can 482 now be any sequence (including strings and native arrays). 483 The arguments to ‘vector-for-each’ can now be arbitrary 484 ‘java.util.List’ values. All of these are inlined. If the 485 sequence type is known, more efficient custom code is 486 generated. 487 488 • A range represents an enumerable sequence, normally integers, 489 but it is represented compactly using the start value, the 490 step (usually 1), and size. There is a new convenient syntax 491 for writing a range: if ‘i’ and ‘j’ are integers then ‘[i <=: 492 j]’ is the sequence of integers starting at ‘i’ and ending at 493 ‘j’ (inclusive). You can also write ‘[i <=: j]’ (excludes the 494 upper bound), ‘[i >: j]’ (counts down to ‘j’, exclusive), and 495 ‘[i >=: j]’ (counts down to ‘j’, inclusive). 496 • You can use a sequences of integers to index a sequence. The 497 result is the sequence of the selected elements. In general 498 ‘(seq [i0 ... in])’ is ‘[(seq i0) ... (seq in)]’. This work 499 well with ranges: ‘(seq [i <: j])’ is the subsequence of ‘seq’ 500 from ‘i’ to ‘j’ (exclusive). 501 502 If the ‘seq’ is a string (a ‘CharSequence’) then the result is 503 also a string. In this case the indexing behavior is slightly 504 different in that indexing selects (16-bit) code units, which 505 are combined to a string. 506 507 • A new ‘dynamic’ type is like ‘Object’. However, it forces runtime 508 lookup and type-checking, and supresses compile-time type check and 509 errors. (This is similar to C#. It is useful as an escape hatch 510 if we ever implement traditional strict static type-checking.) 511 • Specifying the parameter type or return type of a function or 512 method without a ’‘::’’ is deprecated and results in a warning. 513 514 • In ‘--r7rs’ mode: The ’‘l’’ exponent suffix of a number literal 515 creates a floating-point double, rather than a ‘BigInteger’. 516 • Added the hyperbolic functions: sinh, cosh, tanh, asinh, acosh, 517 atanh. 518 • The ‘equal?’ function can now handle cyclic lists and vectors. So 519 can ‘equal-hash’. 520 • The command-line option ‘--with-arg-count=N’ allows finer control 521 of command-line-processing. It is used before an “action”, and 522 specifies the ‘N’ arguments following the action are set as the 523 command-line-arguments. After the action, command-line-processing 524 continues following those ‘N’ arguments. 525 • Added the R6RS module ‘(rnrs arithmetic bitwise)’. 526 • The ‘kawa.repl’ argument processor now handles ‘-D’ options. 527 • The new ‘class’ sub-form of ‘import’ allows you to import classes, 528 and give them abbreviated names, like the Java ‘import’ statement. 529 The new form is more compact and convenient than ‘define-alias’. 530 531 You can also use a classname directly, as a symbol, instead of 532 writing it in the form of a list: 533 534 (import (only java.lang.Math PI)) 535 536 • In the ‘only’ clause of the ‘import’ syntax you can now directly 537 rename, without having to write a ‘rename’ clause. 538 • Changes in the calling-convention for ‘--full-tailcalls’ yields a 539 substantial speed-up in some situations. 540 • The type of boolean literals ‘#f’ and ‘#t’ is now primitive 541 ‘boolean’ rather than ‘java.lang.Boolean’. 542 • General multi-dimensional arrays can be indexed with function call 543 notation. E.g. ‘(arr i j k)’ is equivalent to ‘(array-ref a i j 544 k)’. You can also use ‘set!’ with either ‘array-ref’ or function 545 call notation. 546 • The ‘#!null’ value (Java ‘null’) is now considered false, not true. 547 Likewise for non-canonical false Boolean objects (i.e. all 548 instances of ‘java.lang.Boolean’ for which ‘booleanValue’ returns 549 false, not just ‘Boolean.FALSE’). 550 551 • New standard libraries ‘(kawa base)’ and ‘(kawa reflect)’. 552 • You can now use patterns in the ‘let’ form and related forms. 553 554 • Implemented the lambda lifting 555 (http://en.wikipedia.org/wiki/Lambda_lifting) optimzation. 556 • An expression that has type T is now considered compatible with a 557 context requiring an interface type I only if T implements I (or T 558 is Object). (Before they were considered possibly-compatible if T 559 was non-final because the run-time class might be a subclass of T 560 that implements I.) 561 • New ‘--console’ flag forces input to be treated as an interactive 562 console, with prompting. This is needed on Windows under Emacs, 563 where ‘System.console()’ gives the wrong result. 564 • You can now in a sub-class reference fields from not-yet-compiled 565 super-classes. (This doesn’t work for methods yet.) 566 • The ‘(? name::type value)’ operator supports conditional binding. 567 The ‘(! name::type value)’ operator supports unconditional binding; 568 it is similar to ‘define-constant’, but supports patterns. 569 570 • More efficient implementation of ‘call-with-values’: If either 571 argument is a fixed-arity lambda expression it is inlined. Better 572 type-checking of both ‘call-with-values’ and ‘values’. 573 574 • Jamison Hope enhanced the support for quaternions, primarily the 575 new ‘(kawa rotations)’ library. 576 577Kawa 2.0 (December 2 2014) 578-------------------------- 579 580There are many new features, but the big one is R7RS compatibility. 581 582 • New ‘define-alias’ can define aliases for static class members. 583 • The treatment of keywords is changing to not be self-evaluating (in 584 Scheme). If you want a literal keyword, you should quote it. 585 Unquoted keywords should only be used for keyword arguments. (This 586 will be enforced in a future release.) The compiler now warns 587 about badly formed keyword arguments, for example if a value is 588 missing following a keyword. 589 • The default is now Java 7, rather than Java 6. This means the 590 checked-in source code is pre-processed for Java 7, and future 591 binary releases will require Java 7. 592 • The behavior of parameters and fluid variables has changed. 593 Setting a parameter no longer changes its value in already-running 594 sub-threads. The implementation is simpler and should be more 595 efficient. 596 597 • The form ‘define-early-constant’ is similar to ‘define-constant’, 598 but it is evaluated in a module’s class initializer (or constructor 599 in the case of a non-static definition). 600 • Almost all of R7RS is now working: 601 602 • Importing a SRFI library can now use the syntax ‘(import (srfi 603 N [name]))’ 604 • The various standard libraries such as ‘(scheme base)’ are 605 implemented. 606 • The functions ‘eval’ and ‘load’ can now take an 607 environment-specifier. Implemented the ‘environment’ 608 function. 609 • Extended ‘numerator’, ‘denominator’, ‘gcd’, and ‘lcm’ to 610 inexacts. 611 • The full R7RS library functionality is working, including 612 ‘define-library’ The keyword ‘export’ is now a synonym for 613 ‘module-export’, and both support the ‘rename’ keyword. The 614 ‘prefix’ option of ‘import’ now works. 615 616 • The ‘cond-expand’ form now supports the ‘library’ clause. 617 • Implemented ‘make-promise’ and ‘delay-force’ (equivalent to 618 the older name ‘lazy’). 619 • Changed ‘include’ so that by default it first seaches the 620 directory containing the included file, so by default it has 621 the same effect as ‘include-relative’. However, you can 622 override the search path with the ‘-Dkawa.include.path’ 623 property. Also implemented ‘include-ci’. 624 • Implemented ‘define-values’. 625 • Fixed ‘string->number’ to correctly handle a radix specifier 626 in the string. 627 • The ‘read’ procedure now returns mutable pairs. 628 • If you need to use ‘...’ in a ‘syntax-rules’ template you can 629 use ‘(... template)’, which disables the special meaning of 630 ‘...’ in ‘template’. (This is an extension of the older ‘(... 631 ...)’.) 632 • Alternatively, you can can write ‘(syntax-rules dots 633 (literals) rules)’. The symbol ‘dots’ replaces the 634 functionality of ‘...’ in the ‘rules’. 635 • An underscore ‘_’ in a ‘syntax-rules’ pattern matches 636 anything, and is ignored. 637 • The ‘syntax-error’ syntax (renamed from ‘%syntax-error’) 638 allows error reporting in ‘syntax-rules’ macros. (The older 639 Kawa-specific ‘syntax-error’ procedure was renamed to 640 ‘report-syntax-error’.) 641 • Implemented and documented R7RS exception handling: The syntax 642 ‘guard’ and the procedures ‘with-exception-handler’, ‘raise’, 643 and ‘raise-continuable’ all work. The ‘error’ procedure is 644 R7RS-compatible, and the procedures ‘error-object?’, 645 ‘error-object-message’, ‘error-object-irritants’, 646 ‘file-error?’, and ‘read-error?’ were implemented. 647 648 • Implemented ‘emergency-exit’, and modified ‘exit’ so 649 finally-blocks are executed. 650 651 • Implemented ‘exact-integer?’, ‘floor/’, ‘floor-quotient’, 652 ‘floor-remainder’, ‘truncate/’, ‘truncate-quotient’, and 653 ‘truncate-remainder’. 654 • The ‘letrec*’ syntax is now supported. (It works the same as 655 ‘letrec’, which is an allowed extension of ‘letrec’.) 656 657 • The functions ‘utf8->string’ and ‘string->utf8’ are now 658 documented in the manual. 659 660 • The changes to characters and strings are worth covering 661 separately: 662 663 • The ‘character’ type is now a new primitive type (implemented 664 as ‘int’). This can avoid boxing (object allocation) 665 • There is also a new ‘character-or-eof’. (A union of 666 ‘character’ and the EOF value, except the latter is encoded as 667 -1, thus avoiding object allocation.) The functions read-char 668 and ‘peek-char’ now return a ‘character-or-eof’ value. 669 • Functions like ‘string-ref’ that take a character index would 670 not take into account non-BMP characters (those whose value is 671 greater than ‘#xffff’, thus requiring two surrogate 672 characters). This was contrary to R6RS/R7RS. This has been 673 fixed, though at some performance cost . (For example 674 ‘string-ref’ and ‘string-length’ are no longer constant-time.) 675 • Implemented a ‘string-cursor’ API 676 (Strings.html#String-Cursor-API) (based on Chibi Scheme). 677 Thes allow efficient indexing, based on opaque cursors 678 (actually counts of 16-bits ‘char’s). 679 • Optimized ‘string-for-each’, which is now the preferred way to 680 iterate through a string. 681 • Implemented ‘string-map’. 682 • New function ‘string-append!’ for in-place appending to a 683 mutable string. 684 • New function ‘string-replace!’ for replacing a substring of a 685 string with some other string. 686 • The SRFI-13 function ‘string-append/shared’ is no longer 687 automatically visible; you have to ‘(import (srfi :13 688 strings))’ or similar. 689 690 • The ‘module-name’ form allows the name to be a list, as in a 691 R6RS/R7RS-style library name. 692 • The syntax ‘@expression’ is a _splicing form_. The ‘expression’ 693 must evaluate to a sequence (vector, list, array, etc). The 694 function application or constructor form is equivalent to all the 695 elements of the sequence. 696 • The parameter object ‘current-path’ returns (or sets) the default 697 directory of the current thread. 698 • Add convenience procedures and syntax for working with processes 699 (Processes.html): ‘run-process’, ‘process-exit-wait’, 700 ‘process-exit-ok?’, ‘&cmd’, ‘&`’, ‘&sh’. 701 • The functions ‘path-bytes’, and ‘path-data’ can read or write the 702 entire contents of a file 703 (http://www.gnu.org/software/kawa/Reading-and-writing-whole-files.html). 704 Alternatively, you can use the short-hand syntax: ‘&<{pname}’ 705 ‘&>{pname}’ ‘&>>{pname}’. These work with "blobs" which may be 706 text or binary depending on context. 707 • The initial values of ‘(current-output-port)’ and 708 ‘(current-error-port)’ are now hybrid textual/binary ports. This 709 means you can call ‘write-bytevector’ and ‘write-u8’ on them, 710 making it possible for an application to write binary data to 711 standard output. Similarly, initial value of 712 ‘(current-input-port)’ is a hybrid textual/binary port, but only if 713 there is no console (standard input is not a tty). 714 715 • Jamison Hope contributed support for quaternions 716 (http://en.wikipedia.org/wiki/Quaternion), a generalization of 717 complex numbers containing 4 real components. 718 719 • Andrea Bernardini contributed an optimized implementation of ‘case’ 720 expressions. He was sponsored by Google Summer of Code. 721 • The ‘kawa.sh’ shell script (which is installed as ‘kawa’ when _not_ 722 configuring with ‘--enable-kawa-frontend’) now handles ‘-D’ and 723 ‘-J’ options. The ‘kawa.sh’ script is now also built when usint 724 Ant. 725 • The ‘cond-expand’ features ‘java-6’ though ‘java-9’ are now set 726 based on the ‘System’ property ‘"java.version"’ (rather than how 727 Kawa was configured). 728 • An Emacs-style ‘coding’ declaration allows you to specify the 729 encoding of a Scheme source file. 730 • The command-line option ‘--debug-syntax-pattern-match’ prints 731 logging importation to standard error when a ‘syntax-rules’ or 732 ‘syntax-case’ pattern matches. 733 • SRFI-60 (Integers as Bits) 734 (http://srfi.schemers.org/srfi-60/srfi-60.html) is now fully 735 implemented. 736 737 • Ported SRFI-101 (http://srfi.schemers.org/srfi-101/srfi-101.html). 738 These are immutable (read-only) lists with fast (logarithmic) 739 indexing and functional update (i.e. return a modified list). 740 These are implemented by a ‘RAPair’ class which extends the generic 741 ‘pair’ type, which means that most code that expects a standard 742 list will work on these lists as well. 743 744 • The class ‘kawa.lib.kawa.expressions’ contains an experimental 745 Scheme API for manipulating and validating expressions. 746 • Internal: Changed representation used for multiple values to an 747 abstract class with multiple implementations. 748 749 • Internal: Started converting to more standard Java code formatting 750 and indentation conventions, rather than GNU conventions. Some 751 files converted; this is ongoing work. 752 • Internal: Various I/O-related classes moved to new package 753 ‘gnu.kawa.io’. 754 755 • Various changes to the ‘configure+make’ build framework: A C 756 compiler is now only needed if you configure with 757 ‘--enable-kawa-frontend’. Improved support for building under 758 Windows (using MinGW/MSYS). 759 760 • Support for building with GCJ (http://gcc.gnu.org/java/) was 761 removed. 762 763Kawa 1.14 (October 4, 2013) 764--------------------------- 765 766 • You can pass flags from the ‘kawa’ front-end to the ‘java’ launcher 767 using ‘-J’ and ‘-D’ flags. The ‘kawa’ front-end now passes the 768 ‘kawa.command.line’ property to Java; this is used by the 769 ‘(command-line)’ procedure. 770 • Various improvements to the shell-script handling, including 771 re-written documentation (Scripts.html). 772 • Some initial support for Java 8. 773 774 • More of R7RS is now working: 775 776 • After adding list procedures ‘make-list’, ‘list-copy’, 777 ‘list-set!’ all the R7RS list procedures are implemented. 778 • Other added procedures: ‘square’, ‘boolean=?’, ‘string-copy!’, 779 ‘digit-value’, ‘get-environment-variable’, 780 ‘get-environment-variables’, ‘current-second’, 781 ‘current-jiffy’, ‘jiffies-per-second’, and ‘features’. 782 • The predicates ‘finite?’, ‘infinite?’, and ‘nan?’ are 783 generalized to complex numbers. 784 • The procedures ‘write’, ‘write-simple’, and ‘write-shared’ are 785 now consistent with R7RS. 786 • String and character comparison functions are generalized to 787 more than two arguments (but restricted to strings or 788 characters, respectively). 789 • The procedures ‘string-copy’, ‘string->list’, and 790 ‘string-fill!’ now take optional (start,end)-bounds. All of 791 the R7RS string functions are now implemented. 792 • Support ‘=>’ syntax in ‘case’ form. 793 • Support backslash-escaped special characters in symbols when 794 inside vertical bars, such as ‘'|Hello\nworld|’. 795 • The new functions and syntax are documented in the Kawa manual 796 (index.html); look for the functions in the index 797 (Overall-Index.html). 798 799 • Added ‘define-private-alias’ keyword. 800 • Extended string quasi-literals (templates) 801 (Strings.html#String-templates) as specified by SRFI-109 802 (http://srfi.schemers.org/srfi-109/srfi-109.html). For example, if 803 ‘name’ has the value ‘"John"’, then: 804 805 &{Hello &[name]!} 806 807 evaluates to: ‘"Hello John!"’. 808 809 • Named quasi-literal constructors as specified by SRFI-108 810 (http://srfi.schemers.org/srfi-108/srfi-108.html). 811 • A symbol having the form ‘->type’ is a type conversion function 812 that converts a value to ‘type’. 813 • New and improved check for void-valued expressions in a context 814 requiring a value. This is controlled by the new option 815 ‘--warn-void-used’, which defaults to true. 816 817 • The ‘datum->syntax’ procedure takes an optional third parameter to 818 specify the source location. See ‘testsuite/srfi-108-test.scm’ for 819 an example. 820 • Instead of specifying ‘--main’ the command line, you can now 821 specify ‘(module-compile-options: main: #t)’ in the Scheme file. 822 This makes it easier to compile one or more application (main) 823 modules along with other modules. 824 • A change to the data structure used to detect never-returning 825 procedure uses a lot less memory. (Kawa 1.13 implemented a 826 conservative detection of when a procedure cannot return. This 827 analysis would sometimes cause the Kawa compiler to run out of 828 memory. The improved analysis uses the same basic algorithm, but 829 with a more space-efficient “inverted” data structure.) 830 • Multiple fixes to get Emacs Lisp (JEmacs) working (somewhat) again. 831 832Kawa 1.13 (December 10, 2012) 833----------------------------- 834 835 • We now do a simple (conservative) analysis of when a procedure 836 cannot return. This is combined with earlier and more precise 837 analysis of reachable code. Not only does this catch programmer 838 errors better, but it also avoids some internal compiler errors, 839 because Kawa could get confused by unreachable code. 840 • Implement 2-argument version of ‘log’ function, as specified by 841 R6RS and R7RS (and, prematurely, the Kawa documentation). 842 • Implement the R7RS ‘bytevector’ functions. The ‘bytevector’ type 843 is a synonym for older ‘u8vector’ type. 844 845 • Implement R7RS ‘vector’ procedures. Various procedures now take 846 (start,end)-bounds. 847 848 • Implement most of the R7RS input/output proecdures. Most 849 significant enhancement is support for R7RS-conforming binary 850 ports. 851 • Various enhancements to the manual, including merging in lots of 852 text from R7RS. 853 • Improved Android support, including a more convenient Ant script 854 contributed by Julien Rousseau. Also, documentation merged into 855 manual. 856 857Kawa 1.12 (May 30, 2012) 858------------------------ 859 860 • Implement a compile-time data-flow framework, similar to Single 861 Static Assignment. This enables better type inference, improves 862 some warnings/errors, and enables some optimizations. 863 864 • Jamison Hope added support for co-variant return types and bridge 865 methods for generics. 866 • Macros were improved and more standards-conforming: 867 • ‘datum->syntax’ and ‘syntax->datum’ are preferred names for 868 ‘datum->syntax-object’ and ‘syntax-object->datum’. 869 • Implemented ‘bound-identifier=?’ and re-wrote implementation 870 of ‘free-identifier=?’. 871 872 • Implement ‘unsyntax’ and ‘unsyntax-splicing’, along with the 873 reader prefixes ‘#,’ and ‘#,@’. 874 875 • New and improved lazy evaluation functionality: 876 877 • Lazy values (resulting from ‘delay’ or ‘future’) are 878 implicitly forced as needed. This makes “lazy programming” 879 more convenient. 880 • New type ‘promise’. 881 • The semantics of promises (‘delay’ etc) is now compatible with 882 SRFI 45 (http://srfi.schemers.org/srfi-45/srfi-45.html). 883 • “Blank promises” are useful for passing data between 884 processes, logic programmming, and more. New functions 885 ‘promise-set-value!’, ‘promise-set-alias!’, 886 ‘promise-set-exception!’, and ‘promise-set-thunk!’. 887 • The stream functions of SRFI-41 888 (http://srfi.schemers.org/srfi-41/srfi-41.html) were 889 re-implemented to use the new promise functionality. 890 891 • Different functions in the same module can be compiled with or 892 without full tailcall support. You can control this by using 893 ‘full-tailcalls’ in ‘with-compile-options’. You can also control 894 ‘full-tailcalls’ using ‘module-compile-options’. 895 896 • Charles Turner (sponsored by Google’s Summer of Code 897 (http://code.google.com/soc/)) enhanced the printer with support 898 for SRFI-38: External Representation for Data With Shared Structure 899 (http://srfi.schemers.org/srfi-38/). 900 901 • Optimize tail-recursion in module-level procedures. (We used to 902 only do this for internal functions, for reasons that are no longer 903 relevant.) 904 905 • Add support for building Kawa on Windows using configure+make 906 (autotools) and Cygwin. 907 908 • Some support for parameterized (generic) types: 909 910 Type[Arg1 Arg2 ... ArgN] 911 912 is more-or-less equivalent to Java’s: 913 914 Type<Arg1, Arg2, ..., ArgN> 915 916 • New language options ‘--r5rs’, ‘--r6rs’, and ‘--r7rs’ provide 917 better compatibility with those Scheme standards. (This is a 918 work-in-progress.) For example ‘--r6rs’ aims to disable Kawa 919 extensions that conflict with R6RS. It does not aim to disable all 920 extensions, only incompatible extensions. So far these extensions 921 disable the colon operator and keyword literals. Selecting 922 ‘--r5rs’ makes symbols by default case-insensitive. 923 924 • The special tokens ‘#!fold-case’ and ‘#!no-fold-case’ act like 925 comments except they enable or disable case-folding of symbols. 926 The old ‘symbol-read-case’ global is now only checked when a 927 LispReader is created, not each time a symbol is read. 928 • You can now use square brackets to construct immutable sequences 929 (vectors). 930 • A record type defined using ‘define-record-type’ is now compiled to 931 a class that is a member of the module class. 932 933 • Annotations are now supported. This example 934 (http://per.bothner.com/blog/2011/Using-JAXB-annotations/) shows 935 how to use JAXB (http://java.sun.com/xml/downloads/jaxb.html) 936 annotations to automatically convert between between Java objects 937 and XML files. 938 • Prevent mutation of vector literals. 939 940 • More R6RS procedures: ‘vector-map’, ‘vector-for-each’, 941 ‘string-for-each’, ‘real-valued?’, ‘rational-valued?’, 942 ‘integer-valued?’, ‘finite?’, ‘infinite?’, ‘nan?’, 943 ‘exact-integer-sqrt’. 944 945 • SRFI-14 (http://srfi.schemers.org/srfi-14/srfi-14.html) ("character 946 sets") and SRFI-41 (http://srfi.schemers.org/srfi-41/srfi-41.html) 947 ("streams") are now supported, thanks to porting done by Jamison 948 Hope. 949 950 • Kawa now runs under JDK 1.7. This mostly involved fixing some 951 errors in ‘StackMapTable’ generation. 952 953 • You can now have a class created by ‘define-simple-class’ with the 954 same name as the module class. For example ‘(define-simple-class 955 foo ...)’ in a file ‘foo.scm’. The defined class will serve 956 dual-purpose as the module class. 957 • Improvements in separating compile-time from run-time code, 958 reducing the size of the runtime jar used for compiled code. 959 • In the ‘cond-expand’ conditional form you can now use 960 ‘class-exists:ClassName’ as a feature “name” to tests that 961 ‘ClassName’ exists. 962 963Kawa 1.11 (November 11, 2010) 964----------------------------- 965 966 • A new Kawa logo, contributed by Jakub Jankiewicz 967 (http://jcubic.pl). 968 • A new ‘--warn-unknown-member’ option, which generalizes 969 ‘--warn-invoke-unknown-method’ to fields as well as methods. 970 • A new ‘kawac’ task (ant-kawac.html), useful for Ant ‘build.xml’ 971 files, contributed by Jamison Hope. 972 • Updated Android support 973 (http://per.bothner.com/blog/2010/AndroidHelloScheme). 974 • New ‘define-enum’ macro (Enumerations.html) contributed by Jamison 975 Hope. 976 • Access specifiers ‘'final’ and ‘'enum’ are now allowed in 977 ‘define-class’ and related forms. 978 • Optimized ‘odd?’ and ‘even?’. 979 • If you specify the type of a ‘#!rest’ parameter as an array type, 980 that will now be used for the "varargs" method parameter. (Before 981 only object arrays did this.) 982 • When constructing an object and there is no matching constructor 983 method, look for "‘add’" methods in addition to "‘set’" methods. 984 Also, allow passing constructor args as well as keyword setters. 985 See here (Allocating-objects.html) for the gory details. 986 • New ‘expand’ function (contributed by Helmut Eller, and enabled by 987 ‘(require 'syntax-utils)’) for converting Scheme expressions to 988 macro-expanded forms. 989 • SAM-conversion (Anonymous-classes.html#SAM-conversion): In a 990 context that expects a Single Abstract Method (SAM) type (for 991 example ‘java.lang.Runnable’), if you pass a lambda you will get an 992 ‘object’ where the lambda implements the abstract method. 993 994 • In interactive mode allow dynamic rebinding of procedures. I.e. 995 if you re-define a procedure, the old procedure objects gets 996 modified in-place and re-used, rather than creating a new procedure 997 object. Thus calls in existing procedures will call the new 998 version. 999 1000 • Fix various threading issues related to compilation and eval. 1001 1002 • When ‘format’ returns a string, return a ‘java.lang.String’ rather 1003 than a ‘gnu.lists.FString’. Also, add some minor optimization. 1004 • Inheritance of environments and fluid variables now work properly 1005 for all child threads, not just ones created using ‘future’. 1006 1007Kawa 1.10 (July 24, 2010) 1008------------------------- 1009 1010 • Now defaults to using Java 6, when compiling from source. The 1011 pre-built ‘jar’ works with Java 5, but makes use of some Java 6 1012 features (‘javax.script’, built-in HTTP server) if available. 1013 • You can write XML literals (XML-literals.html) in Scheme code 1014 prefixed by a ‘#’, for example: 1015 1016 #<p>The result is &{result}.</p> 1017 1018 • New functions ‘element-name’ and ‘attribute-name’. 1019 • Various Web server improvements (Server-side-scripts.html). You 1020 have the option of using JDK 6’s builtin web-server 1021 (Options.html#Options-for-web-servers) for auto-configued web pages 1022 (Self-configuring-page-scripts.html). Automatic import of web 1023 server functions, so you should not need to ‘(import 'http)’ any 1024 more. 1025 • Kawa hashtables (Hash-tables.html) now extend ‘java.util.Map’. 1026 1027 • If a source file is specified on the ‘kawa’ command line without 1028 any options, it is read and compiled as a whole module before it is 1029 run. In contrast, if you want to read and evaluate a source file 1030 line-by-line you must use the ‘-f’ flag. 1031 1032 • You can specify a class name on the ‘kawa’ command line: 1033 1034 $ kawa fully.qualified.name 1035 1036 This is like the ‘java’ command. but you don’t need to specify the 1037 path to the Kawa runtime library, and you don’t need a ‘main’ 1038 method (as long as the class is ‘Runnable’). 1039 1040 • The usual bug-fixes, including better handling of the ‘~F’ ‘format’ 1041 directive; and fix in handling of macro hygiene of the ‘lambda’ 1042 (bug #27042 (https://savannah.gnu.org/bugs/index.php?27042)). 1043 1044 • Spaces are now optional before and after the ’::’ in type 1045 specifiers. The preferred syntax leave no space after the ’::’, as 1046 in: 1047 1048 (define xx ::int 1) 1049 1050 • ‘define-for-syntax’ and ‘begin-for-syntax’ work. 1051 1052 • You can now use ‘car’, ‘cdr’ etc to work with ‘syntax’ objects that 1053 wrap lists, as in SRFI-72. 1054 1055 • You can now define a package alias: 1056 1057 (define-alias jutil java.util) 1058 (define mylist :: jutil:List (jutil:ArrayList)) 1059 1060 • ‘--module-static’ is now the default. A new ‘--module-nonstatic’ 1061 (or ‘--no-module-static’) option can be used to get the old 1062 behavior. 1063 1064 • You can use ‘access:’ to specify that a field is ‘'volatile’ or 1065 ‘'transient’. 1066 1067 • You can now have type-specifiers for multiple variables in a ‘do’. 1068 1069 • Imported variables are read-only. 1070 1071 • Exported variables are only made into Locations when needed. 1072 1073 • The letter used for the exponent in a floating-point literal 1074 determines its type: ‘12s2’ is a ‘java.lang.Float’, ‘12d2’ is a 1075 ‘java.lang.Double’, ‘12l2’ is a ‘java.math.BigInteger’, ‘12e2’ is a 1076 ‘gnu.math.DFloat’. 1077 1078 • Internal: Asking for a ‘.class’ file using ‘getResourceAsStream’ on 1079 an ‘ArrayClassLoader’ will now open a ‘ByteArrayInputStream’ on the 1080 class bytes. 1081 1082 • A new ‘disassemble’ function. 1083 1084 • If ‘exp1’ has type ‘int’, the type of ‘(+ exp1 1)’ is now (32-bit) 1085 ‘int’, rather than (unlimited-precision) ‘integer’. Similar for 1086 ‘long’ expressions, other arithmetic operations (as appropriate), 1087 and other untyped integer literals (as long as they fit in 32/64 1088 bits respectively). 1089 1090 • Many more oprimization/specializations of arithmetic, especially 1091 when argument types are known. 1092 1093 • Top-level bindings in a module compiled with ‘--main’ are now 1094 implicitly module-private, unless there is an explicit 1095 ‘module-export’. 1096 1097 • SRFI-2 (http://srfi.schemers.org/srfi-2/srfi-2.html) (‘and-let*’: 1098 an ‘and’ with local bindings, a guarded ‘*’ special form) is now 1099 supported. 1100 1101 • The reader now supports shared sub-objects, as in SRFI-38 1102 (http://srfi.schemers.org/srfi-38/srfi-38.html) and Common Lisp: 1103 ‘(#2=(3 4) 9 #2# #2#)’. (Writing shared sub-objects is not yet 1104 implemented.) 1105 1106 • A module compiled with ‘--main’ by default exports no bindings 1107 (unless overriden by an explicit ‘module-export’). 1108 1109 • Factor out compile-time only code from run-time code. The new 1110 ‘kawart-version.jar’ is smaller because it has less compile-time 1111 only code. (Work in progress.) 1112 • More changes for R6RS compatibility: 1113 1114 • The reader now recognizes ‘+nan.0’, ‘+inf.0’ and variations. 1115 1116 • The ‘div’, ‘mod’, ‘div0’, ‘mod0’, ‘div-and-mod’, 1117 ‘div0-and-mod0’, ‘inexact’ and ‘exact’ functions were 1118 implemented. 1119 1120 • ‘command-line’ and ‘exit’. 1121 1122Kawa 1.9.90 (August 8, 2009) 1123---------------------------- 1124 1125 • Support for ‘javax.script’. 1126 1127 • Support for regular expressions (Regular-expressions.html). 1128 1129 • Performance improvements: 1130 1131 • Emit ‘iinc’ instruction (to increment a local ‘int’ by a 1132 constant). 1133 1134 • Inline the ‘not’ function if the argument is constant. 1135 1136 • If ‘call-with-current-continuation’ is only used to exit a 1137 block in the current method, optimize to a ‘goto’. 1138 1139 • Generate ‘StackMapTable’ attributes when targeting Java 6. 1140 1141 • Kawa can now inline a function with multiple calls (without 1142 code duplication) if all call sites have the same return 1143 location (continuation). For example: ‘(if p (f a) (f b))’. 1144 Also mutually tail-recursive functions are inlined, so you get 1145 constant stack space even without ‘--full-tailcalls’. (Thanks 1146 for Helmut Eller for a prototype.) 1147 1148 • A number of changes for R6RS compatibility: 1149 1150 • The ‘char-titlecase’, ‘char-foldcase’, ‘char-title-case?’ 1151 library functions are implemented. 1152 1153 • Imported variables are read-only. 1154 1155 • Support the R6RS ‘import’ keyword, including support for 1156 renaming. 1157 1158 • Support the R6RS ‘export’ keyword (though without support for 1159 renaming). 1160 1161 • Implemented the ‘(rnrs hashtables)’ library. 1162 1163 • Implemented the ‘(rnrs sorting)’ library. 1164 1165 • CommonLisp-style keyword syntax is no longer supported (for 1166 Scheme): A colon followed by an identifier is no longer a 1167 keyword (though an identifier followed by a colon is still a 1168 keyword). (One reason for this change is to support SRFI-97.) 1169 1170 • The character names ‘#\delete’, ‘#\alarm’, ‘#\vtab’ are now 1171 supported. The old names ‘#\del’, ‘#\rubout’, and ‘#\bel’ are 1172 deprecated. 1173 1174 • Hex escapes in character literals are supported. These are 1175 now printed where we before printed octal escapes. 1176 1177 • A hex escape in a string literal should be terminated by a 1178 semi-colon, but for compatibily any other non-hex-digit will 1179 also terminate the escape. (A terminating semi-colon will be 1180 skipped, though a different terminator will be included in the 1181 string.) 1182 1183 • A backslash-whitespace escape in a string literal will not 1184 only ignore the whitespace through the end of the line, but 1185 also any initial whitespace at the start of the following 1186 line. 1187 1188 • The comment prefix ‘#;’ skips the following S-expression, as 1189 specified by SRFI-62 1190 (http://srfi.schemers.org/srfi-62/srfi-62.html). 1191 1192 • All the R6RS exact bitwise arithmetic 1193 (http://www.r6rs.org/final/html/r6rs-lib/r6rs-lib-Z-H-12.html#node_sec_11.4) 1194 functions are now implemented and documented in the manual 1195 (Logical-Number-Operations.html). The new standard functions 1196 (for example ‘bitwise-and’) are now preferred over the old 1197 functions (for example ‘logand’). 1198 1199 • If ‘delete-file’ fails, throws an exception instead of 1200 returning ‘#f’. 1201 1202 • The code-base now by default assumes Java 5 (JDK 1.5 or newer), and 1203 pre-built ‘jar’ files will require Java 5. Also, the Kawa source 1204 code now uses generics, so you need to use a generics-aware 1205 ‘javac’, passing it the appropriate ‘--target’ flag. 1206 1207 • New SRFIs supported: 1208 1209 • SRFI-62 (http://srfi.schemers.org/srfi-62/srfi-62.html) - 1210 S-expression comments. 1211 1212 • SRFI-64 (http://srfi.schemers.org/srfi-64/srfi-64.html) - 1213 Scheme API for test suites. 1214 1215 • SRFI-95 (http://srfi.schemers.org/srfi-95/srfi-95.html) - 1216 Sorting and Merging. 1217 1218 • SRFI-97 (http://srfi.schemers.org/srfi-97/srfi-97.html) - 1219 Names for SRFI Libraries. This is a naming convention for 1220 R6RS ‘import’ statements to reference SRFI libraries. 1221 1222 • In BRL text outside square brackets (or nested like ‘]this[’) now 1223 evaluates to ‘UnescapedData’, which a Scheme quoted string 1224 evaluates to ‘String’, rather than an ‘FString’. (All of the 1225 mentioned types implement ‘java.lang.CharSequence’.) 1226 1227 • You can now run Kawa Scheme programs on Android 1228 (http://per.bothner.com/blog/2009/AndroidHelloScheme/), Google’s 1229 mobile-phone operating system. 1230 1231 • The macro ‘resource-url’ is useful for accessing resources. 1232 1233 • A new command-line option ‘--target’ (or ‘-target’) similar to 1234 ‘javac’’s ‘-target’ option. 1235 1236 • If there is no console, by default create a window as if ‘-w’ was 1237 specificed. 1238 1239 • If a class method (defined in ‘define-class’, ‘define-simple-class’ 1240 or ‘object’) does not have its parameter or return type specified, 1241 search the super-classes/interfaces for matching methods (same name 1242 and number of parameters), and if these are consistent, use that 1243 type. 1244 1245 • Trying to modify the ‘car’ or ‘cdr’ of a literal list now throws an 1246 exception. 1247 1248 • The ‘.zip’ archive created by ‘compile-file’ is now compressed. 1249 1250 • Java5-style varargs-methods are recognized as such. 1251 1252 • When evaluating or loading a source file, we now always compile to 1253 bytecode, rather than interpreting “simple” expressions. This 1254 makes semantics and performance more consistent, and gives us 1255 better exception stack traces. 1256 1257 • The Scheme type specifier ‘<integer>’ now handles automatic 1258 conversion from ‘java.math.BigInteger’ and the ‘java.lang’ classes 1259 ‘Long’, ‘Integer’, ‘Short’, and ‘Byte’. The various standard 1260 functions that work on ‘<integer>’ (for example ‘gcd’ and 1261 ‘arithmetic-shift’) can be passed (say) a ‘java.lang.Integer’. The 1262 generic functions such as ‘+’ and the real function ‘modulo’ should 1263 also work. (The result is still a ‘gnu.math.IntNum’.) 1264 1265 • If a name such as (‘java.util’) is lexically unbound, and there is 1266 a known package with that name, return the ‘java.lang.Package’ 1267 instance. Also, the colon operator is extended so that 1268 ‘package:name’ evaluates to the ‘Class’ for ‘package.name’. 1269 1270 • ‘`prefix:,expression’ works - it finds a symbol in ‘prefix’’s 1271 package (aka namespace), whose local-name is the value of 1272 ‘expression’. 1273 1274 • A quantity ‘3.0cm’ is now syntactic sugar for ‘(* 3.0 unit:cm)’. 1275 Similarly: 1276 ‘(define-unit name value)’ 1277 is equivalent to: 1278 ‘(define-constant unit:name value)’ 1279 This means that unit names follow normal name-lookup rules (except 1280 being in the ‘unit’ “package”), so for example you can have local 1281 unit definitions. 1282 1283 • You can specify whether a class has public or package access, and 1284 whether it is translated to an interface or class. 1285 1286 • You can declare an abstract method by writing ‘#!abstract’ as its 1287 body. 1288 1289 • If a name of the form ‘type?’ is undefined, but ‘type’ is defined, 1290 then treat the former as ‘(lambda (x) (instance? x type))’. 1291 • A major incompatible (but long-sought) change: Java strings (i.e. 1292 ‘java.lang.String’ values) are now Scheme strings, rather than 1293 Scheme symbols. Since Scheme strings are mutable, while Java 1294 ‘String’s are not, we use a different type for mutable strings: 1295 ‘gnu.lists.FString’ (this is not a change). Scheme string literals 1296 are ‘java.lang.String’ values. The common type for Scheme string 1297 is ‘java.lang.CharSequence’ (which was introducted in JDK 1.4). 1298 1299 Scheme symbols are now instances of ‘gnu.mapping.Symbol’ 1300 (api/gnu/mapping/Symbol.html), specifically the ‘SimpleSymbol’ 1301 class. 1302 1303 • A fully-qualified class name such as ‘java.lang.Integer’ now 1304 evaluates to the corresponding ‘java.lang.Class’ object. I.e. it 1305 is equivalent to the Java term ‘java.lang.Integer.class’. This 1306 assumes that the name does not have a lexical binding, _and_ that 1307 it exists in the class-path at compile time. 1308 1309 Array class names (such as ‘java.lang.Integer[]’) and primitive 1310 types (such as ‘int’) also work. 1311 1312 The older angle-bracket syntax ‘<java.lang.Integer>’ also works and 1313 has the same meaning. It also evaluates to a ‘Class’. It used to 1314 evaluate to a ‘Type’ (api/gnu/bytecode/Type.html), so this is a 1315 change. 1316 1317 The name bound by a ‘define-simple-class’ now evaluates to a 1318 ‘Class’, rather than a ‘ClassType’ 1319 (api/gnu/bytecode/ClassType.html). A ‘define-simple-class’ is not 1320 allowed to reference non-static module-level bindings; for that use 1321 ‘define-class’. 1322 1323 • New convenience macro ‘define-syntax-case’ 1324 (Syntax-and-conditional-compilation.html). 1325 1326Kawa 1.9.1 (January 23, 2007) 1327----------------------------- 1328 1329 • Fix some problems building Kawa from source using ‘configure+make’. 1330 1331Kawa 1.9.0 (January 21, 2007) 1332----------------------------- 1333 1334 • New types and functions for working with paths and URIs 1335 (Paths.html). 1336 1337 • Reader macros URI, namespace, duration. 1338 1339 • Simplified build using gcj (Source-distribution.html), and added 1340 configure flag –with-gcj-dbtool. 1341 1342 • If two “word” values are written, a space is written between them. 1343 A word is most Scheme values, including numbers and lists. A 1344 Scheme string is treated as a word by ‘write’ but by not ‘display’. 1345 1346 • A new ‘--pedantic’ command-line flag. It currently only affects 1347 the XQuery parser. 1348 1349 • The ‘load-compile’ procedure was removed. 1350 1351 • The string printed by the ‘--version’ switch now includes the 1352 Subversion revision and date (but only if Kawa was built using 1353 ‘make’ rather than ‘ant’ from a checked-out Subversion tree). 1354 1355 • Kawa development now uses the Subversion (svn) 1356 (http://subversion.tigris.org/) version control system instead of 1357 CVS. 1358 1359 • Show file/line/column on unbound symbols (both when interpreted and 1360 when compiled). 1361 1362 • Cycles are now allowed between ‘require’’d modules. Also, 1363 compiling at set of modules that depend on each other can now 1364 specified on the compilation command line in any order, as long as 1365 needed ‘require’ forms are given. 1366 1367 • The “colon notation” has been generalized. (PathExpressions.html). 1368 The syntax ‘object:name’ generally means to extract a component 1369 with a given ‘name’ from ‘object’, which may be an object, a class, 1370 or a namespace. 1371 1372 • New command-line options ‘--debug-error-prints-stack-trace’ and 1373 ‘--debug-warning-prints-stack-trace’ provide stack trace on static 1374 error messages. 1375 1376 • The license for the Kawa software (Software-License.html) has been 1377 changed to the X11/MIT license 1378 (http://opensource.org/licenses/mit-license.php). 1379 1380 • A much more convenient syntax for working with Java arrays 1381 (Array-operations.html). 1382 1383 The same function-call syntax also works for Scheme vectors, 1384 uniform vectors, strings, lists - and anything else that implements 1385 ‘java.util.List’. 1386 1387 • The fields and methods of a class and its bases classes are in 1388 scope within methods of the class. 1389 • Unnamed procedures (such as lambda expressions) are printed with 1390 the source filename and line. 1391 1392 • The numeric compare functions (‘=’, ‘<=’, etc) and ‘number->string’ 1393 now work when passed standard Java ‘Number’ objects (such as 1394 ‘java.lang.Long’ or ‘java.math.BigDecimal’). 1395 • SRFI-10 (http://srfi.schemers.org/srfi-10/srfi-10.html) is now 1396 implemented, providing the ‘#,(name args ...)’ form. Predefined 1397 constructor ‘name’s so far are ‘URI’ and ‘namespace’. The 1398 ‘define-reader-ctor’ function is available if you ‘(require 1399 'srfi-10)’. 1400 1401 • A new ‘--script’ option makes it easier to write Unix shell 1402 scripts. 1403 1404 • Allow general URLs for loading (including the ‘-f’ flag), 1405 compilation and ‘open-input-file’, if the “file name” starts with a 1406 URL “scheme” like ‘http:’. 1407 1408 • Classes defined (_e.g._ with ‘define-simple-class’) in a module 1409 can now mutually reference each other. On the other hand, you can 1410 no longer ‘define-class’ if the class extends a class rather than 1411 an interface; you must use ‘define-simple-class’. 1412 1413 • ‘KawaPageServlet’ now automatically selects language. 1414 1415 • ‘provide’ macro. 1416 • ‘quasisyntax’ and the convenience syntax ‘#`’, from SRFI-72 1417 (http://srfi.schemers.org/srfi-72/srfi-72.html). 1418 • ‘define-for-syntax’, ‘syntax-source’, ‘syntax-line’, and 1419 ‘syntax-column’, for better compatibility with mzscheme. 1420 • SRFI-34 (http://srfi.schemers.org/srfi-34/srfi-34.html) (Exception 1421 Handling for Programs), which implements ‘with-exception-handler’, 1422 ‘guard’, and ‘raise’, is now available, if you ‘(require 1423 'srfi-34)’. 1424 Also, SRFI-35 (http://srfi.schemers.org/srfi-35/srfi-35.html) 1425 (Conditions) is available, if you ‘(require 'srfi-35)’. 1426 • The ‘case-lambda’ form from SRFI-16 1427 (http://srfi.schemers.org/srfi-16/srfi-16.html) is now implemented 1428 more efficiently. 1429 1430Kawa 1.8 (October 18, 2005) 1431--------------------------- 1432 1433SRFI-69 “Basic hash tables” 1434(http://srfi.schemers.org/srfi-69/srfi-69.html) is now available, if you 1435‘(require 'hash-table)’ or ‘(require 'srfi-69)’. This is an optimized 1436and Java-compatible port whose default hash function calls the standard 1437‘hashCode’ method. 1438 1439 A ‘define-simple-class’ can now have one (or more) explicit 1440constructor methods. These have the spcial name ‘*init*’. You can call 1441superclass constructors or sibling constructors (‘this’ constructor 1442calls) using the (admittedly verbose but powerful) ‘invoke-special’ 1443form. 1444 1445 The ‘runnable’ function creates a ‘Runnable’ from a ‘Procedure’. It 1446is implemented using the new class ‘RunnableClosure’, which is now also 1447used to implement ‘future’. 1448 1449 The ‘kawa’ command can now be run “in-place” from the build 1450directory: ‘$build_dir/bin/kawa’. 1451 1452 The special field name ‘class’ in ‘(static-name type 'class)’ or 1453‘(prefix:.class)’ returns the ‘java.lang.Class’ object corresponding to 1454the ‘type’ or ‘prefix’. This is similar to the Java syntax. 1455 1456 Contructing an instance (perhaps using ‘make’) of a class defined 1457using ‘define-simple-class’ in the current module is much more 1458efficient, since it no longer uses reflection. (Optimizing classes 1459defined using ‘define-class’ is more difficult.) The constructor 1460function defined by the ‘define-record-type’ macro is also optimized. 1461 1462 You can now access instance methods using this short-hand: 1463‘(*:methodname instance arg ...)’ 1464This is equivalent to: ‘(invoke instance 'methodname arg ...)’ 1465 1466 You can now also access a fields using the same colon-notation as 1467used for accessing methods, except you write a dot before the field 1468name: 1469‘(type:.fieldname)’ ‘ ;; ’is like: ‘(static-field type 'fieldname)’. 1470‘(*:.fieldname instance)’ ‘;;’ is like: ‘(field 'fieldname instance)’ 1471‘(type:.fieldname instance)’ ‘;;’ is like: ‘(*:.fieldname (as instance 1472type))’ 1473These all work with ‘set!’ - for example: ‘(set! (*:.fieldname instance) 1474value)’. 1475 1476 In the above uses of colon-notation, a ‘type’ can be any one of: 1477- a namespace prefix bound using ‘define-namespace’ to a namespace uri 1478of the form ‘"class:classname"’; 1479- a namespace prefix using ‘define-namespace’ bound to a ‘<classname>’ 1480name, which can be a fully-qualified class name or a locally-declared 1481class, or an alias (which might be an imported class); 1482- a fully qualified name of a class (that exists at compile-time), as in 1483‘(java.lang.Integer:toHexString 123)’; or 1484- a ‘<classname>’ variable, for example: ‘(<list>:list3 11 12 13)’. 1485 1486 New fluid variables ‘*print-base*’, ‘*print-radix*’, 1487‘*print-right-margin*’, and ‘*print-miser-width*’ can control output 1488formatting. (These are based on Common Lisp.) 1489 1490 You can new emit elipsis (‘...’) in the output of a ‘syntax’ template 1491using the syntax ‘(... ...)’, as in other ‘syntax-case’ implementations. 1492 1493 The ‘args-fold’ program-argument processor from SRFI-37 1494(http://srfi.schemers.org/srfi-37/srfi-37.html) is available after you 1495‘(require 'args-fold)’ or ‘(require 'srfi-37)’. 1496 1497 The ‘fluid-let’ form now works with lexical bindings, and should be 1498more compatible with other Scheme implementations. 1499 1500 ‘(module-export namespace:prefix)’ can be used to export a namespace 1501prefix. 1502 1503 Static modules are now implemented more similarly to non-static 1504modules. Specifically, the module body is not automatically run by the 1505class initializer. To get the old behavior, use the new 1506‘--module-static-run’ flag. Alternatively, instead of ‘(module-static 1507#t)’ use ‘(module-static 'init-run)’. 1508 1509 Implement SRFI-39 (http://srfi.schemers.org/srfi-39/srfi-39.html) 1510"Parameter-objects". These are like anonymous fluid values and use the 1511same implementation. ‘current-input-port’, ‘current-output-port’, and 1512‘current-error-port’ are now parameters. 1513 1514 Infer types of variables declared with a ‘let’. 1515 1516 Character comparisons (such as ‘char-=?’, ‘char-ci<?’) implemented 1517much more efficiently — and (if using Java5) work for characters not in 1518the Basic Multilingual Plane. 1519 1520 Major re-write of symbol and namespace handling. A ‘Symbol’ 1521(api/gnu/mapping/Symbol.html) is now immutable, consisting of a 1522"print-name" and a pointer to a ‘Namespace’ 1523(api/gnu/mapping/Namespace.html) (package). An ‘Environment’ 1524(api/gnu/mapping/Environment.html) is a mapping from ‘Symbol’ to 1525‘Location’ (api/gnu/mapping/Location.html). 1526 1527 Rename ‘Interpreter’ to ‘Language’ (api/gnu/expr/Language.html) and 1528‘LispInterpreter’ to ‘LispLanguage’ 1529(api/gnu/kawa/lispexpr/LispLanguage.html). 1530 1531 Constant-time property list operations. 1532 1533 Namespace-prefixes are now always resolved at compile-time, never at 1534run-time. 1535 1536 ‘(define-namespace PREFIX <CLASS>)’ is loosely the same as 1537‘(define-namespace PREFIX "class:CLASS")’ but does the right thing for 1538classes defined in this module, including nested or non-simple classes. 1539 1540 Macros capture proper scope automatically, not just when using 1541require. This allows some internal macros to become private. 1542 1543 Major re-write of the macro-handling and hygiene framework. Usable 1544support for ‘syntax-case’; in fact some of the primitives (such as ‘if’) 1545are now implemented using ‘syntax-case’. ‘(syntax form)’ (or the 1546short-cut ‘#!form)’ evaluates to a syntax object. ‘(define-syntax (mac 1547x) tr)’ same as ‘(define-syntax mac (lambda (x) tr))’. The following 1548non-hygienic forms are equivalent: 1549 1550 (define-macro (macro-name (param ...) transformer) 1551 (define-macro macro-name (lambda (param ...) transformer)) 1552 (defmacro macro-name (PARAM ...) transformer) 1553 1554 Allow vectors and more general ellipsis-forms in patterns and 1555templates. 1556 1557 A new configure switch ‘--with-java-source=version’ allows you to 1558tweak the Kawa sources to match Java compiler and libraries you’re 1559using. The default (and how the sources are distributed) is ‘2’ (for 1560"Java 2" – jdk 1.2 or better), but you can also select "‘1’" (for jdk 15611.1.x), and "‘5’" for Java 5 (jdk 1.5). You can also specify a jdk 1562version number: "‘1.4.1’" is equivalent to "2" (for now). Note the 1563default source-base is incompatible with Java 5 (or more generally JAXB 15641.3 or DOM 3), unless you also ‘--disable-xml’. 1565 1566 Configure argument ‘--with-servlet’[‘=servlet-api.jar’] replaces 1567‘--enable-servlet’. 1568 1569 Function argument in error message are now numbered starting at one. 1570Type errors now give better error messages. 1571 1572 A new function calling convention, used for ‘--full-tailcalls’. A 1573function call is split up in two parts: A ‘match0’/.../‘matchN’ method 1574checks that the actual arguments match the expected formal arguments, 1575and leaves them in the per-thread ‘CallContext’ 1576(api/gnu/mapping/CallContext.html). Then after the calling function 1577returns, a zero-argument ‘apply()’ methods evaluates the function body. 1578This new convention has long-term advantages (performance, full 1579continuations), but the most immediate benefit is better handling of 1580generic (otherloaded) functions. There are also improved error 1581messages. 1582 1583 Real numbers, characters, Lisp/Scheme strings (‘FString’ 1584(api/gnu/lists/FString.html)) and symbols all now implement the 1585‘Comparable’ interface. 1586 1587 In ‘define-class’/‘define-simple-class’: [Most of this work was 1588funded by Merced Systems (http://www.mercedsystems.com/).] 1589 1590 • You can specify ‘access: 1591 ’[‘'private’|‘'protected’|‘'publi’c|‘'package’] to set the Java 1592 access permissions of fields and methods. 1593 • Methods can be static by using the ‘access: 'static’ specifier. 1594 • The reflective routines ‘invoke’ , ‘field’ , ‘static-field’ , 1595 ‘slot-ref’ , ‘slot-set!’ can now access non-public methods/fields 1596 when appropriate. 1597 • Such classes are no longer initialized when the containing module 1598 is loaded. 1599 • The ‘expr’ in ‘init-form: expr’ is now evaluated in the outer 1600 scope. 1601 • A new ‘init: expr’ evalues ‘expr’ in the inner scope. 1602 • An option name following ‘allocation:’ can now be a string literal 1603 or a quoted symbol. The latter is preferred: ‘allocation: 'class’. 1604 • Added ‘'static’ as a synonym for ‘'class’ following ‘allocation:’. 1605 • Initialization of static field (‘allocation: 'class init: expr’) 1606 now works, and is performed at class initialization time. 1607 • You can use unnamed “dummy fields” to add initialization-time 1608 actions not tied to a field: 1609 1610 (define-simple-class Foo () 1611 (:init (perform-some-action))) 1612 1613Kawa 1.7.90 (2003) 1614------------------ 1615 1616Various fixes and better error messages in number parsing. Some 1617optimizations for the divide function. 1618 1619 New framework for controlling compiler warnings and other features, 1620supporting command-line flags, and the Scheme forms 1621‘with-compile-options’ and ‘module-compile-options’. The flag 1622‘--warn-undefined-variable’ is useful for catching typos. 1623Implementation funded by Merced Systems (http://www.mercedsystems.com/). 1624 1625 New ‘invoke-special’ syntax form (implemented by Chris Dean). 1626 1627 New ‘define-variable’ form (similar to Common Lisp’s ‘defvar’). 1628 1629Kawa 1.7 (June 7, 2003) 1630----------------------- 1631 1632‘KawaPageServlet’ (api/gnu/kawa/servlet/KawaPageServlet.html) allows 1633automatic loading and on-the-fly compilation in a servlet engine. See 1634http://www.gnu.org/software/qexo/simple-xquery-webapp.html 1635(../qexo/simple-xquery-webapp.html). 1636 1637 The default source-base requires various Java 2 features, such as 1638collection. However, ‘make-select1’ will comment out Java2 1639dependencies, allowing you to build Kawa with an older Java 1640implementation. 1641 1642 The ‘-f’ flag and the load function can take an absolute URL. New 1643Scheme functions ‘load-relative’ and ‘base-uri’. 1644 1645 Imported implementation of cut and cute from SRFI-26 1646(http://srfi.schemers.org/srfi-26/srfi-26.html) (Notation for 1647Specializing Parameters without Currying). 1648 1649 The way top-level definitions (including Scheme procedures) are 1650mapped into Java fields is changed to use a mostly reversible mapping. 1651(The mapping to method names remains more natural but non-reversible.) 1652 1653 ‘define-alias’ of types can now be exported from a module. 1654 1655 New ‘--no-inline’ and ‘--inline=none’ options. 1656 1657 You can use ‘define-namespace’ to define “namespace aliases”. This 1658is used for the new short-hard syntax for method invocation: 1659‘(define-namespace Int32 "class:java.lang.Integer")’ 1660‘(Int32:toHexString 255)’ => ‘"ff"’ 1661‘(Int32:toString (Int32:new "00255"))’ => ‘"255"’ 1662Alternatively, you can write: 1663‘(java.lang.Integer:toHexString 255)’ => ‘"ff"’ 1664 1665 SRFI-9 (http://srfi.schemers.org/srfi-9/srfi-9.html) 1666(define-record-type) has been implemented, and compiled to a 1667‘define-class’, with efficient code. 1668 1669 The configure option ‘--with-collections’ is now the default. 1670 1671 Unknowns are no longer automatically static. 1672 1673 If type not specified in a declaration, don’t infer it from it 1674initial value. If no return type is specified for a function, default 1675to ‘Object’, rather than the return type of the body. (The latter leads 1676to undesirable different behaviour if definitions are re-arranged.) 1677 1678 You can now define and use classes defined using ‘object’, 1679‘define-class’, and ‘define-simple-class’ from the “interpreter”, as 1680well as the compiler. Also, a bug where inherited fields did not get 1681initialized has been fixed. 1682 1683 There are several new procedures useful for servlets. 1684 1685 Numerical comparisions (‘<’, ‘<=’, etc) now generates optimized 1686bytecode if the types of the operands have certain known types. 1687including efficient code for ‘<int>’, ‘<long>’, ‘<double>’, and 1688‘<integer>’. Much more code can now (with type declaration) be written 1689just as efficiently in Scheme as in Java. 1690 1691 There have been some internal re-arranging of how Expressions are 1692processed. The Scheme-specific Translator type now inherits from 1693Compilation, which replaces the old Parser class. A Complation is now 1694allocated much earlier, as part of parsing, and includes a 1695SourceMessages object. SourcesMessages now includes (default) line 1696number, which is used by Compilation for the "current" line numbers. 1697The ExpWalker class includes a SourceMessages instance (which it gets 1698from the Compilation). CanInline.inline method now takes ExpWalker 1699parameter. Checking of the number or parameters, and mapping known 1700procedures to Java methods are now both done during the inlining pass. 1701 1702 The user-visible effect is that Kawa can now emit error mesages more 1703cleanly more places; the inlining pass can be more agressive, and can 1704emit better error messages, which yields better type information. This 1705gives us better code with fewer warnings about unknown methods. 1706 1707Changes from Kawa 1.6.98 to 1.6.99. 1708----------------------------------- 1709 1710A new language front-end handles a tiny subset of XSLT. An example is 1711the check-format-users test in gnu/xquery/testsuite/Makefile. 1712 1713 There are now converters between SAX2 and Consumer events, and a 1714basic implementation of XMLReader based on XMLParser. 1715 1716 The function as-xml prints a value in XML format. 1717 1718 Srfi-0 (cond-expand), srfi-8 (receive), and srfi-25 1719(multi-dimensional arrays) are now implemented. So is srfi-1 (list 1720library), though that requires doing (require ’list-lib). 1721 1722 The JEmacs code is being re-organized, splitting out the 1723Swing-dependent code into a separate gnu.jemacs.swing package. This 1724should make it easier to add JEmacs implementation without Swing. 1725 1726 The class gnu.expr.Interpreter has various new ’eval’ methods that 1727are useful for evaluating Scheme/BRL/XQuery/... expressions from Java. 1728 1729 Kawa now uses current versions of autoconf, autoamke, and libtool, 1730allowing the use of automake file inclusion. 1731 1732 The comparisons ‘<<’, ‘<=’, ‘-’, ‘>’, and ‘=>’ now compile to 1733optimized Java arithmetic if both operands are ‘<int>’ or a literal that 1734fits in ‘<int>’. 1735 1736Changes from Kawa 1.6.97 to 1.6.98 1737---------------------------------- 1738 1739Generated HTML and Postscrpt documents are no longer included in the 1740source distribution. Get ‘kawa-doc-version.tar.gz’ instead. 1741 1742 (format #t ...) and (format PORT ...) now returns #!void instead of 1743#t. 1744 1745 Support fluid bindings (fluid-let) for any thread, not just Future 1746and main. 1747 1748 A Unix script header ‘#!/PROGRAM’ is ignored. 1749 1750 You can now take the same Kawa "web" program (written in Scheme, 1751KRL/BRL, or XQuery) and run it as either a servlet or a CGI script. 1752 1753 There are a number of new functions for accessing HTTP requests and 1754generating HTTP responses. 1755 1756 Kawa now supports a new experimental programming KRL (the "Kawa 1757Report Language"). You select this language using –krl on the Kawa 1758command link. It allows Scheme code to be inside template files, like 1759HTML pages, using a syntax based on BRL (brl.sourceforge.net). However, 1760KRL has soem experimental changes to both BRL and standard Scheme. 1761There is also a BRL-compatibile mode, selected using –brl, though that 1762currently only supports a subset of BRL functions. 1763 1764 If language is not explicitly specified and you’re running a source 1765file (e.g. "java kawa.repl myscript.xql"), Kawa tried to derive the 1766language from the the filename extension (e.g. "xql"). It still 1767defaults to Scheme if there is no extension or the extension is 1768unrecognized. 1769 1770 New command-line option –output-format alias –format can be used to 1771over-ride the format used to write out top-level (repl, load) values. 1772 1773 XMLPrinter can now print in (non-well-formed-XML) HTML. 1774 1775Changes from Kawa 1.6.96 to 1.6.97 1776---------------------------------- 1777 1778Changed lots of error messages to use pairs of single quotes rather than 1779starting with a backquote (accent grave): ’name’ instead of ‘name’. 1780Many newer fonts make the latter look bad, so it is now discouraged. 1781 1782 The types ‘<String>’ and ‘<java.lang.String>’ new behave differently. 1783The type ‘<java.lang.String>’ now works just like (say) 1784‘<java.util.Hashtable>’. Converting an object to a ‘<java.lang.String>’ 1785is done by a simple coercion, so the incoming value must be a 1786java.lang.String reference or null. The special type ‘<String>’ 1787converts any object to a java.string.String by calling toString; it also 1788handles null by specially testing for it. 1789 1790 For convenience (and backwards compatibility) Kawa uses the type 1791‘<String>’ (rather than ‘<java.lang.String>’) when it sees the Java type 1792‘java.lang’.String, for example in the argument to an ‘invoke’. 1793 1794 The default behaviour of ’[’ and ’] was changed back to be token 1795(word) constituents, matching R5RS and Common Lisp. However, you can 1796easily change this behaviour using the new setBrackMode method or the 1797defaultBracketMode static field in ReadTable. 1798 1799 You can now build Kawa from source using the Ant build system (from 1800Apache’s Jakarta project), as an alternative to using the traditional 1801configure+make system. An advantage of Ant is that it works on most 1802Java systems, without requiring a Unix shell and commands. 1803Specifically, this makes it easy to build Kawa under MS-Windows. Thanks 1804to James White for contributing this support. 1805 1806 Added (current-error-port) which does the obvious. 1807 1808 The new let-values and let-values* macros from srfi-11 provide a more 1809convenient way to use multiple values. 1810 1811 All the abstract apply* and eval* methods now specify ’throws 1812Throwable’. A bunch of code was changed to match. The main visible 1813advantage is that the throw and primitive-throw procedures work for any 1814Throwable without requiring it to be (confusingly) wrapped. 1815 1816Changes from Kawa 1.6.95 to 1.6.96 1817---------------------------------- 1818 1819A new compilation flag –servlet generates a Servlet which can be 1820deployed in a servlet engin like Tomcat. This is experimental, but it 1821seesm to work for both Scheme source and XQuery source. 1822 1823 The interface gnu.lists.CharSequence was renamed to avoid conflitcs 1824with the (similar) interface java.lang.CharSequence in JDK 1.4beta. 1825 1826 New –help option (contributed by Andreas Schlapbach). 1827 1828 Changed the code generation used when –full-tailcalls. It now is 1829closer to that used by default, in that we don’t generate a class for 1830each non-inlined procedure. In both cases calling an unknown procedure 1831involves executing a switch statement to select a method. In addition 1832to generating fewer classes and simplifying one of the more fragile 1833parts of Kawa, it is also a step towards how full continuations will be 1834implemented. 1835 1836 Changed the convention for name "mangling" - i.e. how Scheme names 1837are mapped into Java names. Now, if a Scheme name is a valid Java name 1838it is used as is; otherwise a reversible mangling using "$" characters 1839is used. Thus the Scheme names ‘'<’ and ‘'$Leq’ are both mapped into 1840the same Java name ‘"$Leq"’. However, other names not containing "‘$’" 1841should no longer clash, including pairs like "‘char-letter?’" and 1842"‘charLetter?’" and "‘isCharLetter’" which used to be all mapped to 1843"‘isCharLetter’". Now only names containing "‘$’" can be ambiguous. 1844 1845 If the compiler can determine that all the operands of (+ ...) or (- 1846...) are floating-point, then it will generate optimized code using 1847Java primitive arithmetic. 1848 1849 Guile-style keyword syntax ’#:KEYWORD’ is recognized. (Note this 1850conflicts with Common Lisp syntax for uninterned symbols.) 1851 1852 New syntax forms define-class and define-simple-class allow you to 1853define classes more easily. define-class supports true multiple 1854inheritance and first class class values, where each Scheme class is 1855compiled to a pair of an inteface and a class. define-simple-class 1856generates more efficient and Java-compatible classes. 1857 1858Changes from Kawa 1.6.94 to 1.6.95. 1859----------------------------------- 1860 1861A new language "xquery" implements a (so far small subset of) XQuery, 1862the draft XML Query languaage. 1863 1864 Various internal (Java API) changes: Changes to gnu.expr.Interpreter 1865to make it easier to add non-Lisp-like languages; gnu.lists.Consumer now 1866has an endAttribute method that need to be called after each attribute, 1867rather than endAttributes that was called after all of them. 1868 1869 If configured with –with-gcj, Kawa builds and intalls a ’gckawa’ 1870script to simlify linking with needed libraries. 1871 1872 The ‘setter’ function is now inlined, and ‘(set! (field X 'N) V)’ and 1873‘(set! (static-field <T> "N) V)’ are now inlined. 1874 1875 If configured ‘--with-gcj’, then a ‘gckawa’ helper script is 1876installed, to make it easier to link Kawa+gcj-compiled applications. 1877 1878Changes from Kawa 1.6.92 to 1.6.94 1879---------------------------------- 1880 1881The JEmacs code now depends on CommonLisp, rather than vice versa, which 1882means Commonlisp no longer depends on Swing, and can be built with GCJ. 1883CommonLisp and JEmacs symbols are now implemented using Binding, not 1884String. 1885 1886Changes from Kawa 1.6.90 to 1.6.92 1887---------------------------------- 1888 1889Kawa now installs as a .jar file (kawa.jar symlinked to 1890kawa-VERSION.jar), rather than a collection of .class files. 1891 1892 The Kawa manual includes instructions for how to build Kawa using 1893GCJ, and how to compile Scheme code to a native executable using GCJ. 1894 1895 Kawa now has builtin pretty-printer support, using an algorithm from 1896Steel Bank Common Lisp converted from Lisp to Java. The high-level 1897Common Lisp pretty-printing features are mostly not yet implemented, but 1898the low-level support is there. The standard output and error ports 1899default to pretty-printing. 1900 1901 A new formatting framework uses the Consumer interface from 1902gnu.lists. You can associate a format with an output port. Common Lisp 1903and JEmacs finally print using their respective syntaxes. 1904 1905 All output ports (OutPort instances) are now automatically flushed on 1906program exit, using a new WriterManager helper class. 1907 1908 The new commmand-line option –debug-print-expr causes the Expression 1909for each expression to be printed. The option –debug-print-final-expr 1910is similar, but prints Expressions after optimization and just before 1911compilation. They are printed using the new pretty-printer. 1912 1913 Changed calling convention for –full-tailcalls to write results to a 1914Consumer, usually a TreeList or something to be printed. A top-level 1915ModuleBody now uses the same CpsProcedure convention. This is useful 1916for generating xml or html. 1917 1918 New libtool support allows kawa to be built as a shared library. 1919 1920 The new configure flag –with-gcj uses gcj to compile Kawa to both 1921.class files and native code. This is experimental. 1922 1923Changes from Kawa 1.6.70 to 1.6.90 1924---------------------------------- 1925 1926The reader (for Scheme and Lisp) has been re-written to be table-driven, 1927based on the design of Common Lisp readtables. 1928 1929 The new gnu.lists package has new implementations of sequence-related 1930classes. It replaces most of gnu.kawa.util. See the package.html file. 1931 1932 If the expected type of a non-unary ‘+’ or ‘-’ is ‘<int>’ or ‘<long>’ 1933and the operands are integeral types, then the operands will converted 1934to the primitive integer type and the addition or subtraction done using 1935primitive arithmetic. Similarly if the expected type is ‘<float>’ or 1936‘<long>’ and the operands have appropriate type. This optimization an 1937make a big performance difference. (We still need to also optimize 1938compare operations like ‘(< x y)’ to really benefit from ‘<int>’ 1939declarations of loop variables.) 1940 1941 The implementation of procedure closures has been changed to 1942basically be the same as top-level procedures (except when 1943–full-tailcalls is specified): Each procedure is now an instance of a 1944ModuleMethod, which each "frame" is an instance of ModuleBody, just like 1945for top-level functions. This sometimes reduces the number of classes 1946generated, but more importantly it simplifies the implementation. 1947 1948 A new ‘gnu.xml’ (api/gnu/xml/package-summary.html) package contains 1949XML-related code, currently an XML parser and printer, plus some XPath 1950support. The class ‘gnu.lists.TreeList’ (api/gnu/lists/TreeList.html) 1951(alias ‘<document>’) is useful for compactly representing nested 1952structures, including XML documents. If you ‘(require 'xml)’ you will 1953get Scheme interfaces (‘print-as-xml’ and ‘parse-xml-from-url’) to these 1954classes. 1955 1956 New package gnu.kawa.functions, for primitive functions (written in 1957Java). 1958 1959 The map and for-each procedure is now inlined. This is most 1960especially beneficial when it allows the mapped-over procedure to also 1961be inlined, such as when that procedure is a lambda expression. 1962 1963 Added documentation on compiling with Jikes. Renamed some classes to 1964avoid warning when compiling with Jikes. 1965 1966 The reverse! procedure was added. 1967 1968 Internal changes: * If a variable reference is unknown, create a 1969Declaration instance with the IS_UNKNOWN flag to represent an imported 1970binding. * The ExpWalker framework for "tree walking" Expressions had a 1971bit of reorganization. * New package gnu.kawa.functions, for primitive 1972functions (written in Java). 1973 1974 Added a hook for constant-folding and other optimization/inlining at 1975traversal (ExpWalker) time. Optimization of + and - procedures to use 1976primitive Java operations when the operands are primitive types. 1977 1978 Implementation of SRFI-17. Change the definitions of (set! (f x 1979...) val) to ((setter f) x ... val), rather then the old ((setter f) 1980val x ...). You can now associate a setter with a procedure, either 1981using make-procedure or set-procedure-property!. Also, (setter f) is 1982now inlined, when possible. 1983 1984 Internally, Syntax (and hence Macro) no longer extend Declaration. 1985 1986 Various Java-level changes, which may be reflected in Scheme later: * 1987gnu.kawa.util.Consumer interface is similar to ObjectOutput and SAX’s 1988ContentHandler interfaces. * A gnu.expr.ConsumerTarget is used when 1989evaluating to an implicit Consumer. * These interfaces will make it 1990easy to write functional-style but efficient code for transforming data 1991streams, including XML. * gnu.kawa.util.FString is now variable-size. 1992 1993Changes from Kawa 1.6.68 to 1.6.70 1994---------------------------------- 1995 1996The bare beginnings of Common Lisp support, enabled by the –commonlisp 1997(or –clisp) command line option. This is so far little more than a hack 1998of the EmacsLisp support, but with lexical scoping and CL-style format. 1999 2000Changes from Kawa 1.6.66 to 1.6.68 2001---------------------------------- 2002 2003JEmacs news: 2004 2005 • Define emacs-version as Kawa version but with leading 0 instead of 2006 1. For example, the current value is "0.6.68 JEmacs". 2007 • New testsuite directory. 2008 • Improved autoload framework. Handle ELisp autoload comments. 2009 • Handle escape and meta-key. 2010 • Handle lot more of ELisp. 2011 • Lots more is now done in ELisp, using .el files imported from 2012 XEmacs. 2013 • Incomplete support for setting mark, including using selection. 2014 • Basic (but incomplete) implementation of (interactive spec). 2015 • Common Lisp extensions: typep, default arguments. 2016 • A new status.html file to note what works and what doesn’t. 2017 2018 You can now specify in ‘define’ and ‘define-private’ the type of a 2019variable. If the variable is module-level, ‘(define name :: <type> 2020value)’ creates a field named “‘name’” having the specified type and 2021initial value. (If type is not specified, the default is not ‘Object’, 2022but rather a ‘Binding’ that _contains_ the variable’s value.) 2023 2024 You can now define the type of a module-level variable: In 2025(define[-private] :: type expression) New (define-constant name [:: 2026type] expression) definition form. 2027 2028 A procedure can now have arbitrary properties associated with it. 2029Use procedure-property and set-procedure-property! to get and set them. 2030 2031 The new procedure make-procedure creates a generic procedure that may 2032contain one or more methods, as well as specified properties. 2033 2034 New declaration form define-base-unit. Both it and define-unit have 2035been re-implemented to be module-safe. Basically ’(define-unit ft 203612in)’ is sugar for ’(define-constant ft$unit (... (* 12 in$unit)))’, 2037where ft$unit and in$unit are standard identifiers managed by the module 2038system. Also, the output syntax for units and quantities is cleaner. 2039 2040 The new declaration (module-export name ...) allows control over the 2041names exported from a module. The new declaration (module-static ...) 2042allows control over which definitions are static and which are 2043non-static. This makes it easier to use a module as a Java class. 2044 2045 Procedures names that accidentally clash with inherited method names 2046(such as "run") are now re-named. 2047 2048 Simple aliases (define-aliases defining an alias for a variable name) 2049are implemented more efficiently. 2050 2051 The package hierarchy is getter cleaner, with fewer cyclic 2052dependencies: The gnu.math package no longer has any dependencies on 2053kawa.* or gnu.*. Two classes were moved from gnu.text to other classes, 2054avoiding another cyclic package dependency between gnu.text and 2055gnu.mapping. The new gnu.kawa.lispexpr is for compile-time handling of 2056Lisp-like languages. 2057 2058 Compliation of literals has been re-done. A class that can be used 2059in a literal no longer needs to be declared as Compilable. Instead, you 2060declare it as implementaing java.io.Externalizable, and make sure it has 2061appropriate methods. 2062 2063 All the standard "data" types (i.e. not procedures or ports) now 2064implement java.io.Externalizable, and can thus be serialized. If they 2065appear in literals, they can also be compiled. 2066 2067 Created a new class gnu.kawa.util.AbstractString, with the Scheme 2068alias ‘<abstract-string>’. The old gnu.kawa.util.FString now extends 2069AbstractString. A new class CharBuffer provides an growable buffer, 2070with markers (automatically-adjusted positions). Many of the Scheme 2071‘<string>’ procedures now work on ‘<abstract-string>’. The JEmacs 2072BufferContnat class (contains the characters of a buffer) now extends 2073CharBuffer. 2074 2075 Some JEmacs changes to support a "mode" concept, as well as 2076preliminary support for inferior-process and telnet modes. 2077 2078 New section in manual / web page for projects using Kawa. 2079 2080 The record feasture (make-record-type etc) how handles "funny" type 2081and fields names that need to be "mangled" to Java names. 2082 2083 Re-did implementation of define-alias. For example, you can define 2084type-aliases: 2085‘(define-alias <marker> <gnu.jemacs.buffer.Marker>)’ 2086and then use <marker> instead of <gnu.jemacs.buffer.Marker>. 2087 2088 ‘(field array 'length)’ now works. 2089 2090Changes from Kawa 1.6.64 to 1.6.66 2091---------------------------------- 2092 2093Added documentation to the manual for Homogeneous numeric vector 2094datatypes (SRFI-4). 2095 2096 You can now specify characters using their Unicode value: #\u05d0 is 2097alef. 2098 2099 Kawa now uses a more mnemonic name mangling Scheme. For example, a 2100Scheme function named ‘<=’ would get compiled to method ‘$Ls$Eq’. 2101 2102 There is now working and useful module support, thought not all 2103features are implemented. The basic idea is that a module can be any 2104class that has a default constructor (or all of whose fields and methods 2105are static); the public fields and methods of such a class are its 2106exported definitions. Compiling a Scheme file produces such a module. 2107Doing: 2108‘ (require <classname>)’ 2109will create an anonymous instance of ‘<classname>’ (if needed), and add 2110all its exported definitions to the current environment. Note that if 2111you import a class in a module you are compiling, then an instance of 2112the module will be created at compile-time, and imported definitions are 2113not re-imported. (For now you must compile a module, you cannot just 2114load it.) 2115 2116 The define-private keyword creates a module-local definition. 2117 2118 New syntax to override some properties of the current module: 2119‘(module-name <name>)’ overrides the default name for a module. 2120‘(module-extends <class>)’ specifies the super-class. 2121‘(module-implements <interface> ...)’ specfies the implemented 2122interfaces. 2123 2124 The syntax: (require ’keyword) is syntactic sugar for (require 2125<classname>) where the classname is find is a "module catalog" 2126(currently hard-wired). This provides compatibility with Slib. The 2127Slib "features" gen-write, pretty-print, pprint-file, and printf are now 2128available in Kawa; more will be added, depending on time and demand. 2129See the package directory gnu/kawa/slib for what is available. 2130 2131Changes from Kawa 1.6.62 to 1.6.64 2132---------------------------------- 2133 2134A lot of improvements to JEmacs (see JEmacs.SourceForge.net). 2135 2136 kawa-compiled-VERSION.zip is replaced by kawa-compiled-VERSION.jar. 2137 2138 You can now use Kawa to generate applets, using the new –applet 2139switch, Check the "Applet compilation" section in the manual. 2140Generating an application using the –main flag should work again. 2141Neither –applet nor –main has Scheme hard-wired any more. 2142 2143 A new macro ‘(this)’ evaluates to the "this object" - the current 2144instance of the current class. The current implementation is 2145incomplete, and buggy, but it will have to do for now. 2146 2147 The command-line argument -f FILENAME will load the same files types 2148as load. 2149 2150 When a source file is compiled, the top-level definitions 2151(procedures, variables, and macros) are compiled to final fields on the 2152resulting class. This are not automatically entered into the current 2153environment; instead that is the responsibility of whoever loads the 2154compiled class. This is a major step towards a module system for Kawa. 2155 2156 There is a new form define-private which is like define, except that 2157the defined name is not exported from the current module. 2158 2159 A procedure that has optional arguments is now typically compiled 2160into multiple methods. If it’s a top-level procedure, these will be 2161methods in the modules "ModuleBody" class, with the same (mangled) name. 2162The compiler can in many cases call the appropriate method directly. 2163Usually, each method takes a fixed number of arguments, which means we 2164save the overhead of creating an array for the arguments. 2165 2166 A top-level procedure declared using the form (define (NAME ARS ...) 2167BODY ..) is assumed to be "constant" if it isn’t assigned to in the 2168current compilation unit. A call in the same compilation unit will now 2169be implemented as a direct method call. This is not done if the 2170prcedure is declared with the form: (define NAME (lambda (ARGS ,,,) BODY 2171...) 2172 2173 gnu.expr.Declaration no longer inherits from gnu.bytecode.Variable. 2174 2175 A gnu.mapping.Environment now resolves hash index collisions using 2176"double hashing" and "open addressing" instead of "chaining" through 2177Binding. This allows a Binding to appear in multiple Environments. 2178 2179 The classes Sequence, Pair, PairWithPosition, FString, and Char were 2180moved from kawa.lang to the new package gnu.kawa.util. It seems that 2181these classes (except perhaps Char) belong together. The classes List 2182and Vector were also moved, and at the same time renamed to LList and 2183FVector, respectively, to avoid clashed with classes in java.util. 2184 2185 New data types and procedures for "uniform vectors" of primitive 2186types were implemented. These follow the SRFI-4 specification, which 2187you can find at http://srfi.schemers.org/srfi-4/srfi-4.html . 2188 2189 You can now use the syntax ‘name :: type’ to specify the type of a 2190parameter. For example: 2191‘(define (vector-length x :: <vector>) (invoke x 'length))’ 2192The following also works: 2193‘(define (vector-length (x :: <vector>)) ...)’. 2194 2195 ‘(define-member-alias name object [fname])’ is new syntactic sugar 2196for ‘(define-alias name (field object fname))’, where the default for 2197‘fname’ is the mangling of ‘name’. 2198 2199Changes from Kawa 1.6.60 to 1.6.62 2200---------------------------------- 2201 2202The new function ‘invoke’ allows you to call a Java method. All of 2203‘invoke’, ‘invoke-static’ and ‘make’ now select the bets method. They 2204are also inlined at compile time in many cases. Specifically, if there 2205is a method known to be definitely applicable, based on compile-time 2206types of the argument expressions, the compiler will choose the most 2207specific such method. 2208 2209 The functions slot-ref, slot-set!, field, and static-field are now 2210inlined by the compiler when it can. 2211 2212 Added open-input-string, open-output-string, get-output-string from 2213SRFI-6. See http://srfi.schemers.org/srfi-6/srfi-6.html. 2214 2215 The manual has a new section "Mapping Scheme names to Java names", 2216and a new chapter "Types". The chapters "Extensions", "Objects and 2217Classes", and "Low-level functions" have been extensivley re-organized. 2218 2219 The Kawa license has been simplified. There used to be two licenses: 2220One for the packages gnu.*, and one for the packages kawa.*. There 2221latter has been replaced by the former. The "License" section of the 2222manual was also improved. 2223 2224Changes from Kawa 1.6.59 to 1.6.60 2225---------------------------------- 2226 2227There is a new package gnu.kawa.reflect. Some classes that used to be 2228in kawa.lang or kawa.standard are now there. 2229 2230 The procedures slot-ref and slot-set! are now available. They are 2231equivalent to the existing ‘field’, but reading a field ‘x’ will look 2232for ‘getX’ method if there is no public ‘x’ field; writing to a field 2233will look for ‘setX’. 2234 2235 The procedure ‘make’ makes it convenient to create new objects. 2236 2237 There is now a teaser screen snapshot of "JEmacs" at 2238http://www.bothner.com/~per/papers/jemacs.png. 2239 2240 The html version of the manual now has a primitive index. The manual 2241has been slightly re-organized, with a new "Classes and Objects" 2242chapter. 2243 2244 The new functions invoke-static and class-methods allow you to call 2245an arbitary Java method. They both take a class specification and a 2246method name. The result of class-methods is a generic procedure 2247consisting of those methods whose names match. (Instance methods are 2248also matched; they are treated the asme as class methods with an extra 2249initial argument.) The invoke-static function also takes extra 2250arguments, and actually calls the "best"-matching method. An example: 2251 2252 (invoke-static <java.lang.Thread> 'sleep 100) 2253 2254 Many fewer classes are now generated when compiling a Scheme file. 2255It used to be that each top-level procedure got compiled to its own 2256class; that is no longer the case. The change should lead to faster 2257startup and less resource use, but procedure application will probably 2258be noticably slower (though not so much slower as when reflection is 2259used). The reason for the slowdown is that we in the general case now 2260do an extra method call, plus a not-yet-optimized switch statement. 2261This change is part of the new Kawa module system. That will allow the 2262compiler to substitute direct methods calls in more cases, which I hope 2263will more than make up for the slowdown. 2264 2265 A Scheme procedure is now in general compiled to a Java method whose 2266name is a "mangling" of the Scheme procedure’s name. If the procedure 2267takes a variable number of parameters, then "$V" is added to the name; 2268this indicates that the last argument is a Java array containing the 2269rest of the arguments. Conversely, calling a Java method whose name 2270ends in "$V" passes any excess arguments in the last argument, which 2271must be an array type. 2272 2273 Many changes to the "Emacs-emulation" library in gnu.jemacs.buffer: * 2274Implemented commands to read and save files. * We ask for file and 2275buffer names using a dialog pop-up window. * Split windows correctly, 2276so that the windows that are not split keep their sizes, the windows 2277being split gets split as specified, and the frame does not change size. 2278Now also handles horizonal splits. * Fairly good support for 2279buffer-local keymaps and Emacs-style keymap search order. A new class 2280BufferKeymap manages the active keymaps of a buffer. Multi-key 2281key-sequences are handled. Pending prefix keys are remembered on a 2282per-buffer basis (whereas Emacs does it globally). 2283 2284 There is now some low-level support for generic procedures. 2285 2286 The R5RS primitives let-syntax and letrec-syntax for defining local 2287syntax extensions (macros) should now work. Also define-syntax works as 2288an internal definition. All of these should now be properly "hygienic". 2289(There is one known exception: symbols listed among the literals lists 2290are matched as raw symbols, rather that checking that the symbol has the 2291same binding, if any, as at the defining site.) The plan is to support 2292general functions as hygienic rewriters, as in the Chez Scheme 2293"syntax-case" system; as one part of that plan, the syntax-case 2294primitive is available, but so far without any of the supporting 2295machinary to support hygiene. 2296 2297 The read-line procedure was added. This allows you to efficiently 2298read a line from an input port. The interface is the same as scsh and 2299Guile. 2300 2301Changes from Kawa 1.6.58 to 1.6.59 2302---------------------------------- 2303 2304define-alias now works both top-level and inside a function. 2305 2306 Optimized eqv? so if one of the arguments is constant and not Char 2307or Numeric, inline it the same way eq? is. (This helps case when the 2308labels are symbols, which help the "lattice" benchmark.) ??? 2309 2310 The Emacs-related packages are now grouped under a new gnu.jemacs 2311package. 2312 2313 Improved framework for catching errors. This means improved error 2314messages when passing a parameter of the wrong type. Many standard 2315procedures have been improved. 2316 2317 Simplified, documented, and tested (!) procedure for building Kawa 2318from source under Windows (95/98/NT). 2319 2320 New macros trace and untrace for tracing procedures. After executing 2321(trace PROCEDURE), debugging output will be written (to the standard 2322error port) every time PROCEDURE is called, with the parameters and 2323return value. Use (untrace PROCEDURE) to turn tracing off. 2324 2325 New utility functions (system-tmpdir) and (make-temporary-file 2326[format]). 2327 2328 A new (unfinished) framework supports multiple languages. The 2329command-line option –elisp selects Emacs Lisp, while –scheme (the 2330default) selects Scheme. (The only difference so far is the reader 2331syntax; that will change.) 2332 2333 The ‘format’ function now provides fairly complete functionality for 2334CommonLisp-style formatting. (See the Comon Lisp hyperspec at 2335http://www.harlequin.com/education/books/HyperSpec/Body/sec_22-3.html.) 2336The floating point formatters (~F, ~E, ~G, ~$) now pass the formatst.scm 2337test (from Slib, but with some "fixes"; in the testsuite directory). 2338Also, output ports now track column numbers, so ‘~T’ and ‘~&’ also work 2339correctly. 2340 2341 A new package gnu.emacs provides various building blocks for building 2342an Emacs-like text editor. These classes are only compiled when Kawa is 2343configured with the new –with-swing configuration option. This is a 2344large initial step towards "JEmacs" - an Emacs re-implemented to use 2345Kawa, Java, and Swing, but with full support (using gnu.elisp) for 2346traditional Emacs Lisp. For more imformation see 2347gnu/emacs/overview.html. 2348 2349 A new configuration option –with-swing can be used if Swing is 2350available. It is currently only used in gnu.emacs, but that may change. 2351 2352Changes from Kawa 1.6.56 to 1.6.58 2353---------------------------------- 2354 2355Kawa is now "properly tail-recursive" if you invoke it with the 2356–full-tail-calls flag. (Exception: the eval procedure does not perform 2357proper tail calls, in violation of R5RS. This will be fixed in a future 2358release.) Code compiled when –full-tail-calls is in effect is also 2359properly tail-recursive. Procedures compiled with –full-tail-calls can 2360call procedures compiled without it, and vice versa (but of course 2361without doing proper tail calls). The default is still 2362–no-full-tail-calls, partly because of performance concerns, partly 2363because that provides better compatibility with Java conventions and 2364tools. 2365 2366 The keywords let (including named let), let*, and letrec support type 2367specifiers for the declared variables For example: 2368 2369 (let ((lst :: <list> (foo x))) (reverse lst)) 2370 2371 Square brackets [ ... ] are allowed as a synonym of parentheses ( 2372... ). 2373 2374Changes from Kawa 1.6.55 to 1.6.57 2375---------------------------------- 2376 2377A new command-line flag –server PORT specifies that Kawa should run as a 2378telnet server on the specified PORT, creating a new read-eval-print loop 2379for each connection. This allows you to connect using any telnet client 2380program to a remote "Kawa server". 2381 2382 A new front-end program, written in C, that provides editing of input 2383lines, using the GNU readline library. This is a friendlier interface 2384than the plain "java kawa.repl". However, because kawa.c needs readline 2385and suitable networking library support, it is not built by default, but 2386only when you configure Kawa with the –enable-kawa-frontend flag. 2387 2388 The way Scheme names are mapped ("mangled") into Java identifiers is 2389now more natural. E.g. "foo-bar?" now is mapped to "isFooBar". 2390 2391 New syntax (object (SUPERS ...) FIELD-AND-METHODS ...) for creating 2392a new object instance of an anonymous class. Now fairly powerful. 2393 2394 New procedures field and static-field for more convenient field 2395access. 2396 2397 Syntactic sugar: ‘(lambda args <type> body)’ -> ‘(lambda args (as 2398<type> body))’. This is especially useful for declaring methods in 2399classes. 2400 2401 A new synchonized form allows you to synchronize on an arbitrary Java 2402object, and execute some forms while having an exclusive lock on the 2403object. (The syntax matches that used by Skij.) 2404 2405Changes from Kawa 1.6.53 to 1.6.55 2406---------------------------------- 2407 2408New –debug-dump-zip option writes out a .zip file for compilation. 2409(Useful for debugging Kawa.) 2410 2411 You can now declare parameter types. 2412 2413 Lot of work on more efficient procedure representation and calling 2414convention: Inlining, directly callable statics method, plus some 2415procedures no longer generate a separate Class. 2416 2417 Local functions that are only called from one locations, except for 2418tail-recursion, are now inlined. This inlines do loops, and most "named 2419let" loops. 2420 2421 New representation of closures (closures with captured local 2422variables). We no longer use an array for the closure. Instead we 2423store the captured variables in the Procedure itself. This should be 2424faster (since we can use field accesses rather than array indexing, 2425which requires bounds checking), and avoids a separate environment 2426object. 2427 2428 If the compiler sees a function call whose (non-lexically-bound) name 2429matches an existing (globally-defined) procedure, and that procedure 2430instance has a static method named either "apply" or the mangled 2431procedure name, them the compiler emits a direct call to that method. 2432This can make a very noticable speed difference, though it may violate 2433strict Scheme sementics, and some code may break. 2434 2435 Partial support for first-class "location" variables. 2436 2437Changes from Kawa 1.6.53 to 1.6.54 2438---------------------------------- 2439 2440Created new packages gnu.mapping and gnu.expr. Many classes were moved 2441from kawa.lang to the new packages. (This is part of the long-term 2442process of splitting Kawa into more manageable chunks, separating the 2443Scheme-specific code from the language-independent code, and moving 2444classes under the gnu hierarchy.) 2445 2446 You can now write keywords with the colon first (e.g. :KEYWORD), 2447which has exactly the same effect and meaning as putting the colon last 2448(e.g. KEYWORD:). The latter is preferred is being more consistent with 2449normal English use of punctuation, but the former is allowed for 2450compatibility with soem other Scheme implementations and Common Lisp. 2451 2452Changes from Kawa 1.6.52 to 1.6.53 2453---------------------------------- 2454 2455The new package gnu.text contains facilities for reading, formatting, 2456and manipulating text. Some classes in kawa.lang where moved to there. 2457 2458 Added string-upcase!, string-downcase!, string-capitalize!, 2459string-upcase, string-downcase, and string-capitalize; compatible with 2460Slib. 2461 2462 Character constants can now use octal notation (as in Guile). 2463Writing a character uses octal format when that seems best. 2464 2465 A format function, similar to that in Common Lisp (and Slib) has been 2466added. 2467 2468 The default parameter of a #!optional or #!key parameter can now be 2469#!null. 2470 2471Changes since Kawa 1.6.51 2472------------------------- 2473 2474The "record" feature has been changed to that a "record-type descriptor" 2475is now a gnu.bytecode.ClassType (a ‘<record-type>’), rather than a 2476java.lang.Class. Thus make-record-type now returns a ‘<record-typee>’, 2477not a Class, and ‘record-type-descriptor’ takes a ‘<record-typee>’, not 2478a Class. 2479 2480 More robust Eval interfaces. 2481 2482 New Lexer abstract class. New ScmRead class (which extends Lexer) 2483now contains the Scheme reader (moved from Inport). Now read errors are 2484kept in queue, and can be recovered from. 2485 2486 Comparing an exact rational and an inexact real (double) is now done 2487as if by first converting the double to exact, to satisfy R5RS. 2488 2489Changes since Kawa 1.6.1 2490------------------------ 2491 2492The compile virtual method in Expression now takes a Target object, 2493representing the "destination". The special ConditionalTarget is used 2494to evaluate the test of an ’if expression. This allows us to generate 2495much better code for and, or, eq?, not and nested if inside an if. 2496 2497 Added port-line, port-column, and set-port-line! to match Guile. 2498 2499 The Makefiles have been written so all out-of-date .java (or .scm). 2500files in a directory are compiled using a single invocation of javac (or 2501kawa). Building Kawa should now be much faster. (But note that this 2502depends on unreleased recent autoamke changes.) 2503 2504 How the Kawa version number is compiled into Kawa was changed to make 2505it easier for people who want to build from source on non-Unix-like 2506systems. 2507 2508 A new gnu.ecmascript package contains an extremely incomplete 2509implementation of ECMSScript, the ECMA standardized version of 2510JavaScript. It includes an ECMAScript lexer (basically complete), 2511parser (the framework is there but most of the language is missing), 2512incomplete expression evaluation, and a read-eval-print-loop (for 2513testing only). 2514 2515Changes in Kawa 1.6.1 2516--------------------- 2517 2518Improved Kawa home page with extra links, pointer to Java-generated api 2519docs, and homepages for gnu.math and gnu.bytecode. 2520 2521 Implemented system, make-process, and some related procedures. 2522 2523 Added macros for primitive access to object fields, static fields, 2524and Java arrays. Added constant-fold syntax, and used it for the other 2525macros. 2526 2527 The –main flag compiles Scheme code to an application (containing a 2528main method), which can be be invoked directly by a Java interpreter. 2529 2530 Implemented –version (following GNU standards) as kawa.repl 2531command-line flag. 2532 2533Changes since Kawa 1.5.93 2534------------------------- 2535 2536Adding make procedure to create new objects/records. 2537 2538 Extended (set! (f . args) value) to be equivalent to ((setter f) 2539value . args). Implemented setter, as well as (setter car) and (setter 2540cdr). 2541 2542 Can now get and set a record field value using an application: (rec 2543’fname) gets the value of the field named fname in record rec. (set! 2544(rec ’fname) value) sets the value of the field named fname in rec. 2545 2546 A partial re-write of the implementation of input ports and the 2547Scheme reader, to fix some problems, add some features, and improve 2548performance. 2549 2550 Compiled .class files are now installed in $(datadir)/java, rather 2551than $(prefix)/java. By default, that means they are installed in 2552/usr/local/shared/java, rather than /usr/local/java. 2553 2554 There is now internal infrastructure to support inlining of 2555procedures, and general procedure-specific optimized code generation. 2556 2557 There is better testing that the right number of arguments are passed 2558to a procedure, and better error messages when you don’t. If the 2559procedure is inlined, you get a compile-time error message. 2560 2561 The functions created by primitive-constructor, 2562primitive-virtual-method, primitive-static-method, and 2563primitive-interface-method are now first-class procedure values. They 2564use the Java reflection facily, except when the compiler can directly 2565inline them (in which case it generates the same efficient bytecodes as 2566before). 2567 2568 New functions instance? (tests type membership) and as (converts). 2569 2570 The kawa.html is now split into several files, one per chapter. The 2571table of contents is now kawa_toc.html. 2572 2573 The syntactic form try-catch provides low-level exception handler 2574support. It is basically the same as Java’s try/catch form, but in 2575Scheme syntax. The new procedure primitive-throw throws an exception 2576object. 2577 2578 The higher-level catch and throw procedures implement exception 2579handling where the handler is specified with a "key" (a symbol). These 2580functions were taken from Guile. 2581 2582 The error function has been generalized to take multiple arguments 2583(as in Guile). It is now a wrapper around (throw ’misc-error ...). 2584 2585 There is a new "friendly" GUI access to the Kawa command-line. If 2586you invoke kawa.repl with the -w flag, a new interaction window is 2587created. This is uses the AWT TextArea class. You can create multiple 2588"consoles". They can either share top-level enevironments, or have 2589separate environments. This window interface has some nice features, 2590including editing. Added a scheme-window procedure, which is another 2591way to create a window. 2592 2593Changes since Kawa 1.5 2594---------------------- 2595 2596The default prompt now shows continuations lines differently. 2597 2598 The copy-file function was added. 2599 2600 The variable port-char-encoding controls how external files are 2601converted to/from internal Unicode characters. It also controls whether 2602CR and CR-LF are converted to LF. 2603 2604 The reader by default no longer down-cases letters in symbols. A new 2605variable symbol-read-case control how case is handled: ’P (the default) 2606preserves case; ’U upper-cases letters; ’D or -" down-cases letters; and 2607’I inverts case. 2608 2609 The gnu.bytecode package now supports exception handlers. The new 2610syntactic form try-finally supports a cleanup hook that is run after 2611some other code finishes (normally or abnormally). Try-finally is used 2612to implement dynamic-wind and fluid-let. 2613 2614 The environment handling has been improved to support thread-specific 2615environments, a thread-safe fluid-let, and multiple top-levels. (The 2616latter still needs a bit of work.) 2617 2618 The gnu.bytecode package has been extensively changed. There are new 2619classes representing the various standard Attributes, and data 2620associated with an attribute is now stored there. 2621 2622 Added new procedures environment-bound? and 2623scheme-implementation-version. 2624 2625 Scheme symbols are represented as java.lang.String objects. Interned 2626symbols are interned Strings; uninterned symbols are uninterned Strings. 2627Note that Java strings literals are automatically interned in JDK 1.1. 2628This change makes symbols slightly more efficient, and moves Kawa closer 2629to Java. 2630 2631 Ports now use the JDK 1.1 character-based Reader and Writer classes, 2632rather than the byte-oriented InputStream and OutputStream classes. 2633This supports different reading and writing different character 2634encodings [in theory - there is no support yet for other than Ascii or 2635binary files]. 2636 2637 An interactive input port now has a prompt function associated with 2638it. It is settable with set-input-port-prompter!. The prompt function 2639takes one argument (the input port), and returns a prompt string. There 2640are also user functions for inquiring about the current line and column 2641number of an input port. 2642 2643 The R4RS procedures transcript-on and transcript-off are implemented. 2644 2645 Standard types can be referred to using syntax similar to RScheme. 2646For example Scheme strings now have the type ‘<string>’ which is 2647preferred to "‘kawa.lang.FString’" (which in addition to being longer, 2648is also more suspectible to changes in internal implementation). Though 2649these types are first-class values, this is so far mainly useful for 2650invoking primitive methods. 2651 2652Changes from Kawa 1.4 to 1.5 2653---------------------------- 2654 2655Execute a ~/.kawarc.scm file on startup, if it exists. 2656 2657 Add a number of functions for testing, renaming, and deleting files. 2658These are meant to be compatible with scsh, Guile, and MIT Scheme: 2659file-exists?, file-directory?, file-readable?, file-writable?, 2660delete-file, rename-file, create-diretory, and the variable 2661home-directory. 2662 2663 Fixed some small bugs, mainly in gnu.math and in load. 2664 2665 Generalize apply to accept an arbitrary Sequence, or a primitive Java 2666array. 2667 2668Changes from Kawa 1.2 to 1.4 2669---------------------------- 2670 2671The codegen package has been renamed gnu.bytecode. The kawa.math 2672package has been moved to gnu.math. Both packages have new license: No 2673restrictions if you use an unmodified release, but GNU General Public 2674License. Let me know if that causes problems. The rest of Kawa still 2675has the old license. 2676 2677 Implement defmacro and gentemp. 2678 2679 Implement make-record-type and related functions to create and use 2680new record types. A record type is implemented as a java.lang.Class 2681object, and this feature depends on the new reflection features of JDK 26821.1. 2683 2684 Implement keywords, and extend lambda parameter lists to support 2685#!optional #!rest and #!keyword parameters (following DSSSL). 2686 2687 Added more primitives to call arbitrary interface and constructor 2688methods. 2689 2690Changes from Kawa 1.0 to 1.2 2691---------------------------- 2692 2693Added primitives to make it easy to call arbitrary Java methods from 2694Scheme. 2695 2696 Exact rational arithetic is now fully implemented. All integer 2697functions now believed to correctly handle bignums. Logical operations 2698on exact integers have been implemented. These include all the logical 2699functions from Guile. 2700 2701 Complex numbers are implemented (except {,a}{sin,cos,tan}). 2702Quantities (with units) are implemented (as in DSSSL). 2703 2704 Eval is available, as specified for R5RS. Also implemented are 2705scheme-report-environment, null-environment, and 2706interaction-environment. 2707 2708 Internal define is implemented. 2709 2710 Rough support for multiple threads is implemented. 2711 2712 Moved kawa class to kawa/repl. Merged in kawac (compiler) 2713functionality. A ’kawa’ shell-script is now created. This is now the 2714preferred interface to both the interactive evaluator and the compiler 2715(on Unix-like systems). 2716 2717 Now builds "without a snag" using Cafe 1.51 under Win95. (Symantec 2718JIT (ver 2.00b19) requires disabling JIT - ‘JAVA_COMPCMD=disable’.) 2719Compiles under JDK 1.1 beta (with some warnings). 2720 2721 A testsuite (and testing framework) was added. 2722 2723 Documentation moved to doc directory. There is now an internals 2724overview, in doc/kawa-tour.ps. 2725 2726Changes since 0.4 2727----------------- 2728 2729The numeric classes have been re-written. There is partial support for 2730bignums (infinite-precision integers), but divide (for example) has not 2731been implemented yet. The representation of bignums uses 2’s 2732complement, where the "big digits" are laid out so as to be compatible 2733with the mpn functions of the GNU Multi-Precision library (gmp). (The 2734intent is that a future version of Kawa will support an option to use 2735gmp native functions for speed.) 2736 2737 The kawa application takes a number of useful command-line switches. 2738 2739 Basically all of R4RS has been implemented. All the essential forms 2740and functions are implemented. Almost all of the optional forms are 2741implemented. The exceptions are transcript-on, transcript-off, and the 2742functions for complex numbers, and fractions (exact non-integer 2743rationals). 2744 2745 Loading a source file with load now wraps the entire file in a lambda 2746(named "atFileLevel"). This is for better error reporting, and 2747consistency with compile-file. 2748 2749Changes since 0.3 2750----------------- 2751 2752The hygienic macros described in the appendix to R4RS are now impemented 2753(but only the define-syntax form). They are used to implement the 2754standard "do" form. 2755 2756 The R5RS multiple value functions ‘values’ and ‘call-with-values’ are 2757implemented. 2758 2759 Macros (and primitive syntax) can now be autoloaded as well as 2760procedures. 2761 2762 New kawac application compiles to one or more .class files. 2763 2764 Compile time errors include line numbers. Uncaught exceptions cause 2765a stack trace that includes .scm line numbers. This makes it more 2766practical to debug Kawa with a Java debugger. 2767 2768 Quasiquotation is implemented. 2769 2770 Various minor bug fixes and optimizations. 2771 2772Changes since 0.2 2773----------------- 2774 2775The biggest single change is that Scheme procedures are now compiled to 2776Java bytecodes. This is mainly for efficiency, but it also allows us to 2777do tail-recursion-elimination in some cases. 2778 2779 The "codegen" library is included. This is a toolkit that handles 2780most of the details needed to generate Java bytecode (.class) files. 2781 2782 The internal structure of Kawa has been extensively re-written, 2783especially how syntax transforms, eval, and apply are done, largely due 2784to the needs for compilation. 2785 2786 Almost all the R4RS procedures are now implemented, except that there 2787are still large gaps in Section 6.5 "Numbers". 2788 2789 2790File: kawa.info, Node: Features, Next: Community, Prev: News, Up: Top 2791 27922 Features 2793********** 2794 2795Runs on the Java platform, with no native code needed. 2796 2797 Extends the Scheme language 2798(http://en.wikipedia.org/wiki/Scheme_%28programming_language%29), 2799following the R7RS (http://r7rs.org/) specification from 2013. Scheme 2800has many implementations, and is much used in research and teaching. 2801 2802 Programs run fast 2803(http://per.bothner.com/blog/2010/Kawa-in-shootout/) - roughly as fast 2804as Java programs, and much faster than other “scripting languages”. 2805This is due to a sophisticated compiler, compile-time transformations, 2806type inference, and optional type declarations. 2807 2808 Full, convenient, and efficient access to the huge set of Java 2809libraries means you can access objects, methods, fields, and classes 2810without run-time overhead. 2811 2812 Start-up times are fast. You don’t have to wait for a lot of 2813initialization. Even if you start with source code, the parser and 2814compiler are fast. 2815 2816 *note Scripts:: are simple Kawa source files that can run as an 2817application or command. These are simple to write, start, and run 2818efficiently, since they’re automatically compiled before execution. 2819 2820 Alternatively, you can embed Kawa as a *note scripting language for 2821Java applications: Evaluating Scheme expressions from Java. 2822 2823 Deployment is easy and flexible. You just need the Kawa jar file. 2824 2825 *note Macros:: and *note custom named literals: Named quasi-literals. 2826make it easy to extend the syntax and implement Domain-Specific 2827Languages. 2828 2829 Kawa provides the usual *note read-eval-print loop: REPL Console, as 2830well as batch modes. 2831 2832 Kawa has builtin *note pretty-printer: Pretty-printing. support, and 2833fancy formatting. 2834 2835 Kawa supports class-definition facilities, and separately-compiled 2836modules. 2837 2838 You can *note allocate and initialize objects: Allocating objects. 2839with a compact “builder” syntax. It works out-of-the-box (with no 2840run-time overhead) on many classes and APIs, but can be customized if 2841need be. 2842 2843 A library for functional *note composable pictures: Composable 2844pictures. lets you create “picture” objects, display them, transform 2845them, combine them, convert to SVG or images, and more. This can be 2846“printed” directly in the Kawa console (either the DomTerm console or 2847the Swing one). 2848 2849 *note JavaFX programming: Building JavaFX applications. is simpler. 2850 2851 You can *note run Kawa programs on Android: Building for Android, and 2852there is special handling to make *note constructing View objects: 2853Android view construction. easier. 2854 2855 Flexible shell-like functionality, including *note process 2856literals::. 2857 2858 *note Web page scripts: Server-side scripts. are easy to write and 2859install with *note self-configuring web servers: Self-configuring page 2860scripts, optionally using *note servlets: Servlets. and *note XML 2861literals::. 2862 2863 *note Arrays:: and sequences have a lot of flexibility: Arrays can be 2864multi-dimensional; you can use an array as an index (which generalizes 2865slices and permutations); you can define a lazy array using a function 2866that maps indexes to values; you can re-map the indexes to yield a 2867transformed array. 2868 2869 Many useful features for mathematics and numerics: 2870 • The full “numeric tower” includes infinite-precision rational 2871 numbers and complex numbers. 2872 • Compile-time optimization of arithmetic with the use of type 2873 declarations and inference. 2874 • A *note “quantity”: Quantities. is a real number with a unit, such 2875 as ‘3cm’. 2876 • *note Quaternions:: are a 4-dimensional generalization of complex 2877 numbers. Unsigned primitive integer types (‘ubyte’, ‘ushort’, 2878 ‘uint’, ‘ulong’) are implemented efficiently without object 2879 allocation. 2880 2881 A *note lazy value: Lazy evaluation. wraps an expression which is 2882evaluated only when it is needed. 2883 2884 Kawa provides a *note framework: Framework. for implementing other 2885programming languages, and comes with incomplete support for CommonLisp, 2886Emacs Lisp, and EcmaScript, and XQuery 2887(http://www.gnu.org/software/qexo/). 2888 2889* Menu: 2890 2891* Implemented SRFIs:: 2892* Compatibility:: Compatibility with standards 2893 2894 2895File: kawa.info, Node: Implemented SRFIs, Next: Compatibility, Up: Features 2896 28972.1 Implemented SRFIs 2898===================== 2899 2900Kawa implements the following semi-standard SRFIs (Scheme Request for 2901Implementation (http://srfi.schemers.org/)): 2902 • SRFI 0 (http://srfi.schemers.org/srfi-0/srfi-0.html): Feature-based 2903 conditional expansion construct, using ‘cond-expand’ - *note Syntax 2904 and conditional compilation::. 2905 • SRFI 1 (http://srfi.schemers.org/srfi-1/srfi-1.html): List Library, 2906 if ‘(require 'list-lib)’ - *note SRFI-1::. 2907 • SRFI 2 (http://srfi.schemers.org/srfi-2/srfi-2.html): AND-LET*: an 2908 AND with local bindings, a guarded LET* special form. 2909 • SRFI 4 (http://srfi.schemers.org/srfi-4/srfi-4.html): Homogeneous 2910 numeric vector datatypes - *note Uniform vectors::. 2911 • SRFI 6 (http://srfi.schemers.org/srfi-6/srfi-6.html): Basic String 2912 Ports - *note Ports::. 2913 • SRFI 8 (http://srfi.schemers.org/srfi-8/srfi-8.html): ‘receive’: 2914 Binding to multiple values - *note Multiple values::. 2915 • SRFI 9 (http://srfi.schemers.org/srfi-9/srfi-9.html): Defining 2916 Record Types, using ‘define-record-type’ - *note Record types::. 2917 • SRFI 10 (http://srfi.schemers.org/srfi-10/srfi-10.html): ‘#,’ 2918 external form for special named types. This is deprecated for 2919 various reasons, including that it conflicts with syntax-case 2920 ‘unsyntax’. Better to use srfi-108 *note Named quasi-literals::. 2921 • SRFI 11 (http://srfi.schemers.org/srfi-11/srfi-11.html): Syntax for 2922 receiving multiple values, using ‘let-values’ and ‘let*-value’ - 2923 *note Multiple values::. 2924 • SRFI 13 (http://srfi.schemers.org/srfi-13/srfi-13.html): String 2925 Library. Needs some polishing. 2926 • SRFI 14 (http://srfi.schemers.org/srfi-14/srfi-14.html): 2927 Character-set Library - *note Character sets::. 2928 • SRFI 16 (http://srfi.schemers.org/srfi-16/srfi-16.html): Syntax for 2929 procedures of variable arity, using ‘case-lambda’ 2930 (http://srfi.schemers.org/srfi-16/srfi-16.html). 2931 • SRFI 17 (http://srfi.schemers.org/srfi-17/srfi-17.html): 2932 Generalized ‘set!’ - *note Locations::. 2933 • SRFI 23 (http://srfi.schemers.org/srfi-23/srfi-23.html): Error 2934 reporting mechanism, using ‘error’ - *note Exceptions::. 2935 • SRFI 25 (http://srfi.schemers.org/srfi-25/srfi-25.html): 2936 Multi-dimensional Array Primitives - *note Arrays::. 2937 • SRFI 26 (http://srfi.schemers.org/srfi-26/srfi-26.html): Notation 2938 for Specializing Parameters without Currying - *note Procedures::. 2939 • SRFI 28 (http://srfi.schemers.org/srfi-28/srfi-28.html): Basic 2940 Format Strings - *note Format::. 2941 • SRFI 30 (http://srfi.schemers.org/srfi-30/srfi-30.html): Nested 2942 Multi-line Comments. 2943 • SRFI 35 (http://srfi.schemers.org/srfi-35/srfi-35.html): 2944 Conditions. 2945 • SRFI 37 (http://srfi.schemers.org/srfi-37/srfi-37.html): 2946 ‘args-fold’ - a program argument processor 2947 (http://srfi.schemers.org/srfi-37/srfi-37.html), if ‘(require 2948 'args-fold)’. 2949 • SRFI 38 (http://srfi.schemers.org/srfi-38/srfi-38.html): External 2950 Representation for Data With Shared Structure. The 2951 ‘read-with-shared-structure’ is missing, but subsumed by ‘read’. 2952 • SRFI 39 (http://srfi.schemers.org/srfi-39/srfi-39.html): *Note 2953 Parameter objects::. 2954 • SRFI 41 (http://srfi.schemers.org/srfi-41/srfi-41.html): Streams - 2955 *note Streams::. 2956 • SRFI 45 (http://srfi.schemers.org/srfi-45/srfi-45.html): Primitives 2957 for Expressing Iterative Lazy Algorithms - *note Lazy evaluation::. 2958 • SRFI 60 (http://srfi.schemers.org/srfi-60/srfi-60.html): Integers 2959 as Bits. - *note Logical Number Operations::. 2960 • SRFI 62 (http://srfi.schemers.org/srfi-62/srfi-62.html): 2961 S-expression comments. 2962 • SRFI 64 (http://srfi.schemers.org/srfi-64/srfi-64.html): A Scheme 2963 API for test suites. 2964 • SRFI 69 (http://srfi.schemers.org/srfi-69/srfi-69.html): Basic hash 2965 tables - *note Hash tables::. 2966 • SRFI 87 (http://srfi.schemers.org/srfi-87/srfi-87.html): ‘=>’ in 2967 ‘case’ clauses. 2968 • SRFI 88 (http://srfi.schemers.org/srfi-88/srfi-88.html): Keyword 2969 objects - *note Keywords::. 2970 • SRFI 95 (http://srfi.schemers.org/srfi-95/srfi-95.html): Sorting 2971 and Merging. 2972 • SRFI 97 (http://srfi.schemers.org/srfi-97/srfi-97.html): Names for 2973 SRFI Libraries. 2974 • SRFI 98 (http://srfi.schemers.org/srfi-98/srfi-98.html): An 2975 interface to access environment variables 2976 • SRFI 101 (http://srfi.schemers.org/srfi-101/srfi-101.html): Purely 2977 Functional Random-Access Pairs and Lists - *note SRFI-101::. 2978 • SRFI 107 (http://srfi.schemers.org/srfi-107/): XML reader syntax - 2979 *note XML literals::. 2980 • SRFI 108 (http://srfi.schemers.org/srfi-108/): Named quasi-literal 2981 constructors - *note Named quasi-literals::. 2982 • SRFI-109 (http://srfi.schemers.org/srfi-109/srfi-109.html): 2983 Extended string quasi-literals - *note string quasi-literals::. 2984 • SRFI-118 (http://srfi.schemers.org/srfi-118/srfi-118.html): Simple 2985 adjustable-size strings (‘string-append!’ and ‘string-replace!’). 2986 • SRFI-140 (http://srfi.schemers.org/srfi-140/srfi-140.html): 2987 Immutable Strings. 2988 • SRFI-163 (http://srfi.schemers.org/srfi-163/srfi-163.html): 2989 Enhanced array literals. 2990 • SRFI-164 (http://srfi.schemers.org/srfi-164/srfi-164.html): 2991 Enhanced multi-dimensional Arrays 2992 2993 2994File: kawa.info, Node: Compatibility, Prev: Implemented SRFIs, Up: Features 2995 29962.2 Compatibility with standards 2997================================ 2998 2999Kawa implements all the required and optional features of R7RS, with the 3000following exceptions. 3001 3002 The entire “numeric tower" is implemented. However, some 3003transcendental functions only work on reals. Integral functions do not 3004necessarily work on inexact (floating-point) integers. (The whole idea 3005of “inexact integer" in R5RS seems rather pointless ...) 3006 3007 Also, ‘call-with-current-continuation’ is only “upwards" (?). I.e. 3008once a continuation has been exited, it cannot be invoked. These 3009restricted continuations can be used to implement catch/throw (such as 3010the examples in R4RS), but not co-routines or backtracking. 3011 3012 Kawa now does general tail-call elimination, but only if you use the 3013flag ‘--full-tailcalls’. (Currently, the ‘eval’ function itself is not 3014fully tail-recursive, in violation of R5RS.) The ‘--full-tailcalls’ flag 3015is not on by default, partly because it is noticably slower (though I 3016have not measured how much), and partly I think it is more useful for 3017Kawa to be compatible with standard Java calling conventions and tools. 3018Code compiled with ‘--full-tailcalls’ can call code compiled without it 3019and vice versa. 3020 3021 Even without ‘--full-tailcalls’, if the compiler can prove that the 3022procedure being called is the current function, then the tail call will 3023be replaced by a jump. This includes must “obvious” cases of calls to 3024the current function named using ‘define’ or ‘letrec’, and many cases of 3025mutual tail-recursion (including state-machines using ‘letrec’). 3026 3027 By default, symbols are case sensitive. 3028 3029 Kawa implements most of the features of the expression language of 3030DSSSL, the Scheme-derived ISO-standard Document Style Semantics and 3031Specification Language for SGML. Of the core expression language, the 3032only features missing are character properties, ‘external-procedure’, 3033the time-relationed procedures, and character name escapes in string 3034literals. From the full expression language, Kawa additionally is 3035missing ‘format-number’, ‘format-number-list’, and language objects. 3036Quantities, keyword values, and the expanded ‘lambda’ form (with 3037optional and keyword parameters) are supported. 3038 3039 3040File: kawa.info, Node: Community, Next: Installation, Prev: Features, Up: Top 3041 30423 The Kawa Community 3043******************** 3044 3045* Menu: 3046 3047* Reporting bugs:: Where to report bugs 3048* Mailing lists:: Where to discuss changes, etc 3049* Acknowledgements:: Acknowledgements and thanks 3050* Support:: Technical support for Kawa 3051* Projects:: Projects using Kawa 3052* Ideas and tasks:: Ideas and tasks for contributing to Kawa 3053 3054 3055File: kawa.info, Node: Reporting bugs, Next: Mailing lists, Up: Community 3056 30573.1 Reporting bugs 3058================== 3059 3060To report a bug or a feature request use the Issue Tracker 3061(https://gitlab.com/kashell/Kawa/issues). This does require a GitLab 3062(https://gitlab.com/) account; if this is a problem you can use the 3063Savannah bug tracker. 3064 3065Older Savannah bug tracker 3066.......................... 3067 3068The older bug tracker for Kawa on Savannah is still available, but we 3069request you use the GitLab Issue Tracker 3070(https://gitlab.com/kashell/Kawa/issues) for new issues. 3071 3072 To report a bug or feature request for Kawa (including Qexo or 3073JEmacs) through Savannah, use the bug-submission page 3074(http://savannah.gnu.org/bugs/?func=additem&group=kawa). You can browse 3075and comment on existing bug reports using the Kawa Bugzilla page 3076(http://savannah.gnu.org/bugs/?group=kawa). 3077 3078 When a bug report is created or modified, mail is automatically sent 3079to the <bug-kawa@gnu.org> list. You can subscribe, unsubscribe, or 3080browse the archives through the ‘bug-kawa’ web interface 3081(http://mail.gnu.org/mailman/listinfo/bug-kawa). 3082 3083 3084File: kawa.info, Node: Mailing lists, Next: Acknowledgements, Prev: Reporting bugs, Up: Community 3085 30863.2 General Kawa email and discussion 3087===================================== 3088 3089The general Kawa email list is <kawa@sourceware.org>. This mailing list 3090is used for announcements, questions, patches, and general discussion 3091relating to Kawa. If you wish to subscribe, send a blank message 3092request to <kawa-subscribe@sourceware.org>. To unsubscribe, send a 3093blank message to <kawa-unsubscribe@sourceware.org>. (If your mail is 3094forwarded and you’re not sure which email address you’re subscribed as, 3095send mail to the address following ‘mailto:’ in the ‘List-Unsubscribe’ 3096line in the headers of the messages you get from the list.) 3097 3098 You can browse the archive of past messages 3099(http://sourceware.org/ml/kawa/). 3100 3101 There are separate mailing lists for Qexo 3102(http://mail.gnu.org/mailman/listinfo/qexo-general) and JEmacs 3103(http://lists.sourceforge.net/mailman/listinfo/jemacs-info). 3104 3105 3106File: kawa.info, Node: Acknowledgements, Next: Support, Prev: Mailing lists, Up: Community 3107 31083.3 Acknowledgements and thanks 3109=============================== 3110 3111The author and project leader of Kawa is Per Bothner 3112(http://per.bothner.com/) <per@bothner.com>. 3113 3114 Kawa is a re-write of Kawa 0.2, which was a Scheme interpreter 3115written by R. Alexander Milowski <alex@milowski.com>. 3116 3117 Thanks to Cygnus Solutions (now part of Red Hat) for sponsoring the 3118initial development of Kawa, and then transferring their ownership 3119interest to Per. 3120 3121Financial support 3122................. 3123 3124Ean Schuessler and Brainfood (http://www.brainfood.com/) provided 3125financial support and encouragement. 3126 3127 Thanks to Chris Dean, Dean Ferreyra, and others at Merced Systems 3128(http://www.mercedsystems.com/) for financial support and other 3129contributions. 3130 3131 Google (http://google.com/) through their Summer of Code 3132(http://code.google.com/soc/) project sponsored Charles Turner during 3133Summer 2011 and 2012, Andrea Bernardini Summer 2014 and 2015, and Tom 3134Bousso Summer 2017. 3135 3136 Thomas Kirk and AT&T provided financial support, and useful bug 3137reports. 3138 3139Various contributions 3140..................... 3141 3142Jakub Jankiewicz (http://jcubic.pl/) contributed the Kawa logo. 3143 3144 Helmut Eller provided SLIME support, syntaxutils.scm, and many bug 3145reports. 3146 3147 Daniel Bonniot for multiple small improvements to gnu.bytecode and 3148gnu.expr. 3149 3150 Jamison Hope for multiple contributions, including quaternion 3151support, the SRFI-14 implementation, Ant improvements, and Google Summer 3152of Code mentoring. 3153 3154 Jim White for Ant support and other improvements. 3155 3156 Bruce R. Lewis implemented *note KRL: KRL. and made other 3157contributions. 3158 3159 Geoff Berry: Handle Exceptions attribute. Other improvements. 3160 3161 Tom Bousso re-implemented ‘gnu.bytecode’ to make use of ASM 3162(asm.ow2.org); plus other changes, 3163 3164 Shad Gregory improved JEmacs. 3165 3166 Al Petrofsky improved gnu.math printing and added some IntNum 3167methods. 3168 3169 Marco Vezzoli: SRFI-1 tailoring for Kawa. 3170 3171 Albert Ting - old GuiConsole code. 3172 3173 Christian Surlykke ported JEmacs to use SWT. 3174 3175 Geoff Berry for various gnu.bytecode improvements. 3176 3177 Ivelin Ivanov and Tom Reilly for servlet support. 3178 3179 Anthony Green for Fedora packaging. 3180 3181 Charles Turner for pretty-printer improvements, improvements in the 3182Common Lips support, and other changes. 3183 3184 Andrea Bernardini optimized the implementation of ‘case’, and 3185implemented full continuation support (in experimental ‘callcc’ branch. 3186 3187 Julien Rousseau and Marius Kjeldahl contributed to Android support. 3188 3189 Peter Lane for many documentation improvements. 3190 3191 William D Clinger for test-cases. 3192 3193Small fixes and improvements 3194............................ 3195 3196Patrick Barta; Joseph Bowbeer; Dominique Boucher; Alexander Bunkenburg; 3197Harold Carr; Emmanuel Castro; Álvaro Castro-Castilla; Sudarshan S 3198Chawathe; Heather Downs; Francisco Vides Fernández; Nic Ferrier; Oliver 3199Flasch; Weiqi Gao; Luke Gorrie; Mario Domenech Goulart; Zvi Har’E; Jeff 3200Haynes; Ethan Herdrick; Joerg-Cyril Hoehle; Elliott Hughes; Mike Kenne; 3201Brian Jones; Gerardo Jorvilleur; Simon Josefsson (JEmacs menu); Shiro 3202Kawai; Thomas Kirk; Jay Krell; Timo Myyrä; Edouard Parmelan; Walter C. 3203Pelissero; Rafael Jesus Alcantara Perez; Lynn Quam; Marcus Otto; Terje 3204Pedersen (some XQuery functions); Matthias Radestock; Jim Rees; Ola 3205Rinta-Koski; Andreas Schlapbach; Robert D. Skeels; Benny Tsai; Vladimir 3206Tsichevski; Matthieu Vachon; Vasantha Ganesh; Phil Walker; Knut 3207Wannheden; Chris Wegrzyn; Kay Zheng; Michael Zucchi. 3208 3209Bug reports and test cases 3210.......................... 3211 3212Seth Alves; Khairul Azhar; Bob Bane; Hans Boehm; Adrián Medraño Calvo; 3213Brian D. Carlstrom; Luis Casillas; Sudarshan S Chawathe; Ken Dickey 3214(format tests); Helge Dietert; Allan Erskine; Marc Feeley 3215(polytype.scm); Margus Freudenthal; Weiqi Gao; Andrea Girotto; Norman 3216Hard; Gerardo Horvilleur; Yaroslav Kavenchuk; Felix S Klock II; Francois 3217Leygues; Mirko Luedde; Leonardo Valeri Manera; Kjetil S. Matheussen; 3218Alex Mitchell; Alex Moiseenko; Marc Nieper-Wißkirchen; Okumura Yuki; 3219Edouard Parmelan; Walter C. Pelissero; Stephen L. Peters; François 3220Pinard; Bill Robinson; Dan Stanger (Eaton Vance); Hallvard Traetteberg; 3221Taylor Venable; Alessandro Vernet; Tony White John Whittaker; Robert 3222Yokota. 3223 3224Code ported from other packages 3225............................... 3226 3227Kawa includes Free Software originally written for other purposes, but 3228incorporated into Kawa, perhaps with some porting. A partial list: 3229 3230 Dorai Sitaram wrote pregexp. 3231 3232 The ‘rationalize’ algorithm is by Alan Bawden and Marc Feeley. 3233 3234 Lars T Hansen wrote SRFI-11 (let-values, let*-values macros). 3235 3236 Olin Shivers wrote the SRFI-1 list-processing library, and the 3237SRFI-13 reference impementation. 3238 3239 John David Stone wrote SRFI-8 (receive macro) 3240 3241 Jussi Piitulainen wrote the SRFI-25 specification and tests. 3242 3243 Richard Kelsey and Michael Sperber wrote SRFI-34. 3244 3245 Anthony Carrico wrote the SRFI-37 reference implementation. 3246 3247 Panu Kalliokoski wrote the SRFI-69 reference implementation. 3248 3249 Donovan Kolbly wrote the srfi-64 “meta” testsuite. Alex Shinn 3250improved SRFI-64 portability. 3251 3252 Philip L. Bewig wrote the SRFI-41 (streams) specification and 3253reference implementation. 3254 3255 Simon Tatham wrote listsort. 3256 3257 Aubrey Jaffer wrote much of SLIB, some of which has been imported 3258into gnu.kawa.slib. He also wrote some tests we’re using. 3259 3260 3261File: kawa.info, Node: Support, Next: Projects, Prev: Acknowledgements, Up: Community 3262 32633.4 Technical Support for Kawa 3264============================== 3265 3266If you have a project that depends on Kawa or one of its component 3267packages, you might do well to get paid priority support from Kawa’s 3268author. 3269 3270 The base price is $2400 for one year. This entitles you to basic 3271support by email or phone. Per <per@bothner.com> will answer techical 3272questions about Kawa or its implementation, investigate bug reports, and 3273suggest work-arounds. I may (at my discretion) provide fixes and 3274enhancements (patches) for simple problems. Response for support 3275requests received during the day (California time) will normally be 3276within a few hours. 3277 3278 All support requests must come through a single designated contact 3279person. If Kawa is important to your business, you probably want at 3280least two contact people, doubling the price. 3281 3282 If the support contract is cancelled (by either party), remaining 3283time will be prorated and refunded. 3284 3285 Per is also available for development projects. 3286 3287 3288File: kawa.info, Node: Projects, Next: Ideas and tasks, Prev: Support, Up: Community 3289 32903.5 Projects using Kawa 3291======================= 3292 3293MIT App Inventor (http://appinventor.mit.edu/) for Android (formerly 3294Google App Inventor) uses Kawa to translate its visual blocks language. 3295 3296 The HypeDyn (http://www.narrativeandplay.org/hypedyn/) hypertext 3297fiction authoring tool is written in Kawa. HypeDyn (pronounced "hyped 3298in") is a procedural hypertext fiction authoring tool for people who 3299want to create text-based interactive stories that adapt to reader 3300choice. HypeDyn is free to download and open source, and runs on Linux, 3301MacOS and Windows. This is a research project carried out at the 3302Department of Communications and New Media, National University of 3303Singapore. 3304 3305 Nü Echo (http://www.nuecho.com) develops high-performance speech 3306enabled applications. Nü Echo uses Kawa for the development of 3307innovative speech application development tools, like a complete grammar 3308IDE (http://www.nuecho.com/en/services/grammar.shtml). 3309 3310 Merced Systems, Inc. (http://www.mercedsystems.com/) uses Kawa 3311extensively in their contact center performance management product 3312Merced Peformance Suite. Kawa Scheme is used for all development and 3313has allowed Merced to realize the large productivity gains that come 3314with using Scheme while still maintaining tight integration with a large 3315number of Java libraries. 3316 3317 JEmacs is included in the Kawa distribution. It is a project to 3318re-implement Emacs, allowing a mix of Java, Scheme, and Emacs Lisp. It 3319has its own home-page (http://jemacs.sourceforge.net/). 3320 3321 BRL (“the Beautiful Report Language") is a database-oriented language 3322to embed in HTML and other markup. BRL (http://brl.sourceforge.net/) 3323allows you to embed Scheme in an HTML file on a web server. 3324 3325 The SchemeWay Project (http://schemeway.sourceforge.net) is a set of 3326Eclipse (http://www.eclipse.org) plug-ins for professional Scheme 3327programming. The first plugin released, SchemeScript, is a 3328fully-featured Scheme editor customizable in Scheme. It embeds the Kawa 3329Scheme system and has many features that ease Kawa Scheme programming 3330(like code completion on variable names, class and method names, 3331namespaces, etc). 3332 3333 The Health Media Research Laboratory, part of the Comprehensive 3334Cancer Center at the University of Michigan, is using Kawa as an 3335integral part of its core tailoring technologies. Java programs using 3336Kawa libraries are used to administer customized web-based surveys, 3337generate tailored feedback, validate data, and "characterize," or 3338transform, data. Kawa code is embedded directly in XML-formatted 3339surveys and data dictionaries. Performance and ease of implementation 3340has far exceeded expectations. For more information contact Paul R. 3341Potts, Technical Director, Health Media Research Lab, 3342‘<potts@umich.edu>’. 3343 3344 Mike Dillon (‘mdillon@gjt.org’) did the preliminary work of creating 3345a Kawa plugin for jEdit. It is called SchemeShell and provides a REPL 3346inside of the jEdit console for executing expressions in Kawa (much as 3347the BeanShell plugin does with the BeanShell scripting language). It is 3348currently available only via CVS from: 3349 CVSROOT=:pserver:anonymous@cvs.jedit.sourceforge.net:/cvsroot/jedit 3350 MODULE=plugins/SchemeShell 3351 3352 STMicroelectronics (‘marco.vezzoli@st.com’) uses Kawa in a prototypal 3353intranet 3tier information retrieval system as a communication protocol 3354between server and clients, and to do server agents programming. 3355 3356 3357File: kawa.info, Node: Ideas and tasks, Prev: Projects, Up: Community 3358 33593.6 Ideas and tasks for contributing to Kawa 3360============================================ 3361 3362Kawa (like other Free Software projects) has no lack of tasks and 3363projects to work on. Here are some ideas. 3364 3365 The ones marked (GSoC) are probably most suitable for a Google Summer 3366of Code project, in being a reasonable size, self-contained, and not 3367depending on other tasks. 3368 33693.6.1 Recusively initialized data structures 3370-------------------------------------------- 3371 3372(GSoC) 3373 3374 Kawa has convenient syntax to *note allocate and initialize objects: 3375Allocating objects, but it gets messier it you want to initialize 3376multiple objects that reference each other. Likewise for a single 3377object “tree” which contains links to the root. In this example, we 3378will looks at two vectors, but the feature is more useful for tree 3379structures. Assume: 3380 (define-constant list1 [1 2 list2]) 3381 (define-constant list2 ['a 'b list1]) 3382 The compiler translates this to: 3383 (define-constant list1 3384 (let ((t (object[] length: 3))) ;; allocate native Java array 3385 (set! (t 0) 1) 3386 (set! (t 1) 2) 3387 (set! (t 2) list2) 3388 (FVector:makeConstant t))) 3389 (define-constant list2 3390 (let ((t (object[] length: 3))) ;; allocate native Java array 3391 (set! (t 0) 'a) 3392 (set! (t 1) 'b) 3393 (set! (t 2) list1) 3394 (FVector:makeConstant t))) 3395 The problem is that ‘list2’ has not been created when we evaluate the 3396initializing expression for ‘list’. 3397 3398 We can solve the problem by re-writing: 3399 (define-private tmp1 (object[] length: 3)) 3400 (define-constant list1 (FVector:makeConstant tmp1) 3401 (define-private tmp2 (object[] length: 3)) 3402 (define-constant list2 (FVector:makeConstant tmp2) 3403 (set! (tmp1 0) 1) 3404 (set! (tmp1 1) 2) 3405 (set! (tmp1 2) list2) 3406 (set! (tmp2 0) 1) 3407 (set! (tmp2 1) 2) 3408 (set! (tmp2 2) list1) 3409 3410 The complication is that the code for re-writing vector and object 3411constructors is spread out (depending on the result type), and not where 3412we deal with initializing the variables. One solution is to introduce 3413an inlineable helper function ‘$build$’ defined as: 3414 (define ($build$ raw-value create init) 3415 (let ((result (create raw-value)) 3416 (init raw-value result) 3417 result)) 3418 Then we can re-write the above code to: 3419 (define-constant list1 3420 ($build$ 3421 (object[] length: 3) 3422 (lambda (raw) (FVector:makeConstant raw)) 3423 (lambda (raw result) 3424 ($init-raw-array$ raw 1 2 list2)))) 3425 (define-constant list2 3426 ($build$ 3427 (object[] length: 3) 3428 (lambda (raw) (FVector:makeConstant raw)) 3429 (lambda (raw result) 3430 ($init-raw-array$ raw 'a 'b list1)))) 3431 Note that the call to ‘$build$’, as well as the generated ‘lambda’ 3432expressions, are all easily inlineable. 3433 3434 Now assume if at the top-level BODY if there is a sequence of 3435‘define-constant’ definitions initialized with calls to ‘$build$’. Now 3436it is relatively easy to move all the ‘init’ calls after all ‘alloc’ and 3437‘create’ expressions. The ‘$init-raw-array$’ calls are expanded after 3438the code has been re-ordered. 3439 3440 The project includes both implementing the above framework, as well 3441as updating type-specific (and default) object creation to use the 3442framework. It would also be good to have compiler warnings if accessing 3443an uninitialized object. 3444 34453.6.2 Enhance texinfo-js documentation browser for Kawa documentation 3446--------------------------------------------------------------------- 3447 3448(GSoC) 3449 34503.6.3 Run interactive process in separate Java Virtual Machine: 3451--------------------------------------------------------------- 3452 3453(GSoC) 3454 3455 When developing and testing it is useful for the REPL to support 3456hot-swapping (replacing functions on-the-fly) and debugging. The main 3457goal being able to smoothly reload changed modules (files or functions), 3458and have other modules not break. Debugging (such as setting 3459breakpoints) would not be a priority for this project, but could be a 3460follow-on project. Skills: Should be experienced with Java, and 3461interested in learning about JVM TI 3462(https://docs.oracle.com/javase/8/docs/technotes/guides/jvmti/index.html) 3463and similar low-level parts of the platform. Difficulty: Challenging, 3464but you can study how Java-9’s new jshell 3465(https://en.wikipedia.org/wiki/Jshell) uses the JVM TI. 3466 34673.6.4 Better dynamic reload 3468--------------------------- 3469 3470(GSoC - this is related to the previous item) 3471 3472 Kawa does a lot of optimizations and inlining. This conflicts with 3473being able to “reload” a module into an already-running interactive 3474environment. 3475 3476 We could add an option to load a module in “reloadable” mode. Kawa 3477already patches an old function object (a ‘ModuleMethod’) so existing 3478references to the function get automatically updated. However, there 3479are problems if the “signature” of the function changes - for example if 3480the return type (declared or inferred) becomes more general. In those 3481cases the best thing is to re-compile any code that depends on the 3482modified function. 3483 3484 Reloading a module that defines a class is even trickier, at least if 3485there are existing instances that should work as the updated class. We 3486can handle the special case where only method bodies change: In 3487reloadable mode, each method body is compiled to a separate function, 3488the actual body indirects to the function. We must also recognize when 3489compiling a new version of the same class, which requires a textual 3490comparison between the old and new versions, or a structural comparison 3491between the old class and the new code. 3492 3493 When it comes to top-level variables, an issue is when to re-evaluate 3494the initializing expression. It is reasonable to do so if and only if 3495the expression is modified, which again requires a textual comparison. 3496 34973.6.5 Easier Access to Native Libraries using JNA/JNR 3498----------------------------------------------------- 3499 3500(GSoC) 3501 3502 The traditional way to access native (C/C++) functions is using JNI, 3503but it’s very awkward. JNA and JNR (https://github.com/jnr) are much 3504easier to use 3505(http://www.oracle.com/technetwork/java/jvmls2013nutter-2013526.pdf). 3506This project would design and implement an easy-to-use Kawa wrapper for 3507for JNR. You should study existing JNR wrappers, such as that for JRuby. 3508Difficulty: Medium. Need to study existing wrappers and "foreign 3509function interfaces" (in multiple languages) and design one suitable for 3510Kawa. Some Scheme (Kawa) experience would be helpful. 3511 35123.6.6 Types for units 3513--------------------- 3514 3515(GSoC) 3516 3517 Kawa supports units (such as ‘cm^2’ for square centimeters) and *note 3518quantities: Quantities. (such as ‘4cm^2’). We would like to integrate 3519these into the type system, both for performance and compile-time type 3520checking. 3521 3522 For syntax we can use a pseudo-parameterized type ‘quantity’. For 3523example: 3524 (define a1 ::quantity[cm^2] 4cm^2) 3525 (* 2.0 a1) ;; ⇒ 8cm^2 3526 (+ 2.0 a1) ;; compile-time error 3527 The run-time type of the variable ‘a1’ should be a primitive 3528‘double’, without object allocation. Of course when ‘a1’ is converted 3529to an object, we create a ‘Quantity’, not a ‘Double’. We can build on 3530Kawa’s existing framework for non-standard primitive types such as 3531‘character’ and ‘ulong’. Skills: Need good Java experience, and 3532somewhat familiar with the Java Virtual Machine. You will need to 3533become comfortable reading ‘javap’ output. Difficulty: Modest. 3534 35353.6.7 Compiler should use class-file reading instead of reflection 3536------------------------------------------------------------------ 3537 3538The Kawa compiler currently uses reflection to determine properties 3539(such as exported function definitions) from referenced classes. It 3540would be better to read class files. This should not be too difficult, 3541since the ‘gnu.bytecode’ library abstracts over class information read 3542by reflection or class reading. 3543 35443.6.8 Mutually dependent Java and Scheme modules 3545------------------------------------------------ 3546 3547(GSoC - maybe) 3548 3549 We’d like a command for compiling a list of Java and Scheme source 3550files that may have mutual dependencies. A good way to do this is to 3551hook into ‘javac’, which is quite extensible and pluggable. 3552 3553 One could do something like: 3554 1. Read the “header" of each Kawa source file, to determine the name 3555 of the generated main class. 3556 2. Enter these class names into the javac tables as “uncompleted” 3557 classes. 3558 3. Start compiling the Java files. When this requires the members of 3559 the Kawa classes, switch to the Kawa files. From javac, treat 3560 these as pre-compiled .class files. I.e. we treat the Kawa 3561 compiler as a black box that produces Symbols in the same way as 3562 reading class files. At this point we should only need the initial 3563 “scan” phase on Kawa. 3564 4. If necessary, finish compiling remaining Kawa files. 3565 3566 This approach may not immediately provide as robust mixed-language 3567support as is ideal, but it is more amenable to incremental improvement 3568than a standalone stub-generator. 3569 3570 This project is good if you know or want to learn how ‘javac’ works. 3571 35723.6.9 Use Java-7 MethodHandles and invokedynamic 3573------------------------------------------------ 3574 3575Java 7 supports MethodHandles which are meant to provide better 3576performance (ultimately) for dynamic languages. See JSR 292 3577(http://jcp.org/en/jsr/detail?id=292) and the Da Vinci Machine Project 3578(http://openjdk.java.net/projects/mlvm/). Kawa makes limited use of 3579MethodHandles, and no use of invokedynamic. There is more to be done. 3580For example, we can start by optimizing arithmetic when the types are 3581unknown at compile-time. They could make implementing generic functions 3582(multimethods) more efficient. At some point we want to compile lambdas 3583in the same way as Java 8 does. This can potentially be more efficient 3584than Kawa’s current mechanism. 3585 3586 Remi Forax’s vmboiler (https://github.com/forax/vmboiler) is a small 3587library on top of ASM that generates optimistically typed bytecodes. It 3588could be useful for ideas. 3589 35903.6.10 Parameterized types 3591-------------------------- 3592 3593(GSoC) 3594 3595 Kawa has some limited support for parameterized types, but it’s not 3596used much. Improve type inferencing. Support definition of 3597parameterized classes. Better use of parameterized types for sequence 3598class. Support wildcards. (It might be better to have wild-carding be 3599associated with declarations, as in Scala or proposed for Java 3600(http://openjdk.java.net/jeps/300), rather than uses.) See also 3601<http://openjdk.java.net/jeps/8043488>. 3602 36033.6.11 Optimized function types and values using MethodHandles 3604-------------------------------------------------------------- 3605 3606(GSoC) 3607 3608 Kawa doesn’t have true function types: Parameter and result types are 3609only handled for “known” functions. The general case with optional and 3610keyword parameter is complicated, but simple fixed-arity procedure types 3611would be very useful. 3612 3613 The following syntax is suggested: 3614 procedure[(T1 .. TN) TR] 3615 T1 through T1 are types of the parameters, and TR is the type of the 3616result. For example: ‘procedure[(vector int) string]’. We call this a 3617typed-procedure type (in contrast to plain ‘procedure’). 3618 3619 If a value has a typed-procedure type then its run-time 3620representation is a just a ‘MethodHandle’. If such a procedure is 3621called, the generated bytecode is to just call its ‘invokeExact’ method. 3622The argument expressions are converted (and type-checked) the same way 3623as if we were calling a statically-known procedure. 3624 3625 Note that passing an ‘int’ argument of to ‘procedure[(vector int) 3626string]’ value does _not_ require allocating an object to “box” the 3627‘int’; we can pass a plain ‘int’ as-is. Thus using typed-procedure 3628types can lead to major speed-up. For example the ‘lib-test.scm’ should 3629become much faster. 3630 3631 Converting a known procedure to a typed-procedure type is usually 3632just a matter of creating a ‘MethodHandle’ that references the method 3633implementing the procedure. Some glue code may be needed if the types 3634aren’t identical, or if the procedure is a closure. 3635 3636 Converting a type-procedure value ‘p’ to generic value (such as 3637untyped ‘procedure’ or ‘object’) can be though of as wrapping it in a 3638‘lambda’: 3639 ((lambda (arg1::vector arg2::int)::string (p arg1 arg2)) 3640 3641 Coercing a generic value or an untyped procedure to a typed-procedure 3642would need to generate a method whose signature matches the 3643typed-procedure type, and in the body of the method use a generic apply. 3644 3645 Coercing from one typed-procedure type to a different typed-procedure 3646type is a combination of the above techniques (as if converting first to 3647object and then to the target type), though some optimizations are worth 3648doing. 3649 3650 Adding varargs support can be done later. 3651 3652 We need a fall-back mechanism for platforms (such as Android) that 3653don’t support ‘MethodHandle’s. The easiest is to just treat a 3654typed-procedure type as plain ‘procedure’ at run-time, though we still 3655want the compile-time type-checking, 3656 36573.6.12 Full continuations 3658------------------------- 3659 3660_Currently being worked on._ 3661 3662 Add support for full continuations, which is the major feature 3663missing for Kawa to qualify as a “true Scheme”. One way to implement 3664continuations is to add a add that converts the abstract syntax tree to 3665continuation-passing-style, and then expand the existing full-tail-call 3666support to manage a stack. There are other ways to solve the problem. 3667This may benefit from *note Faster tailcalls: task-faster-tailcalls. 3668 36693.6.13 Faster tailcalls 3670----------------------- 3671 3672Make ‘--full-tailcalls’ run faster. This may depend on (or incorporate) 3673*note TreeList-optimization: task-TreeList-optimization. 3674 36753.6.14 TreeList-optimization 3676---------------------------- 3677 3678The TreeList 3679(http://www.gnu.org/software/kawa/api/gnu/lists/TreeList.html) class is 3680a data structure for “flattened” trees. It is used for XML-style nodes, 3681for multiple values, and for the full-tail-call API. The basic concept 3682is fine, but it could do with some re-thinking to make make 3683random-access indexing fast. Also, support for updating is 3684insufficient. (This needs someone into designing and hacking on 3685low-level data-structures, along with lots of profiling and testing.) 3686 36873.6.15 Asynchronous evaluation 3688------------------------------ 3689 3690C# recently added ‘asynch’ and ‘await’ keywords for asynchronous 3691programming (http://msdn.microsoft.com/en-us/vstudio/gg316360). Kawa’s 3692recently improved support for lazy programming seems like a good 3693framework for equivalent functionality: Instead of an ‘asynch’ method 3694that returns a ‘Task<T>’, the Kawa programmer would write a function 3695that returns a ‘lazy[T]’. This involves some design work, and modifying 3696the compiler to rewrite the function body as needed. 3697 3698 This is related to full continuations, as the re-writing is similar. 3699 37003.6.16 REPL console and other REPL improvement 3701---------------------------------------------- 3702 3703_Currently being worked on._ 3704 3705 Improvements to the read-eval-print console. In addition to a 3706traditional Swing console, it would be useful to support using a web 3707browser as a remote terminal, possibly using web-sockets. (This allows 3708“printing” HTML-expressions, which can be a useful way to learn and 3709experiment with web technologies.) See here 3710(http://per.bothner.com/blog/2007/ReplPane/) for an article on the 3711existing Swing REPL, along with some to-do items. Being able to hide 3712and show different parts of the output might be nice. Being able to 3713link from error messages to source might be nice. Better handling of 3714redefinitions is discussed here in the context of JavaXF Script 3715(http://per.bothner.com/blog/2009/REPL-for-JavaFX/); this is a general 3716REPL issue, mostly independent of the GUI for it. 3717 3718 An interesting possibility is to use the IPython 3719(http://ipython.org/) framework. There are existing ports for Scala: 3720either IScala (https://github.com/mattpap/IScala) or Scala Notebook 3721(https://github.com/Bridgewater/scala-notebook). 3722 37233.6.17 XQuery-3.0 functionality 3724------------------------------- 3725 3726(GSoC, for some subset) 3727 3728 It would be nice to update the XQuery (Qexo) support to some subset 3729of XQuery 3.0 (http://www.w3.org/TR/xquery-30/). 3730 37313.6.18 XQuery-updates 3732--------------------- 3733 3734It would be nice to support XQuery updates 3735(http://www.w3.org/TR/xquery-update-10/). This depends on *note 3736TreeList-optimization: task-TreeList-optimization. 3737 37383.6.19 Common Lisp support 3739-------------------------- 3740 3741Kawa supports a small subset of the Common Lisp language, but it 3742supports a much larger subset of core Common Lisp concepts and data 3743structures, some designed with Common Lisp functionality in mind. 3744Examples include packages, arrays, expanded function declarations, type 3745specifications, and format. A lot could be done to improve the Common 3746Lisp support with modest effort. Some Common Lisp features could also 3747be useful for Scheme: Documentation strings (or markup) as Java 3748annotations, better MOP-like introspection, and generic methods a la 3749defmethod (i.e. with multiple definition statements, possibly in 3750separate files, as opposed to the current make-procedure) all come to 3751mind. Being able to run some existing Common Lisp code bases with at 3752most modest changes should be the goal. One such package to start with 3753might be an existing test framework 3754(http://aperiodic.net/phil/archives/Geekery/notes-on-lisp-testing-frameworks.html), 3755perhaps FivaAM (http://common-lisp.net/project/bese/FiveAM.html). Full 3756Common Lisp compatibility is nice, but let’s walk before we can run. 3757 37583.6.20 JEmacs improvements 3759-------------------------- 3760 3761(GSoC, for some subset) 3762 3763 A lot of work is needed to make JEmacs 3764(http://jemacs.sourceforge.net/) useful. One could try to import a 3765useful package and see what works and what fails. Or one may look at 3766basic editing primitives. Enhancements may be needed to core Emacs Lisp 3767language primitives (enhancing *note Common Lisp support: 3768task-common-lisp. may help), or to the display engine. 3769 3770 Emacs now supports lexical bindings 3771(http://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html) 3772- we should do the same. 3773 37743.6.21 Improved IDE integration 3775------------------------------- 3776 3777There is some Kawa support for Eclipse (Schemeway), and possibly other 3778IDEs (NetBeans, IntelliJ). But many improvements are desirable. *note 3779REPL improvements: task-REPL-improvements. may be a component of this. 3780 37813.6.21.1 Plugin for NetBeans IDE 3782................................ 3783 3784Kawa-Scheme support for the NetBeans IDE would be useful. One could 3785perhaps build on the Clojure plugin. 3786 37873.6.21.2 Plugin for Eclipse IDE 3788............................... 3789 3790Kawa-Scheme support for the Eclipse IDE would be useful. Probably makes 3791sense to enhance SchemeWay (http://sourceforge.net/projects/schemeway/). 3792It may also make sense to build on the Dynamic Languages Toolkit 3793(http://www.eclipse.org/dltk/), possibly making use of Schemeide 3794(http://schemeide.sourceforge.net/), though DLTk seems more oriented 3795towards interpreted non-JVM-based languages. 3796 37973.6.21.3 Improve Emacs integration 3798.................................. 3799 3800SLIME (http://en.wikipedia.org/wiki/SLIME) is an Emacs mode that 3801provides IDE-like functionality. It supports Kawa. 3802 3803 JDEE (http://jdee.sourceforge.net/) is a Java development 3804environment, so might have better hooks to the JVM and Java debugging 3805architecture. 3806 3807 CEDET (http://cedet.sourceforge.net/) is a more general framework of 3808development tools. 3809 38103.6.22 Hop-style web programming 3811-------------------------------- 3812 3813Hop (http://hop.inria.fr/) is an interesting design for integrating 3814server-side and client-side programming using a Scheme dialect. These 3815ideas seem like they would port quite well to Kawa. 3816 38173.6.23 String localization 3818-------------------------- 3819 3820(GSoC) 3821 3822 Support localization by extending the SRFI_109 3823(http://srfi.schemers.org/srfi-109/srfi-109.html) syntax, in the manner 3824of (and compatible with) GNU gettext 3825(http://www.gnu.org/software/gettext/). I.e. optionally specify a 3826localization key (to use as an index in the translation database); if 3827there is no key specified, default to using the literal parts of the 3828string. 3829 38303.6.24 Data binding 3831------------------- 3832 3833Implement a “bind” mechanism similar to that of JavaFX Script 3834(http://docs.oracle.com/javafx/1.3/tutorials/core/dataBinding/). The 3835idea is that when you initialize a variable or field, instead of 3836initializing it to a fixed value, you bind it to an expression depending 3837on other variables. We install “listeners” on those variables, so when 3838those variables change, we update the bound variable. This feature is 3839useful in many applications, but the initial focus could be GUI 3840programming and perhaps web programming. 3841 38423.6.25 Decimal arithmetic and repeated decimals 3843----------------------------------------------- 3844 3845(GSoC. Possibly a bit light for a full Summer project, but can be 3846extended or combined with other projects.) 3847 3848 Exact decimal arithmetic is a variation of exact rational arithmetic, 3849but may be more user-friendly. In particular, printing using decimals 3850is generally nicer than fractions. It is also sometimes useful to 3851specify an explicit scale, so we can distinguish 0.2 from 0.20. We can 3852use the Java ‘BigDecimal’ class, but run into problems with division - 3853for example ‘(/ 1.0 3.0)’. We should implement a subclass of ‘RatNum’ 3854that generalizes ‘BigDecimal’ to also handle repeating decimals. We 3855need a lexical syntax for repeating decimals. Possible ideas: ‘0._81_’ 3856or ‘0.#81’. If a Scheme number literal is specified as exact and has 3857either a decimal point or an exponent (for example ‘#e1.25’), then it 3858should read as an exact decimal, not a fraction. 3859 38603.6.26 Optional strict typing along with an explicit ‘dynamic’ type 3861------------------------------------------------------------------- 3862 3863(GSoC) 3864 3865 Kawa currently implements “optimistic” typing: The compiler only 3866complains if an expression has no values in common with the target type 3867- for example, if assigning a ‘string’ expression to an ‘integer’ 3868variable. It would be interesting to experiment with a 3869‘--strict-typing’ option (which would never be the default): Strict 3870typing would only allow “widening” conversions - i.e. that the 3871expression type be a subtype of the target type. For example it would 3872complain if assigning a ‘number’ to an ‘integer’ unless you used an 3873explicit cast. 3874 3875 To make this easier to work with we’d make use of the *note ‘dynamic’ 3876type: dynamic-type, similar to what ‘C#’ does 3877(https://msdn.microsoft.com/en-us/library/dd264736.aspx): Any expression 3878can be converted to or from ‘dynamic’ without the compiler complaining. 3879Similarly, if ‘x’ is ‘dynamic’ then ‘x:name’ is allowed by the compiler 3880regardless of ‘name’, with all checking being deferred to run-time. If 3881a variable is declared without a type, it should default to ‘dynamic’. 3882The ‘dynamic’ type is represented in the VM as ‘object’ but with an 3883annotation (like we do with ‘character’). 3884 3885 The type-checker might need some changes to better distinguish 3886implicit conversions from explicit casts. 3887 3888 3889File: kawa.info, Node: Installation, Next: Tutorial, Prev: Community, Up: Top 3890 38914 Getting and installing Kawa 3892***************************** 3893 3894* Menu: 3895 3896* Getting Kawa:: 3897* Running Java:: Getting and running Java 3898* Binary distribution:: Installing and using the binary distribution 3899* Source distribution:: Installing and using the source distribution 3900 3901 3902File: kawa.info, Node: Getting Kawa, Next: Running Java, Up: Installation 3903 39044.1 Getting Kawa 3905================ 3906 3907You can compile Kawa from the source distribution. Alternatively, you 3908can install the pre-compiled binary distribution. 3909 3910 You can get Kawa sources and binaries from the Kawa ftp site 3911<ftp://ftp.gnu.org/pub/gnu/kawa/>, or from a mirror site 3912(http://www.gnu.org/order/ftp.html). 3913 3914 The current release of the Kawa source code is 3915<ftp://ftp.gnu.org/pub/gnu/kawa/kawa-3.1.1.tar.gz>. (To unpack 3916‘.tar.gz’ files Windows users can use 7-Zip (http://www.7-zip.org/), 3917which is Free Software.) 3918 3919 The corresponding pre-compiled release is 3920<ftp://ftp.gnu.org/pub/gnu/kawa/kawa-3.1.1.zip>. The most recent 3921snapshot is <ftp://ftp.gnu.org/pub/gnu/kawa/kawa-latest.zip>. 3922Instructions for using either are *note here: Binary distribution. 3923 39244.1.1 Getting the development sources using Git 3925----------------------------------------------- 3926 3927The Kawa sources are managed using a git 3928(https://gitlab.com/kashell/Kawa) repository. If you want the very 3929latest version grab a git client (https://git-scm.com/downloads), and 3930then check out the source using this command: 3931 git clone https://gitlab.com/kashell/Kawa.git 3932 3933 After a checkout you will need to run: 3934 ./autogen.sh 3935 before proceding with instructions for *note building the source 3936distribution: Source distribution. 3937 3938 Once you have it checked out, you can keep it up-to-date with ‘git 3939pull’. 3940 3941 You can also browse the git archive 3942(https://gitlab.com/kashell/Kawa/tree/master) online. 3943 3944 3945File: kawa.info, Node: Running Java, Next: Binary distribution, Prev: Getting Kawa, Up: Installation 3946 39474.2 Getting and running Java 3948============================ 3949 3950Before installing Kawa, you will need a working Java system. The 3951released Kawa jar file assumes Java 8 or newer. You need to build Kawa 3952from source if you have Java 5, Java 6, or are targeting Android. 3953(Older versions of Kawa have been reported to work with JDK from 1.1, 3954Kaffe, Symantec Cafe, J++, and GCJ, but these are no longer supported.) 3955 3956 The discussion below assumes you are using the Java Developer’s Kit 3957(JDK) from Oracle. You can download free copies of JDK 8 3958(http://www.oracle.com/technetwork/java/javase/downloads/index.html) for 3959various platforms. 3960 3961 The program ‘java’ is the Java interpreter. The program ‘javac’ is 3962the Java compiler, and is needed if you want to compile the source 3963release yourself. Both programs must be in your ‘PATH’. If you have 3964the JDK in directory ‘$JAVA_HOME’, and you are using a Bourne-shell 3965compatible shell (/bin/sh, ksh, bash, and some others) you can set 3966‘PATH’ thus: 3967 PATH=$JAVA_HOME/bin:$PATH 3968 export PATH 3969 3970 3971File: kawa.info, Node: Binary distribution, Next: Source distribution, Prev: Running Java, Up: Installation 3972 39734.3 Installing and using the binary distribution 3974================================================ 3975 3976The binary release comes as a ‘.zip’ archive that includes Kawa itself 3977(as a ‘.jar’ file ‘kawa-VERSION.jar’), some third-party helper 3978libraries, ‘kawa’ command scripts (for GNU/Linux/Unix/MacOS or Windows), 3979and documentation (basically this manual). 3980 3981 After downloading (see *note Getting Kawa::), extract the files from 3982the ‘.zip’ archive using a suitable ‘unzip’ program, which will create a 3983directory ‘kawa-VERSION’, with ‘lib’, ‘bin’, and ‘doc’ sub-directories. 3984In the following, we assume the environment variable ‘KAWA_HOME’ refers 3985to this directory: 3986 unzip ~/Downloads/kawa-VERSION.zip 3987 export KAWA_HOME=`pwd`/kawa-VERSION 3988 3989 The binary release requires Java 8 or later. If you have an older 3990Java implementation, or build for a mobile environment like Android, 3991then you will need to get the source distribution. 3992 3993 If you want to use Kawa as part of some other application, you just 3994need the ‘$KAWA_HOME/lib/kawa.jar’. 3995 3996Running the ‘kawa’ command 3997.......................... 3998 3999To run a Kawa script file or the Kawa read-eval-print-loop run the Kawa 4000application. There are various way to do so. 4001 4002 The recommended way is to execute the ‘$KAWA_HOME/bin/kawa’ Bash 4003shell script. This should work on most Unix-like platforms that have 4004Bash installed, including GNU/Linux, BSD, MacOS, and Cygwin/MingW. 4005(Please report if you have problems.) 4006 4007 The script assumes that either a suitable ‘java’ program is in your 4008‘PATH’; or the ‘JAVA’ environment variable names a suitable ‘java’ 4009executable; or that ‘JAVA_HOME’ is set so ‘$JAVA_HOME/bin/java’ is 4010suitable. 4011 4012 If you want to put ‘kawa’ in your search path you can of course do: 4013 PATH=$KAWA_HOME/bin:$PATH 4014 Alternatively you can create a symbolic link in an already-searched 4015directory. For example: 4016 cd /usr/local/bin 4017 ln -s $KAWA_HOME/bin/kawa kawa 4018 4019 The ‘bin/kawa.bat’ script works on Windows. 4020 4021 Both scripts add some helper libraries, including support for input 4022editing. 4023 4024 It is also possible to run Kawa using ‘java’ directly: 4025 java -jar $KAWA_HOME/lib/kawa.jar 4026 or: 4027 CLASSPATH=$KAWA_HOME/lib/kawa.jar 4028 export CLASSPATH 4029 java kawa.repl 4030 On Windows: 4031 set classpath=%KAWA_HOME%\lib\kawa.jar 4032 4033 To run Kawa in a fresh window use the -w flag: 4034 kawa -w 4035 or 4036 java kawa.repl -w 4037 4038Reading the documentation 4039......................... 4040 4041The file ‘doc/kawa-manual.epub’ contains the Kawa documention packaged 4042as an electronic book, which is readable by most e-book readers. 4043Plugins are also available for common browsers, for example EPUBReader 4044(http://www.epubread.com) for ‘firefox’. 4045 4046 Even easier is to invoke *note ‘bin/kawa --browse-manual’: 4047browse-manual-option. (or on Windows: ‘bin\kawa.bat --browse-manual’). 4048 4049 An ‘epub’ is essentially a zip archive, which you can unzip: 4050 cd $KAWA_HOME/doc 4051 unzip kawa-manual.epub 4052 Then you can use a plain browser with the URL 4053‘file:$KAWA_HOME/doc/OEBPS/index.html’. 4054 4055 4056File: kawa.info, Node: Source distribution, Prev: Binary distribution, Up: Installation 4057 40584.4 Installing and using the source distribution 4059================================================ 4060 4061The Kawa release normally comes as a gzip-compressed tar file named 4062‘kawa-3.1.1.tar.gz’. Two methods are supporting for compiling the Kawa 4063sources; choose whichever is most convenient for you. 4064 4065 One method uses the traditional GNU ‘configure’ script, followed by 4066running ‘make’. This works well on Unix-like systems, such as 4067GNU/Linux. You can also use this method on Microsoft Windows, with the 4068help of tools from MinGW (http://www.MinGW.org/) or Cygwin 4069(http://www.cygwin.org/). 4070 4071 The other method uses the ‘ant’ command, a Java-based build system 4072released by Apache’s Jakarta project. This uses an ‘build.xml’ file in 4073place of ‘Makefile’s, and works on non-Unix systems such as Microsoft 4074Windows. However, the ‘ant’ method does not support all the features of 4075the ‘configure’+‘make’ method. 4076 40774.4.1 Build Kawa using ‘configure’ and ‘make’ 4078--------------------------------------------- 4079 4080(See *note below: building-on-Windows-with-make. for some notes for 4081building on Microsoft Windows.) 4082 4083 If you have a ‘tar.gz’ file, first unpack that in your build 4084directory: 4085 tar xzf kawa-3.1.1.tar.gz 4086 cd kawa-3.1.1 4087 4088 If you’re building from the Git repository, you need to generate 4089‘configure’ and some other files. This is easiest done with the 4090‘autogen.sh’ script: 4091 ./autogen.sh 4092 4093 Then you must configure the sources. This you do in the same way you 4094configure most other GNU software. Normally you can just run the 4095configure script with no arguments: 4096 4097 ./configure 4098 The ‘configure’ script takes a number of *note options: configure 4099options. 4100 4101 If you have installed Kawa before, make sure your ‘CLASSPATH’ does 4102not include old versions of Kawa, or other classes that may conflict 4103with the new ones. 4104 4105 Then you need to compile all the .java source files. Just run make: 4106 make 4107 This assumes that ‘java’ and ‘javac’ are the java interpreter and 4108compiler, respectively. 4109 4110 It has been reported that parallel make doesn’t work, so don’t use 4111the ‘-j2’ or above options. 4112 4113 You can now test the system by running Kawa in place: 4114 java kawa.repl 4115 4116 or you can run the test suite: 4117 make check 4118 4119 or you can install the compiled files: 4120 make install 4121 4122 This will install your classes into ‘$PREFIX/share/java’ (and its 4123sub-directories). Here ‘$PREFIX’ is the directory you specified to 4124configure with the ‘--prefix’ option, or ‘/usr/local’ if you did not 4125specify a ‘--prefix’ option. 4126 4127 To use the installed files, you need to set ‘CLASSPATH’ so that 4128‘$PREFIX/share/java/kawa.jar’ is in the path: 4129 CLASSPATH=$PREFIX/share/java/kawa.jar 4130 export CLASSPATH 4131 This is done automatically if you use the ‘kawa’ script. 4132 41334.4.1.1 Configure options 4134......................... 4135 4136The ‘configure’ script takes a number of options. The ‘--help’ switch 4137gives you a list of options. The following are some of the more common 4138or important ones. 4139 4140‘--prefix=INSTALL-DIR’ 4141‘--prefix INSTALL-DIR’ 4142 By default ‘make install’ will install the compiled ‘.jar’ files 4143 info ‘/usr/local/share/java’, the ‘kawa’ command into 4144 ‘/usr/local/bin’, and so on in ‘/usr/local’. The ‘--prefix’ option 4145 causes the files to be installed under ‘INSTALL-DIR’ instead of 4146 ‘/usr/local’. For example to install the ‘.jar’ in 4147 ‘/opt/kawa/share/java’ and otherwise use ‘/opt/kawa’ do: 4148 ./configure --prefix=/opt/kawa 4149 4150‘--with-java-source=VERSION’ 4151 As distributed, the Kawa source code requires Java 8. If you only 4152 have Java 7, Java 6, or Java 5, use the ‘--with-java-source’ 4153 option: 4154 ./configure --with-java-source=6 4155 4156 Kawa no longer supports older verisons of Java (JDK 1.4 or older). 4157 It might be possible to use a tool like Retroweaver 4158 (http://retroweaver.sourceforge.net/) on the Kawa ‘.jar’ to fix up 4159 Java 5 dependencies. Contact the Kawa author if you want to be a 4160 tester for this. 4161 4162‘--with-docbook-stylesheets[=PATH]’ 4163 Build the documentation (this manual) as an electronic book (in 4164 ebook format) or a website, using the DocBook xslt stylesheets. 4165 (You can build the documentation without DocBook, but using it 4166 enables nicer-looking and more functional documentation.) 4167 4168 The stylesheets are found using PATH; the file 4169 ‘PATH/epub3/chunk.xsl’ needs to exist. (For example, on Fedora 25 4170 PATH can be ‘/usr/share/sgml/docbook/xsl-ns-stylesheets’, while on 4171 Debian use ‘/usr/share/xml/docbook/stylesheet/docbook-xsl-ns’.) 4172 4173‘--with-domterm’ 4174‘--with-domterm=DOMTERM_HOME’ 4175 Compile with extra support for the *note DomTerm: Using DomTerm. 4176 terminal emulator library, where ‘DOMTERM_HOME’ is such that 4177 ‘DOMTERM_HOME/lib/domterm.jar’ exists. (Some DomTerm support is 4178 built-in regardless.) 4179 4180 If you use this option along with ‘--with-javafx’ then creating a 4181 new *note REPL: REPL Console. window will create a DomTerm window. 4182 4183 As an optional convenience, you can use the ‘domterm.jar’ in the 4184 Kawa binary distribution. 4185 4186‘--with-jline3’ 4187‘--with-jline3=JLINE3.JAR’ 4188 Build support for using JLine 3 (https://github.com/jline/jline3), 4189 which is a library for handling console input, similar to GNU 4190 readline. If specified, the JLINE3.JAR is added to the classpath 4191 of the generated ‘kawa.sh’ or ‘kawa’ shell program. 4192 4193 An advantage of ‘--with-jline3’ (compared to 4194 ‘--enable-kawa-frontend’) is that the former works without native 4195 code (on most Unix-like platforms), and it does not require a C 4196 wrapper program. 4197 4198 As an optional convenience, you can use the ‘jline.jar’ in the Kawa 4199 binary distribution. 4200 4201‘--with-domterm’ 4202‘--with-domterm=DOMTERM.JAR’ 4203 Compile with extra support for the *note DomTerm: Using DomTerm. 4204 terminal emulator library. (Some DomTerm support is built-in 4205 regardless.) 4206 4207 If you use this option along with ‘--with-javafx’ then creating a 4208 new *note REPL: REPL Console. window will create a DomTerm window. 4209 4210 As an optional convenience, you can use the ‘domterm.jar’ in the 4211 Kawa binary distribution. 4212 4213‘--with-servlet’ 4214‘--with-servlet=SERVLET-JAR’ 4215 Build support for *note servlets: Servlets, which are used in web 4216 servers. This requires the ‘servlet-api.jar’ (available various 4217 places including Tomcat (http://tomcat.apache.org/) or Glassfish 4218 (https://glassfish.java.net/)), for ‘javax.servlet.Servlet’ and 4219 related classes. If this class isn’t in your classpath, specify 4220 its location as ‘SERVLET-JAR’. For example: 4221 ./configure --with-servlet=/path/to/servlet-api.jar 4222 4223‘--enable-jemacs’ 4224 Build JEmacs (enable Emacs-like text editor) and support (a subset 4225 of) the Emacs Lisp language. JEmacs is a proof of concept - not 4226 really usable or maintained. 4227 4228‘--with-javafx’ 4229‘--with-javafx=JAVAFX-HOME’ 4230 Set this flag to enable the convenience features for *note JavaFX: 4231 Building JavaFX applications. The JavaFX classes are included in 4232 JDK 8 (but not OpenJDK 8), and you don’t need to specify 4233 ‘JAVAFX-HOME’. JDK 11 or later does not include JavaFX, so you 4234 need to specify the location of the modular OpenJFX SDK as 4235 ‘JAVAFX-HOME’. 4236 4237‘--with-android=ANDROID-JAR’ 4238 Build for the Android platform. This requires *note special 4239 instructons: Building for Android. 4240 4241‘--enable-kawa-frontend’ 4242 If you have the GNU ‘readline’ library installed, you might try 4243 adding the ‘--enable-kawa-frontend’ flag. This will build the 4244 ‘kawa’ front-end program, which provides input-line editing and an 4245 input history. You can get ‘readline’ from archives of GNU 4246 programs, including <ftp://www.gnu.org/>. 4247 4248 Note that using JLine, enabled by ‘--with-jline3’, is now 4249 recommended instead of using the ‘readline’ frontend. 4250 4251 You may need to specify to ‘make’ where to find the ‘readline’ 4252 include files (with ‘READLINE_INCLUDE_PATH’) and the library (with 4253 ‘READINE_LIB_PATH’). For example on OS/X you need to do: 4254 make READLINE_INCLUDE_PATH=-I/usr/local/unix/readline/include \ 4255 READLINE_LIB_PATH=-L/usr/local/unix/readline/lib 4256 42574.4.1.2 Building on Windows using MinGW 4258....................................... 4259 4260The Kawa ‘configure’ and ‘make’ process assumes Unix-like tools, which 4261you can get from the MinGW project (http://mingw.org). Download the 4262MingGW Installation Manager, and use it to install at least 4263‘mingw-developer-toolkit’. (Also installing ‘msys-groff’ avoids a minor 4264problem building the documentation.) 4265 4266 The ‘C:\MinGW\msys\1.0\msys.bat’ script creates a command window with 4267the ‘bash’ shell and the ‘PATH’ set up as needed. Alternatively, you 4268can use the standard Windows command prompt if you set your ‘PATH’ as 4269described in here (http://mingw.org/wiki/Getting_Started). 4270 42714.4.1.3 Building on Windows using Cygwin 4272........................................ 4273 4274The free Cygwin (http://sourceware.org/cygwin/) environment can be used 4275for building Kawa: The Kawa configure script recognizes Cygwin, and 4276modifies the classpath to use Windows-style path separators. 4277 4278 Beyond the base packages, you probably want to install ‘autoconf’, 4279‘automake’, ‘git’, ‘texinfo’, ‘groff’, ‘make’, and ‘diffutils’. 4280 4281 Cygwin (unlike MinGW) has a current version of ‘makeinfo’, but an 4282undiagnosed bug still prevents building ‘kawa.info’. You can work 4283around that problem with ‘touch doc/kawa.info’. 4284 42854.4.2 Building the documentation 4286-------------------------------- 4287 42884.4.2.1 Plain HTML documentation 4289................................ 4290 4291You can build a plain HTML version of the documentation (using 4292‘makeinfo’ from the ‘texinfo’ distribution): 4293 cd doc && make kawa-html/index.html 4294 4295 In this case, point your browser at 4296‘file:/KAWA_SRCDIR/doc/kawa-html/index.html’. 4297 42984.4.2.2 Fancier HTML documentation 4299.................................. 4300 4301To build the documentation in a nicer form suitable for a web-site you 4302need ‘makeinfo’ _and_ the DocBook XSLT tools (and to have run 4303‘configure’ with the ‘--with-docbook-stylesheets’ option): 4304 cd doc && make web/index.html 4305 4306 You can then point your browser at 4307‘file:/KAWA_SRCDIR/doc/web/index.html’. 4308 43094.4.2.3 Using ebook readers or the –browse-manual option 4310........................................................ 4311 4312To build an ‘EPUB’ file suitable for ebook readers, as well as enabling 4313support for the *note ‘kawa --browse-manual’ option: 4314browse-manual-option, do: 4315 4316 cd doc && make kawa-manual.epub 4317 4318 This also requires the DocBook XSLT tools. 4319 43204.4.2.4 Building a printable PDF file 4321..................................... 4322 4323To build a ‘pdf’ file suitable for printing or online viewing do: 4324 cd doc && make kawa.pdf 4325 4326 The resulting ‘kawa.pdf’ is somewhat unsatisfactory - when viewed 4327online, links aren’t clickable. Furthermore, box drawing characters are 4328missing. 4329 43304.4.3 Build Kawa using ‘ant’ 4331---------------------------- 4332 4333Kawa now includes an Ant buildfile (‘build.xml’). Ant 4334(http://ant.apache.org) is a part of the Apache Jakarta project. If you 4335don’t hava Ant installed, get it from 4336<http://ant.apache.org/bindownload.cgi>. The build is entirely Java 4337based and works equally well on *nix, Windows, and presumably most any 4338other operating system. 4339 4340 Once Ant has been installed and configured (you may need to set the 4341‘JAVA_HOME’, and ‘ANT_HOME’ environment variables), you should be able 4342to change to the directory containing the ‘build.xml’ file, and invoke 4343the ‘ant’ command. With the default settings, a successful build will 4344result in a ‘kawa-3.1.1.jar’ in the current directory. 4345 4346 There are a few Ant "targets" of interest (they can be supplied on 4347the Ant command line): 4348 4349‘all’ 4350 This is the default, it does ‘classes’ and ‘jar’. 4351‘classes’ 4352 Compiles all the files into ‘*.class’ files into the directory 4353 specified by the ‘build.dir’ property. 4354‘jar’ 4355 Builds a jar into into the directory specified by the ‘dist.dir’ 4356 property. 4357‘runw’ 4358 Run Kawa in a GUI window. 4359‘clean’ 4360 Deletes all files generated by the build, including the jar. 4361 4362 There is not yet a ‘test’ target for running the testsuite. 4363 4364 There are various “properties" that control what ‘ant’ does. You can 4365override these on the command line or by editing the ‘build.properties’ 4366file in the same directory as ‘build.xml’. For example, the ‘build.dir’ 4367property tells ‘ant’ where to build temporary files, and where to leave 4368the resulting ‘.jar’ file. For example, to leave the generated files in 4369the sub-directory named ‘BUILD’ do: 4370 ant -Dbuild.dir=BUILD 4371 A sample ‘build.properties’ is provided and it contains comments 4372explaining many of the options. 4373 4374 Here are a few general properties that help to customize your build: 4375‘build.dir’ 4376 Path to put the temporary files used for building. 4377‘dist.dir’ 4378 Path to put the resulting jar file. 4379‘version.local’ 4380 A suffix to add to the version label for your customized version. 4381‘debug’ 4382 Whether (true/false) the Javac "-g" option is enabled. 4383‘optimize’ 4384 Whether (true/false) the Javac "-O" option is enabled. 4385 4386 Here are some Kawa-specific ones (all ‘true’/‘false’): 4387‘with-collections’, ‘with-references’, ‘with-awt’, ‘with-swing’, 4388‘enable-jemacs’, and ‘enable-servlet’> See the sample ‘build.properties’ 4389for more information on these. 4390 4391 If you change any of the build properties, you will generally want to 4392do an ‘ant clean’ before building again as the build is often not able 4393to notice that kind of change. In the case of changing a directory 4394path, you would want to do the ‘clean’ before changing the path. 4395 4396 A special note for NetBeans users: For some reason the build-tools 4397target which compiles an Ant task won’t compile with the classpath 4398provided by NetBeans. You may do ‘ant build-tools’ from the command 4399line outside of NetBeans, in which case you will not want to use the 4400‘clean’ target as that will delete the tool files as well. You can use 4401the ‘clean-build’ and/or ‘clean-dist’ targets as appropriate. 4402Alternatively you can add ‘ant.jar’ to the ‘build-tools’ classpath by 4403copying or linking it into a ‘lib/ext’ directory in Kawa’s source 4404directory (the one containing the ‘build.xml’ file). 4405 4406 4407File: kawa.info, Node: Tutorial, Next: Running, Prev: Installation, Up: Top 4408 44095 Kawa Scheme Tutorial 4410********************** 4411 4412_This is obviously incomplete, but it may be useful, especially if 4413you’re starting with Kawa from scratch._ If you’re new to Scheme you 4414might also check out one of these tutorials: Takafumi Shido’s Yet 4415Another Scheme Tutorial (http://www.shido.info/lisp/idx_scm_e.html); 4416Dorai Sitaram’s Teach Yourself Scheme in Fixnum Days 4417(http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme-Z-H-1.html); or 4418Paul Wilson’s An Introduction to Scheme and its Implementation 4419(ftp://ftp.cs.utexas.edu/pub/garbage/cs345/schintro-v14/schintro_toc.html). 4420 4421* Menu: 4422 4423* Tutorial - Introduction:: Introduction 4424* Tutorial - Booleans:: Booleans 4425* Tutorial - Numbers:: Numbers 4426* Tutorial - Functions:: Functions 4427* Tutorial - Variables:: Variables 4428* Tutorial - Pictures:: Pictures 4429* Tutorial - Sequences:: Lists and sequences 4430* Tutorial - Objects:: Creating and using objects 4431* Tutorial - Types:: Types and declarations 4432* Tutorial - Exceptions and errors:: 4433* Tutorial - Classes:: Classes 4434* Tutorial - Other Java features:: 4435 4436 4437File: kawa.info, Node: Tutorial - Introduction, Next: Tutorial - Booleans, Up: Tutorial 4438 44395.1 Introduction 4440================ 4441 4442You’ve heard about all the hot scripting languages – you might even be 4443tired of hearing about them. But Kawa offers you something different 4444than the scripting-language du-jour can. You may be interested in one 4445that runs on the Java virtual machine, either because you have to 4446interact with other Java tools, or because you like having access to all 4447the Java packages out there. Or maybe you don’t care about Java, but 4448you care about performance. If so, let me tell you about Kawa, which is 4449actually one of the very oldest language implementations running on the 4450Java Virtual Machine, dating back to 1996. 4451 4452 The Kawa language is a dialect/implementation of the Scheme language. 4453(The Kawa project also supports other languages, including XQuery 4454(http://www.w3.org/XML/Query) and Emacs Lisp 4455(http://jemacs.sourceforge.net), as well as tools for implementing mew 4456programming languages, but we won’t cover that in this tutorial.) 4457 4458 Scheme (http://www.schemers.org/) is an established language with 4459many implementations 4460(http://community.schemewiki.org/?scheme-faq-standards#implementations), 4461a standard (http://www.schemers.org/Documents/Standards/) specification 4462(the traditional R5RS 4463(http://www.schemers.org/Documents/Standards/R5RS/), R6RS 4464(http://www.r6rs.org/) which was ratified in 2007, and R7RS 4465(http://www.r7rs.org/) which was ratified in 2013), and is used by 4466universities for both teaching and research. Scheme also has a 4467reputation for being difficult to learn, with a weird parenthesis-heavy 4468syntax, and hard-to-understand concepts like continuations 4469(http://en.wikipedia.org/wiki/Continuation). Luckily, you don’t need to 4470understand continuations! (Kawa doesn’t fully implement them anyway.) 4471 4472 The following assumes that Kawa is already installed on your 4473computer; if not see these *note installation instructions: 4474Installation. Running the ‘kawa’ command in interactive mode is a good 4475way start learning Kawa: 4476 $ kawa 4477 #|kawa:1|# 4478 If you don’t have ‘kawa’ but you have a Kawa “jar” and you have Java 4479installed you can instead do: 4480 4481 $ java -jar kawa-VERSION-NUMBER.jar 4482 #|kawa:1|# 4483 4484 The prompt string has the form of a Scheme comment, to make it easier 4485to cut-and-paste. Kawa is expecting you type in an expression or 4486command, which it will evaluate, and then print out the result. For 4487example, a quoted string is a simple expression that evaluates to a 4488string value, which will print as itself, before printing the next 4489prompt: 4490 4491 #|kawa:1|# "Hello, world!" 4492 Hello, world! 4493 #|kawa:2|# 4494 4495 The most noticable difference from most other programming languages 4496is that Scheme uses “prefix” notation for function calls. For example 4497Kawa has a function ‘max’ which returns the largest value of the 4498arguments. Instead of ‘max(5, 7, 3)’ you write ‘(max 5 7 3)’: 4499 4500 (max 5 7 3) ⇒ 7 4501 4502 (We use the ‘⇒’ symbol above to indicate that the expression ‘(max 5 45037 3)’ evaluates to the value ‘7’.) 4504 4505 The prefix notation may feel a bit weird, but you quickly get used to 4506it, and it has some advantages. One is consistency: What are special 4507infix operators in most languages are just regular functions in Scheme. 4508For example, addition is just a regular function call, and ‘+’ is just a 4509regular function name: 4510 (+ 2.5 1.2) ⇒ 3.7 4511 4512 The same prefix notation is used for special operations like 4513assignments: 4514 #|kawa:1|# (set! sqrt-of-2 (sqrt 2)) 4515 #|kawa:2|# sqrt-of-2 4516 1.4142135623730951 4517 4518 4519File: kawa.info, Node: Tutorial - Booleans, Next: Tutorial - Numbers, Prev: Tutorial - Introduction, Up: Tutorial 4520 45215.2 Booleans 4522============ 4523 4524Scheme uses the syntax ‘#t’ and ‘#f’ for Boolean true and false value, 4525respectively. For example, the “less-than” function is named ‘<’. Its 4526result is true if the first argument is less than the second (or, if 4527there are more than two arguments, that they are in increasing order): 4528 (< 3 4) ⇒ #t 4529 (< -3 -4) ⇒ #f 4530 (< 2 3 5 7 11)) ⇒ #t 4531 4532 The ‘if’ special form takes two or three sub-expressions: It 4533evaluates the first expression. If that is true it evaluates the second 4534expression; otherwise it evaluates the third expression, if provided: 4535 (if (< 3 4) (+ 5 5) (+ 5 6)) ⇒ 10 4536 4537 We call ‘if’ a special form rather than a function, because for a 4538function all the arguments are evaluated before the function is called, 4539but in a special form that is not neceassarily the case. 4540 4541 In addition to ‘#t’ any value except ‘#f’ (and the Kawa-specific 4542‘#!null’) counts as “true” when evaluating the first expression of an 4543‘if’. Unlike C or JavaScript both (zero) and ‘""’ (the empty string) 4544are true: 4545 4546 (if 0 (+ 5 5) (+ 5 6)) ⇒ 10 4547 4548 You can use ‘and’, ‘or’, and ‘not’ to create complex boolean 4549expressions. Of these ‘and’ and ‘or’ are special forms that only 4550evaluate as many of the sub-expressions as needed. 4551 (if (not (and (>= i 0) (<= i 9))) 4552 (display "error")) 4553 4554 You can use the ‘cond’ form as an alternative to ‘if’: 4555 (cond ((< 3 3) 'greater) 4556 ((> 3 3) 'less) 4557 (else ’equal)) ⇒ equal 4558 4559 The null value (written as ‘#!null’ in Kawa or ‘null’ in Java) is 4560also considered as false. 4561 4562 4563File: kawa.info, Node: Tutorial - Numbers, Next: Tutorial - Functions, Prev: Tutorial - Booleans, Up: Tutorial 4564 45655.3 Numbers 4566=========== 4567 4568Exact integers and fractions 4569---------------------------- 4570 4571Kawa has the usual syntax for decimal integers. Addition, subtraction, 4572and multiplication are written using the usual ‘+’, ‘-’, and ‘*’, but 4573these are all prefix functions that take a variable number of arguments: 4574 4575 (+ 1 2 3) ⇒ 6 4576 (- 10 3 4) ⇒ (- (- 10 3) 4) ⇒ 3 4577 (* 2 -6) ⇒ -12 4578 4579 Kawa has arbitrary-precision integers. 4580 4581 Let us implement the factorial 4582(http://en.wikipedia.org/wiki/Factorial) function. Type in the 4583following (we’ll look at the syntax shortly): 4584 #|kawa:1|# (define (factorial x) 4585 #|(---:2|# (if (< x 1) 1 4586 #|(---:3|# (* x (factorial (- x 1))))) 4587 4588 (The prompt changes to indicate a continuation line.) This binds the 4589name ‘factorial’ to a new function, with formal parameter ‘x’. This new 4590function is immediately compiled to Java bytecodes, and later a JIT 4591compiler may compile it to native code. 4592 4593 A few tests: 4594 #|kawa:4|# (list (factorial 3) (factorial 4)) 4595 (6 24) 4596 #|kawa:5|# (factorial 30) 4597 265252859812191058636308480000000 4598 4599Floating-point real numbers 4600--------------------------- 4601 4602Given what was said above about being able to add, subtract and multiply 4603integers, the following may be unexpected: 4604 4605 #|kawa:1|# (/ 2 3) 4606 2/3 4607 #|kawa:2|# (+ (/ 1 3) (/ 2 3)) 4608 1 4609 4610 In many languages, dividing two integers, as 2/3, would result in 0. 4611At best, the result would be a floating point number, similar to 46120.666667. Instead, Kawa has a _rational_ number type, which holds the 4613results of divisions _exactly_, as a proper fraction. Hence, adding one 4614third to two thirds will always result in exactly one. 4615 4616 Floating-point real numbers are known in Kawa as _inexact_ numbers, 4617as they cannot be stored exactly. Consider: 4618 4619 #|kawa:3|# (exact? 2/3) 4620 #t 4621 #|kawa:4|# (exact? 0.33333333) 4622 #f 4623 #|kawa:5|# (exact->inexact 2/3) 4624 0.6666666666666666 4625 4626 The first two examples check numbers for being ‘exact?’; there is a 4627corresponding ‘inexact?’ test. The last shows how an exact number can 4628be converted to an inexact form. 4629 4630 Numbers are converted between exact and inexact versions when 4631required within operations or procedures: 4632 4633 #|kawa:6|# (+ 0.33333333 2/3) 4634 0.9999999966666666 4635 #|kawa:7|# (inexact? (+ 0.33333333 2/3)) 4636 #t 4637 #|kawa:8|# (sin 2/3) 4638 0.618369803069737 4639 4640Complex numbers 4641--------------- 4642 4643A _complex_ number is made from two parts: a _real_ part and an 4644_imaginary_ part. They are written ‘2+3i’. A complex number can be 4645manipulated just like other numbers: 4646 4647 #|kawa:9|# (+ 2+3i 5+2i) 4648 7+5i 4649 #|kawa:10|# (* 2+3i 4-3i) 4650 17+6i 4651 #|kawa:11|# (integer? (+ 2+3i -3i)) 4652 #t 4653 4654 Notice how in the last example the result is an integer, which Kawa 4655recognises. 4656 4657 Kawa also includes *note quaternion: Quaternions. numbers. 4658 4659Units and dimensions 4660-------------------- 4661 4662In many applications, numbers have a _unit_. For example, 5 might be a 4663number of dollar bills, a weight on a scale, or a speed. Kawa enables 4664us to represent numbers as _quantities_: numbers along with their unit. 4665For example, with weight, we might measure weight in pounds and ounces, 4666where an ounce is 1/16 of a pound. 4667 4668 Using Kawa, we can define units for our weight measurements, and 4669specify the units along with numbers: 4670 4671 #|kawa:12|# (define-base-unit pound "Weight") 4672 #|kawa:13|# (define-unit ounce 0.0625pound) 4673 #|kawa:14|# 3pound 4674 3.0pound 4675 #|kawa:15|# (+ 1pound 5ounce) 4676 1.3125pound 4677 4678 In this example we define a base unit, the pound, and a unit based on 4679it, the ounce, which is valued at 0.0625 pounds (one sixteenth). 4680Numbers can then be written along with their unit (making them 4681quantities). Arithmetic is possible with quantities, as shown in the 4682last line, and Kawa will do the smart thing when combining units. In 4683this case, 1 pound and 5 ounces is combined to make 1.3125 pounds. 4684 4685 4686File: kawa.info, Node: Tutorial - Functions, Next: Tutorial - Variables, Prev: Tutorial - Numbers, Up: Tutorial 4687 46885.4 Functions 4689============= 4690 4691To declare a new function use ‘define’, which has the following form: 4692 (define (FUNCTION-NAME PARAMETER-NAMES) BODY) 4693 4694 This creates a new function named FUNCTION-NAME, which takes 4695PARAMETER-NAMES as parameters. When the function is called, the 4696PARAMETER-NAMES are initialized with the actual arguments. Then BODY is 4697evaluated, and its value becomes the result of the call. 4698 4699 For example, in the ‘factorial’ function we looked at recently, the 4700FUNCTION-NAME is ‘factorial’, and the PARAMETER-NAMES is ‘x’: 4701 4702 (define (factorial x) 4703 (if (< x 1) 1 4704 (* x (factorial (- x 1))))) 4705 4706Anonymous functions 4707------------------- 4708 4709An _anonymous_ function is simply a function which does not have a name. 4710We define an anonymous function using a “lambda expression”, which has 4711the following form: 4712 (lambda (PARAMETER-NAMES) BODY) 4713 4714 The lambda expression has the PARAMETER-NAMES and BODY of a function, 4715but it has no name. What is the point of this? 4716 4717 An important example is creating a function to act on a list, perhaps 4718using ‘map’. The ‘map’ function takes two parameters: the first is a 4719function which takes a value and returns a value; the second is a list. 4720Here, we want to double every number in the list. 4721 4722 The usual way of doing this is to create a named function, called 4723‘double’, and then apply it to a list: 4724 4725 #|kawa:1|# (define (double x) 4726 #|.....2|# (* 2 x)) 4727 #|kawa:3|# (map double (list 1 2 3 4 5)) 4728 (2 4 6 8 10) 4729 4730 Instead, anonymous functions make it easy to create a function to 4731work on a list, without having to define it in advance: 4732 4733 #|kawa:4|# (map (lambda (x) (* 2 x)) (list 1 2 3 4 5)) 4734 (2 4 6 8 10) 4735 #|kawa:5|# (define y 3) 4736 #|kawa:6|# (map (lambda (x) (* x y)) (list 1 2 3 4 5)) 4737 (3 6 9 12 15) 4738 4739 The first example shows the double example rewritten as an anonymous 4740function. The second example shows how the anonymous function can be 4741changed to fit the place in which it is used: here, the value of Y 4742determines the value by which the list values are multiplied. 4743 4744 Notice that we can name our anonymous functions, in just the same way 4745we name any value in Kawa, using ‘define’: 4746 4747 (define double 4748 (lambda (n) 4749 (* 2 n))) 4750 4751 although more frequently we use the short-hand for defining 4752functions, which we have already met: 4753 4754 (define (double n) 4755 (* 2 n)) 4756 4757 Anonymous functions are “first-class values” in Kawa, and can be 4758passed to other functions as arguments (like we did with ‘map’), and 4759they can even be created and returned by functions as results. 4760 4761Optional, rest and keyword parameters 4762------------------------------------- 4763 4764You can declare a function that takes optional arguments, or a variable 4765number of arguments. You can also use keyword parameters. 4766 4767 The following function illustrates the use of _optional_ arguments. 4768The function identifies an optional argument ‘z’: if the function is 4769called with 3 arguments, ‘z’ will be bound to the third value, otherwise 4770it will be ‘#f’. 4771 4772 (define (addup x y #!optional z) 4773 (if z 4774 (+ x y z) 4775 (+ x y))) 4776 4777 The following examples show ‘addup’ applied to 2, 3 and invalid 4778arguments. It is an error to pass just one argument or more than three: 4779‘x’ and ‘y’ are compulsory, but ‘z’ is optional. 4780 4781 #|kawa:12|# (addup 1 2) 4782 3 4783 #|kawa:13|# (addup 1 2 3) 4784 6 4785 #|kawa:14|# (addup 1) 4786 /dev/stdin:14:1: call to 'addup' has too few arguments (1; min=2, max=3) 4787 #|kawa:15|# (addup 1 2 3 4) 4788 /dev/stdin:15:1: call to 'addup' has too many arguments (4; min=2, max=3) 4789 4790 In this example, a better way to define the function would be to 4791include a default value for ‘z’, for when its value is not given by the 4792caller. This is done as follows, with the same behavior as above: 4793 4794 (define (addup x y #!optional (z 0)) 4795 (+ x y z)) 4796 4797 You can include as many optional parameters as you wish, after the 4798‘#!optional’. 4799 4800 _Rest_ arguments are an alternative way to pass an undefined number 4801of arguments to a function. Here is ‘addup’ written with rest 4802arguments, notice the variable name after the . (dot): 4803 4804 (define (addup x y . args) 4805 (+ x y (apply + args))) 4806 4807 The ‘args’ are simply a list of all remaining values. The following 4808now all work, as the function only requires a minimum of two numbers: 4809 4810 #|kawa:4|# (addup 1 2) 4811 3 4812 #|kawa:5|# (addup 1 2 3) 4813 6 4814 #|kawa:6|# (addup 1 2 3 4 5 6 7 8) 4815 36 4816 4817 An alternative way to identify the rest args is with ‘#!rest’: 4818 4819 (define (addup x y #!rest args) 4820 (+ x y (apply + args))) 4821 4822 Finally, it can be useful to identify parameters by name and, for 4823this, Kawa provides _keyword_ arguments. Consider the following 4824function: 4825 4826 #|kawa:38|# (define (vector-3d #!key x y z) 4827 #|.....39|# (vector x y z)) 4828 #|kawa:40|# (vector-3d #:x 2 #:z 3 #:y 4) 4829 #(2 4 3) 4830 4831 ‘vector-3d’ is defined with three keyword arguments: ‘x’, ‘y’, and 4832‘z’. When the function is called, we identify the name for each value 4833by writing ‘#:’ at the start of the name. This allows us to write the 4834arguments in any order. Keyword parameters can also be given default 4835values, as with optional parameters. Keyword parameters with no default 4836value, and no value in the caller, will get the value ‘#f’. 4837 4838 In the caller, keywords are symbols with ‘#:’ at the front (or ‘:’ at 4839the end): *note read more here: Keywords. 4840 4841 All these extended types of arguments are available both for “named” 4842and for “anonymous” functions. Optional, rest and keyword arguments can 4843be mixed together, along with the usual arguments. For details *note 4844read more here.: Extended formals. 4845 4846 4847File: kawa.info, Node: Tutorial - Variables, Next: Tutorial - Pictures, Prev: Tutorial - Functions, Up: Tutorial 4848 48495.5 Variables 4850============= 4851 4852You can declare a variable using a ‘!’ form. This takes a variable 4853name, and an expression. It declares a new variable with the given 4854name, and gives it the value of the expression. 4855 #|kawa:1|# (! binary-kilo 1024) 4856 #|kawa:2|# (! binary-mega (* binary-kilo binary-kilo)) 4857 #|kawa:3|# binary-mega 4858 1048576 4859 4860 If you prefer, you can use ‘define’ instead of ‘!’: 4861 4862 #|kawa:1|# (define binary-kilo 1024) 4863 #|kawa:2|# (define binary-mega (* binary-kilo binary-kilo)) 4864 #|kawa:3|# binary-mega 4865 1048576 4866 4867 The advantage of using ‘define’ is that it is portable to other 4868Scheme implementations. The advantages of using ‘!’ is that it is 4869shorter; it generalizes to patterns (see later); and it guards against 4870accidentally “shadowing” a variable by a nested variable with the same 4871name. 4872 4873 A ‘!’ (or ‘define’) typed into the command-line defines a top-level 4874variable. 4875 4876 You can also declare local variables, which are variables defined for 4877a given block of code. For example, in the following code ‘let’ is used 4878to set up a local binding of ‘x’ to 3: this does not affect the outer 4879binding of ‘x’ to 5: 4880 4881 (define x 5) 4882 4883 (let ((x 3)) 4884 (display x)) ⇒ 3 4885 4886 (display x) ⇒ 5 4887 4888 Alternative forms for defining local variables are ‘let’, ‘let*’, or 4889‘letrec’/‘letrec*’. 4890 4891 The differences are in the order in which definitions are made. 4892‘let’ evaluates all its definitions in the environment holding at the 4893start of the ‘let’ statement. In the following example, the local 4894variables are defined using values from the global variables: 4895 4896 (define x 5) 4897 (define y 2) 4898 4899 (let ((x (+ 2 y)) ; uses value of global y, i.e. 2 4900 (y (+ 3 x))) ; uses value of global x, i.e. 5 4901 (display (list x y))) ⇒ (4 8) 4902 4903 ‘let*’ instead evaluates each definition in the environment holding 4904at the start of the ‘let*’ statement, along with all _previous_ local 4905definitions. In the following example, ‘y’ is now defined with the 4906_local_ value of ‘x’: 4907 4908 (define x 5) 4909 (define y 2) 4910 4911 (let* ((x (+ 2 y)) ; uses value of global y, i.e. 2 4912 (y (+ 3 x))) ; uses value of local x, i.e. 4 4913 (display (list x y))) ⇒ (4 7) 4914 4915 ‘letrec/letrec*’ are similar, but allow the definition of recursive 4916functions: 4917 4918 (letrec ((is-even? (lambda (n) (and (not (= 1 n)) 4919 (or (zero? n) 4920 (is-odd? (- n 1)))))) 4921 (is-odd? (lambda (n) (and (not (zero? n)) 4922 (or (= 1 n) 4923 (is-even? (- n 1))))))) 4924 (display (is-even? 11))) ⇒ #f 4925 4926 4927File: kawa.info, Node: Tutorial - Pictures, Next: Tutorial - Sequences, Prev: Tutorial - Variables, Up: Tutorial 4928 49295.6 Composable pictures 4930======================= 4931 4932The ‘pictures’ library lets you create geometric shapes and images, and 4933combine them in interesting ways. You first need to import the library: 4934 (import (kawa pictures)) 4935 The easiest way to use and learn the library is with a suitable REPL, 4936where you can type expressions that evaluate to pictures values, and 4937view the resulting pictures directly on the console. The easiest way is 4938to start the ‘kawa’ command with the ‘-w’ flag. Alternatively, you can 4939use a *note DomTerm: Using DomTerm.-based terminal emulator such as 4940‘qtdomterm’ (which is shown in the image below), and then the ‘kawa’ 4941command. 4942 4943�[image src="images/domterm-pictures-1.png"�] 4944 4945 The above image shows two simple examples: a filled circle (radius 30 4946pixels, color magenta), and a non-filled rotated rectangle (color maroon 49473-pixel wide strokes). 4948 4949 See *note Composable pictures:: for details and more examples. 4950 4951Shapes and coordinates 4952---------------------- 4953 4954A “shape” is a geometrical figure consisting of one or more curves and 4955lines. One kind of shape is a circle; you can create one with the 4956‘circle’ procedure, specifying the radius in “pixels”. 4957 4958 #|kawa:1|# (import (kawa pictures)) 4959 #|kawa:2|# (circle 30) 4960 �[image src="images/fill-circ-1.png"�] 4961 It you print a shape, it will show it as a thin black curve. 4962 4963 A “point” has two real-numbered parts: the point’s x-coordinate, and 4964its y-coordinate. The x-coordinate increases as you move right along 4965the page/screen, while the y-coordinate increases as you move _down_. 4966(Unlike traditional mathematics, where the y-coordinate increases as you 4967go up.) The unit distance is one “pixel”, which is defined as CSS or 4968HTML. You can create a point with ‘&P’ operator. For example: 4969 &P[30 20] 4970 is a point 30 pixels right and 20 pixels down from the origin point. 4971To create a circle centered on that point do ‘(center 30 &P[30 20])’. 4972 4973 The expression ‘(rectangle &P[10 20] &P[50 40])’ creates a rectangle 4974whose upper left corner is (10,20) and whose lower right corner is 4975(50,40). 4976 4977 A “dimension” is a pair, a width and height, and is written: 4978 &D[WIDTH HEIGHT] 4979 In addition to being used for sizes, a dimension is also used for 4980relative offsets. For example, the previous rectangle could also be 4981written ‘(rectangle &P[10 20] &D[40 20])’. 4982 4983 You can use ‘line’ to create a line. More generally, if you specify 4984N points you get a “polyline” of N-1 line segments: 4985 #|kawa:3|# (line &P[10 20] &P[50 60] &P[90 0]) 4986 �[image src="images/polyline-1.png"�] 4987 The same line using dimensions for relative offsets: 4988 #|kawa:4|# (line &P[10 20] &D[40 20] &D[40 -60]) 4989 4990 A “closed shape” is one whose end point is the same as its start 4991point. The ‘polygon’ function creates one using straight line segments 4992 #|kawa:5|# (polygon &P[10 20] &P[50 60] &P[90 0]) 4993 �[image src="images/polygon-1.png"�] 4994 4995Colors and filling 4996------------------ 4997 4998You can override the default color (black) using the ‘with-paint’ 4999procedure, which takes a color and a picture to produce a new picture: 5000 #|kawa:6|# (with-paint 'red (circle 32)) 5001 5002 The first argument can be either one of the standard CSS/HTML5 color 5003names (such as ‘'red’ or ‘'medium-slate-blue’), or an integer 5004representing an sRGB color, usually written as a hex literal in the form 5005‘#xRRGGBB’: 5006 #|kawa:7|# (with-paint #x0808FF (circle 32)) 5007 5008 The name ‘with-paint’ is because the first argument can be not just a 5009color, but a general “paint”, such as a gradient or a background image. 5010However, we won’t go into that. 5011 5012 If the shape is closed, you can “fill” its inside: 5013 (fill (circle 32)) 5014 5015 You can change the color using ‘with-paint’: 5016 (with-paint 'goldenrod (fill (circle 32))) 5017 or as an extra argument to ‘fill’: 5018 (fill 'goldenrod (circle 32)) 5019 5020 draw TODO 5021 5022Images 5023------ 5024 5025An image is a picture represented as a rectangular grid of color values. 5026It may be a photograph from a camera, or be created by a painting 5027program like Photoshop or gimp. You can use ‘image-read’ to read an 5028image from a file, typically a ‘.png’ or ‘.jpg’ file. 5029 5030 #|kawa:10|# (define img1 (image-read "http://pics.bothner.com/2013/Cats/06t.jpg")) 5031 #|kawa:11|# img1 5032 �[image src="images/image-cat-1a.png"�] 5033 5034Transforms TODO 5035--------------- 5036 5037 #|kawa:12|# (scale 0.6 (rotate 30 img1)) 5038 �[image src="images/image-cat-1b.png"�] 5039 5040Combining and adjusting pictures TODO 5041------------------------------------- 5042 5043Using and combining pictures TODO 5044--------------------------------- 5045 5046 5047File: kawa.info, Node: Tutorial - Sequences, Next: Tutorial - Objects, Prev: Tutorial - Pictures, Up: Tutorial 5048 50495.7 Lists and sequences 5050======================= 5051 5052A “sequence” is a generalized array or list: Zero or more values treated 5053as a compound value. Sequences have certain common operations, 5054including indexing and iteration. (Technical note: Sequences generally 5055implement the ‘java.util.List’ interface, but Kawa will also treat 5056strings and native Java arrays as sequences.) 5057 5058Lists 5059----- 5060 5061In traditional Lisp-family languages, the “list” is the most important 5062kind of sequence. (Don’t confuse Java’s ‘List’ interface with Kawa’s 5063use of the word list. They’re related, in that a Kawa “list” implements 5064the ‘List’ interface, so any list is also ‘List’, but not vice versa.) 5065 5066 A list is implemented as a chain of linked “pairs”. You can create a 5067constant list by quoting a parenthesized list: 5068 '(3 4 (10 20 30) "a string") 5069 5070 See *note Lists:: for details and operations. 5071 5072Vectors 5073------- 5074 5075A “vector” is a sequence that is implemented by storing the elements 5076side-by-side in memory. A vector uses less space than a list of the 5077same length, and is generally more efficient than a list. 5078 5079 To create a vector you can use a bracketed list: 5080 (! vec1 ['A 'B 'C 'D 'E 'F]) 5081 This creates a vector of 6 symbols and binds it to ‘vec1’. To select 5082an element you can use the traditional ‘vector-ref’ procedure: 5083 (vector-ref vec1 3) ⇒ 'D 5084 Alternatively, in Kawa you can use function-call notation: 5085 (vec1 3) ⇒ 'D 5086 5087 You can also create a vector using the traditional ‘vector’ 5088constructor: 5089 (! vec2 (vector 'A 'B 'C 'D 'E 'F)) 5090 There is one important difference between ‘vec1’ and ‘vec2’: You can 5091modify ‘vec2’ by changing some or all of its elements. You can’t do 5092that for ‘vec1’. (We say that ‘vec1’ is an “immutable” or “constant” 5093vector, while ‘vec1’ is a “mutable” or “modifiable” vector.) To change 5094an element use either the traditional ‘vector-set!’ procedure, or 5095function-call notation: 5096 (vector-set! vec2 2 'Y) 5097 (set! (vec2 4) 'Z) 5098 vec2 ⇒ ['A 'B 'Y 'D 'Z 'F] 5099 (vector-set! vec1 2 'Y) ⇒ throws exception 5100 5101 See *note Vectors:: for details and operations. 5102 5103Java arrays and primitive vectors 5104--------------------------------- 5105 5106See *note Using Java arrays: Array operations. for examples. 5107 5108Indexing of general sequences 5109----------------------------- 5110 5111You can use function-call notation to index a generalized sequence, 5112whether it is a list, vector, any ‘java.util.List’, native Java array, 5113or string: 5114 ((list 'A 'B 'C 'D) 2) ⇒ 'C 5115 ("abcdef" 3) ⇒ ⇒ 5116 (! farr (float[] 1.5 3 4.5)) ;; native Java array 5117 (farr 2) ⇒ 4.5 5118 5119 Note that indexing a list with an index I will be slow, since it has 5120to step through the list I times. (So don’t do that!) 5121 5122Ranges 5123------ 5124 5125A “range” is a sequence of numbers in order, spaced uniformly apart. 5126Usually, these are (exact) integers that increase by one. The usual 5127notation is: 5128 [START <: END] 5129 This is the sequence of integers starting with the integer START 5130(inclusive) and ending with the integer END (exclusive). For example 5131‘[3 <: 7]’ is the sequence ‘[3 4 5 6]’. 5132 5133 The ‘<:’ is a keyword; the ‘<’ is a mnemonic for the set of integers 5134that are ‘<’ the end value 6. You can also use ‘<=:’ if you want to 5135include the upper bound: ‘[4 <=: 8]’ is ‘[4 5 6 7 8]’. 5136 5137 You can use ‘>=:’ or ‘>:’ for a decreasing range. ‘[5 >=: 1]’ or ‘[5 5138>: 0]’ both evaluate to ‘[5 4 3 2 1]’. You can also specifify a step 5139value: ‘[1 by: 2 <=: 9]’, which evaluates to ‘[1 3 5 7 9]’. (*note 5140Details here: Ranges.) 5141 5142Using vector and ranges indexes 5143------------------------------- 5144 5145If an index is a sequence of integers, the result is a new sequence (of 5146the same type) selecting only the elements matching the index values. 5147For example: 5148 #|kawa:2|# (vec1 [3 5 2]) 5149 #(D F C) 5150 In general, ‘((V1 V2) I)’ is ‘(V1 (V2 I))’. 5151 5152 You can use a range to create a slice - a contiguous subset of a 5153list. 5154 #|kawa:3|# (vec1 [2 <: 6]) 5155 #(C D E F) 5156 5157 A range is different from a vector integer in that you can use a 5158range as the index in the LHS of a set!: 5159 5160 #|kawa:4|# (set! (vec1 [2 <: 4]) #(a b c d e)) 5161 #|kawa:5|# vec1 5162 #(A B a b c d e E F) 5163 5164 Notice how the number of replaced elements can be different then the 5165number of elements in the replacement value. I.e. you can do insertion 5166and deletion this way. 5167 5168 #|kawa:7|# (! str1 (string-copy "ABCDEF")) 5169 #|kawa:8|# (set! (str1 [2 <: 5]) "98") 5170 AB98F 5171 5172 5173File: kawa.info, Node: Tutorial - Objects, Next: Tutorial - Types, Prev: Tutorial - Sequences, Up: Tutorial 5174 51755.8 Creating and using objects 5176============================== 5177 5178An “object” is a value that has the following features: 5179 • class - each object is an instance of a specific class, making it 5180 part of the class hierarchy, which is an important aspect of the 5181 type system; 5182 • properties - various fields and methods, depending on the class; 5183 • identity - it is distinct from all other objects, even if all the 5184 properties are the same. 5185 5186 We later discuss *note how to write a new class: Tutorial - Classes. 5187Here we assume you’re using an existing class, which could be written in 5188Java or Scheme. 5189 5190Creating a new object 5191--------------------- 5192 5193To create a new object of class ‘T’ you call ‘T’ as if it were a 5194function, passing it the various constructor arguments: 5195 (java.io.File "src" "build.xml") 5196 5197 If there are keyword arguments they are used to initialize the 5198corresponding named properties: 5199 (! button1 (javax.swing.JButton text: "Do it!" tool-tip-text: "do it")) 5200 This create a new ‘JButton’ object (using ‘JButton’’s default 5201constructor), and sets the ‘text’ and ‘tool-tip-text’ properties (by 5202calling ‘JButton’’s ‘setText’ and ‘setToolTipText’ methods). If there 5203are constructor arguments, they must come before the keywords. 5204 5205 For objects that have components or elements, you can list these at 5206the end. For example: 5207 (java.util.ArrayList 11 22 33) 5208 This creates a fresh ‘java.util.ArrayList’ (using the default 5209constructor), and then calls the ‘add’ method 3 times. 5210 5211 If you prefer you can use the ‘make’ procedure, but that only handle 5212simple constructor calls: 5213 (make java.io.File "src" "build.xml") 5214 5215 See *note Allocating objects:: for details. 5216 5217Calling instance methods 5218------------------------ 5219 5220Given an object OBJ of a class that has a method METH, you can call it 5221with argumens V1 ... V2 using *note Colon notation::: 5222 (OBJ:METH V1 ... V2) 5223 For example: 5224 (button1:paintImmediately 10 10 30 20) 5225 5226 If you prefer, you can use the ‘invoke’ procedure, normally with a 5227quoted method name: 5228 (invoke button1 'paintImmediately 10 10 30 20) 5229 You need to use ‘invoke’ (rather than colon notation) if OBJ is a 5230‘Class’ or a type expression, or its class implements 5231‘gnu.mapping.HasNamedParts’. 5232 5233 See *note Method operations:: for details. 5234 5235Accessing properties 5236-------------------- 5237 5238If OBJ has a field or property named FLD you can also use colon 5239notation: 5240 OBJ:FLD 5241 5242 You use the same syntax whether FLD is an actual field in the object, 5243or a “property” (in the Java Beans sense). The latter is implemented 5244using a getter/setter pair: Methods named ‘getF’ and ‘setF’, 5245respectively. For example: 5246 button1:tool-tip-text 5247 is equivalent to: 5248 (button1:getToolTipText) 5249 5250 You can also change a field or property using colon notation: 5251 (set! OBJ:FLD VALUE) 5252 For example: 5253 (set! button1:tool-tip-text "really do it!") 5254 This is equivalent to: 5255 (button1:setToolTipText "really do it!") 5256 5257 Instead of colon notation, you can use the ‘field’ procedure. 5258 5259 See *note Field operations:: for details. 5260 5261Static fields and methods 5262------------------------- 5263 5264Kawa views static properties and methods as properties and methods of 5265the class itself. To call a static method use the syntax: 5266 (CLAS:METH V1 ... VN) 5267 For example: 5268 (java.math.BigDecimal:valueOf 12345 2) ⇒ 123.45 5269 5270 To access a static field do ‘CLAS:FLD’. For example: 5271 java.awt.Color:RED 5272 5273 You can also use the ‘static-field’ and ‘invoke-static’ procedures. 5274 5275 5276File: kawa.info, Node: Tutorial - Types, Next: Tutorial - Exceptions and errors, Prev: Tutorial - Objects, Up: Tutorial 5277 52785.9 Types and declarations 5279========================== 5280 5281A “type” is a named value for a set of objects with related properties. 5282For example, ‘vector’ is the type for standard Scheme vectors. You can 5283use a type to specify that a variable can only have values of the 5284specified type: 5285 5286 #|kawa:5|# (define v ::vector #(3 4 5)) 5287 #|kawa:6|# v 5288 #(3 4 5) 5289 #|kawa:7|# (set! v 12) 5290 /dev/stdin:7:1: warning - cannot convert literal (of type gnu.math.IntNum) to vector 5291 Value (12) for variable 'v' has wrong type (gnu.math.IntNum) (gnu.math.IntNum cannot be cast to gnu.lists.FVector) 5292 at atInteractiveLevel$7.run(stdin:7) 5293 at gnu.expr.ModuleExp.evalModule(ModuleExp.java:302) 5294 at kawa.Shell.run(Shell.java:275) 5295 at kawa.Shell.run(Shell.java:186) 5296 at kawa.Shell.run(Shell.java:167) 5297 at kawa.repl.main(repl.java:870) 5298 Caused by: java.lang.ClassCastException: gnu.math.IntNum cannot be cast to gnu.lists.FVector 5299 ... 6 more 5300 5301 Using a type specification catches errors, and makes your programs 5302more readable. It can also allow the Kawa compiler to generate code 5303that runs faster. 5304 5305 You can use a type to check that a value is an instance of the type, 5306using either the ‘instance?’ function: 5307 5308 (instance? #(3 4 5) vector) ⇒ #t 5309 (instance? '(3 4 5) vector) ⇒ #f 5310 5311 As a convenience, you can use a type-name followed by a “‘?’”: 5312 (TYPE? VAL) == (instance? VAL TYPE) 5313 5314 You can “call” a type as if it were a function, which constructs a 5315new instance of the type. The following example shows how to construct 5316a normal Scheme vector, and a Java array of ints: 5317 5318 #|kawa:1|# (vector) 5319 #() 5320 #|kawa:2|# (instance? (vector) vector) 5321 #t 5322 #|kawa:3|# (define x (int[] 1 2 3)) 5323 #|kawa:4|# x 5324 [1 2 3] 5325 #|kawa:5|# (instance? x int[]) 5326 #t 5327 5328 A fully-qualified Java class is a type name. So are the names of 5329Java primitive types. So are Java array types, as shown above. 5330 5331 e.g. a JFrame is constructed by using its class name as a function: 5332 5333 #|kawa:6|# (javax.swing.JFrame) 5334 javax.swing.JFrame[frame0,0,25,0x0,invalid,hidden,layout=java.awt.BorderLayout, 5335 title=,resizable,normal,defaultCloseOperation=HIDE_ON_CLOSE, 5336 rootPane=javax.swing.JRootPane[,0,0,0x0,invalid, 5337 layout=javax.swing.JRootPane$RootLayout,alignmentX=0.0,alignmentY=0.0,border=, 5338 flags=16777673,maximumSize=,minimumSize=,preferredSize=],rootPaneCheckingEnabled=true] 5339 5340 A type is a true run-time value: 5341 5342 (define mytypes (list vector list string)) 5343 (instance? #(3 4 5) (car mytypes) ⇒ #t 5344 5345 The ‘define-alias’ form is useful for defining shorter names for 5346types, like a generalization of Java’s ‘import’ statement: 5347 5348 (define-alias jframe javax.swing.JFrame) 5349 5350 5351File: kawa.info, Node: Tutorial - Exceptions and errors, Next: Tutorial - Classes, Prev: Tutorial - Types, Up: Tutorial 5352 53535.10 Exceptions and errors 5354========================== 5355 5356Kawa supports the exception framework and forms from R6RS and R7RS. See 5357*note Exceptions:: for details. 5358 5359Native exception handling 5360------------------------- 5361 5362You can also work with native Java exceptions at a low level. 5363 5364 The ‘primitive-throw’ procedure throws a ‘Throwable’ value. It is 5365implemented just like Java’s ‘throw’. 5366 (primitive-throw (java.lang.IndexOutOfBoundsException "bad index")) 5367 5368 You can catch an exception with the ‘try-catch’ syntax. For example: 5369 (try-catch 5370 (do-a-bunch-of-stuff) 5371 (ex java.lang.Throwable 5372 (format #f "caught ~a~%~!" ex) 5373 (exit))) 5374 5375 A ‘try-finally’ does the obvious: 5376 (define (call-with-port port proc) 5377 (try-finally 5378 (proc port) 5379 (close-port port))) 5380 5381 Both ‘try-catch’ and ‘try-finally’ are expression forms that can 5382return values, while the corresponding Java forms are statements that 5383cannot return values. 5384 5385 5386File: kawa.info, Node: Tutorial - Classes, Next: Tutorial - Other Java features, Prev: Tutorial - Exceptions and errors, Up: Tutorial 5387 53885.11 Classes 5389============ 5390 5391See *note Defining new classes:: for the gory details; no tutorial yet. 5392 5393 5394File: kawa.info, Node: Tutorial - Other Java features, Prev: Tutorial - Classes, Up: Tutorial 5395 53965.12 Other Java features 5397======================== 5398 5399Import 5400------ 5401 5402The ‘import’ form can be used to avoid having to write fully-qualified 5403class names. For example: 5404 (import (class java.util 5405 Map 5406 (HashMap HMap))) 5407 This defines aliases for two classes in the ‘java.util’ package, one 5408with renaming: ‘Map’ is an alias for ‘java.util.Map’, and ‘HMap’ is an 5409alias for ‘java.util.HashMap’. 5410 5411 The ‘class’ keyword is needed because the ‘import’ form is also used 5412for Kawa’s module system. See *note importing-class-names:: and *note 5413Importing:: for details. 5414 5415Synchronized blocks 5416------------------- 5417 5418You can use a ‘synchronized’ expression: 5419 5420 (synchronized obj form1 ... formn) 5421 This waits until it can get an exclusive lock on OBJ and then 5422evaluates FORM1 through FORMN. Unlike Java, this is an expression and 5423returns the value of FORMN. 5424 5425Annotations 5426----------- 5427 5428You can write annotation declarations - see *note Annotations:: for 5429details. 5430 5431 Kawa does not yet support annotations on types, or declaring new 5432annotation classes. 5433 5434 5435File: kawa.info, Node: Running, Next: Syntax, Prev: Tutorial, Up: Top 5436 54376 How to start up and run Kawa 5438****************************** 5439 5440The easiest way to start up Kawa is to run the ‘kawa’ program. This 5441finds your Java interpreter, and sets up ‘CLASSPATH’ correctly. If you 5442have installed Kawa such that ‘$PREFIX/bin’ is in your ‘$PATH’, just do: 5443 kawa 5444 However, ‘kawa’ only works if you have a Unix-like environment. On 5445some platforms, ‘kawa’ is a program that uses the GNU ‘readline’ library 5446to provide input line editing. 5447 5448 To run Kawa manually, you must start a Java Virtual Machine. How you 5449do this depends on the Java implementation. For Oracle’s JDK, and some 5450other implementations, you must have the Java evaluator (usually named 5451‘java’) in your ‘PATH’. You must also make sure that the 5452‘kawa/repl.class’ file, the rest of the Kawa packages, and the standard 5453Java packages can be found by searching CLASSPATH. *Note Running Java::. 5454 5455 Then you do: 5456 java kawa.repl 5457 5458 In either case, you will then get the ‘#|kawa:1|#’ prompt, which 5459means you are in the Kawa read-eval-print-loop. If you type a Scheme 5460expression, Kawa will evaluate it. Kawa will then print the result (if 5461there is a non-"void" result). 5462 5463* Menu: 5464 5465* Options:: Command-line arguments 5466* Scripts:: Running Command Scripts 5467* REPL Console:: The REPL (read-eval-print-loop) console 5468* Exiting:: Exiting Kawa 5469* Compiling:: Compiling to byte-code 5470 5471 5472File: kawa.info, Node: Options, Next: Scripts, Prev: Running, Up: Running 5473 54746.1 Command-line arguments 5475========================== 5476 5477You can pass various flags to Kawa, for example: 5478 kawa -e '(display (+ 12 4))(newline)' 5479 or: 5480 java kawa.repl -e '(display (+ 12 4))(newline)' 5481 Either causes Kawa to print ‘16’, and then exit. 5482 5483 At startup, Kawa executes an init file from the user’s home 5484directory. The init file is named ‘.kawarc.scm’ on Unix-like systems 5485(those for which the file separator is ‘'/'’), and ‘kawarc.scm’ on other 5486systems. This is done before the read-eval-print loop or before the 5487first ‘-f’ or ‘-c’ argument. (It is not run for a ‘-e’ command, to 5488allow you to set options to override the defaults.) 5489 54906.1.1 Argument processing 5491------------------------- 5492 5493Kawa processes the command-line arguments in order. Options (which 5494either start with ‘-’ or contain a ‘=’) may “use up” one or more command 5495arguments. Some of the options (‘-c’, ‘-e’, ‘-f’, ‘-s’, ‘-C’, ‘-w’, 5496‘--’, ‘--browse-manual’) are “action options”; others set various 5497properties. 5498 5499 When all the command-line arguments have been “used up” and if no 5500action options have been seen, then Kawa enters an interactive 5501read-eval-print loop. (If an action option has been seen, we’re done.) 5502 5503 If the next command-line argument is not an option (does not start 5504with ‘-’ nor contains a ‘=’) then we’re done if we’ve seen an action 5505option (and the last action option wasn’t preceded by 5506‘--with-arg-count’). (Presumably any remaining arguments were 5507command-line-arguments used by the action option.) 5508 5509 Otherwise, the first remaining argument names either a file that is 5510read and evaluated, or a compiled class. In the former case, the whole 5511file is read and compiled as a module before being loaded (unlike the 5512‘-f’ flag which reads and evaluates the file command by command.) If 5513the argument is the fully-qualified name of a class, then the class is 5514loaded, an instance allocated, and its ‘run’ method invoked. If the 5515class was compiled from a Kawa Scheme module, then invoking ‘run’ has 5516the effect of evaluating the module body. The ‘command-line-arguments’ 5517vector is set to any remaining arguments after the file/class name. 5518(This can be overridden with the ‘--with-arg-count’ option. 5519Command-line processing continues if there are any further arguments.) 5520 55216.1.2 General options 5522--------------------- 5523 5524‘-e EXPR’ 5525 Kawa evaluates EXPR, which contains one or more Scheme expressions. 5526 Does not cause the ‘~/.kawarc.scm’ init file to be run. 5527‘-c EXPR’ 5528 Same as ‘-e EXPR’, except that it does cause the ‘~/.kawarc.scm’ 5529 init file to be run. 5530‘-f FILENAME-OR-URL’ 5531 Kawa reads and evaluates expressions from the file named by 5532 FILENAME-OR-URL. If the latter is ‘-’, standard input is read 5533 (with no prompting). Otherwise, it is equivalent to evaluating 5534 ‘(load "FILENAME-OR-URL")’. The FILENAME-OR-URL is interpreted as 5535 a URL if it is absolute - it starts with a "URI scheme" like 5536 ‘http:’. 5537‘-s’ 5538‘--’ 5539 The remaining arguments (if any) are passed to 5540 ‘command-line-arguments’ and (the ‘cdr’ of) ‘(command-line’), and 5541 an interactive read-eval-print loop is started. This uses the same 5542 "console" as where you started up Kawa; use ‘-w’ to get a new 5543 window. 5544‘--script FILENAME-OR-URL’ 5545‘--scriptN FILENAME-OR-URL’ 5546 The global variable ‘command-line-arguments’ is set to the 5547 remaining arguments (if any). Kawa reads and evaluates expressions 5548 from the file named by FILENAME-OR-URL. If ‘script’ is followed by 5549 an integer N, then N lines are skipped first. 5550 5551 Skipping some initial lines is useful if you want to have a 5552 non-Kawa preamble before the actual Kawa code. One use for this is 5553 for Kawa shell scripts (*note Scripts::). 5554 5555‘-w’ 5556‘-wSUB-OPTION’ 5557 Creates a new top-level window, and runs an interactive 5558 read-eval-print in the new window. See *note New-Window::. Same 5559 as ‘-e (scheme-window #t)’. You can specify multiple ‘-w’ options, 5560 and also use ‘-s’. 5561‘--help’ 5562 Prints out some help. 5563‘--version’ 5564 Prints out the Kawa version number, and then exits. 5565 5566 If Kawa was built with a ‘.git’ repository present, also prints the 5567 result of ‘git describe’. 5568‘--browse-manual’ 5569‘--browse-manual=COMMAND’ 5570 Browse a local copy of the documentation (this manual). 5571 5572 This creates a mini web-server that reads from 5573 ‘doc/kawa-manual.epub’, which is included in the binary 5574 distributions, but not built by default from source. 5575 5576 If no COMMAND is specified, creates a new mini-browser-window using 5577 JavaFX (if the JavaFX modules are available), or creates a new 5578 window or tab in your default web browser (otherwise). If COMMAND 5579 is a string containing ‘%U’, then Kawa replaces ‘%U’ with a URL 5580 that references itself, and then executes the resulting command. 5581 If COMMAND does not contain ‘%U’, then COMMAND becomes COMMAND‘" 5582 %U"’. For example to use the Firefox browser to browse the manual 5583 do either of: 5584 kawa --browse-manual=firefox 5585 kawa --browse-manual="firefox %U" 5586 5587‘--server PORTNUM’ 5588 Start a server listening from connections on the specified PORTNUM. 5589 Each connection using the Telnet protocol causes a new 5590 read-eval-print-loop to start. This option allows you to connect 5591 using any Telnet client program to a remote "Kawa server". 5592‘--with-arg-count=ARGC’ 5593 This option is used before an action option (such as ‘-f’). The 5594 ARGC arguments after the action become the value of the 5595 ‘command-line-arguments’ during the action. When the action is 5596 finished, command-line-processing resumes after skipping the ARGC 5597 arguments. 5598 5599 For example: 5600 $ kawa -f a.scm -f b.scm x y 5601 When evaluating ‘a.scm’ the ‘command-line-arguments’ by default is 5602 _all_ the remaining arguments: ‘["-f" "b.scm" "x" "y"]’. Then 5603 ‘b.scm’ is evaluated with ‘command-line-arguments’ set to ‘["x" 5604 "y"]’ 5605 5606 $ kawa --with-arg-count=0 -f a.scm -f b.scm x y 5607 In this case ‘a.scm’ is evaluated with ‘command-line-arguments’ set 5608 to the empty vector ‘[]’, and then ‘b.scm’ is evaluated with 5609 ‘command-line-arguments’ set to ‘["x" "y"]’ 5610 5611 $ kawa --with-arg-count=4 -f a.scm -f b.scm x y 5612 In this case ‘a.scm’ is evaluated with ‘command-line-arguments’ set 5613 to ‘["-f" "b.scm" "x" "y"]’. Since command-line processing skips 5614 the arguments specified by ‘--with-arg-count=4’, in this case 5615 ‘b.scm’ is not evaluated. 5616 56176.1.3 Options for language selection 5618------------------------------------ 5619 5620‘--scheme’ 5621 Set the default language to Scheme. (This is the default unless 5622 you select another language, or you name a file with a known 5623 extension on the command-line.) 5624‘--r5rs’ 5625‘--r6rs’ 5626‘--r7rs’ 5627 Provide better compatibility with the specified Scheme standards. 5628 (This is a work-in-progress.) For example ‘--r6rs’ aims to disable 5629 Kawa extensions that conflict with R6RS. It does not aim to disable 5630 all extensions, only incompatible extensions. These extensions 5631 disable the colon operator and keyword literals, as well as the use 5632 of initial ‘@’ as a splicing operator. The “‘l’” exponent suffix 5633 of a number literal creates a floating-point double, rather than a 5634 ‘BigInteger’. Selecting ‘--r5rs’ makes symbols by default 5635 case-insensitive. 5636‘--elisp’ 5637‘--emacs’ 5638‘--emacs-lisp’ 5639 Set the default language to Emacs Lisp. (The implementation is 5640 quite incomplete.) 5641‘--lisp’ 5642‘--clisp’ 5643‘--clisp’ 5644‘--commonlisp’ 5645‘--common-lisp’ 5646 Set the default language to CommonLisp. (The implementation is 5647 _very_ incomplete.) 5648‘--krl’ 5649 Set the default language to KRL. See *note KRL::. 5650‘--brl’ 5651 Set the default language to KRL, in BRL-compatibility mode. See 5652 *note KRL::. 5653‘--xquery’ 5654 Set the default language to the draft XML Query language. See the 5655 Kawa-XQuery page (http://www.gnu.org/software/qexo/) for more 5656 information. 5657‘--xslt’ 5658 Set the default language to XSLT (XML Stylesheet Language 5659 Transformations). (The implementation is _very_ incomplete.) See 5660 the Kawa-XSLT page (http://www.gnu.org/software/qexo/xslt.html) for 5661 more information. 5662‘--pedantic’ 5663 Try to follow the approprate language specification to the letter, 5664 even in corner cases, and even if it means giving up some Kawa 5665 convenience features. This flag so far only affects the XQuery 5666 parser, but that will hopefully change. 5667 56686.1.4 Options for warnings and errors 5669------------------------------------- 5670 5671‘--warn-undefined-variable’ 5672 Emit a warning if the code references a variable which is neither 5673 in lexical scope nor in the compile-time dynamic (global) 5674 environment. This is useful for catching typos. (A 5675 ‘define-variable’ form can be used to silence warnings. It 5676 declares to the compiler that a variable is to be resolved 5677 dynamically.) This defaults to on; to turn it off use the 5678 ‘--no-warn-undefined-variable’ flag. 5679‘--warn-unknown-member’ 5680 Emit a warning if the code references a named member (field or 5681 method) for which there is no match in the compile-time type of the 5682 receiver. This defaults to on; to turn it off use the 5683 ‘--no-warn-unknown-member’ flag. 5684‘--warn-invoke-unknown-method’ 5685 Emit a warning if the ‘invoke’ function calls a named method for 5686 which there is no matching method in the compile-time type of the 5687 receiver. This defaults to the value of ‘--warn-unknown-member’, 5688 to turn it off use the ‘--no-warn-invoke-unknown-method’ flag. 5689‘--warn-unused’ 5690 Emit a warning if a variable is unused or code never executed. 5691 This defaults to on; to turn it off use the ‘--no-warn-unused’ 5692 flag. 5693‘--warn-uninitialized’ 5694 Warn if accessing an uninitialized variable. This defaults to on; 5695 to turn it off use the ‘--no-warn-uninitialized’ flag. 5696‘--warn-unreachable’ 5697 Emit a warning if the code can never be executed. This defaults to 5698 on; to turn it off use the ‘--no-warn-unreachable’ flag. 5699‘--warn-void-used’ 5700 Emit a warning if an expression depends on an expression that is 5701 void (always has zero values), including call to ‘void’ functions 5702 and method. Also warn if an expression depends on a conditional 5703 (‘if’) that has no “else” clause. Examples include using the value 5704 of ‘set-car!’ as an argument to a function, or to initialize a 5705 variable. This defaults to on; to turn it off use the 5706 ‘--no-warn-void-used’ flag. 5707‘--warn-as-error’ 5708 Treat a compilation warning as if it were an error and halt 5709 compilation. 5710‘--max-errors=VALUE’ 5711 Print no more than VALUE errors or warnings (at a time). The value 5712 ‘-1’ removes the limit. The initial default is 20. (A single 5713 error may so confuse Kawa that it prints very many useless error 5714 messages.) 5715 5716 An option can be followed by a value, as in 5717‘--warn-invoke-unknown-method=no’. For boolean options, the values 5718‘yes’, ‘true’, ‘on’, or ‘1’ enable the option, while ‘no’, ‘false’, 5719‘off’, or ‘0’ disable it. You can also negate an option by prefixing it 5720with ‘no-’: The option ‘--no-warn-unknown-member’ is the same as 5721‘--warn-unknown-member=no’. 5722 5723 These options can also be used in the module source, using 5724‘module-compile-options’ or ‘with-compile-options’. (In that case they 5725override the options on the command line.) 5726 57276.1.5 Options for setting variables 5728----------------------------------- 5729 5730‘NAME=VALUE’ 5731 Set the global variable with the specified NAME to the given VALUE. 5732 The type of the VALUE is currently unspecified; the plan is for it 5733 to be like XQuery’s “untyped atomic” which can be coerced as 5734 needed. 5735‘{NAMESPACE-URI}LOCAL-NAME=VALUE’ 5736 Set the global variable with the specified namespace uri and 5737 namespace-local name to the given value. 5738 5739 These options are processed when invoking the ‘kawa’ application 5740(i.e. the ‘kawa.repl’ application). If you want a Kawa application 5741compiled with ‘--main’ to process these these assignments, call the 5742‘process-command-line-assignments’ utility function. 5743 5744‘-DVARIABLE-NAME=VARIABLE-VALUE’ 5745 Sets the JVM property VARIABLE-NAME to VARIABLE-VALUE, using the 5746 ‘setProperty’ method of ‘java.lang.System’. 5747 57486.1.6 Options for the REPL console 5749---------------------------------- 5750 5751‘--console’ 5752‘--no-console’ 5753 Usually Kawa can detect when the standard input port is a “console” 5754 or “terminal”, but these are useful for overriding that detection. 5755 The ‘--console’ flag is useful when the standard input is a pipe, 5756 but you want to direct Kawa to treat it as an interactive terminal. 5757 The ‘--no-console’ flag was useful for older pre-Java-6 5758 implementations that did not have the ‘java.lang.Console’ class. 5759‘console:type=’CONSOLE-TYPES 5760‘console:use-jline=’[‘yes’|‘no’] 5761‘console:jline-mouse=’[‘yes’|‘no’] 5762 See the *note REPL Console:: section. 5763‘console:prompt1=PROMPT1’ 5764‘console:prompt2=PROMPT2’ 5765 Initialize *note ‘input-prompt1’ and ‘input-prompt2’: 5766 input-prompt1, respectively. 5767 See also the ‘--output-format’ flag. 5768 57696.1.7 Options for controlling output formatting 5770----------------------------------------------- 5771 5772‘--output-format FORMAT’ 5773‘--format FORMAT’ 5774 Change the default output format to that specified by FORMAT. See 5775 *note Named output formats:: for more information and a list. 5776 5777‘out:base=INTEGER’ 5778 The number base (radix) to use by default when printing rational 5779 numbers. Must be an integer between 2 and 36, and the default is 5780 of course 10. For example the option ‘out:base=16’ produces 5781 hexadecimal output. Equivalent to setting the ‘*print-base*’ 5782 variable. 5783‘out:radix=no|yes’ 5784 If true, prints an indicator of the radix used when printing 5785 rational numbers. The default is ‘no’. Equivalent to setting the 5786 ‘*print-radix*’ variable. 5787‘out:doctype-system=SYSTEM-IDENTIFIER’ 5788 If ‘out:doctype-system’ is specified then a ‘DOCTYPE’ declaration 5789 is written before writing a top-level XML element, using the 5790 specified SYSTEM-IDENTIFIER. 5791‘out:doctype-public=PUBLIC-IDENTIFIER’ 5792 Ignored unless ‘out:doctype-system’ is also specified, in which 5793 case the PUBLIC-IDENTIFIER is written as the public identifiers of 5794 the ‘DOCTYPE’ declaration. 5795‘out:xml-indent=KIND’ 5796 Controls whether extra line breaks and indentation are added when 5797 printing XML. If KIND is ‘always’ or ‘yes’ then newlines and 5798 appropriate indentation are added before and after each element. 5799 If KIND is ‘pretty’ then the pretty-printer is used to only add new 5800 lines when an element otherwise won’t fit on a single line. If 5801 KIND is ‘no’ (the default) then no extra line breaks or indentation 5802 are added. 5803‘out:line-length=COLUMNS’ 5804‘out:right-margin=COLUMNS’ 5805 Specifies the maximum number of number of columns in a line when 5806 the pretty-printer decides where to break a line. (The two options 5807 are equivalent.) 5808 58096.1.8 Options for compiling and optimizing 5810------------------------------------------ 5811 5812‘--target VERSION’ 5813 The VERSION can be a JDK or Java specification version: ‘5’, ‘6’, 5814 or ‘7’. The JDK versions ‘1.5’ and ‘1.6’ are equivalent to ‘5’ or 5815 ‘6’, respectively. Specify a JVM (classfile) version to target. 5816 This is useful if (for example) you use Java 6, but want to create 5817 ‘.class’ files that can run on Java 5. In that case specify 5818 ‘--target 5’. 5819 5820 The following options control which calling conventions are used: 5821‘--full-tailcalls’ 5822 Use a calling convention that supports proper tail recursion. 5823‘--no-full-tailcalls’ 5824 Use a calling convention that does not support proper tail 5825 recursion. Self-tail-recursion (i.e. a recursive call to the 5826 current function) is still implemented correctly, assuming that the 5827 called function is known at compile time. 5828‘--no-inline’ 5829 Disable inlining of known functions and methods. The generated 5830 code runs slower, but you can more reliably trace procedures. 5831 Normally Kawa will assume that a procedure ‘fn’ declared using a 5832 ‘(define (fn args) body)’ form is constant, assuming it isn’t 5833 modified in the current module. However, it is possible some other 5834 module might modify the binding of ‘fn’. You can use the 5835 ‘--no-inline’ to disable the assumption that ‘fn’ is constant. 5836 5837 The default is currently ‘--no-full-tailcalls’ because it is usually 5838faster. It is also closer to the Java call model, so may be better for 5839people primarily interested in using Kawa for scripting Java systems. 5840 5841 Both calling conventions can co-exist: Code compiled with 5842‘--full-tailcalls’ can call code compiled with ‘--no-full-tailcalls’ and 5843vice versa. 5844 5845 These options can also be used in the module source, using 5846‘module-compile-options’ or ‘with-compile-options’. (In that case they 5847override the options on the command line.) 5848 5849 The options ‘-C’, ‘-d’, ‘-T’, ‘-P’, ‘--main’ ‘--applet’, and 5850‘--servlet’ are used to compile a Scheme file; see *note Files 5851compilation::. The options ‘--module-static’, ‘--module-nonstatic’, 5852‘--no-module-static’, and ‘--module-static-run’ control how a module is 5853mapped to a Java class; see *note static-or-non-modules::. The option 5854‘--connect PORTNUM’ is only used by the ‘kawa’ front-end program. 5855 58566.1.9 Options for debugging 5857--------------------------- 5858 5859The following options are useful if you want to debug or understand how 5860Kawa works. 5861‘--debug-dump-zip’ 5862 Normally, when Kawa loads a source file, or evaluates a non-trivial 5863 expression, it generates new internal Java classes but does not 5864 write them out. This option asks it to write out generated classes 5865 in a ‘.zip’ archive whose name has the prefix ‘kawa-zip-dump-’. 5866‘--debug-print-expr’ 5867 Kawa translates source language forms into an internal ‘Expression’ 5868 data structure. This option causes that data structure to be 5869 written out in a readable format to the standard output. 5870‘--debug-print-final-expr’ 5871 Similar to the previous option, but prints out the ‘Expression’ 5872 after various transformations and optimizations have been done, and 5873 just before code generation. 5874‘--debug-syntax-pattern-match’ 5875 Prints logging information to standard error when a ‘syntax-rules’ 5876 or ‘syntax-case’ pattern matches. 5877‘--debug-error-prints-stack-trace’ 5878 Prints a stack trace with any error found during compilation. 5879‘--debug-warning-prints-stack-trace’ 5880 Prints a stack trace with any warning found during compilation. 5881‘--langserver’ 5882 Starts Kawa in server mode, responding to requests using the 5883 Language Server Protocol (https://langserver.org). This is used by 5884 editors and IDEs for on-the-fly syntax checking and more. Highly 5885 experimental. 5886 58876.1.10 Options for web servers 5888------------------------------ 5889 5890JDK 6 (or later) includes a complete web server library. 5891 5892‘--http-auto-handler CONTEXT-PATH APPDIR’ 5893 Register a web application handler that uses files in the directory 5894 APPDIR to handle HTTP (web) requests containing the given 5895 CONTEXT-PATH. That is it handles requests that start with 5896 ‘http://localhost:PORTCONTEXT-PATH’. (This assumes the 5897 CONTEXT-PATH starts with a ‘/’.) *Note Self-configuring page 5898 scripts::. 5899‘--http-start PORT’ 5900 Start the web server, listing on the specified PORT. 5901 59026.1.11 Options for the JVM 5903-------------------------- 5904 5905The ‘kawa’ front-end can pass options to the ‘java’ launcher, using ‘-J’ 5906or ‘-D’ options. These must be given _before_ any other arguments. For 5907example: 5908 kawa -J-Xms48m -Dkawa.command.name=foo foo.scm 5909 is equivalent to (ignoring classpath issues): 5910 java -Xms48m -Dkawa.command.name=foo kawa.repl foo.scm 5911 You can also pass a ‘-D’ option (but not a ‘-J’ option) after the 5912class name, in which case it is processed by the Kawa command-line 5913processor rather than the ‘java’ launcher. The effect is normally the 5914same. 5915 5916‘-JJVM-OPTION’ 5917 Passes the JVM-OPTION to the ‘java’ command, before the class-name 5918 (‘kawa.repl’) and Kawa options. 5919‘-DVARIABLE-NAME=VARIABLE-VALUE’ 5920 Sets the JVM property VARIABLE-NAME to VARIABLE-VALUE. Equivalent 5921 to ‘-J-DVARIABLE-NAME=VARIABLE-VALUE’. 5922 5923 5924File: kawa.info, Node: Scripts, Next: REPL Console, Prev: Options, Up: Running 5925 59266.2 Running Command Scripts 5927=========================== 5928 5929If you write a Kawa application, it is convenient to be able to execute 5930it directly (from the command line or clicking an icon, say), without 5931have to explicitly run ‘kawa’ or ‘java’. On Unix-like systems the 5932easiest way to do this is to write a small shell script that runs your 5933Kawa application. 5934 5935 For modest-sized applications it is convenient if the shell script 5936and the Kawa code can be in the same file. Unix-like systems support a 5937mechanism where a “script” can specify a program that should execute it. 5938The convention is that the first line of the file should start with the 5939two characters ‘#!’ followed by the absolute path of the program that 5940should process (interpret) the script. 5941 5942 (Windows has “batch files”, which are similar.) 5943 5944 This convention works well for script languages that use ‘#’ to 5945indicate the start of a comment, since the interpreter will 5946automatically ignore the line specifying the interpreter filename. 5947Scheme, however, uses ‘#’ as a multi-purpose prefix, and Kawa 5948specifically uses ‘#!’ as a prefix for various *note Special named 5949constants:: such as ‘#!optional’. 5950 5951 Kawa does recognize the three-character sequence ‘#!/’ at the 5952beginning of a file as special, and ignores it. Here is an example: 5953 #!/usr/local/bin/kawa 5954 (format #t "The command-line was:~{ ~w~}~%" (command-line)) 5955 5956 If you copy this text to a file named ‘/home/me/bin/scm-echo’, set 5957the execute permission, and make sure it is in your ‘PATH’, then you can 5958execute it just by naming it on command line: 5959 $ chmod +x /home/me/bin/scm-echo 5960 $ PATH=/home/me/bin:$PATH 5961 $ scm-env a b 5962 The command-line was: "/home/me/bin/scm-echo" "a" "b" 5963 The system kernel will automatically execute ‘kawa’, passing it the 5964filename as an argument. 5965 5966 Note that the full path-name of the ‘kawa’ interpreter must be 5967hard-wired into the script. This means you may have to edit the script 5968depending on where Kawa is installed on your system. Another possible 5969problem is that the interpreter must be an actual program, not a shell 5970script. Depending on how you configure and install Kawa, ‘kawa’ can be 5971a real program or a script. You can avoid both problems by the ‘env’ 5972program, available on most modern Unix-like systems: 5973 5974 #!/usr/bin/env kawa 5975 (format #t "The command-line was:~{ ~w~}~%" (command-line)) 5976 5977 This works the same way, but assumes ‘kawa’ is in the command ‘PATH’. 5978 59796.2.1 Setting kawa options in the script 5980---------------------------------------- 5981 5982If you need to specify extra arguments to ‘kawa’, you can run arbitrary 5983shell command inside Scheme block comments. Here is an example: 5984 #!/bin/sh 5985 #| 5986 exec kawa out:base=16 out:radix=yes "$0" "$*" 5987 |# 5988 (format #t "The command-line is:~{ ~w~}.~%" (command-line)) 5989 (display "It has ") 5990 (display (apply + (map string-length (command-line)))) 5991 (display " characters.") 5992 (newline) 5993 5994 The trick is to hide the shell code from Kawa inside a ‘#|...|#’ 5995block-comment. The start of the block comment is a line starting with a 5996‘#’, so it is treated as a comment by the shell. You can then invoke 5997‘kawa’ (or ‘java’ directly) as you prefer, setting up class-path and 5998jars as needed, and passing whatever arguments you want. (The shell 5999replaces the ‘"$0"’ by the name of the script, and replaces the ‘"$@"’ 6000by the remaining arguments passed to the script.) You need to make sure 6001the shell finishes before it reaches the end of the block comment or the 6002Scheme code, which would confuse it. The example uses ‘exec’, which 6003tells the shell to _replace_ itself by KAWA; an alternative is to use 6004the shell ‘exit’ command. 6005 6006 If you copy the above file to ‘/tmp/sch-echo’ and make that file 6007executable, you can run it directly: 6008 $ /tmp/scm-echo "a b" "c d" 6009 The command-line is: "/tmp/scm-echo" "a b c d". 6010 It has #x14 characters. 6011 6012 When the Kawa reader sees the initial ‘#/’ it sets the command name 6013to the file name, so it can be used by a future call to 6014‘(command-name)’. If you want to override this you can use the 6015‘-Dkawa.command.name=NAME’ option. 6016 6017 Using comments this way has the advantage that you have the option of 6018running the script “manually” if you prefer: 6019 $ kawa /tmp/scm-echo out:base=8 "x y" 6020 The command-line is: "/tmp/scm-echo" "out:base=8" "x y". 6021 It has 26 characters. 6022 60236.2.2 Other ways to pass options using meta-arg or –script 6024---------------------------------------------------------- 6025 6026An argument consisting of just a ‘\’ (backslash) causes Kawa to read the 6027_second_ line looking for options. (Quotes and backslashes work like in 6028the shell.) These replace the backslash in the command line. 6029 6030 This is a less verbose mechanism, but it requires an absolute path to 6031‘kawa’, due to shell limitations. 6032 6033 #!/usr/bin/kawa \ 6034 --scheme --full-tailcalls 6035 (format #t "The command-line is:~{ ~w~}.~%" (command-line)) 6036 6037 In this case the effective command line received by Kawa will be 6038‘--scheme’, ‘--full-tailcalls’, followed by the script filename, 6039followed by other arguments specified when running the script. 6040 6041 The backslash used this way originated in scsh (http://www.scsh.net) 6042where it is called the “meta-arg”. (Unlike scsh, Kawa’s ‘#!’ is not a 6043block comment, but a rest-of-line, though the backslash causes the 6044following line to also be skipped.) 6045 6046 An alternative method is to use the ‘--script2’ option, which tells 6047Kawa to execute the script after ignoring the initial two lines. For 6048example: 6049 6050 #!/bin/sh 6051 exec kawa --commonlisp out:base=16 --script2 "$0" "$@" 6052 (setq xx 20) (display xx) (newline) 6053 6054 This is slightly more compact than using block-comments as shown 6055earlier, but it has the disadvantage that you can’t explicitly use 6056‘kawa’ or ‘java’ to run the script unless you make sure to pass it the 6057‘--script2’ option. 6058 60596.2.3 Scripts for compiled code 6060------------------------------- 6061 6062If you compile your Kawa application to class files (or better: a ‘jar’ 6063file), you probably still want to write a small shell script to set 6064things up. Here is one method: 6065 6066 #!/bin/sh 6067 export CLASSPATH=/my/path 6068 exec kawa -Dkawa.command.name="$0" foo "$@" 6069 6070 Using the ‘kawa’ front-end is a convenience, since it automatically 6071sets up the paths for the Kawa classes, and (if enabled) it provides 6072readline support for the default input port. 6073 6074 Setting the ‘kawa.command.name’ property to ‘"$0"’ (the filename used 6075to invoke the script) enables ‘(command-line’) to use the script name as 6076the command name. 6077 6078 You can invoke ‘java’ directly, which is necessary when running a 6079‘jar’ file: 6080 6081 #!/bin/sh 6082 exec java -cp /path/to/kawa -Dkawa.command.name="$0" foo.jar "$@" 6083 6084 6085File: kawa.info, Node: REPL Console, Next: Exiting, Prev: Scripts, Up: Running 6086 60876.3 The REPL (read-eval-print-loop) console 6088=========================================== 6089 6090The read-eval-print-loop (REPL) console is a convenient way to do simple 6091programming, test out things, and experiment. As the name implies, the 6092REPL repeatedly (in a loop) prints out a prompt, reads an input command, 6093evaluates it, then prints the result. 6094 6095 The REPL is started when you invoke the ‘kawa’ command with no 6096arguments. For example: 6097 6098 $ kawa 6099 #|kawa:1|# (define pi (* 2 (asin 1))) 6100 #|kawa:2|# (list pi (sqrt pi)) 6101 (3.141592653589793 1.7724538509055159) 6102 #|kawa:3|# 6103 6104 The colors and styles used for the prompt and the user input depend 6105on user preference and the capabilities of the console device. (If you 6106read this on a color screen you should see pale green for the prompt and 6107pale yellow for the user input; this matches the defaults for the 6108DomTerm console.) 6109 6110 You can *note change the prompt string: Prompts. if you want. The 6111default format depends on the (programming) language used; the one shown 6112above is used for Scheme. It has the form of a comment, which can be 6113convenient for copying and pasting lines. 6114 6115 You can *note change the output formatting: Named output formats. 6116with the ‘--output-format’ command-line option. 6117 6118 The basic console has few frills, but should work in any enviroment 6119where you have a console or terminal. It has no dependencies, except 6120the kawa ‘.jar’ file (and Java): 6121 $ java kawa-3.1.1.jar 6122 #|kawa:2|# 6123 6124 On rare occason you may need to specify the ‘--console’ flag. 6125 61266.3.1 Input line editing and history 6127------------------------------------ 6128 6129When typing a command in a console it is helpful to go back and correct 6130mistakes, repeat and edit previous commands, and so on. How well you 6131can do this varies a lot depending on which tools you use. Kawa 6132delegates input editing to an external tool. The recommended and 6133default input-editing tool is the JLine3 library 6134(https://github.com/jline/jline3), which is bundled with the Kawa binary 6135distribution. 6136 6137 JLine3 handles the normal editing comands, including arrow keys for 6138moving around in the input, and deleting with backspace or delete. In 6139general, JLine3 uses the same keybindings as GNU readline, which are 6140based on Emacs key-bindings. 6141 6142 You can use the up-arrow to move to previous commands in the input 6143history and down-arrow to go forwards. Control-R (“reverse search” 6144searches backwards in the history for a previous command that contains 6145the search string. 6146 6147 Multi-line commands are treated as a unit by JLine3: If Kawa 6148determines that input is “incomplete” it will ask for continuation lines 6149- and you can go back and edit previous lines in the same command. You 6150can explicitly create a multi-line command with Escape-Space. An entry 6151in the command history may be multiple lines. 6152 6153 Tab-completion works for Kawa-Scheme identifiers: If you type TAB 6154after an identifier, Kawa will present a list of possible completions. 6155 6156 There are multiple alternatives to using JLine3. You can use GNU 6157readline (if you configured with ‘--enable-kawa-frontend’). You can use 6158a front-end program like ‘rlfe’ or ‘fep’. You can use Emacs shell or 6159scheme mode. You can also use DomTerm in line-edit mode, where the 6160browser handles the editing. 6161 6162‘console:use-jline=’[‘yes’|‘no’] 6163 Disable (with ‘no’) or enable (with ‘yes’, which is the default) 6164 input line editing with JLine. 6165‘console:console:jline-mouse=’[‘yes’|‘no’] 6166 Enable (with ‘yes’) mouse click reporting from most xterm-like 6167 terminals to JLine, which means you can move the input cursor with 6168 the mouse. This is disabled by default because it conflicts with 6169 other useful mouse actions (text selection using drag; 6170 middle-button paste; right-button context menu; and wheel mouse 6171 scrolling). If you enable mouse-reporting, on most terminals you 6172 can get the standard behavior when pressing the shift key. E.g. 6173 to enable selection, drag with the shift key pressed. (However, 6174 mouse-wheel scrolling may not work even with shift pressed.) 6175 61766.3.2 Running a Command Interpreter in a new Window 6177--------------------------------------------------- 6178 6179Instead of using an existing terminal window for Kawa’s REPL console, 6180you can request a new window. The command-line options ‘-w’ creates a 6181new window. Kawa also creates a new window when it needs to create a 6182REPL (for example if invoked with no options) and it is not running in a 6183console. 6184 6185 You have a number of options for how the window appears and what it 6186supports, controlled by text following ‘-w’. All except ‘-wswing’ (and 6187‘-wconsole’) use DomTerm, so they depend on some kind of web browser 6188technology. All except ‘-wswing’ by default use JLine3 input editing, 6189if available. 6190 6191‘-w’ 6192 Pick the default/preferred console implementation. You can specify 6193 your preference with the ‘console:type=’ option, which is followed 6194 by one of the options below (without the ‘"-w"’ prefix), It can 6195 also be list of options separated by semi-colons, in which case 6196 they are tried in order. 6197 6198 The current default (it may change) is as if you specified: 6199 console:type="google-chrome;browser;javafx;swing;console" 6200 6201‘-wbrowser’ 6202 Creates a Kawa window or tab in your preferred desktop browser. 6203 Kawa starts a builtin HTTP and WebSocket server to communicate with 6204 the browser. 6205‘-wbrowser=COMMAND’ 6206 Uses COMMAND to display the Kawa REPL. The COMMAND should include 6207 the pattern ‘%U’, which Kawa replaces with a URL that it listens 6208 to. (Alternatively, it can use the pattern ‘%W’, which Kawa 6209 replaces with the port number of its WebSocket server. However, 6210 this feature may be removed.) If the is no ‘%’ in the COMMAND, 6211 Kawa add ‘" %U"’. Thus ‘-wbrowser=firefox’ is the same as 6212 ‘-wbrowser="firefox %U"’. 6213‘-wgoogle-chrome’ 6214 Creates a new Google Chrome window in “app mode” - i.e. with no 6215 location or menu bar. This is the same as 6216 ‘-wbrowser="google-chrome --app=%U"’. 6217‘-wjavafx’ 6218 Creates a new window using JavaFX WebView, which runs in the same 6219 JVM as Kawa. While this doesn’t currently have much in the way of 6220 Kawa-specific menus or other features, it has the most potential 6221 for adding them in the future. However, it does require JavaFX, 6222 which is not always available, and which does not see a lot of love 6223 from Oracle. (It uses an old version of WebKit.) 6224‘-wswing’ 6225 Create a console using the Swing toolkit. This is the old 6226 implementation of ‘-w’. It is deprecated because it only supports 6227 the builtin Swing line editing. (I.e. neither DomTerm or JLine3 6228 features are available, though “printing” *note pictures: 6229 Composable pictures. does work.) 6230‘-wserve’ 6231‘-wserve=’PORT 6232 Starts up an HTTP server (along with a WebSocket server), but does 6233 not automatically create any browser windows. Instead you can use 6234 any modern browser to load ‘http://localhost:PORT/’. If PORT is 6235 not specified, the systems selects it (and prints it out). 6236‘-wconsole’ 6237 Same as ‘"--"’ - i.e. it uses the existing console. 6238‘console:type=’PREFERENCE-LIST 6239 Specify the behavior of plain ‘-w’. 6240 62416.3.3 Using DomTerm 6242------------------- 6243 6244DomTerm (http://domterm.org) is a family of terminal emulators that use 6245the DomTerm JavaScript library. 6246 6247 You can either have Kawa start DomTerm: 6248 $ kawa OPTIONS -w 6249 or start a DomTerm terminal emulator and have it start Kawa: 6250 $ domterm kawa OPTIONS -- 6251 (You can also start a shell in a ‘domterm’ window, and then start 6252‘kawa’.) 6253 6254 Either approach works and both give you the benefits of DomTerm: 6255 • A xterm/ansi-compatible terminal emulator, which means you can use 6256 (for example) JLine3 for input editing. 6257 • You can “print” images, *note pictures: Composable pictures, or 6258 HTML elements. 6259 • Pretty-printing is handled by the terminal, which means 6260 line-breaking is re-computed when window width changes. 6261 • Hide/show buttons allow you to temporarily hide/unhide the output 6262 from a specific command. 6263 • You can save a session as an HTML file, which can be viewed later. 6264 (Still with dynamic line-breaking and pretty-printing, as well as 6265 working hide/show buttons.) The file is actually XHTML, so it can 6266 be processed with XML-reading tools. 6267 • Distinct styles for prompts, input, error output and regular 6268 output, which can be customized with CSS. 6269 6270 For now it is recommended to use both DomTerm and JLine3. 6271 6272 -- Procedure: domterm-load-stylesheet stylesheet [name] 6273 The string STYLESHEET should be a literal CSS stylesheet which is 6274 downloaded into the current DomTerm console. The new stylesheet is 6275 given the attribute ‘name=NAME’, where NAME defaults to ‘"Kawa"’. 6276 If there is an existing stylesheey whose ‘name’ attribute is NAME, 6277 it is replaced. In this example we change the background color to 6278 light gray: 6279 (domterm-load-stylesheet "div.domterm { background-color: lightgray}") 6280 6281 6282File: kawa.info, Node: Exiting, Next: Compiling, Prev: REPL Console, Up: Running 6283 62846.4 Exiting Kawa 6285================ 6286 6287Kawa normally keeps running as long as there is an active 6288read-eval-print loop still awaiting input or there is an unfinished 6289other computation (such as requested by a ‘-e’ or ‘-f’ option). 6290 6291 To close a read-eval-print-loop, you can type the special literal 6292‘#!eof’ at top level. This is recognized as end-of-file. Typing an 6293end-of-file character (normally ctrl-D under Unix) should also work, but 6294that depends on your operating system and terminal interface. 6295 6296 If the read-eval-print-loop is in a new window, you can select 6297‘Close’ from the ‘File’ menu. 6298 6299 To exit the entire Kawa session, call the *note ‘exit’ procedure: 6300Exiting the current process. (with 0 or 1 integer arguments). 6301 6302 6303File: kawa.info, Node: Compiling, Up: Running 6304 63056.5 Compiling to byte-code 6306========================== 6307 6308All Scheme functions and source files are invisibly compiled into 6309internal Java byte-codes. (A traditional interpreter is used for 6310macro-expansion. Kawa used to also interpret “simple” expressions in 6311interactive mode, but always compiling makes things more consistent, and 6312allows for better stack traces on errors.) 6313 6314 To save speed when loading large Scheme source files, you probably 6315want to pre-compile them and save them on your local disk. There are 6316two ways to do this. 6317 6318 You can compile a Scheme source file to a single archive file. You 6319do this using the ‘compile-file’ function. The result is a single file 6320that you can move around and ‘load’ just like the ‘.scm’ source file. 6321You just specify the name of the archive file to the ‘load’ procedure. 6322Currently, the archive is a "zip" archive and has extension ".zip"; a 6323future release will probably use "Java Archive" (jar) files. The 6324advantage of compiling to an archive is that it is simple and 6325transparent. 6326 6327 Alternatively, you can compile a Scheme source file to a collection 6328of ‘.class’ files. You then use the standard Java class loading 6329mechanism to load the code. The compiled class files do have to be 6330installed somewhere in the ‘CLASSPATH’. 6331 6332* Menu: 6333 6334* Files compilation:: Compiling to a set of .class files 6335* Archive compilation:: Compiling to an archive file 6336* Compiling using Ant:: 6337* Application compilation:: Compiling to a standalone application 6338* Applet compilation:: Compiling to an applet 6339* Compiling to executable:: Compiling to a native executable 6340 6341 6342File: kawa.info, Node: Files compilation, Next: Archive compilation, Up: Compiling 6343 63446.5.1 Compiling to a set of .class files 6345---------------------------------------- 6346 6347Invoking ‘kawa’ (or ‘java kawa.repl’) with the ‘-C’ flag will compile a 6348‘.scm’ source file into one or more ‘.class’ files: 6349 kawa --main -C myprog.scm 6350 6351 You run it as follows: 6352 kawa [-d OUTDIRECTORY] [-P PREFIX] [-T TOPNAME] [--main | --applet | --servlet] -C INFILE ... 6353 6354 Note the ‘-C’ must come last, because ‘Kawa’ processes the arguments 6355and options in order, 6356 6357 Here: 6358‘-C INFILE ...’ 6359 The Scheme source files we want to compile. 6360‘-d OUTDIRECTORY’ 6361 The directory under which the resulting ‘.class’ files will be. 6362 The default is the current directory. 6363‘-P PREFIX’ 6364 A string to prepend to the generated class names. The default is 6365 the empty string. 6366‘-T TOPNAME’ 6367 The name of the "top" class - i.e. the one that contains the code 6368 for the top-level expressions and definitions. The default is 6369 generated from the INFILE and PREFIX. 6370‘--main’ 6371 Generate a ‘main’ method so that the resulting "top" class can be 6372 used as a stand-alone application. *Note Application 6373 compilation::. 6374‘--applet’ 6375 The resulting class inherits from ‘java.applet.Applet’, and can be 6376 used as an applet. *Note Applet compilation::. 6377‘--servlet’ 6378 The resulting class implements ‘javax.servlet.http.HttpServlet’, 6379 and can be used as a servlet in a servlet container like Tomcat. 6380 6381 When you actually want to load the classes, the OUTDIRECTORY must be 6382in your ‘CLASSPATH’. You can use the ‘require’ syntax or the ‘load’ 6383function to load the code, by specifying the top-level class, either as 6384a file name (relative to OUTDIRECTORY) or as a class name. E.g. if you 6385did: 6386 kawa -d /usr/local/share/java -P my.lib. -T foo -C foosrc.scm 6387 you can use either: 6388 (require my.lib.foo) 6389 or: 6390 (load "my.lib.foo") 6391 Using ‘require’ is preferred as it imports the definitions from 6392‘my.lib.foo’ into the compile-time environment, while ‘load’ only 6393imports the definitions into the run-time environment. 6394 6395 If you are compiling a Scheme source file (say ‘foosrc.scm’) that 6396uses macros defined in some other file (say ‘macs.scm’), you need to 6397make sure the definitions are visible to the compiler. One way to do 6398that is with the ‘-f’: 6399 kawa -f macs.scm -C foosrc.scm 6400 6401 Many of the options *note described earlier: Options. are relevant 6402when compiling. Commonly used options include language selection, the 6403‘--warn-xxx’ options, and ‘--full-tailcalls’. 6404 6405 6406File: kawa.info, Node: Archive compilation, Next: Compiling using Ant, Prev: Files compilation, Up: Compiling 6407 64086.5.2 Compiling to an archive file 6409---------------------------------- 6410 6411 -- Procedure: compile-file source-file compiled-archive 6412 Compile the SOURCE-FILE, producing a ‘.zip’ archive COMPILED-FILE. 6413 6414 For example, to byte-compile a file ‘foo.scm’ do: 6415 (compile-file "foo.scm" "foo") 6416 6417 This will create ‘foo.zip’, which contains byte-compiled JVM 6418 ‘.class’ files. You can move this file around, without worrying 6419 about class paths. To load the compiled file, you can later ‘load’ 6420 the named file, as in either ‘(load "foo")’ or ‘(load "foo.zip")’. 6421 This should have the same effect as loading ‘foo.scm’, except you 6422 will get the faster byte-compiled versions. 6423 6424 6425File: kawa.info, Node: Compiling using Ant, Next: Application compilation, Prev: Archive compilation, Up: Compiling 6426 64276.5.3 Compiling using Ant 6428------------------------- 6429 6430Many Java projects use Ant (http://ant.apache.org) for building Java 6431projects. Kawa includes a ‘<kawac>’ Ant task that simplifies compiling 6432Kawa source files to classes. See the ‘build.xml’ in the Kawa source 6433distribution for examples. See the ‘kawac’ task documentation 6434(ant-kawac.html) for details. 6435 6436 6437File: kawa.info, Node: Application compilation, Next: Applet compilation, Prev: Compiling using Ant, Up: Compiling 6438 64396.5.4 Compiling to a standalone application 6440------------------------------------------- 6441 6442A Java application is a Java class with a special method (whose name is 6443‘main’). The application can be invoked directly by naming it in the 6444Java command. If you want to generate an application from a Scheme 6445program, create a Scheme source file with the definitions you need, plus 6446the top-level actions that you want the application to execute. 6447 6448 For example, assuming your Scheme file is ‘MyProgram.scm’, you have 6449two ways at your disposal to compile this Scheme program to a standalone 6450application: 6451 1. Compile in the regular way described in the previous section, but 6452 add the ‘--main’ option. 6453 kawa --main -C MyProgram.scm 6454 6455 The ‘--main’ option will compile all Scheme programs received in 6456 arguments to standalone applications. 6457 2. Compile in the regular way decribed in the previous section, but 6458 add the ‘main: #t’ module compile option to your module. 6459 ;; MyProgram.scm 6460 (module-name <myprogram>) 6461 (module-compile-options main: #t) 6462 6463 kawa -C MyProgram.scm 6464 6465 This way you can compile multiple Scheme programs at once, and 6466 still control which one(s) will compile to standalone 6467 application(s). 6468 6469 Both methods will create a ‘MyProgram.class’ which you can either 6470‘load’ (as described in the previous section), or invoke as an 6471application: 6472 java MyProgram [ARGS] 6473 Your Scheme program can access the command-line arguments ARGS by 6474using the global variable ‘command-line-arguments’, or the R6RS function 6475‘command-line’. 6476 6477 If there is no explicit ‘module-export’ in a module compiled with 6478‘--main’ then no names are exported. (The default otherwise is for all 6479names to be exported.) 6480 6481 6482File: kawa.info, Node: Applet compilation, Next: Compiling to executable, Prev: Application compilation, Up: Compiling 6483 64846.5.5 Compiling to an applet 6485---------------------------- 6486 6487An applet is a Java class that inherits from ‘java.applet.Applet’. The 6488applet can be downloaded and run in a Java-capable web-browser. To 6489generate an applet from a Scheme program, write the Scheme program with 6490appropriate definitions of the functions ‘init’, ‘start’, ‘stop’ and 6491‘destroy’. You must declare these as zero-argument functions with a 6492‘<void>’ return-type. 6493 6494 Here is an example, based on the scribble applet in Flanagan’s "Java 6495Examples in a Nutshell" (O’Reilly, 1997): 6496 (define-private last-x 0) 6497 (define-private last-y 0) 6498 6499 (define (init) :: void 6500 (let ((applet (this))) 6501 (applet:addMouseListener 6502 (object (java.awt.event.MouseAdapter) 6503 ((mousePressed e) 6504 (set! last-x (e:getX)) 6505 (set! last-y (e:getY))))) 6506 (applet:addMouseMotionListener 6507 (object (java.awt.event.MouseMotionAdapter) 6508 ((mouseDragged e) 6509 (let ((g (applet:getGraphics)) 6510 (x (e:getX)) 6511 (y (e:getY))) 6512 (g:drawLine last-x last-y x y) 6513 (set! last-x x) 6514 (set! last-y y))))))) 6515 6516 (define (start) :: void (format #t "called start.~%~!")) 6517 (define (stop) :: void (format #t "called stop.~%~!")) 6518 (define (destroy) :: void (format #t "called destroy.~%~!")) 6519 6520 You compile the program with the ‘--applet’ flag in addition to the 6521normal ‘-C’ flag: 6522 java kawa.repl --applet -C scribble.scm 6523 6524 You can then create a ‘.jar’ archive containing your applet: 6525 jar cf scribble.jar scribble*.class 6526 6527 Finally, you create an ‘.html’ page referencing your applet and its 6528support ‘jar’s: 6529 <html><head><title>Scribble testapp</title></head> 6530 <body><h1>Scribble testapp</h1> 6531 You can scribble here: 6532 <br> 6533 <applet code="scribble.class" archive="scribble.jar, kawa-3.1.1.jar" width=200 height=200> 6534 Sorry, Java is needed.</applet> 6535 </body></html> 6536 6537 The problem with using Kawa to write applets is that the Kawa ‘.jar’ 6538file is quite big, and may take a while to download over a network 6539connection. Some possible solutions: 6540 6541 • Try to strip out of the Kawa ‘.jar’ any classes your applet doesn’t 6542 need. 6543 • Java 2 provides a mechanism to install a download extension 6544 (http://java.sun.com/docs/books/tutorial/ext/basics/download.html). 6545 • Consider some alternative to applets, such as Java Web Start 6546 (http://java.sun.com/products/javawebstart/). 6547 6548 6549File: kawa.info, Node: Compiling to executable, Prev: Applet compilation, Up: Compiling 6550 65516.5.6 Compiling to a native executable 6552-------------------------------------- 6553 6554In the past it was possible to compile a Scheme program to native code 6555using GCJ. However, using GCJ with Kawa is no longer supported, as GCJ 6556is no longer being actively maintained. 6557 6558 6559File: kawa.info, Node: Syntax, Next: Program structure, Prev: Running, Up: Top 6560 65617 Syntax 6562******** 6563 6564* Menu: 6565 6566* Syntax notation:: 6567* Lexical and datum syntax:: 6568* Lexical syntax:: 6569* Datum syntax:: 6570* Hash-prefixed forms:: 6571* Primitive expression syntax:: 6572* Colon notation:: Property access using colon notation 6573* Bodies:: 6574* Syntax and conditional compilation:: 6575* Macros:: 6576* Named quasi-literals:: 6577 6578 6579File: kawa.info, Node: Syntax notation, Next: Lexical and datum syntax, Up: Syntax 6580 65817.1 Notation 6582============ 6583 6584The formal syntax for Kawa Scheme is written in an extended BNF. 6585Non–terminals are written LIKE-THIS. Case is insignificant for 6586non–terminal names. Literal text (terminals) are written ‘like this’. 6587 6588 All spaces in the grammar are for legibility. 6589 6590 The following extensions to BNF are used to make the description more 6591concise: THING^{*} or THING‘...’ both mean zero or more occurrences of 6592THING, and THING^{+} means at least one THING. 6593 6594 Some non-terminal names refer to the Unicode scalar values of the 6595same name: CHARACTER-TABULATION (U+0009), LINEFEED (U+000A), 6596CARRIAGE-RETURN (U+000D), LINE-TABULATION (U+000B), FORM-FEED (U+000C), 6597SPACE (U+0020), NEXT-LINE (U+0085), LINE-SEPARATOR (U+2028), and 6598PARAGRAPH-SEPARATOR (U+2029). 6599 6600 6601File: kawa.info, Node: Lexical and datum syntax, Next: Lexical syntax, Prev: Syntax notation, Up: Syntax 6602 66037.2 Lexical and datum syntax 6604============================ 6605 6606The syntax of Scheme code is organized in three levels: 6607 6608 1. the _lexical syntax_ that describes how a program text is split 6609 into a sequence of lexemes, 6610 6611 2. the _datum syntax_, formulated in terms of the lexical syntax, that 6612 structures the lexeme sequence as a sequence of _syntactic data_, 6613 where a syntactic datum is a recursively structured entity, 6614 6615 3. the _program syntax_ formulated in terms of the datum syntax, 6616 imposing further structure and assigning meaning to syntactic data. 6617 6618 Syntactic data (also called _external representations_) double as a 6619notation for objects, and the ‘read’ and ‘write’ procedures can be used 6620for reading and writing syntactic data, converting between their textual 6621representation and the corresponding objects. Each syntactic datum 6622represents a corresponding _datum value_. A syntactic datum can be used 6623in a program to obtain the corresponding datum value using ‘quote’. 6624 6625 Scheme source code consists of syntactic data and (non–significant) 6626comments. Syntactic data in Scheme source code are called _forms_. (A 6627form nested inside another form is called a _subform_.) Consequently, 6628Scheme’s syntax has the property that any sequence of characters that is 6629a form is also a syntactic datum representing some object. This can 6630lead to confusion, since it may not be obvious out of context whether a 6631given sequence of characters is intended to be a representation of 6632objects or the text of a program. It is also a source of power, since 6633it facilitates writing programs such as interpreters or compilers that 6634treat programs as objects (or vice versa). 6635 6636 A datum value may have several different external representations. 6637For example, both ‘#e28.000’ and ‘#x1c’ are syntactic data representing 6638the exact integer object 28, and the syntactic data ‘(8 13)’, ‘( 08 13 6639)’, ‘(8 . (13 . ()))’ all represent a list containing the exact integer 6640objects 8 and 13. Syntactic data that represent equal objects (in the 6641sense of ‘equal?’) are always equivalent as forms of a program. 6642 6643 Because of the close correspondence between syntactic data and datum 6644values, we sometimes uses the term _datum_ for either a syntactic datum 6645or a datum value when the exact meaning is apparent from the context. 6646 6647 6648File: kawa.info, Node: Lexical syntax, Next: Datum syntax, Prev: Lexical and datum syntax, Up: Syntax 6649 66507.3 Lexical syntax 6651================== 6652 6653The lexical syntax determines how a character sequence is split into a 6654sequence of lexemes, omitting non–significant portions such as comments 6655and whitespace. The character sequence is assumed to be text according 6656to the Unicode standard (http://unicode.org/). Some of the lexemes, 6657such as identifiers, representations of number objects, strings etc., of 6658the lexical syntax are syntactic data in the datum syntax, and thus 6659represent objects. Besides the formal account of the syntax, this 6660section also describes what datum values are represented by these 6661syntactic data. 6662 6663 The lexical syntax, in the description of comments, contains a 6664forward reference to DATUM, which is described as part of the datum 6665syntax. Being comments, however, these DATUMs do not play a significant 6666role in the syntax. 6667 6668 Case is significant except in representations of booleans, number 6669objects, and in hexadecimal numbers specifying Unicode scalar values. 6670For example, ‘#x1A’ and ‘#X1a’ are equivalent. The identifier ‘Foo’ is, 6671however, distinct from the identifier ‘FOO’. 6672 66737.3.1 Formal account 6674-------------------- 6675 6676INTERLEXEME-SPACE may occur on either side of any lexeme, but not within 6677a lexeme. 6678 6679 IDENTIFIERs, ‘.’, NUMBERs, CHARACTERs, and BOOLEANs, must be 6680terminated by a DELIMITER or by the end of the input. 6681 6682 LEXEME ::= IDENTIFIER | BOOLEAN | NUMBER 6683 | CHARACTER | STRING 6684 | ‘(’ | ‘)’ | ‘[’ | ‘]’ | ‘#(’ 6685 | ‘’’ | ‘‘’ | ‘,’ | ‘,@’ | ‘.’ 6686 | ‘#’’ | ‘#‘’ | ‘#,’ | ‘#,@’ 6687 DELIMITER ::= ‘(’ | ‘)’ | ‘[’ | ‘]’ | ‘"’ | ‘;’ | ‘#’ 6688 | WHITESPACE 6689 6690 ((UNFINISHED)) 6691 66927.3.2 Line endings 6693------------------ 6694 6695Line endings are significant in Scheme in single–line comments and 6696within string literals. In Scheme source code, any of the line endings 6697in LINE-ENDING marks the end of a line. Moreover, the two–character 6698line endings CARRIAGE-RETURN LINEFEED and CARRIAGE-RETURN NEXT-LINE each 6699count as a single line ending. 6700 6701 In a string literal, a LINE-ENDING not preceded by a ‘\’ stands for a 6702linefeed character, which is the standard line–ending character of 6703Scheme. 6704 67057.3.3 Whitespace and comments 6706----------------------------- 6707 6708 INTRALINE-WHITESPACE ::= SPACE | CHARACTER-TABULATION 6709 WHITESPACE ::= INTRALINE-WHITESPACE 6710 | LINEFEED | LINE-TABULATION | FORM-FEED 6711 | CARRIAGE-RETURN | NEXT-LINE 6712 | any character whose category is Zs, Zl, or Zp 6713 LINE-ENDING ::= LINEFEED | CARRIAGE RETURN 6714 | CARRIAGE-RETURN LINEFEED | NEXT-LINE 6715 | CARRIAGE-RETURN NEXT-LINE | LINE-SEPARATOR 6716 COMMENT ::= ‘;’ all subsequent characters up to a LINE-ENDING 6717 or PARAGRAPH-SEPARATOR 6718 | NESTED-COMMENT 6719 | ‘#;’ INTERLEXEME-SPACE DATUM 6720 | SHEBANG-COMMENT 6721 NESTED-COMMENT ::= ‘#|’ COMMENT-TEXT COMMENT-CONT* ‘|#’ 6722 COMMENT-TEXT ::= character sequence not containing ‘#|’ or ‘|#’ 6723 COMMENT-CONT ::= NESTED-COMMENT COMMENT-TEXT 6724 ATMOSPHERE ::= WHITESPACE | COMMENT 6725 INTERLEXEME-SPACE ::= ATMOSPHERE^{*} 6726 6727 As a special case the characters ‘#!/’ are treated as starting a 6728comment, but only at the beginning of file. These characters are used 6729on Unix systems as an Shebang interpreter directive 6730(http://en.wikipedia.org/wiki/Shebang_(Unix)). The Kawa reader skips 6731the entire line. If the last non-whitespace character is ‘\’ 6732(backslash) then the following line is also skipped, and so on. 6733 SHEBANG-COMMENT ::= ‘#!’ ABSOLUTE-FILENAME text up to non-escaped LINE-ENDING 6734 6735_Whitespace_ characters are spaces, linefeeds, carriage returns, 6736character tabulations, form feeds, line tabulations, and any other 6737character whose category is Zs, Zl, or Zp. Whitespace is used for 6738improved readability and as necessary to separate lexemes from each 6739other. Whitespace may occur between any two lexemes, but not within a 6740lexeme. Whitespace may also occur inside a string, where it is 6741significant. 6742 6743 The lexical syntax includes several comment forms. In all cases, 6744comments are invisible to Scheme, except that they act as delimiters, 6745so, for example, a comment cannot appear in the middle of an identifier 6746or representation of a number object. 6747 6748 A semicolon (‘;’) indicates the start of a line comment. The comment 6749continues to the end of the line on which the semicolon appears. 6750 6751 Another way to indicate a comment is to prefix a DATUM with ‘#;’, 6752possibly with INTERLEXEME-SPACE before the DATUM. The comment consists 6753of the comment prefix ‘#;’ and the DATUM together. This notation is 6754useful for “commenting out” sections of code. 6755 6756 Block comments may be indicated with properly nested ‘#|’ and ‘|#’ 6757pairs. 6758 #| 6759 The FACT procedure computes the factorial of a 6760 non-negative integer. 6761 |# 6762 (define fact 6763 (lambda (n) 6764 ;; base case 6765 (if (= n 0) 6766 #;(= n 1) 6767 1 ; identity of * 6768 (* n (fact (- n 1)))))) 6769 67707.3.4 Identifiers 6771----------------- 6772 6773 IDENTIFIER ::= INITIAL SUBSEQUENT* 6774 | PECULIAR-IDENTIFIER 6775 INITIAL ::= CONSTITUENT | SPECIAL-INITIAL 6776 | INLINE-HEX-ESCAPE 6777 LETTER ::= ‘a’ | ‘b’ | ‘c’ | ... | ‘z’ 6778 | ‘A’ | ‘B’ | ‘C’ | ... | ‘Z’ 6779 CONSTITUENT ::= LETTER 6780 | any character whose Unicode scalar value is greater than 6781 127, and whose category is Lu, Ll, Lt, Lm, Lo, Mn, 6782 Nl, No, Pd, Pc, Po, Sc, Sm, Sk, So, or Co 6783 SPECIAL-INITIAL ::= ‘!’ | ‘$’ | ‘%’ | ‘&’ | ‘*’ | ‘/’ | ‘<’ | ‘=’ 6784 | ‘>’ | ‘?’ | ‘^’ | ‘_’ | ‘~’ 6785 SUBSEQUENT ::= INITIAL | DIGIT 6786 | any character whose category is Nd, Mc, or Me 6787 | SPECIAL-SUBSEQUENT 6788 DIGIT ::= ‘0’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘5’ | ‘6’ | ‘7’ | ‘8’ | ‘9’ 6789 OCT-DIGIT ::= ‘0’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘5’ | ‘6’ | ‘7’ 6790 HEX-DIGIT ::= DIGIT 6791 | ‘a’ | ‘A’ | ‘b’ | ‘B’ | ‘c’ | ‘C’ | ‘d’ | ‘D’ | ‘e’ | ‘E’ | ‘f’ | ‘F’ 6792 SPECIAL-SUBSEQUENT ::= ‘+’ | ‘-’ | ‘.’ | ‘@’ 6793 ESCAPE-SEQUENCE ::= INLINE-HEX-ESCAPE 6794 | ‘\’CHARACTER-EXCEPT-X 6795 | MULTI-ESCAPE-SEQUENCE 6796 INLINE-HEX-ESCAPE ::= ‘\x’HEX-SCALAR-VALUE‘;’ 6797 HEX-SCALAR-VALUE ::= HEX-DIGIT+ 6798 MULTI-ESCAPE-SEQUENCE ::= ‘|’SYMBOL-ELEMENT^{*}‘|’ 6799 SYMBOL-ELEMENT ::= any character except ‘|’ or ‘\’ 6800 | INLINE-HEX-ESCAPE | MNEMONIC-ESCAPE | ‘\|’ 6801 6802 CHARACTER-EXCEPT-X ::= any character except ‘x’ 6803 PECULIAR-IDENTIFIER ::= ‘+’ | ‘-’ | ‘...’ | ‘->’ SUBSEQUENT^{*} 6804 6805 Most identifiers allowed by other programming languages are also 6806acceptable to Scheme. In general, a sequence of letters, digits, and 6807“extended alphabetic characters” is an identifier when it begins with a 6808character that cannot begin a representation of a number object. In 6809addition, ‘+’, ‘-’, and ‘...’ are identifiers, as is a sequence of 6810letters, digits, and extended alphabetic characters that begins with the 6811two–character sequence ‘->’. Here are some examples of identifiers: 6812 6813 lambda q soup 6814 list->vector + V17a 6815 <= a34kTMNs ->- 6816 the-word-recursion-has-many-meanings 6817 6818 Extended alphabetic characters may be used within identifiers as if 6819they were letters. The following are extended alphabetic characters: 6820 6821 ! $ % & * + - . / < = > ? @ ^ _ ~ 6822 6823 Moreover, all characters whose Unicode scalar values are greater than 6824127 and whose Unicode category is Lu, Ll, Lt, Lm, Lo, Mn, Mc, Me, Nd, 6825Nl, No, Pd, Pc, Po, Sc, Sm, Sk, So, or Co can be used within 6826identifiers. In addition, any character can be used within an 6827identifier when specified using an ESCAPE-SEQUENCE. For example, the 6828identifier ‘H\x65;llo’ is the same as the identifier ‘Hello’. 6829 6830 Kawa supports two additional non-R6RS ways of making identifiers 6831using special characters, both taken from Common Lisp: Any character 6832(except ‘x’) following a backslash is treated as if it were a LETTER; as 6833is any character between a pair of vertical bars. 6834 6835 Identifiers have two uses within Scheme programs: 6836 • Any identifier may be used as a *note variable: variable-reference. 6837 or as a *note syntactic keyword: macro-reference. 6838 • When an identifier appears as or with in *note literal: 6839 literal-expression, it is being used to denote a *note symbol: 6840 Simple symbols. 6841 6842 In contrast with older versions of Scheme, the syntax distinguishes 6843between upper and lower case in identifiers and in characters specified 6844via their names, but not in numbers, nor in inline hex escapes used in 6845the syntax of identifiers, characters, or strings. The following 6846directives give explicit control over case folding. 6847 6848 -- Syntax: #!fold-case 6849 -- Syntax: #!no-fold-case 6850 6851 These directives may appear anywhere comments are permitted and are 6852 treated as comments, except that they affect the reading of 6853 subsequent data. The ‘#!fold-case’ directive causes the ‘read’ 6854 procedure to case-fold (as if by ‘string-foldcase’) each identifier 6855 and character name subsequently read from the same port. The 6856 ‘#!no-fold-case’ directive causes the ‘read’ procedure to return to 6857 the default, non-folding behavior. 6858 6859 Note that colon ‘:’ is treated specially for *note colon notation: 6860Colon notation. in Kawa Scheme, though it is a SPECIAL-INITIAL in 6861standard Scheme (R6RS). 6862 68637.3.5 Numbers 6864------------- 6865 6866((INCOMPLETE)) 6867 6868 NUMBER ::= ((TODO)) 6869 | QUANTITY 6870 DECIMAL ::= DIGIT+ OPTIONAL-EXPONENT 6871 | ‘.’ DIGIT+ OPTIONAL-EXPONENT 6872 | DIGIT+ ‘.’ DIGIT+ OPTIONAL-EXPONENT 6873 6874 OPTIONAL-EXPONENT ::= empty 6875 | EXPONENT-MARKER OPTIONAL-SIGN DIGIT+ 6876 EXPONENT-MARKER ::= ‘e’ | ‘s’ | ‘f’ | ‘d’ | ‘l’ 6877 The letter used for the exponent in a floating-point literal 6878determines its type: 6879‘e’ 6880 Returns a ‘gnu.math.DFloat’ - for example ‘12e2’. Note this 6881 matches the default when there is no EXPONENT-MARKER. 6882‘s’ or ‘f’ 6883 Returns a primitive ‘float’ (or ‘java.lang.Float’ when boxed as an 6884 object) - for example ‘12s2’ or ‘12f2’. 6885‘d’ 6886 Returns a primitive ‘double’ (or ‘java.lang.Double’ when boxed) - 6887 for example ‘12d2’. 6888‘l’ 6889 Returns a ‘java.math.BigDecimal’ - for example ‘12l2’. 6890 OPTIONAL-SIGN ::= empty | ‘+’ | ‘-’ 6891 DIGIT-2 ::= ‘0’ | ‘1’ 6892 DIGIT-8 ::= ‘0’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘5’ | ‘6’ | ‘7’ 6893 DIGIT-10 ::= DIGIT 6894 DIGIT-16 ::= DIGIT-10 | ‘a’ | ‘b’ | ‘c’ | ‘d’ | ‘e’ | ‘f’ 6895 6896
