[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[7983] add js directory to hold work from mthl's GSOC project in 2017
|
From: |
gavinsmith0123 |
|
Subject: |
[7983] add js directory to hold work from mthl's GSOC project in 2017 |
|
Date: |
Thu, 9 Nov 2017 13:52:07 -0500 (EST) |
Revision: 7983
http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=7983
Author: gavin
Date: 2017-11-09 13:52:07 -0500 (Thu, 09 Nov 2017)
Log Message:
-----------
add js directory to hold work from mthl's GSOC project in 2017
Added Paths:
-----------
trunk/js/
trunk/js/.dir-locals.el
trunk/js/.gitignore
trunk/js/HACKING
trunk/js/Makefile.am
trunk/js/README
trunk/js/TODO
trunk/js/build-aux/
trunk/js/build-aux/eslint.json
trunk/js/build-aux/modernizr.json
trunk/js/configure.ac
trunk/js/examples/
trunk/js/examples/hello/
trunk/js/examples/hello/fdl.texi
trunk/js/examples/hello/hello.texi
trunk/js/examples/hello/version.texi
trunk/js/examples/kawa/
trunk/js/examples/kawa/images/
trunk/js/examples/kawa/images/border-1.png
trunk/js/examples/kawa/images/domterm-pictures-1.png
trunk/js/examples/kawa/images/fill-circ-1.png
trunk/js/examples/kawa/images/image-cat-1a.png
trunk/js/examples/kawa/images/image-cat-1b.png
trunk/js/examples/kawa/images/image-scaled-1.png
trunk/js/examples/kawa/images/padding-1.png
trunk/js/examples/kawa/images/paint-circ-1.png
trunk/js/examples/kawa/images/paint-circ-2.png
trunk/js/examples/kawa/images/paint-circ-3.png
trunk/js/examples/kawa/images/paint-circ-4.png
trunk/js/examples/kawa/images/polygon-1.png
trunk/js/examples/kawa/images/polyline-1.png
trunk/js/examples/kawa/images/re-center-1.png
trunk/js/examples/kawa/images/re-center-2.png
trunk/js/examples/kawa/images/show-draw-1.png
trunk/js/examples/kawa/images/show-draw-2.png
trunk/js/examples/kawa/images/show-draw-3.png
trunk/js/examples/kawa/kawa.texi
trunk/js/examples/kawa/news.texi
trunk/js/examples/kawa/version.texi
trunk/js/info.js
trunk/js/modernizr.js
trunk/js/package.json
trunk/js/server.js
trunk/js/style/
trunk/js/style/info.css
trunk/js/style/kawa.css
trunk/js/tsconfig.json
trunk/js/yarn.lock
Added: trunk/js/.dir-locals.el
===================================================================
--- trunk/js/.dir-locals.el (rev 0)
+++ trunk/js/.dir-locals.el 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,7 @@
+;;; Directory Local Variables
+;;; For more information see (info "(emacs) Directory Variables")
+
+((nil
+ (indent-tabs-mode))
+ (makefile-mode
+ (indent-tabs-mode . t)))
Added: trunk/js/.gitignore
===================================================================
--- trunk/js/.gitignore (rev 0)
+++ trunk/js/.gitignore 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,12 @@
+*.log
+/Makefile
+/Makefile.in
+/aclocal.m4
+/autom4te.cache/
+/build-aux/install-sh
+/build-aux/missing
+/config.status
+/configure
+/examples/hello-html/
+/examples/kawa-html/
+/node_modules/
Added: trunk/js/HACKING
===================================================================
--- trunk/js/HACKING (rev 0)
+++ trunk/js/HACKING 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,32 @@
+While the build process doesn't require any tool since the program is
+written as single script directly loadable in browsers, it is
+convenient for the developpers to have some of them to improve its
+coding experience and avoid them some headaches.
+
+Those tools consists of a linter (ESLint) and a type checker
+(TypeScript). They can be fetched with 'NPM' by running the 'npm
+install' command from the the source directory.
+
+To run the linter you can execute:
+
+ $ make lint
+
+To run the type check you can execute:
+
+ $ make check-types
+
+When modifying the 'info.js' source we recommend that you often run
+those commands.
+
+Additionaly the NPM install process provides 'modernizr' which can
+update the "modernizr.js" script which is used for ensuring the
+portability of "info.js" across browsers by doing features tests. The
+update can be done by executing:
+
+ $ make modernizr
+
+Finally 'Uglify-js' (which is provided by NPM too) is used to check
+the size of a minified version of the script. To do that you can
+execute:
+
+ $ make minify
Added: trunk/js/Makefile.am
===================================================================
--- trunk/js/Makefile.am (rev 0)
+++ trunk/js/Makefile.am 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,82 @@
+## Process this file with automake to produce Makefile.in
+# Copyright (C) 2017 Free Software Foundation, Inc.
+#
+# This file is part of GNU Texinfo.
+#
+# GNU Texinfo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# GNU Texinfo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNU Texinfo. If not, see <http://www.gnu.org/licenses/>.
+
+all: $(examples)
+
+phony =
+
+if HAVE_ESLINT
+phony += lint
+lint:
+ $(ESLINT) -c build-aux/eslint.json info.js -f unix
+endif
+
+if HAVE_TYPESCRIPT
+phony += check-types
+check-types:
+ $(TSC) --allowJs --checkJS --noEmit --lib dom,es2017 info.js
+endif
+
+if HAVE_UGLIFYJS
+phony += minify
+minify:
+ $(UGLIFYJS) info.js -o info.min.js --mangle --compress
+endif
+
+if HAVE_MODERNIZR
+phony += modernizr
+modernizr:
+ $(MODERNIZR) -c build-aux/modernizr.json
+endif
+
+.PHONY: $(phony)
+
+## ---------- ##
+## Examples. ##
+## ---------- ##
+
+examples = \
+ examples/hello-html \
+ examples/kawa-html
+
+# Javascript files that will be included in the html pages. The order
+# of those files is the order in which they will be included
+js_scripts = \
+ modernizr.js \
+ info.js
+
+hello_extra_head = '<link rel="stylesheet" type="text/css"
href="info.css"/><script src="modernizr.js"
type="text/javascript"></script><script src="info.js"
type="text/javascript"></script>'
+
+examples/hello-html: examples/hello/hello.texi
+ $(MAKEINFO) -I=$(srcdir) --html \
+ -c EXTRA_HEAD=$(hello_extra_head) \
+ examples/hello/hello.texi -o $@ && \
+ cp $(js_scripts) style/info.css $@
+
+kawa_extra_head = '<link rel="stylesheet" type="text/css"
href="info.css"/><link rel="stylesheet" type="text/css"
href="kawa.css"/><script src="modernizr.js"
type="text/javascript"></script><script src="info.js"
type="text/javascript"></script>'
+
+examples/kawa-html: examples/kawa/kawa.texi
+ $(MAKEINFO) -I=$(srcdir) --html \
+ -c EXTRA_HEAD=$(kawa_extra_head) \
+ examples/kawa/kawa.texi -o $@ && \
+ cp $(js_scripts) style/info.css style/kawa.css $@
+
+clean-local:
+ rm -rf $(examples)
+
+.PHONY: $(examples)
Added: trunk/js/README
===================================================================
--- trunk/js/README (rev 0)
+++ trunk/js/README 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,16 @@
+To build the provided examples you need to have 'makeinfo' installed
+on your system. 'makeinfo' is provided by GNU Texinfo. After that
+execute the following commands:
+
+ autoreconf -fi
+ ./configure
+ make
+
+note: The Makefile doesn't support out of tree build.
+
+To check the result of EXAMPLE:
+
+ firefox examples/EXAMPLE-html/index.html
+
+See the "HACKING" file for information about the development of this
+program.
Added: trunk/js/TODO
===================================================================
--- trunk/js/TODO (rev 0)
+++ trunk/js/TODO 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,7 @@
+- Handle 'n', 'p', 'u' for anchors linkids.
+- Order the datalist 'option' children using a lexicographic order
+- Make message and text inputs not overlap the iframe scroll bar
+- Implement regexp search which is associated with the 's' key
+- Make sure the index search work with multiples indices
+- Remove nested nodes from the table of content (navigation commands
+ should ignore them too)
Added: trunk/js/build-aux/eslint.json
===================================================================
--- trunk/js/build-aux/eslint.json (rev 0)
+++ trunk/js/build-aux/eslint.json 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,172 @@
+{
+ "env": { "browser": true },
+ "extends": "eslint:recommended",
+ "parserOptions": { "sourceType": "script" },
+ "rules": {
+ "accessor-pairs": "error",
+ "array-bracket-spacing": "error",
+ "array-callback-return": "error",
+ "arrow-body-style": "error",
+ "arrow-parens": ["error", "as-needed"],
+ "arrow-spacing": "error",
+ "block-spacing": "error",
+ "callback-return": "error",
+ "class-methods-use-this": "error",
+ "comma-dangle": "error",
+ "comma-spacing": "error",
+ "comma-style": "error",
+ "complexity": "error",
+ "computed-property-spacing": "error",
+ "consistent-return": "error",
+ "consistent-this": "error",
+ "curly": ["error", "multi-or-nest"],
+ "default-case": "error",
+ "dot-location": ["error", "property"],
+ "eol-last": "error",
+ "eqeqeq": "off",
+ "func-call-spacing": ["error", "always"],
+ "func-name-matching": "error",
+ "func-style": ["error", "declaration", { "allowArrowFunctions": true }],
+ "generator-star-spacing": ["error", "both"],
+ "global-require": "error",
+ "guard-for-in": "error",
+ "handle-callback-err": "error",
+ "id-blacklist": "error",
+ "id-match": [
+ "error",
+ "^([A-Z]+(_[A-Z]+)*|[_A-Z]?[a-z\\d]+(_[a-z\\d]+)*\\$*)$",
+ { "onlyDeclarations": true }
+ ],
+ "key-spacing": "error",
+ "keyword-spacing": "error",
+ "linebreak-style": ["error", "unix"],
+ "lines-around-directive": "error",
+ "max-depth": "error",
+ "max-len": ["error", 80],
+ "max-nested-callbacks": ["error", 3],
+ "max-params": "error",
+ "max-statements": "off",
+ "max-statements-per-line": "error",
+ "new-cap": "error",
+ "new-parens": "error",
+ "newline-per-chained-call": "error",
+ "no-alert": "error",
+ "no-array-constructor": "off",
+ "no-await-in-loop": "error",
+ "no-bitwise": "error",
+ "no-caller": "error",
+ "no-catch-shadow": "error",
+ "no-compare-neg-zero": "error",
+ "no-confusing-arrow": ["error", {"allowParens": true}],
+ "no-console": "off",
+ "no-div-regex": "error",
+ "no-duplicate-imports": "error",
+ "no-empty-function": "error",
+ "no-eq-null": "error",
+ "no-eval": "error",
+ "no-extend-native": "error",
+ "no-extra-bind": "error",
+ "no-floating-decimal": "error",
+ "no-implicit-coercion": "error",
+ "no-implicit-globals": "error",
+ "no-implied-eval": "error",
+ "no-iterator": "error",
+ "no-labels": "error",
+ "no-lone-blocks": "error",
+ "no-lonely-if": "error",
+ "no-loop-func": "error",
+ "no-magic-numbers": ["error", { "ignore": [-1, 0, 1] }],
+ "no-mixed-operators": "error",
+ "no-mixed-requires": "error",
+ "no-multi-assign": "error",
+ "no-multi-spaces": "error",
+ "no-multiple-empty-lines": "error",
+ "no-native-reassign": "error",
+ "no-negated-in-lhs": "error",
+ "no-nested-ternary": "error",
+ "no-new-func": "error",
+ "no-new-object": "error",
+ "no-new-require": "error",
+ "no-new-wrappers": "error",
+ "no-octal-escape": "error",
+ "no-path-concat": "error",
+ "no-plusplus": "error",
+ "no-process-env": "error",
+ "no-process-exit": "error",
+ "no-proto": "error",
+ "no-restricted-globals": "error",
+ "no-restricted-imports": "error",
+ "no-restricted-modules": "error",
+ "no-restricted-properties": "error",
+ "no-restricted-syntax": "error",
+ "no-return-assign": "error",
+ "no-return-await": "error",
+ "no-script-url": "error",
+ "no-self-compare": "error",
+ "no-sequences": "error",
+ "no-shadow-restricted-names": "error",
+ "no-sync": "error",
+ "no-tabs": "error",
+ "no-template-curly-in-string": "error",
+ "no-throw-literal": "error",
+ "no-trailing-spaces": "error",
+ "no-undef-init": "error",
+ "no-undefined": "error",
+ "no-underscore-dangle": "error",
+ "no-unmodified-loop-condition": "error",
+ "no-unneeded-ternary": "error",
+ "no-unused-expressions": "error",
+ "no-use-before-define": "off",
+ "no-useless-call": "error",
+ "no-useless-computed-key": "error",
+ "no-useless-concat": "error",
+ "no-useless-constructor": "error",
+ "no-useless-rename": "error",
+ "no-useless-return": "error",
+ "no-void": "error",
+ "no-whitespace-before-property": "error",
+ "no-with": "error",
+ "object-curly-newline": "error",
+ "object-curly-spacing": ["error", "always"],
+ "object-property-newline": [
+ "error",
+ { "allowMultiplePropertiesPerLine": true }
+ ],
+ "object-shorthand": ["error", "never"],
+ "one-var": ["error", "never"],
+ "one-var-declaration-per-line": "error",
+ "operator-assignment": "error",
+ "operator-linebreak": [
+ "error",
+ "before",
+ { "overrides": { "=" : "after", "?": "after", ":": "after" } }
+ ],
+ "padded-blocks": ["error", "never"],
+ "prefer-numeric-literals": "error",
+ "prefer-promise-reject-errors": "error",
+ "prefer-spread": "error",
+ "quote-props": ["error", "as-needed"],
+ "quotes": ["error", "double"],
+ "radix": "error",
+ "require-await": "error",
+ "require-jsdoc": "off",
+ "rest-spread-spacing": "error",
+ "semi": "error",
+ "semi-spacing": "error",
+ "sort-imports": "error",
+ "space-before-blocks": "error",
+ "space-before-function-paren": "error",
+ "space-in-parens": ["error", "never"],
+ "space-infix-ops": "error",
+ "space-unary-ops": "error",
+ "strict": "error",
+ "symbol-description": "error",
+ "template-curly-spacing": "error",
+ "unicode-bom": "error",
+ "valid-jsdoc": "off",
+ "wrap-iife": "error",
+ "wrap-regex": "error",
+ "yield-star-spacing": ["error", { "before": true, "after": false }],
+ "yoda": "error"
+ }
+}
Added: trunk/js/build-aux/modernizr.json
===================================================================
--- trunk/js/build-aux/modernizr.json (rev 0)
+++ trunk/js/build-aux/modernizr.json 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,14 @@
+{
+ "options": [],
+ "feature-detects": [
+ "test/dom/classlist",
+ "test/dom/hidden",
+ "test/elem/datalist",
+ "test/es5/specification",
+ "test/eventlistener",
+ "test/history",
+ "test/postmessage",
+ "test/queryselector",
+ "test/window/framed"
+ ]
+}
Added: trunk/js/configure.ac
===================================================================
--- trunk/js/configure.ac (rev 0)
+++ trunk/js/configure.ac 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,46 @@
+dnl Process this file with autoconf to produce a configure script.
+# Copyright (C) 2017 Free Software Foundation, Inc.
+#
+# This file is part of GNU Texinfo.
+#
+# GNU Texinfo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# GNU Texinfo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNU Texinfo. If not, see <http://www.gnu.org/licenses/>.
+
+AC_INIT([info.js], [0.1], address@hidden)
+AC_CONFIG_SRCDIR([info.js])
+AC_CONFIG_AUX_DIR([build-aux])
+
+AM_INIT_AUTOMAKE([foreign])
+AM_SILENT_RULES([yes])
+
+AC_PATH_PROG([MAKEINFO], [makeinfo])
+if test "x$ac_cv_path_MAKEINFO" = "x"; then
+ AC_MSG_ERROR([makeinfo not found])
+fi
+
+npm_path="${srcdir}/node_modules/.bin${PATH_SEPARATOR}$PATH"
+
+AC_PATH_PROG([ESLINT], [eslint], [], [$npm_path])
+AM_CONDITIONAL([HAVE_ESLINT], [test "x$ac_cv_path_ESLINT" != "x"])
+
+AC_PATH_PROG([TSC], [tsc], [], [$npm_path])
+AM_CONDITIONAL([HAVE_TYPESCRIPT], [test "x$ac_cv_path_TSC" != "x"])
+
+AC_PATH_PROG([UGLIFYJS], [uglifyjs], [], [$npm_path])
+AM_CONDITIONAL([HAVE_UGLIFYJS], [test "x$ac_cv_path_UGLIFYJS" != "x"])
+
+AC_PATH_PROG([MODERNIZR], [modernizr], [], [$npm_path])
+AM_CONDITIONAL([HAVE_MODERNIZR], [test "x$ac_cv_path_MODERNIZR" != "x"])
+
+AC_CONFIG_FILES([Makefile])
+AC_OUTPUT
Added: trunk/js/examples/hello/fdl.texi
===================================================================
--- trunk/js/examples/hello/fdl.texi (rev 0)
+++ trunk/js/examples/hello/fdl.texi 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,505 @@
address@hidden The GNU Free Documentation License.
address@hidden Version 1.3, 3 November 2008
+
address@hidden This file is intended to be included within another document,
address@hidden hence no sectioning command or @node.
+
address@hidden
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation,
Inc.
address@hidden://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, address@hidden input
+format, SGML or XML using a publicly available
+DTD, and standard-conforming simple HTML,
+PostScript or PDF designed for human modification. Examples
+of transparent image formats include PNG, XCF and
address@hidden Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, SGML or
+XML for which the DTD and/or processing tools are
+not generally available, and the machine-generated HTML,
+PostScript or PDF produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section Entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
address@hidden
+Preserve any Warranty Disclaimers.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation. If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
address@hidden
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works. A
+public wiki that anybody can edit is an example of such a server. A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.3
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the address@hidden''@: line with this:
+
address@hidden
address@hidden
+ with the Invariant Sections being @var{list their titles}, with
+ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+ being @var{list}.
address@hidden group
address@hidden smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
Added: trunk/js/examples/hello/hello.texi
===================================================================
--- trunk/js/examples/hello/hello.texi (rev 0)
+++ trunk/js/examples/hello/hello.texi 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,322 @@
+\input texinfo @c -*-texinfo-*-
address@hidden %**start of header
address@hidden hello.info
address@hidden version.texi
address@hidden GNU Hello @value{VERSION}
+
address@hidden Define a new index for options.
address@hidden op
address@hidden Combine everything into one index (arbitrarily chosen to be the
address@hidden concept index).
address@hidden op cp
address@hidden %**end of header
+
address@hidden
+This manual is for GNU Hello (version @value{VERSION}, @value{UPDATED}),
+which prints a friendly greeting (and serves as an example GNU package).
+
+Copyright @copyright{} 1992, 1993, 1996, 2002, 2005, 2006, 2007, 2008,
+2009, 2010, 2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc.
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
address@hidden quotation
address@hidden copying
address@hidden If your manual is published on paper by the FSF, it should
include
address@hidden the standard FSF Front-Cover and Back-Cover Texts, as given in
address@hidden maintain.texi.
+
address@hidden Basics
address@hidden
+* Hello: (hello). Hello, GNU world.
address@hidden direntry
+
address@hidden
address@hidden GNU Hello
address@hidden for version @value{VERSION}, @value{UPDATED}
address@hidden GNU Hello Developers (@email{bug-hello@@gnu.org})
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden
+
+
address@hidden
address@hidden Top
address@hidden GNU Hello
+
+This manual is for GNU Hello (version @value{VERSION}, @value{UPDATED}),
+which prints a friendly greeting (and serves as an example GNU package).
address@hidden ifnottex
+
address@hidden
+* Overview:: General purpose and information.
+* Sample output:: Sample output from @command{hello}.
+* Invoking hello:: How to run @command{hello}.
+* Reporting bugs:: Sending bug reports and feature suggestions.
+* GNU Free Documentation License:: Copying and sharing this documentation.
+* Concept index:: Index of concepts.
address@hidden menu
+
+
address@hidden Overview
address@hidden Overview
+
address@hidden greetings
address@hidden overview
+
+The GNU @command{hello} program
+(@url{http://www.gnu.org/software/hello/}) produces a familiar,
+friendly greeting. It allows nonprogrammers to use a classic computer
+science tool which would otherwise be unavailable to them. Because it
+is protected by the GNU General Public License, users are free (in
+perpetuity) to share and change it.
+
address@hidden joke, not
+Not to spoil the joke, but of course the practical purpose of GNU
+Hello is to serve as a minimal example of a GNU package. So, although
+most manuals don't need to discuss the implementation of the programs
+they document, that is part of the goal here.
+
address@hidden GNU coding standards
address@hidden GNU maintainer standards
address@hidden standards, GNU coding
address@hidden standards, GNU maintainer
+First, GNU Hello follows the GNU coding standards
+(@pxref{Top,,Preface,standards,GNU Coding Standards}) and GNU
+maintainer standards (@pxref{Top,,Preface,maintain, Information for
+GNU Maintainers}). These are the basic documents which all GNU
+packages should adhere to.
+
+The Hello package also implements recommended development practices
+not embodied in the standards, using other GNU packages and features:
+
address@hidden @bullet
address@hidden
address@hidden Automake
address@hidden Autoconf
+It uses Automake (@pxref{Top,,Introduction,automake,GNU Automake}) and
+hence also Autoconf (@pxref{Top,,Introduction,autoconf,GNU Autoconf})
+for configuration.
+
address@hidden
address@hidden Gnulib
address@hidden @command{srclist-update} script
address@hidden @file{README-dev} source file
+It uses Gnulib (@pxref{Top,,Introduction,gnulib,GNU Gnulib}) to enhance
+portability and avoid duplication of common sources. Both
address@hidden and @code{srclist-update} are used, for purposes of
+example. See the @file{README-dev} file in the distribution.
+
address@hidden
address@hidden Gettext
+GNU Gettext (@pxref{Top,,Introduction,gettext,GNU Gettext}) is used
+for internationalization support. Hello's greeting has been translated
+into many languages.
+
address@hidden
address@hidden --help
+Internally, Hello uses the GNU @code{getopt_long} function
+(@pxref{Getopt Long Options,,,libc,GNU C Library}) to parse options,
+thus supporting GNU-style long options such as @option{--help}.
+
address@hidden
address@hidden Help2man
+The Hello Man page is generated with GNU @code{help2man}
+(@pxref{Top,,Overview,help2man,GNU @code{help2man}}) from the
address@hidden output. This relieves the maintainers from the burden
+of updating separate man documentation, yet provides a reasonable
+overview for man devotees.
+
address@hidden
address@hidden Texinfo
+Finally, Texinfo (@pxref{Top,,Introduction,texinfo,Texinfo}) is the
+documentation format for this manual. It supports output in Info,
+HTML, PDF, DVI, plain text, XML, and other formats.
+
address@hidden itemize
+
+GNU Hello is implemented in address@hidden The GNU Gettext distribution
contains
+``hello world'' examples in many other programming languages; see the
+Gettext home page at @url{http://www.gnu.org/software/gettext/}.
+
address@hidden @file{Makefile.am} targets
+The top-level @file{Makefile.am} in Hello also contains a few special
+targets for other projects to adapt as desired:
+
address@hidden @code
address@hidden diff
+Make a diff from the previous release, assuming the current tarball is
+in the current tarball.
+
address@hidden po-check
+Verify that all source files using @code{_()} are included for
+translation in @file{po/POTFILES.in}, so translators will have all the
+messages.
+
address@hidden wwwdoc
+Sample procedure for updating the manual on the GNU web site, in this
+case @url{http://www.gnu.org/software/hello/manual/}.
address@hidden table
+
address@hidden authors
address@hidden Haertel, Mike
address@hidden MacKenzie, David
address@hidden Brittenson, Jan
address@hidden Hannum, Charles
address@hidden McGrath, Roland
address@hidden Friedman, Noah
address@hidden Eichwalder, Karl
address@hidden King, The
address@hidden Berry, Karl
+GNU Hello was written by Mike Haertel, David MacKenzie, Jan
+Brittenson, Charles Hannum, Roland McGrath, Noah Friedman, Karl
+Eichwalder, Karl Berry, and @w{The King}.
+
+
address@hidden Sample output
address@hidden Sample output
+
address@hidden sample output
address@hidden examples
+
+Here are some examples of running GNU Hello.
+
+This is the output of the command @samp{hello}:
+
address@hidden
+Hello, world!
address@hidden example
+
+This is the output of the command @samp{hello --traditional}:
+
address@hidden
+hello, world
address@hidden example
+
+This is the output of the command @samp{hello --greeting=hi}:
+
address@hidden
+hi
address@hidden example
+
+
address@hidden Invoking hello
address@hidden Invoking @command{hello}
+
address@hidden invoking
address@hidden options
address@hidden usage
address@hidden help
+
+The format for running the @command{hello} program is:
+
address@hidden
+hello @var{option} @dots{}
address@hidden example
+
+With no options, @command{hello} prints the greeting @samp{Hello,
+world!}.
+
address@hidden supports the following options:
+
address@hidden @option
address@hidden address@hidden
address@hidden -g @var{text}
address@hidden --greeting
address@hidden -g
+Output @var{text} instead of the default greeting.
+
address@hidden --help
address@hidden -h
address@hidden --help
address@hidden -h
+Print an informative help message on standard output and exit
+successfully.
+
address@hidden environment variables, help for
address@hidden This comment prevents `make syntax-check' from diagnosing a
doubled word "for\nFor"
+For the @option{--help} output of GNU programs, it's strongly
+encouraged to include a brief (one or two sentences) description of
+what the program does, as well as the synopsis of how to run the
+program. Any environment variables which affect execution should also
+be mentioned (Hello doesn't have any).
+
address@hidden --traditional
address@hidden -t
address@hidden --traditional
address@hidden -t
address@hidden traditional
address@hidden modern
+Output the traditional greeting message @samp{hello, world}.
+
address@hidden --version
address@hidden -v
address@hidden --version
address@hidden -v
+Print the version number and licensing information of Hello on
+standard output and then exit successfully.
+
address@hidden table
+
+If more than one of the greeting options (@option{-g},
address@hidden, and their long-named equivalents) is specified, whichever
+comes last takes precedence.
+
+
address@hidden Reporting bugs
address@hidden Reporting bugs
+
address@hidden bug reporting
address@hidden problems
address@hidden reporting bugs
+
+To report bugs, suggest enhancements or otherwise discuss GNU Hello,
+please send electronic mail to @email{bug-hello@@gnu.org}.
+
address@hidden checklist for bug reports
+For bug reports, please include enough information for the maintainers
+to reproduce the problem. Generally speaking, that means:
+
address@hidden @bullet
address@hidden The version numbers of Hello (which you can find by running
+ @address@hidden --version}}) and any other program(s) or
+ manual(s) involved.
address@hidden Hardware and operating system names and versions.
address@hidden The contents of any input files necessary to reproduce the bug.
address@hidden The expected behavior and/or output.
address@hidden A description of the problem and samples of any erroneous output.
address@hidden Options you gave to @command{configure} other than specifying
+ installation directories.
address@hidden Anything else that you think would be helpful.
address@hidden itemize
+
+When in doubt whether something is needed or not, include it. It's
+better to include too much than to leave out something important.
+
address@hidden patches, contributing
+Patches are welcome; if possible, please make them with @address@hidden
+-c}} (@pxref{Top,, Overview, diff, Comparing and Merging Files}) and
+include @file{ChangeLog} entries (@pxref{Change Log,,, emacs, The GNU
+Emacs Manual}). Please follow the existing coding style.
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden fdl.texi
+
+
address@hidden Concept index
address@hidden Concept index
+
address@hidden cp
+
address@hidden
Added: trunk/js/examples/hello/version.texi
===================================================================
--- trunk/js/examples/hello/version.texi (rev 0)
+++ trunk/js/examples/hello/version.texi 2017-11-09 18:52:07 UTC (rev
7983)
@@ -0,0 +1,4 @@
address@hidden UPDATED 10 May 2015
address@hidden UPDATED-MONTH May 2015
address@hidden EDITION 2.10.11-e8e4
address@hidden VERSION 2.10.11-e8e4
Added: trunk/js/examples/kawa/images/border-1.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/border-1.png
===================================================================
--- trunk/js/examples/kawa/images/border-1.png 2017-11-09 18:23:23 UTC (rev
7982)
+++ trunk/js/examples/kawa/images/border-1.png 2017-11-09 18:52:07 UTC (rev
7983)
Property changes on: trunk/js/examples/kawa/images/border-1.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/domterm-pictures-1.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/domterm-pictures-1.png
===================================================================
--- trunk/js/examples/kawa/images/domterm-pictures-1.png 2017-11-09
18:23:23 UTC (rev 7982)
+++ trunk/js/examples/kawa/images/domterm-pictures-1.png 2017-11-09
18:52:07 UTC (rev 7983)
Property changes on: trunk/js/examples/kawa/images/domterm-pictures-1.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/fill-circ-1.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/fill-circ-1.png
===================================================================
--- trunk/js/examples/kawa/images/fill-circ-1.png 2017-11-09 18:23:23 UTC
(rev 7982)
+++ trunk/js/examples/kawa/images/fill-circ-1.png 2017-11-09 18:52:07 UTC
(rev 7983)
Property changes on: trunk/js/examples/kawa/images/fill-circ-1.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/image-cat-1a.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/image-cat-1a.png
===================================================================
--- trunk/js/examples/kawa/images/image-cat-1a.png 2017-11-09 18:23:23 UTC
(rev 7982)
+++ trunk/js/examples/kawa/images/image-cat-1a.png 2017-11-09 18:52:07 UTC
(rev 7983)
Property changes on: trunk/js/examples/kawa/images/image-cat-1a.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/image-cat-1b.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/image-cat-1b.png
===================================================================
--- trunk/js/examples/kawa/images/image-cat-1b.png 2017-11-09 18:23:23 UTC
(rev 7982)
+++ trunk/js/examples/kawa/images/image-cat-1b.png 2017-11-09 18:52:07 UTC
(rev 7983)
Property changes on: trunk/js/examples/kawa/images/image-cat-1b.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/image-scaled-1.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/image-scaled-1.png
===================================================================
--- trunk/js/examples/kawa/images/image-scaled-1.png 2017-11-09 18:23:23 UTC
(rev 7982)
+++ trunk/js/examples/kawa/images/image-scaled-1.png 2017-11-09 18:52:07 UTC
(rev 7983)
Property changes on: trunk/js/examples/kawa/images/image-scaled-1.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/padding-1.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/padding-1.png
===================================================================
--- trunk/js/examples/kawa/images/padding-1.png 2017-11-09 18:23:23 UTC (rev
7982)
+++ trunk/js/examples/kawa/images/padding-1.png 2017-11-09 18:52:07 UTC (rev
7983)
Property changes on: trunk/js/examples/kawa/images/padding-1.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/paint-circ-1.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/paint-circ-1.png
===================================================================
--- trunk/js/examples/kawa/images/paint-circ-1.png 2017-11-09 18:23:23 UTC
(rev 7982)
+++ trunk/js/examples/kawa/images/paint-circ-1.png 2017-11-09 18:52:07 UTC
(rev 7983)
Property changes on: trunk/js/examples/kawa/images/paint-circ-1.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/paint-circ-2.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/paint-circ-2.png
===================================================================
--- trunk/js/examples/kawa/images/paint-circ-2.png 2017-11-09 18:23:23 UTC
(rev 7982)
+++ trunk/js/examples/kawa/images/paint-circ-2.png 2017-11-09 18:52:07 UTC
(rev 7983)
Property changes on: trunk/js/examples/kawa/images/paint-circ-2.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/paint-circ-3.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/paint-circ-3.png
===================================================================
--- trunk/js/examples/kawa/images/paint-circ-3.png 2017-11-09 18:23:23 UTC
(rev 7982)
+++ trunk/js/examples/kawa/images/paint-circ-3.png 2017-11-09 18:52:07 UTC
(rev 7983)
Property changes on: trunk/js/examples/kawa/images/paint-circ-3.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/paint-circ-4.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/paint-circ-4.png
===================================================================
--- trunk/js/examples/kawa/images/paint-circ-4.png 2017-11-09 18:23:23 UTC
(rev 7982)
+++ trunk/js/examples/kawa/images/paint-circ-4.png 2017-11-09 18:52:07 UTC
(rev 7983)
Property changes on: trunk/js/examples/kawa/images/paint-circ-4.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/polygon-1.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/polygon-1.png
===================================================================
--- trunk/js/examples/kawa/images/polygon-1.png 2017-11-09 18:23:23 UTC (rev
7982)
+++ trunk/js/examples/kawa/images/polygon-1.png 2017-11-09 18:52:07 UTC (rev
7983)
Property changes on: trunk/js/examples/kawa/images/polygon-1.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/polyline-1.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/polyline-1.png
===================================================================
--- trunk/js/examples/kawa/images/polyline-1.png 2017-11-09 18:23:23 UTC
(rev 7982)
+++ trunk/js/examples/kawa/images/polyline-1.png 2017-11-09 18:52:07 UTC
(rev 7983)
Property changes on: trunk/js/examples/kawa/images/polyline-1.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/re-center-1.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/re-center-1.png
===================================================================
--- trunk/js/examples/kawa/images/re-center-1.png 2017-11-09 18:23:23 UTC
(rev 7982)
+++ trunk/js/examples/kawa/images/re-center-1.png 2017-11-09 18:52:07 UTC
(rev 7983)
Property changes on: trunk/js/examples/kawa/images/re-center-1.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/re-center-2.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/re-center-2.png
===================================================================
--- trunk/js/examples/kawa/images/re-center-2.png 2017-11-09 18:23:23 UTC
(rev 7982)
+++ trunk/js/examples/kawa/images/re-center-2.png 2017-11-09 18:52:07 UTC
(rev 7983)
Property changes on: trunk/js/examples/kawa/images/re-center-2.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/show-draw-1.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/show-draw-1.png
===================================================================
--- trunk/js/examples/kawa/images/show-draw-1.png 2017-11-09 18:23:23 UTC
(rev 7982)
+++ trunk/js/examples/kawa/images/show-draw-1.png 2017-11-09 18:52:07 UTC
(rev 7983)
Property changes on: trunk/js/examples/kawa/images/show-draw-1.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/show-draw-2.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/show-draw-2.png
===================================================================
--- trunk/js/examples/kawa/images/show-draw-2.png 2017-11-09 18:23:23 UTC
(rev 7982)
+++ trunk/js/examples/kawa/images/show-draw-2.png 2017-11-09 18:52:07 UTC
(rev 7983)
Property changes on: trunk/js/examples/kawa/images/show-draw-2.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/images/show-draw-3.png
===================================================================
(Binary files differ)
Index: trunk/js/examples/kawa/images/show-draw-3.png
===================================================================
--- trunk/js/examples/kawa/images/show-draw-3.png 2017-11-09 18:23:23 UTC
(rev 7982)
+++ trunk/js/examples/kawa/images/show-draw-3.png 2017-11-09 18:52:07 UTC
(rev 7983)
Property changes on: trunk/js/examples/kawa/images/show-draw-3.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Added: trunk/js/examples/kawa/kawa.texi
===================================================================
--- trunk/js/examples/kawa/kawa.texi (rev 0)
+++ trunk/js/examples/kawa/kawa.texi 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,24092 @@
+\input texinfo.tex @c -*-texinfo-*-
address@hidden %**start of header
address@hidden kawa.info
address@hidden UTF-8
address@hidden The Kawa Scheme language
address@hidden off
address@hidden fn cp
address@hidden vr cp
address@hidden pg cp
address@hidden on
address@hidden on
address@hidden version: %W% %G%
address@hidden %**end of header
+
address@hidden false{}
address@hidden
address@hidden macro
+
address@hidden true{}
address@hidden
address@hidden macro
+
address@hidden func{NAME}
address@hidden
address@hidden macro
+
address@hidden stxdef{NAME}
address@hidden @i{\NAME\}
address@hidden@var{\NAME\} @t{::=}
address@hidden macro
+
address@hidden
address@hidden
address@hidden stxref{NAME}
address@hidden, @var{\NAME\}, @var{\NAME\}}
address@hidden macro
address@hidden ifnottex
address@hidden ifnotinfo
address@hidden
address@hidden stxref{NAME}
address@hidden
address@hidden macro
address@hidden ifinfo
address@hidden
address@hidden stxref{NAME}
address@hidden
address@hidden macro
address@hidden iftex
+
address@hidden stxlit{TEXT}
address@hidden@b{\TEXT\}}
address@hidden macro
address@hidden stxlitlbrace{TEXT}
address@hidden@address@hidden
address@hidden macro
+
address@hidden arbno{THING}
address@hidden
address@hidden macro
address@hidden maybe use \x2217
address@hidden \THING\ @var{...}
+
address@hidden atleastone{THING}
address@hidden
address@hidden macro
+
address@hidden meta{THING}
address@hidden
address@hidden macro
+
address@hidden PerformanceNote
address@hidden note:}
address@hidden macro
+
address@hidden CompatibilityNote
address@hidden:}
address@hidden macro
+
address@hidden
address@hidden vari{THING}
address@hidden
address@hidden macro
address@hidden varii{THING}
address@hidden
address@hidden macro
address@hidden variii{THING}
address@hidden
address@hidden macro
address@hidden variv{THING}
address@hidden
address@hidden macro
address@hidden ifinfo
address@hidden
address@hidden vari{THING}
address@hidden@sub{1}
address@hidden macro
address@hidden varii{THING}
address@hidden@sub{2}
address@hidden macro
address@hidden variii{THING}
address@hidden@sub{3}
address@hidden macro
address@hidden variv{THING}
address@hidden@sub{4}
address@hidden macro
address@hidden ifnotinfo
+
address@hidden version.texi
+
address@hidden
address@hidden
address@hidden iftex
address@hidden
address@hidden The Kawa Scheme language
address@hidden @value{UPDATED}
address@hidden 1
address@hidden Per Bothner
address@hidden
address@hidden titlepage
+
address@hidden
+
address@hidden
address@hidden
+START-INFO-DIR-ENTRY
+* kawa: (kawa). The Kawa Scheme language
+END-INFO-DIR-ENTRY
address@hidden format
address@hidden ifinfo
+
address@hidden
address@hidden Top, Installation, (dir), (dir)
address@hidden The Kawa Scheme language
address@hidden ifnottex
+
address@hidden Kawa is best known as an implementation of the
address@hidden @uref{http://www.schemers.org/,Scheme language} for the Java
platform.
address@hidden It compiles Scheme to high-performance Java bytecodes.
address@hidden It is also a general framework for implementing dynamic
languages,
address@hidden and includes a full implementation of XQuery and the beginnings
of
address@hidden implementations of Common Lisp and Emacs Lisp (JEmacs).
+
+Kawa is a general-purpose programming language that runs on the Java platform.
+It aims to combine:
address@hidden
address@hidden
+the benefits of dynamic scripting languages
+(non-verbose code with less boiler-plate, fast and easy start-up,
+a @uref{http://en.wikipedia.org/wiki/Read-eval-print_loop,REPL},
+no required compilation step); with
address@hidden
+the benefits of traditional compiled languages (fast execution, static error
detection,
+modularity, zero-overhead Java platform integration).
address@hidden itemize
+It is an extension of the long-established
@uref{http://www.schemers.org/,Scheme}
+language, which is in the Lisp family of programming languages.
+Kawa has many @ref{Features,useful features}.
+
+Kawa is also a useful @ref{Framework,framework} for implementing
+other programming languages on the Java platform.
+It has many useful utility classes.
+
+This manual describes version @value{VERSION}, updated @value{UPDATED}.
+See the summary of @ref{News,recent changes}.
+
address@hidden Old versions of makeinfo don't support: @ifnotdocbook
+The Kawa home page (which is currently just an on-line
+version of this document) is @uref{http://www.gnu.org/software/kawa/}.
+
address@hidden (blank line needed above) @end ifnotdocbook
+
+The @ref{Tutorial,Kawa tutorial} is useful to get stated.
+While it is woefully incomplete, it does link to some other more in-depth
+(but not Kawa-specific) Scheme tutorials.
+
+For copyright information on the software and documentation,
+see @ref{License}.
+
+Various people and orgnizations @ref{Acknowledgements,have contributed to
Kawa}.
+
+This package has nothing to do with the defunct Kawa commercial Java IDE.
+
address@hidden
+* News:: News - Recent Changes
+* Features::
+* Community::
+* Installation:: Building and installing Kawa
+* Tutorial:: Kawa Scheme Tutorial
+* Running:: Invoking, Running, and Using Kawa
+* Syntax::
+* Program structure::
+* Control features::
+* Symbols and namespaces::
+* Procedures::
+* Numbers:: Quantities and Numbers
+* Characters and text::
+* Data structures::
+* Eval and Environments::
+* Debugging::
+* Input-Output:: Input, output, and file handling
+* Types::
+* Objects Classes and Modules::
+* XML tools:: XML, HTML, and the web
+* Miscellaneous::
+* FAQs:: Frequently Asked Questions
+* Framework:: The Kawa language framework
+* License::
+* Overall Index:: Index of functions, macros, concepts, and more.
address@hidden menu
+
address@hidden News
address@hidden News - Recent Changes
address@hidden news.texi
+
address@hidden Features
address@hidden Features
+
+Runs on the Java platform, with no native code needed.
+
+Extends the
@uref{http://en.wikipedia.org/wiki/Scheme_%28programming_language%29,Scheme
language}, following the @uref{http://r7rs.org/,R7RS} specification from 2013.
+Scheme has many implementations, and is much used in research and teaching.
+
+Programs @uref{http://per.bothner.com/blog/2010/Kawa-in-shootout/, run fast}
+- roughly as fast as Java programs,
+and much faster than other ``scripting languages''.
+This is due to a sophisticated compiler,
+compile-time transformations, type inference, and optional type declarations.
+
+Full, convenient, and efficient access to the huge set of Java libraries
+means you can access objects, methods, fields, and classes without run-time
overhead.
+
+Start-up times are fast. You don't have to wait for a lot of
+initialization. Even if you start with source code, the parser
+and compiler are fast.
+
address@hidden are simple Kawa source files
+that can run as an application or command. These are simple to write,
+start, and run efficiently, since they're automatically
+compiled before execution.
+
+Alternatively, you can embed Kawa as a @ref{Evaluating Scheme expressions from
Java,
+scripting language for Java applications}.
+
+Deployment is easy and flexible. You just need the Kawa jar file.
+
address@hidden and @ref{Named quasi-literals,custom named literals} make it easy
+to extend the syntax and implement Domain-Specific Languages.
+
+Kawa provides the usual @ref{REPL Console,read-eval-print loop}, as well as
batch modes.
+
+Kawa has builtin @ref{Pretty-printing,pretty-printer} support, and fancy
formatting.
+
+Kawa supports class-definition facilities, and separately-compiled modules.
+
+You can @ref{Allocating objects,allocate and initialize objects}
+with a compact ``builder'' syntax. It works out-of-the-box
+(with no run-time overhead) on many classes and APIs,
+but can be customized if need be.
+
+A library for functional @ref{Composable pictures,composable pictures}
+lets you create ``picture'' objects,
+display them, transform them, combine them, convert to
+SVG or images, and more.
+This can be ``printed'' directly in the Kawa console
+(either the DomTerm console or the Swing one).
+
address@hidden JavaFX applications,JavaFX programming} is simpler.
+
+You can @ref{Building for Android,run Kawa programs on Android},
+and there is special handling to make @ref{Android view
construction,constructing View objects} easier.
+
+Flexible shell-like functionality, including @ref{process literals}.
+
address@hidden scripts,Web page scripts} are easy to write and install
+with @ref{Self-configuring page scripts,self-configuring web servers},
+optionally using @ref{Servlets,servlets} and @ref{XML literals}.
+
address@hidden and sequences have a lot of flexibility:
+Arrays can be multi-dimensional;
+you can use an array as an index (which generalizes slices and permutations);
+you can define a lazy array using a function that maps indexes to values;
+you can re-map the indexes to yield a transformed array.
+
+Many useful features for mathematics and numerics:
address@hidden
address@hidden
+The full ``numeric tower'' includes infinite-precision
+rational numbers and complex numbers.
address@hidden
+Compile-time optimization of arithmetic
+with the use of type declarations and inference.
address@hidden
+A @ref{Quantities,@dfn{quantity}} is a real number with a unit,
+such as @code{3cm}.
address@hidden
address@hidden are a 4-dimensional generalization of complex numbers.
+Unsigned primitive integer types (@code{ubyte}, @code{ushort},
address@hidden, @code{ulong}) are implemented efficiently without
+object allocation.
address@hidden itemize
+
+A @ref{Lazy evaluation,lazy value} wraps an expression which is evaluated
+only when it is needed.
+
+Kawa provides a @ref{Framework,framework} for implementing other programming
languages,
+and comes with incomplete support for CommonLisp, Emacs Lisp, and
+EcmaScript, and
address@hidden://www.gnu.org/software/qexo/,XQuery}.
+
address@hidden
+* Implemented SRFIs::
+* Compatibility:: Compatibility with standards
address@hidden menu
+
address@hidden Implemented SRFIs
address@hidden Implemented SRFIs
+
+Kawa implements the following semi-standard SRFIs
+(@uref{http://srfi.schemers.org/,Scheme Request for Implementation}):
address@hidden
address@hidden
address@hidden://srfi.schemers.org/srfi-0/srfi-0.html, SRFI 0}: Feature-based
conditional expansion construct,
+using @code{cond-expand} - @pxref{Syntax and conditional compilation}.
address@hidden
address@hidden://srfi.schemers.org/srfi-1/srfi-1.html, SRFI 1}: List Library,
if @code{(require 'list-lib)} - @pxref{SRFI-1}.
address@hidden
address@hidden://srfi.schemers.org/srfi-2/srfi-2.html, SRFI 2}: AND-LET*: an
AND with local bindings, a guarded LET* special form.
address@hidden
address@hidden://srfi.schemers.org/srfi-4/srfi-4.html, SRFI 4}: Homogeneous
numeric vector datatypes - @pxref{Uniform vectors}.
address@hidden
address@hidden://srfi.schemers.org/srfi-6/srfi-6.html, SRFI 6}: Basic String
Ports - @pxref{Ports}.
address@hidden
address@hidden://srfi.schemers.org/srfi-8/srfi-8.html, SRFI 8}: @code{receive}:
Binding to multiple values - @pxref{Multiple values}.
address@hidden
address@hidden://srfi.schemers.org/srfi-9/srfi-9.html, SRFI 9}: Defining Record
Types, using @code{define-record-type}
+- @pxref{Record types}.
address@hidden
address@hidden://srfi.schemers.org/srfi-10/srfi-10.html, SRFI 10}: @code{#,}
external form for special named types.
+This is deprecated for various reasons, including that it conflicts
+with syntax-case @code{unsyntax}.
+Better to use srfi-108 @ref{Named quasi-literals}.
address@hidden
address@hidden://srfi.schemers.org/srfi-11/srfi-11.html, SRFI 11}: Syntax for
receiving multiple values,
+using @code{let-values} and @code{let*-value} - @pxref{Multiple values}.
address@hidden
address@hidden://srfi.schemers.org/srfi-13/srfi-13.html, SRFI 13}: String
Library.
+Needs some polishing.
address@hidden
address@hidden://srfi.schemers.org/srfi-14/srfi-14.html, SRFI 14}:
Character-set Library - @pxref{Character sets}.
address@hidden
address@hidden://srfi.schemers.org/srfi-16/srfi-16.html, SRFI 16}: Syntax for
procedures of variable arity,
+using @uref{http://srfi.schemers.org/srfi-16/srfi-16.html, @code{case-lambda}}.
address@hidden
address@hidden://srfi.schemers.org/srfi-17/srfi-17.html, SRFI 17}: Generalized
@code{set!} - @pxref{Locations}.
address@hidden
address@hidden://srfi.schemers.org/srfi-23/srfi-23.html, SRFI 23}: Error
reporting mechanism, using @code{error} - @pxref{Exceptions}.
address@hidden
address@hidden://srfi.schemers.org/srfi-25/srfi-25.html, SRFI 25}:
Multi-dimensional Array Primitives - @pxref{Arrays}.
address@hidden
address@hidden://srfi.schemers.org/srfi-26/srfi-26.html, SRFI 26}: Notation for
Specializing Parameters without Currying - @pxref{Procedures}.
address@hidden
address@hidden://srfi.schemers.org/srfi-28/srfi-28.html, SRFI 28}: Basic Format
Strings - @pxref{Format}.
address@hidden
address@hidden://srfi.schemers.org/srfi-30/srfi-30.html, SRFI 30}: Nested
Multi-line Comments.
address@hidden
address@hidden://srfi.schemers.org/srfi-35/srfi-35.html, SRFI 35}: Conditions.
address@hidden
address@hidden://srfi.schemers.org/srfi-37/srfi-37.html, SRFI 37}:
@uref{http://srfi.schemers.org/srfi-37/srfi-37.html,@code{args-fold} - a
program argument processor}, if @code{(require 'args-fold)}.
address@hidden
address@hidden://srfi.schemers.org/srfi-38/srfi-38.html, SRFI 38}: External
Representation for Data With Shared Structure.
+The @code{read-with-shared-structure} is missing, but subsumed by @code{read}.
address@hidden
address@hidden://srfi.schemers.org/srfi-39/srfi-39.html, SRFI 39}:
address@hidden objects}.
address@hidden
address@hidden://srfi.schemers.org/srfi-41/srfi-41.html, SRFI 41}: Streams -
@pxref{Streams}.
address@hidden
address@hidden://srfi.schemers.org/srfi-45/srfi-45.html, SRFI 45}: Primitives
for Expressing Iterative Lazy Algorithms - @pxref{Lazy evaluation}.
address@hidden
address@hidden://srfi.schemers.org/srfi-60/srfi-60.html, SRFI 60}: Integers as
Bits. - @pxref{Logical Number Operations}.
address@hidden
address@hidden://srfi.schemers.org/srfi-62/srfi-62.html, SRFI 62}: S-expression
comments.
address@hidden
address@hidden://srfi.schemers.org/srfi-64/srfi-64.html, SRFI 64}: A Scheme API
for test suites.
address@hidden
address@hidden://srfi.schemers.org/srfi-69/srfi-69.html, SRFI 69}: Basic hash
tables - @pxref{Hash tables}.
address@hidden
address@hidden://srfi.schemers.org/srfi-87/srfi-87.html, SRFI 87}: @code{=>} in
@code{case} clauses.
address@hidden
address@hidden://srfi.schemers.org/srfi-88/srfi-88.html, SRFI 88}: Keyword
objects - @pxref{Keywords}.
address@hidden
address@hidden://srfi.schemers.org/srfi-95/srfi-95.html, SRFI 95}: Sorting and
Merging.
address@hidden
address@hidden://srfi.schemers.org/srfi-97/srfi-97.html, SRFI 97}: Names for
SRFI Libraries.
address@hidden
address@hidden://srfi.schemers.org/srfi-98/srfi-98.html, SRFI 98}: An interface
to access environment variables
address@hidden
address@hidden://srfi.schemers.org/srfi-101/srfi-101.html, SRFI 101}: Purely
Functional Random-Access Pairs and Lists - @pxref{SRFI-101}.
address@hidden
address@hidden://srfi.schemers.org/srfi-107/,SRFI 107}: XML reader syntax -
@pxref{XML literals}.
address@hidden
address@hidden://srfi.schemers.org/srfi-108/,SRFI 108}: Named quasi-literal
constructors - @pxref{Named quasi-literals}.
address@hidden
address@hidden://srfi.schemers.org/srfi-109/srfi-109.html, SRFI-109}: Extended
string quasi-literals - @pxref{string quasi-literals}.
address@hidden
address@hidden://srfi.schemers.org/srfi-118/srfi-118.html, SRFI-118}: Simple
adjustable-size strings (@code{string-append!} and @code{string-replace!}).
address@hidden itemize
+
address@hidden Compatibility
address@hidden Compatibility with standards
+
+Kawa implements all the required and optional features of R7RS,
+with the following exceptions.
+
+The entire ``numeric tower" is implemented.
+However, some transcendental functions only work on reals.
+Integral functions do not necessarily work on
+inexact (floating-point) integers.
+(The whole idea of ``inexact integer" in R5RS seems rather pointless ...)
+
+Also, @code{call-with-current-continuation} is only ``upwards" (?).
+I.e. once a continuation has been exited, it cannot be invoked.
+These restricted continuations can be used to implement catch/throw
+(such as the examples in R4RS), but not co-routines or backtracking.
+
+Kawa now does general tail-call elimination, but only if
+you use the flag @code{--full-tail-calls}. (Currently, the
address@hidden function itself is not fully tail-recursive, in violation
+of R5RS.) The @code{--full-tail-calls} flag is not on by default,
+partly because it is noticably slower (though I have not measured how
+much), and partly I think it is more useful for Kawa to be compatible
+with standard Java calling conventions and tools.
+Code compiled with @code{--full-tail-calls} can call code
+ compiled without it and vice versa.
+
+Even without @code{--full-tail-calls}, if the
+compiler can prove that the procedure being called is the current
+function, then the tail call will be replaced by a jump.
+This includes must ``obvious'' cases of calls to the
+current function named using @code{define} or @code{letrec},
+and many cases of mutual tail-recursion (including
+state-machines using @code{letrec}).
+
+By default, symbols are case sensitive.
+
+Kawa implements most of the features of the expression language of DSSSL,
+the Scheme-derived ISO-standard Document Style Semantics and Specification
+Language for SGML. Of the core expression language, the only features
+missing are character properties, @code{external-procedure},
+the time-relationed procedures, and character name escapes in
+string literals.
+From the full expression language, Kawa additionally is missing
address@hidden, @code{format-number-list}, and language objects.
+Quantities, keyword values, and the expanded @code{lambda} form
+(with optional and keyword parameters) are supported.
+
address@hidden Community
address@hidden The Kawa Community
+
address@hidden
+* Reporting bugs:: Where to report bugs
+* Mailing lists:: Where to discuss changes, etc
+* Acknowledgements:: Acknowledgements and thanks
+* Support:: Technical support for Kawa
+* Projects:: Projects using Kawa
+* Ideas and tasks:: Ideas and tasks for contributing to Kawa
address@hidden menu
+
address@hidden Reporting bugs
address@hidden Reporting bugs
+
+To report a bug or a feature request
+use the @uref{https://gitlab.com/kashell/Kawa/issues,Issue Tracker}.
+This does require a @uref{https://gitlab.com/,GitLab} account;
+if this is a problem you can use the Savannah bug tracker.
+
address@hidden Older Savannah bug tracker
+
+The older bug tracker for Kawa on Savannah is still available,
+but we request you use
+the @uref{https://gitlab.com/kashell/Kawa/issues,GitLab Issue Tracker}
+for new issues.
+
+To report a bug or feature request for Kawa (including Qexo or JEmacs) through
Savannah,
+use the
address@hidden://savannah.gnu.org/bugs/?func=additem&group=kawa,bug-submission
page}.
+You can browse and comment on existing bug reports
+using the @uref{http://savannah.gnu.org/bugs/?group=kawa, Kawa Bugzilla page}.
+
+When a bug report is created or modified, mail is automatically sent to the
address@hidden@@gnu.org} list. You can subscribe, unsubscribe, or browse
+the archives through the
address@hidden://mail.gnu.org/mailman/listinfo/bug-kawa,
address@hidden web interface}.
+
address@hidden Mailing lists
address@hidden General Kawa email and discussion
+
+The general Kawa email list is @email{kawa@@sourceware.org}.
+This mailing list is used for announcements, questions, patches,
+and general discussion relating to Kawa. If you wish to subscribe,
+send a blank message request to @email{kawa-subscribe@@sourceware.org}.
+To unsubscribe, send a blank message to
address@hidden@@sourceware.org}.
+(If your mail is forwarded and you're not sure which email address you're
+subscribed as, send mail to the address following @code{mailto:} in the
address@hidden line in the headers of the messages you get from
+the list.)
+
+You can browse the @uref{http://sourceware.org/ml/kawa/,
+archive of past messages}.
+
+There are separate mailing lists for
address@hidden://mail.gnu.org/mailman/listinfo/qexo-general, Qexo}
+and @uref{http://lists.sourceforge.net/mailman/listinfo/jemacs-info,JEmacs}.
+
address@hidden Acknowledgements
address@hidden Acknowledgements and thanks
+
+The author and project leader of Kawa is
address@hidden://per.bothner.com/,Per Bothner}
address@hidden@@bothner.com}.
+
+Kawa is a re-write of Kawa 0.2, which was a Scheme interpreter written by
+R. Alexander Milowski @email{alex@@milowski.com}.
+
+Thanks to Cygnus Solutions (now part of Red Hat) for sponsoring
+the initial development of Kawa, and then transferring
+their ownership interest to Per.
+
address@hidden Financial support
+
+Ean Schuessler and @uref{http://www.brainfood.com/,Brainfood}
+provided financial support and encouragement.
+
+Thanks to Chris Dean, Dean Ferreyra, and others
+at @uref{http://www.mercedsystems.com/,Merced Systems} for financial
+support and other contributions.
+
address@hidden://google.com/,Google} through their
address@hidden://code.google.com/soc/,Summer of Code} project
+sponsored Charles Turner during Summer 2011 and 2012,
+and sponsored Andrea Bernardini Summer 2014.
+
+Thomas Kirk and AT&T provided financial support, and useful bug reports.
+
address@hidden Various contributions
+
address@hidden://jcubic.pl/,Jakub Jankiewicz} contributed the Kawa logo.
+
+Helmut Eller provided SLIME support, syntaxutils.scm, and many bug reports.
+
+Daniel Bonniot for multiple small improvements
+to gnu.bytecode and gnu.expr.
+
+Jamison Hope for multiple contributions,
+including quaternion support, the SRFI-14 implementation,
+Ant improvements, and Google Summer of Code mentoring.
+
+Jim White for Ant support and other improvements.
+
+Bruce R. Lewis implemented @ref{KRL,,KRL} and made other contributions.
+
+Geoff Berry: Handle Exceptions attribute. Other improvements.
+
+Shad Gregory improved JEmacs.
+
+Al Petrofsky improved gnu.math printing and added some IntNum methods.
+
+Marco Vezzoli: SRFI-1 tailoring for Kawa.
+
+Albert Ting - old GuiConsole code.
+
+Christian Surlykke ported JEmacs to use SWT.
+
+Geoff Berry for various gnu.bytecode improvements.
+
+Ivelin Ivanov and Tom Reilly for servlet support.
+
+Anthony Green for Fedora packaging.
+
+Charles Turner for pretty-printer improvements,
+improvements in the Common Lips support, and other changes.
+
+Andrea Bernardini optimized the implementation of @code{case}.
+
+Julien Rousseau and Marius Kjeldahl contributed to Android support.
+
+Peter Lane for many documentation improvements.
+
address@hidden Small fixes and improvements
+
+Patrick Barta;
+Joseph Bowbeer;
+Dominique Boucher;
+Alexander Bunkenburg;
+Harold Carr;
+Emmanuel Castro;
+Álvaro Castro-Castilla;
+Heather Downs;
+Francisco Vides Fernández;
+Nic Ferrier;
+Oliver Flasch;
+Weiqi Gao;
+Luke Gorrie;
+Mario Domenech Goulart;
+Zvi Har'E;
+Jeff Haynes;
+Ethan Herdrick;
+Joerg-Cyril Hoehle;
+Elliott Hughes;
+Mike Kenne;
+Brian Jones;
+Gerardo Jorvilleur;
+Simon Josefsson (JEmacs menu);
+Thomas Kirk;
+Jay Krell;
+Edouard Parmelan;
+Walter C. Pelissero;
+Rafael Jesus Alcantara Perez;
+Lynn Quam;
+Marcus Otto;
+Terje Pedersen (some XQuery functions);
+Matthias Radestock;
+Ola Rinta-Koski;
+Andreas Schlapbach;
+Robert D. Skeels;
+Benny Tsai;
+Vladimir Tsichevski;
+Matthieu Vachon;
+Phil Walker;
+Knut Wannheden;
+Chris Wegrzyn.
+
address@hidden Bug reports and test cases
+
+Seth Alves;
+Khairul Azhar;
+Bob Bane;
+Hans Boehm;
+Adrián Medraño Calvo;
+Brian D. Carlstrom;
+Luis Casillas;
+Sudarshan S Chawathe;
+Ken Dickey (format tests);
+Helge Dietert;
+Allan Erskine;
+Marc Feeley (polytype.scm);
+Margus Freudenthal;
+Weiqi Gao;
+Andrea Girotto;
+Norman Hard;
+Gerardo Horvilleur;
+Yaroslav Kavenchuk;
+Felix S Klock II;
+Francois Leygues;
+Mirko Luedde;
+Leonardo Valeri Manera;
+Kjetil S. Matheussen;
+Alex Mitchell;
+Alex Moiseenko
+Edouard Parmelan;
+Walter C. Pelissero;
+Stephen L. Peters;
+François Pinard;
+Bill Robinson;
+Dan Stanger (Eaton Vance);
+Hallvard Traetteberg;
+Taylor Venable;
+Alessandro Vernet;
+Tony White
+John Whittaker;
+Robert Yokota.
+
address@hidden Code ported from other packages
+
+Kawa includes Free Software originally written for other purposes,
+but incorporated into Kawa, perhaps with some porting. A partial list:
+
+Dorai Sitaram wrote pregexp.
+
+The @code{rationalize} algorithm is by Alan Bawden and Marc Feeley.
+
+Lars T Hansen wrote SRFI-11 (let-values, let*-values macros).
+
+Olin Shivers wrote the SRFI-1 list-processing library,
+and the SRFI-13 reference impementation.
+
+John David Stone wrote SRFI-8 (receive macro)
+
+Jussi Piitulainen wrote the SRFI-25 specification and tests.
+
+Richard Kelsey and Michael Sperber wrote SRFI-34.
+
+Anthony Carrico wrote the SRFI-37 reference implementation.
+
+Panu Kalliokoski wrote the SRFI-69 reference implementation.
+
+Donovan Kolbly wrote the srfi-64 ``meta'' testsuite.
+Alex Shinn improved SRFI-64 portability.
+
+Philip L. Bewig wrote the SRFI-41 (streams) specification and
+reference implementation.
+
+Simon Tatham wrote listsort.
+
+Aubrey Jaffer wrote much of SLIB, some of which has been
+imported into gnu.kawa.slib. He also wrote some tests we're using.
+
address@hidden Support
address@hidden Technical Support for Kawa
+
+If you have a project that depends on Kawa or one of its component
+packages, you might do well to get paid priority support from
+Kawa's author.
+
+The base price is $2400 for one year. This entitles you to basic
+support by email or phone. Per @email{per@@bothner.com} will answer techical
+questions about Kawa or its implementation, investigate bug reports, and
+suggest work-arounds. I may (at my discretion) provide fixes and
+enhancements (patches) for simple problems. Response for support
+requests received during the day (California time) will normally be
+within a few hours.
+
+All support requests must come through a single designated contact
+person. If Kawa is important to your business, you probably
+want at least two contact people, doubling the price.
+
+If the support contract is cancelled (by either party), remaining
+time will be prorated and refunded.
+
+Per is also available for development projects.
+
address@hidden Projects
address@hidden Projects using Kawa
+
address@hidden://appinventor.mit.edu/,MIT App Inventor}
+for Android (formerly Google App Inventor)
+uses Kawa to translate its visual blocks language.
+
+The @uref{http://www.narrativeandplay.org/hypedyn/,HypeDyn} hypertext
+fiction authoring tool is written in Kawa. HypeDyn (pronounced "hyped
+in") is a procedural hypertext fiction authoring tool for people who
+want to create text-based interactive stories that adapt to reader
+choice. HypeDyn is free to download and open source, and runs on
+Linux, MacOS and Windows. This is a research project carried out at
+the Department of Communications and New Media, National University of
+Singapore.
+
address@hidden://www.nuecho.com,Nü Echo} develops high-performance speech
+enabled applications. Nü Echo uses Kawa for the development of innovative
+speech application development tools, like a complete
address@hidden://www.nuecho.com/en/services/grammar.shtml,grammar IDE}.
+
address@hidden://www.mercedsystems.com/, Merced address@hidden Inc.} uses Kawa
+extensively in their contact center performance management product
+Merced Peformance Suite. Kawa Scheme is used for all development
+and has allowed Merced to realize the large productivity gains
+that come with using Scheme while still maintaining tight
+integration with a large number of Java libraries.
+
+JEmacs is included in the Kawa distribution. It is a project to
+re-implement Emacs, allowing a mix of Java, Scheme, and Emacs Lisp.
+It has its own @uref{http://jemacs.sourceforge.net/,home-page}.
+
+BRL (``the Beautiful Report Language") is a database-oriented language
+to embed in HTML and other markup.
address@hidden://brl.sourceforge.net/, BRL} allows you to embed Scheme in
+an HTML file on a web server.
+
+The @uref{http://schemeway.sourceforge.net,SchemeWay Project} is a set of
address@hidden://www.eclipse.org,Eclipse} plug-ins for professional Scheme
+programming. The first plugin released, SchemeScript, is a fully-featured
+Scheme
+editor customizable in Scheme. It embeds the Kawa Scheme system and has
+many features that ease Kawa Scheme programming (like code completion on
+variable names,
+class and method names, namespaces, etc).
+
+The Health Media Research Laboratory, part of the Comprehensive Cancer
+Center at the University of Michigan, is using Kawa as an integral part of
+its core tailoring technologies. Java programs using Kawa libraries are used
+to administer customized web-based surveys, generate tailored feedback,
+validate data, and "characterize," or transform, data. Kawa code is embedded
+directly in XML-formatted surveys and data dictionaries. Performance and
+ease of implementation has far exceeded expectations. For more information
+contact Paul R. Potts, Technical Director, Health Media Research Lab,
address@hidden<potts@@umich.edu>}.
+
+Mike Dillon (@code{mdillon@@gjt.org})
+did the preliminary work of creating a
+Kawa plugin for jEdit. It is called SchemeShell and provides a REPL inside
+of the jEdit console for executing expressions in Kawa (much as the BeanShell
+plugin does with the BeanShell scripting language).
+It is currently available only via CVS from:
address@hidden
+CVSROOT=:pserver:anonymous@@cvs.jedit.sourceforge.net:/cvsroot/jedit
+MODULE=plugins/SchemeShell
address@hidden example
+
+STMicroelectronics (@code{marco.vezzoli@@st.com})
+uses Kawa in a prototypal
+intranet 3tier information retrieval system as a communication protocol
+between server and clients, and to do server agents programming.
+
address@hidden
+The Nice Programming Language is a new open source language with a
+Java-like syntax. It features multiple dispatch, parametric types,
+higher-order functions, tuples, optional parameters, safe static typing
+of @code{null}, ..., and the new concept of "abstract interfaces".
+The Nice compiler (@code{nicec}) uses Kawa's @code{gnu.expr}
+and @code{gnu.bytecode}
+packages to generate Java bytecode.
+You can find more about Nice at @uref{http://nice.sourceforge.net}.
+For more information feel free to contact
+Daniel Bonniot @email{bonniot@@users.sf.net}).
address@hidden ignore
+
address@hidden Ideas and tasks
address@hidden Ideas and tasks for contributing to Kawa
+
+Kawa (like other Free Software projects) has no lack of tasks and projects
+to work on. Here are some ideas.
+
+The ones marked @i{(GSoC)} are probably most suitable for a Google
+Summer of Code project, in being a reasonable size, self-contained, and not
+depending on other tasks.
+
address@hidden Run interactive process in separate Java Virtual Machine:
address@hidden(GSoC)}
+
+When developing and testing it is useful for the REPL to support
+hot-swapping (replacing functions on-the-fly) and debugging.
+The main goal being able to smoothly reload changed modules
+(files or functions), and have other modules not break.
+Debugging (such as setting breakpoints) would not be a priority
+for this project, but could be a follow-on project.
+Skills: Should be experienced with Java, and interested in learning
+about
@uref{https://docs.oracle.com/javase/8/docs/technotes/guides/jvmti/index.html,JVM
TI} and similar low-level parts of the platform.
+Difficulty: Challenging, but you can study
+how @uref{https://en.wikipedia.org/wiki/Jshell,Java-9's new jshell}
+uses the JVM TI.
+
address@hidden Better dynamic reload
+
address@hidden(GSoC - this is related to the previous item)}
+
+Kawa does a lot of optimizations and inlining. This conflicts
+with being able to ``reload'' a module into an already-running
+interactive environment.
+
+We could add an option to load a module in ``reloadable'' mode.
+Kawa already patches an old function object (a @code{ModuleMethod})
+so existing references to the function get automatically updated.
+However, there are problems if the ``signature'' of the function
+changes - for example if the return type (declared or inferred)
+becomes more general. In those cases the best thing is to
+re-compile any code that depends on the modified function.
+
+Reloading a module that defines a class is even trickier,
+at least if there are existing instances that should
+work as the updated class. We can handle the special case
+where only method bodies change: In reloadable mode, each
+method body is compiled to a separate function, the
+actual body indirects to the function. We must also
+recognize when compiling a new version of the same
+class, which requires a textual comparison between the
+old and new versions, or a structural comparison
+between the old class and the new code.
+
+When it comes to top-level variables, an issue is when
+to re-evaluate the initializing expression. It is reasonable
+to do so if and only if the expression is modified, which
+again requires a textual comparison.
+
address@hidden Easier Access to Native Libraries using JNA/JNR
address@hidden(GSoC)}
+
+The traditional way to access native (C/C++) functions is using JNI,
+but it's very awkward.
+JNA and @uref{https://github.com/jnr,JNR} are
@uref{http://www.oracle.com/technetwork/java/jvmls2013nutter-2013526.pdf,much
easier to use}.
+This project would design and implement an easy-to-use Kawa wrapper for
+for JNR. You should study existing JNR wrappers, such as that for JRuby.
+Difficulty: Medium. Need to study existing wrappers and "foreign
+function interfaces" (in multiple languages) and design one suitable for Kawa.
+Some Scheme (Kawa) experience would be helpful.
+
address@hidden Types for units
+
address@hidden(GSoC)}
+
+Kawa supports units (such as @code{cm^2} for square centimeters)
+and @ref{Quantities,quantities} (such as @code{4cm^2}).
+We would like to integrate these into the type system, both
+for performance and compile-time type checking.
+
+For syntax we can use a pseudo-parameterized type @code{quantity}. For
example:
address@hidden
+(define a1 ::quantity[cm^2] 4cm^2)
+(* 2.0 a1) ;; @result{} 8cm^2
+(+ 2.0 a1) ;; @i{compile-time error}
address@hidden example
+The run-time type of the variable @code{a1} should be
+a primitive @code{double}, without object allocation.
+Of course when @code{a1} is converted to an object, we
+create a @code{Quantity}, not a @code{Double}.
+We can build on Kawa's existing framework for
+non-standard primitive types such as @code{character} and @code{ulong}.
+Skills: Need good Java experience, and somewhat familiar with the
+Java Virtual Machine.
+You will need to become comfortable reading <code>javap</code> output.
+Difficulty: Modest.
+
address@hidden Compiler should use class-file reading instead of reflection
+The Kawa compiler currently uses reflection to determine properties
+(such as exported function definitions) from referenced classes.
+It would be better to read class files.
+This should not be too difficult, since the @code{gnu.bytecode} library
+abstracts over class information read by reflection or class reading.
+
address@hidden Mutually dependent Java and Scheme modules
+
address@hidden(GSoC - maybe)}
+
+We'd like a command for compiling a list of Java and Scheme
+source files that may have mutual dependencies. A good way
+to do this is to hook into @code{javac}, which is quite extensible
+and pluggable.
+
+One could do something like:
address@hidden
address@hidden
+Read the ``header" of each Kawa source file, to determine the
+name of the generated main class.
address@hidden
+Enter these class names into the javac tables as ``uncompleted''
+classes.
address@hidden
+Start compiling the Java files. When this requires the members
+of the Kawa classes, switch to the Kawa files. From javac,
+treat these as pre-compiled .class files. I.e. we treat the Kawa
+compiler as a black box that produces Symbols in the same way as
+reading class files. At this point we should only need the
+initial ``scan'' phase on Kawa.
address@hidden
+If necessary, finish compiling remaining Kawa files.
address@hidden enumerate
+
+This approach may not immediately provide as robust mixed-language
+support as is ideal, but it is more amenable to incremental improvement
+than a standalone stub-generator.
+
+This project is good if you know or want to learn how @code{javac} works.
+
address@hidden Use Java-7 MethodHandles and invokedynamic
+Java 7 supports MethodHandles which are meant to provide better
+performance (ultimately) for dynamic languages.
+See @uref{http://jcp.org/en/jsr/detail?id=292,JSR 292}
+and the @uref{http://openjdk.java.net/projects/mlvm/,Da Vinci Machine Project}.
+Kawa makes limited use of MethodHandles, and no use of invokedynamic.
+There is more to be done. For example, we
+can start by optimizing arithmetic when the types are unknown
+at compile-time. They could make implementing
+generic functions (multimethods) more efficient.
+At some point we want to compile lambdas in the same way
+as Java 8 does. This can potentially
+be more efficient than Kawa's current mechanism.
+
+Remi Forax's @uref{https://github.com/forax/vmboiler,vmboiler} is
+a small library on top of ASM that generates optimistically typed bytecodes.
+It could be useful for ideas.
+
address@hidden
address@hidden Parameterized types
address@hidden(GSoC)}
+
+Kawa has some limited support for parameterized types, but
+it's not used much. Improve type inferencing.
+Support definition of parameterized classes.
+Better use of parameterized types for sequence class.
+Support wildcards.
+(It might be better to have wild-carding be associated with
+declarations, as in Scala or @uref{http://openjdk.java.net/jeps/300,proposed
for Java}, rather than uses.)
+See also @uref{http://openjdk.java.net/jeps/8043488}.
+
address@hidden Optimized function types and values using MethodHandles
address@hidden(GSoC)}
+
+Kawa doesn't have true function types: Parameter and result types
+are only handled for ``known'' functions. The general case with
+optional and keyword parameter is complicated, but simple
+fixed-arity procedure types would be very useful.
+
+The following syntax is suggested:
address@hidden
+procedure[(@var{T1} .. @var{Tn}) @var{Tr}]
address@hidden example
address@hidden through @var{T1} are types of the parameters, and
address@hidden is the type of the result.
+For example: @code{procedure[(vector int) string]}.
+We call this a typed-procedure type (in contrast to plain @code{procedure}).
+
+If a value has a typed-procedure type then its run-time representation
+is a just a @code{MethodHandle}. If such a procedure is called,
+the generated bytecode is to just call its @code{invokeExact} method.
+The argument expressions are converted (and type-checked) the same
+way as if we were calling a statically-known procedure.
+
+Note that passing an @code{int} argument
+of to @code{procedure[(vector int) string]} value does @emph{not}
+require allocating an object to ``box'' the @code{int};
+we can pass a plain @code{int} as-is.
+Thus using typed-procedure types can lead to major speed-up.
+For example the @code{lib-test.scm} should become much faster.
+
+Converting a known procedure to a typed-procedure type is usually
+just a matter of creating a @code{MethodHandle} that references the
+method implementing the procedure. Some glue code may be needed
+if the types aren't identical, or if the procedure is a closure.
+
+Converting a type-procedure value @code{p} to generic value (such
+as untyped @code{procedure} or @code{object}) can be though of as
+wrapping it in a @code{lambda}:
address@hidden
+((lambda (arg1::vector arg2::int)::string (p arg1 arg2))
address@hidden example
+
+Coercing a generic value or an untyped procedure to a typed-procedure would
+need to generate a method whose signature matches the typed-procedure type,
+and in the body of the method use a generic apply.
+
+Coercing from one typed-procedure type to a different typed-procedure type
+is a combination of the above techniques (as if converting first to object and
+then to the target type), though some optimizations are worth doing.
+
+Adding varargs support can be done later.
+
address@hidden Later, we might consider merging @code{MHProcedure} and
@code{PrimProcedure}.
+
+We need a fall-back mechanism for platforms (such as Android)
+that don't support @code{MethodHandle}s. The easiest is to
+just treat a typed-procedure type as plain @code{procedure} at run-time,
+though we still want the compile-time type-checking,
+
address@hidden Full continuations
address@hidden being worked on.}
+
+Add support for full continuations, which is the major
+feature missing for Kawa to qualify as a ``true Scheme''.
+One way to implement continuations is to add a add that converts
+the abstract syntax tree to continuation-passing-style, and then
+expand the existing full-tail-call support to manage a stack.
+There are other ways to solve the problem.
+This may benefit from @ref{task-faster-tailcalls,Faster tailcalls}.
+
address@hidden Faster tailcalls
address@hidden
+Make @code{--full-tailcalls} run faster.
+This may depend on (or incorporate)
address@hidden,TreeList-optimization}.
+
address@hidden
address@hidden TreeList-optimization
+The
@uref{http://www.gnu.org/software/kawa/api/gnu/lists/TreeList.html,TreeList}
class is a data structure for ``flattened'' trees. It is used for
+XML-style nodes, for multiple values, and for the full-tail-call API.
+The basic concept is fine, but it could do with some re-thinking
+to make make random-access indexing fast. Also, support for updating
+is insufficient. (This needs someone into designing and hacking on
+low-level data-structures, along with lots of profiling and testing.)
+
address@hidden Asynchronous evaluation
+
+C# recently added @code{asynch} and @code{await} keywords
+for @uref{http://msdn.microsoft.com/en-us/vstudio/gg316360,asynchronous
programming}. Kawa's recently improved support for lazy programming
+seems like a good framework for equivalent functionality:
+Instead of an @code{asynch} method that returns a @code{Task<T>},
+the Kawa programmer would write a function that returns a @code{lazy[T]}.
+This involves some design work, and modifying the compiler to
+rewrite the function body as needed.
+
+This is related to full continuations, as the re-writing is similar.
+
address@hidden
address@hidden REPL console and other REPL improvement
address@hidden being worked on.}
+
+Improvements to the read-eval-print console.
+In addition to a traditional Swing console,
+it would be useful to support using a web browser as a remote terminal,
+possibly using web-sockets.
+(This allows ``printing'' HTML-expressions, which can be a useful way
+to learn and experiment with web technologies.)
+See @uref{http://per.bothner.com/blog/2007/ReplPane/, here} for an article
+on the existing Swing REPL, along with some to-do items.
+Being able to hide and show different parts of the output might be nice.
+Being able to link from error messages to source might be nice.
+Better handling of redefinitions is discussed
address@hidden://per.bothner.com/blog/2009/REPL-for-JavaFX/, here in the
context of JavaXF Script}; this is a general REPL issue, mostly independent of
the GUI for it.
+
+An interesting possibility is to use the @uref{http://ipython.org/,IPython}
+framework. There are existing ports for Scala: either
address@hidden://github.com/mattpap/IScala,IScala}
+or @uref{https://github.com/Bridgewater/scala-notebook, Scala Notebook}.
+
address@hidden XQuery-3.0 functionality
address@hidden(GSoC, for some subset)}
+
+It would be nice to update the XQuery (Qexo) support
+to some subset of @uref{http://www.w3.org/TR/xquery-30/,XQuery 3.0}.
+
address@hidden XQuery-updates
+It would be nice to support @uref{http://www.w3.org/TR/xquery-update-10/,
XQuery updates}. This depends on
@ref{task-TreeList-optimization,TreeList-optimization}.
+
address@hidden
address@hidden Common Lisp support
+Kawa supports a small subset of the Common Lisp language, but it supports
+a much larger subset of core Common Lisp concepts and data structures, some
+designed with Common Lisp functionality in mind. Examples include
+packages, arrays, expanded function declarations, type specifications,
+and format. A lot could be done to improve the Common Lisp support
+with modest effort. Some Common Lisp features could also be useful
+for Scheme: Documentation strings (or markup) as Java annotations,
+better MOP-like introspection, and generic methods a la defmethod
+(i.e. with multiple definition statements, possibly in separate files,
+as opposed to the current make-procedure) all come to mind.
+Being able to run some existing Common Lisp code bases with
+at most modest changes should be the goal.
+One such package to start with might be an
address@hidden://aperiodic.net/phil/archives/Geekery/notes-on-lisp-testing-frameworks.html,existing
test framework}, perhaps
address@hidden://common-lisp.net/project/bese/FiveAM.html, FivaAM}.
+Full Common Lisp compatibility is nice, but let's walk before we can run.
+
address@hidden JEmacs improvements
+
address@hidden(GSoC, for some subset)}
+
+A lot of work is needed to make
address@hidden://jemacs.sourceforge.net/,JEmacs} useful.
+One could try to import a useful package and see what works and what fails.
+Or one may look at basic editing primitives.
+Enhancements may be needed to core Emacs Lisp language primitives
+(enhancing @ref{task-common-lisp, Common Lisp support} may help),
+or to the display engine.
+
+Emacs now supports
@uref{http://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html,lexical
bindings} - we should do the same.
+
address@hidden Improved IDE integration
+There is some Kawa support for Eclipse (Schemeway), and possibly
+other IDEs (NetBeans, IntelliJ). But many improvements are
+desirable.
address@hidden, REPL improvements} may be a component of this.
+
address@hidden Plugin for NetBeans IDE
+
+Kawa-Scheme support for the NetBeans IDE would be useful.
+One could perhaps build on the Clojure plugin.
+
address@hidden Plugin for Eclipse IDE
+
+Kawa-Scheme support for the Eclipse IDE would be useful.
+Probably makes sense to
+enhance @uref{http://sourceforge.net/projects/schemeway/,SchemeWay}.
+It may also make sense to build on
+the @uref{http://www.eclipse.org/dltk/,Dynamic Languages Toolkit},
+possibly making use of @uref{http://schemeide.sourceforge.net/,Schemeide},
+though DLTk seems more oriented towards interpreted non-JVM-based languages.
+
address@hidden Improve Emacs integration
+
address@hidden://en.wikipedia.org/wiki/SLIME, SLIME} is an Emacs mode
+that provides IDE-like functionality. It supports Kawa.
+
address@hidden://jdee.sourceforge.net/,JDEE} is a Java development environment,
+so might have better hooks to the JVM and Java debugging architecture.
+
address@hidden://cedet.sourceforge.net/,CEDET} is a more general
+framework of development tools.
+
address@hidden Hop-style web programming
address@hidden://hop.inria.fr/,Hop} is an interesting design
+for integrating server-side and client-side programming using
+a Scheme dialect. These ideas seem like they would port
+quite well to Kawa.
+
address@hidden String localization
+
address@hidden(GSoC)}
+
+Support localization by extending the
address@hidden://srfi.schemers.org/srfi-109/srfi-109.html,SRFI_109}
+syntax, in the manner of (and compatible with)
address@hidden://www.gnu.org/software/gettext/,GNU gettext}.
+I.e. optionally specify a localization key (to use as an index
+in the translation database); if there is no key specified,
+default to using the literal parts of the string.
+
address@hidden Data binding
+Implement a ``bind'' mechanism similar to that
+of @uref{http://docs.oracle.com/javafx/1.3/tutorials/core/dataBinding/,JavaFX
Script}.
+The idea is that when you initialize a variable or field,
+instead of initializing it to a fixed value, you bind it to
+an expression depending on other variables.
+We install ``listeners'' on those variables, so when those variables
+change, we update the bound variable.
+This feature is useful in many applications, but the initial
+focus could be GUI programming and perhaps web programming.
address@hidden Note in general the result is a ``text'', which is a
generalization
address@hidden of a string: A text is a sequence of characters *or* other
values.
address@hidden If an embedded expression evaluates to a non-string, it is
@emph{not}
address@hidden automatically converted to a string. Conversion to a string
address@hidden is done on demand, for example on printing.
address@hidden (This is similar to values in the XML data model.)
+
address@hidden Decimal arithmetic and repeated decimals
+
address@hidden(GSoC. Possibly a bit light for a full Summer project,
+but can be extended or combined with other projects.)}
+
+Exact decimal arithmetic is a variation of exact rational arithmetic,
+but may be more user-friendly. In particular, printing using
+decimals is generally nicer than fractions.
+It is also sometimes useful to specify an explicit scale,
+so we can distinguish 0.2 from 0.20.
+We can use the Java @code{BigDecimal} class, but run into problems
+with division - for example @code{(/ 1.0 3.0)}.
+We should implement a subclass of @code{RatNum} that generalizes
address@hidden to also handle repeating decimals.
+We need a lexical syntax for repeating decimals.
+Possible ideas: @code{0._81_} or @code{0.#81}.
+If a Scheme number literal is specified as exact and has either
+a decimal point or an exponent (for example @code{#e1.25}), then it should
+read as an exact decimal, not a fraction.
+
address@hidden Optional strict typing along with an explicit @code{dynamic} type
+
address@hidden(GSoC)}
+
+Kawa currently implements ``optimistic'' typing: The compiler only
+complains if an expression has no values in common with the target type
+- for example, if assigning a @code{string} expression to an @code{integer}
+variable.
+It would be interesting to experiment with a
address@hidden option (which would never be the default):
+Strict typing would only allow ``widening'' conversions - i.e.
+that the expression type be a subtype of the target type.
+For example it would complain if assigning a @code{number} to an @code{integer}
+unless you used an explicit cast.
+
+To make this easier to work with we'd make use
+of the @ref{dynamic-type,@code{dynamic} type}, similar to
address@hidden://msdn.microsoft.com/en-us/library/dd264736.aspx,what
address@hidden does}: Any expression can be converted
+to or from @code{dynamic} without the compiler complaining.
+Similarly, if @code{x} is @code{dynamic} then @code{x:name}
+is allowed by the compiler regardless of @code{name}, with all checking
+being deferred to run-time. If a variable is declared without a type,
+it should default to @code{dynamic}. The @code{dynamic} type
+is represented in the VM as @code{object} but with an annotation
+(like we do with @code{character}).
+
+The type-checker might need some changes to better distinguish
+implicit conversions from explicit casts.
+
address@hidden Installation
address@hidden Getting and installing Kawa
+
address@hidden
+* Getting Kawa::
+* Running Java:: Getting and running Java
+* Binary distribution:: Installing and using the binary distribution
+* Source distribution:: Installing and using the source distribution
address@hidden menu
+
address@hidden Getting Kawa, Running Java, , Installation
address@hidden Getting Kawa
+
+You can compile Kawa from the source distribution.
+Alternatively, you can install the pre-compiled binary distribution.
+
+You can get Kawa sources and binaries from the Kawa ftp site
address@hidden://ftp.gnu.org/pub/gnu/kawa/},
+or from a @uref{http://www.gnu.org/order/ftp.html,mirror site}.
+
+The current release of the Kawa source code is
address@hidden://ftp.gnu.org/pub/gnu/kawa/address@hidden
+(To unpack @code{.tar.gz} files Windows users can use
address@hidden://www.7-zip.org/,7-Zip}, which is Free Software.)
+
+The corresponding pre-compiled release
+is @uref{ftp://ftp.gnu.org/pub/gnu/kawa/address@hidden
+The most recent snapshot is
address@hidden://ftp.gnu.org/pub/gnu/kawa/kawa-latest.zip}.
+Instructions for using either are @ref{Binary distribution,here}.
+
address@hidden Getting the development sources using Git
+
+The Kawa sources are managed using a
address@hidden://gitlab.com/kashell/Kawa,git} repository.
+If you want the very latest version grab
address@hidden://git-scm.com/downloads,a git client},
+and then check out the source using this command:
address@hidden
+git clone https://gitlab.com/kashell/Kawa.git
address@hidden example
+
+After a checkout you will need to run:
address@hidden
+./autogen.sh
address@hidden example
+before proceding with instructions for @ref{Source distribution,building the
source distribution}.
+
+Once you have it checked out, you can keep it up-to-date with @code{git pull}.
+
+You can also
address@hidden://gitlab.com/kashell/Kawa/tree/master,browse the git archive}
online.
+
address@hidden Running Java, Binary distribution, Getting Kawa, Installation
address@hidden Getting and running Java
+
+Before installing Kawa, you will need a working Java system.
+The released Kawa jar file assumes Java 8 or newer.
+You need to build Kawa from source if you have Java 5, Java 6,
+or are targeting Android.
+(Older versions of Kawa have been reported to
+work with JDK from 1.1, Kaffe, Symantec Cafe, J++, and GCJ,
+but these are no longer supported.)
+
+The discussion below assumes you are using the Java Developer's Kit
+(JDK) from Oracle. You can download free copies of
address@hidden://www.oracle.com/technetwork/java/javase/downloads/index.html,
JDK 8} for various platforms.
+
address@hidden If you want to run Kawa on a Macintosh, see
address@hidden @uref{http://rdsathene.org/scheme/mackawa.html}.
+
+The program @code{java} is the Java interpreter.
+The program @code{javac} is the Java compiler,
+and is needed if you want to compile the source release yourself.
+Both programs must be in your @code{PATH}.
+If you have the JDK in directory @code{$JAVA_HOME},
+and you are using a Bourne-shell compatible shell
+(/bin/sh, ksh, bash, and some others) you can set @code{PATH} thus:
address@hidden
+PATH=$JAVA_HOME/bin:$PATH
+export PATH
address@hidden example
+
address@hidden Binary distribution
address@hidden Installing and using the binary distribution
+
+The binary release comes as a @code{.zip} archive that
+includes Kawa itself (as a @code{.jar} file @address@hidden),
+some third-party helper libraries, @code{kawa} command scripts
+(for GNU/Linux/Unix/MacOS or Windows),
+and documentation (basically this manual).
+
+After downloading (see @ref{Getting Kawa}), extract the files
+from the @code{.zip} archive using a suitable @code{unzip} program,
+which will create a directory @address@hidden,
+with @code{lib}, @code{bin}, and @code{doc} sub-directories.
+In the following, we assume the environment variable @code{KAWA_HOME}
+refers to this directory:
address@hidden
+unzip ~/Downloads/address@hidden
+export KAWA_HOME=`pwd`/address@hidden
address@hidden example
+
+The binary release requires Java 8 or later.
+If you have an older Java implementation, or build for a mobile
+environment like Android,
+then you will need to get the source distribution.
+
+If you want to use Kawa as part of some other application,
+you just need the @code{$KAWA_HOME/lib/kawa.jar}.
+
address@hidden Running the @code{kawa} command
+
+To run a Kawa script file or the Kawa read-eval-print-loop
+run the Kawa application. There are various way to do so.
+
+The recommended way is to execute the @code{$KAWA_HOME/bin/kawa} Bash
+shell script.
+This should work on most Unix-like platforms that have Bash installed,
+including GNU/Linux, BSD, MacOS, and Cygwin/MingW.
+(Please report if you have problems.)
+
+The script assumes that either a suitable @code{java} program is
+in your @code{PATH}; or the @code{JAVA} environment variable
+names a suitable @code{java} executable; or that @code{JAVA_HOME}
+is set so @code{$JAVA_HOME/bin/java} is suitable.
+
+If you want to put @code{kawa} in your search path you can of course do:
address@hidden
+PATH=$KAWA_HOME/bin:$PATH
address@hidden example
+Alternatively you can create a symbolic link in an already-searched directory.
+For example:
address@hidden
+cd /usr/local/bin
+ln -s $KAWA_HOME/bin/kawa kawa
address@hidden example
+
+The @code{bin/kawa.bat} script works on Windows.
+
+Both scripts add some helper libraries, including support for input editing.
+
+It is also possible to run Kawa using @code{java} directly:
address@hidden
+java -jar $KAWA_HOME/lib/kawa.jar
address@hidden example
+or:
address@hidden
+CLASSPATH=$KAWA_HOME/lib/kawa.jar
+export CLASSPATH
+java kawa.repl
address@hidden example
+On Windows:
address@hidden
+set classpath=%KAWA_HOME%\lib\kawa.jar
address@hidden example
+
+To run Kawa in a fresh window use the -w flag:
address@hidden
+kawa -w
address@hidden example
+or
address@hidden
+java kawa.repl -w
address@hidden example
+
address@hidden Reading the documentation
+
+The file @code{doc/kawa-manual.epub} contains the Kawa documention
+packaged as an electronic book, which is readable by most
+e-book readers. Plugins are also available for common browsers,
+for example @uref{http://www.epubread.com,EPUBReader} for @code{firefox}.
+
+Even easier is to invoke
address@hidden,@code{bin/kawa --browse-manual}}
+(or on Windows: @code{bin\kawa.bat --browse-manual}).
+
+An @code{epub} is essentially a zip archive, which you can unzip:
address@hidden
+cd $KAWA_HOME/doc
+unzip kawa-manual.epub
address@hidden example
+Then you can use a plain browser
+with the URL @code{file:$KAWA_HOME/doc/OEBPS/index.xhtml}.
+
address@hidden Source distribution, , Binary distribution, Installation
address@hidden Installing and using the source distribution
+The Kawa release normally comes as a gzip-compressed tar file named
address@hidden@value{VERSION}.tar.gz}.
address@hidden The same sources are available as a zip file
address@hidden @address@hidden
+Two methods are supporting for compiling the Kawa sources;
+choose whichever is most convenient for you.
+
+One method uses the traditional GNU @code{configure} script,
+followed by running @code{make}. This works well on Unix-like
+systems, such as GNU/Linux.
+You can also use this method on Microsoft Windows,
+with the help of tools from @uref{http://www.MinGW.org/, MinGW}
+or @uref{http://www.cygwin.org/, Cygwin}.
+
+The other method uses the @code{ant} command, a Java-based
+build system released by Apache's Jakarta project. This uses
+an @code{build.xml} file in place of @code{Makefile}s, and
+works on non-Unix systems such as Microsoft Windows. However,
+the @code{ant} method does not support all
+the features of the @address@hidden method.
+
address@hidden Build Kawa using @code{configure} and @code{make}
+
+(See @ref{building-on-Windows-with-make,below} for some notes for building
+on Microsoft Windows.)
+
+If you have a @code{tar.gz} file, first unpack that in your build directory:
address@hidden
+tar xzf address@hidden
+cd address@hidden
address@hidden example
+
+If you're building from the Git repository, you need to
+generate @code{configure} and some other files. This is
+easiest done with the @code{autogen.sh} script:
address@hidden
+./autogen.sh
address@hidden example
+
+Then you must configure the sources. This you do in
+the same way you configure most other GNU software. Normally
+you can just run the configure script with no arguments:
+
address@hidden
+./configure
address@hidden example
+The @code{configure} script takes a number of @ref{configure options,options}.
+
+If you have installed Kawa before, make sure your @code{CLASSPATH}
+does not include old versions of Kawa, or other classes that may
+conflict with the new ones.
+
+Then you need to compile all the .java source files.
+Just run make:
address@hidden
+make
address@hidden example
+This assumes that @samp{java} and @samp{javac} are the java interpreter
+and compiler, respectively.
+
+It has been reported that parallel make doesn't work,
+so don't use the @code{-j2} or above options.
+
+You can now test the system by running Kawa in place:
address@hidden
+java kawa.repl
address@hidden example
+
+or you can run the test suite:
address@hidden
+make check
address@hidden example
+
+or you can install the compiled files:
address@hidden
+make install
address@hidden example
+
+This will install your classes into @code{$PREFIX/share/java} (and its
+sub-directories). Here @code{$PREFIX} is the directory you specified
+to configure with the @code{--prefix} option, or @code{/usr/local} if you
+did not specify a @code{--prefix} option.
+
+To use the installed files, you need to set @code{CLASSPATH} so
+that @code{$PREFIX/share/java/kawa.jar} is in the path:
address@hidden
+CLASSPATH=$PREFIX/share/java/kawa.jar
+export CLASSPATH
address@hidden example
+This is done automatically if you use the @samp{kawa} script.
+
address@hidden options}
address@hidden configure options
address@hidden Configure options
+
+The @code{configure} script takes a number of options.
+The @code{--help} switch gives you a list of options.
+The following are some of the more common or important ones.
+
address@hidden @asis
address@hidden @address@hidden
address@hidden @code{--prefix @var{install-dir}}
+By default @code{make install} will install the compiled @code{.jar}
+files info @code{/usr/local/share/java},
+the @code{kawa} command into @code{/usr/local/bin},
+and so on in @code{/usr/local}.
+The @code{--prefix} option causes the files to be installed
+under @address@hidden instead of @code{/usr/local}.
+For example to install the @code{.jar} in @code{/opt/kawa/share/java}
+and otherwise use @code{/opt/kawa} do:
address@hidden
+./configure --prefix=/opt/kawa
address@hidden example
+
address@hidden @address@hidden
+As distributed, the Kawa source code requires Java 8.
+If you only have Java 7, Java 6, or Java 5, use the @code{--with-java-source}
option:
address@hidden
+./configure --with-java-source=6
address@hidden example
+
+Kawa no longer supports older verisons of Java (JDK 1.4 or older).
+It might be possible to use a tool
+like @uref{http://retroweaver.sourceforge.net/, Retroweaver}
+on the Kawa @code{.jar} to fix up Java 5 dependencies.
+Contact the Kawa author if you want to be a tester for this.
+
address@hidden @address@hidden
+Build the documentation (this manual) as an electronic book
+(in ebook format) or a website, using
+the DocBook xslt stylesheets.
+(You can build the documentation without DocBook, but using
+it enables nicer-looking and more functional documentation.)
+
+The stylesheets are found using @var{path};
+the file @address@hidden/epub3/chunk.xsl} needs to exist.
+(For example, on Fedora 25 @var{path} can be
@code{/usr/share/sgml/docbook/xsl-ns-stylesheets},
+while on Debian use @code{/usr/share/xml/docbook/stylesheet/docbook-xsl-ns}.)
+
address@hidden @code{--with-domterm}
address@hidden @address@hidden
+Compile with extra support for the @ref{Using DomTerm,DomTerm}
+terminal emulator library, where @address@hidden
+is such that @address@hidden/lib/domterm.jar} exists.
+(Some DomTerm support is built-in regardless.)
+
+If you use this option along with @code{--with-javafx}
+then creating a new @ref{REPL Console,REPL} window
+will create a DomTerm window.
+
+As an optional convenience, you can use the @code{domterm.jar}
+in the Kawa binary distribution.
+
address@hidden @code{--with-jline3}
address@hidden @address@hidden
+Build support for using @uref{https://github.com/jline/jline3,JLine 3},
+which is a library for handling console input, similar to GNU readline.
+If specified, the @var{jline3.jar} is added to the classpath of the
+generated @code{kawa.sh} or @code{kawa} shell program.
+
+An advantage of @code{--with-jline3} (compared to
address@hidden) is that the former works without native code
+(on most Unix-like platforms), and it does not require a C wrapper program.
+
+As an optional convenience, you can use the @code{jline.jar}
+in the Kawa binary distribution.
+
address@hidden @code{--with-domterm}
address@hidden @address@hidden
+Compile with extra support for the @ref{Using DomTerm,DomTerm}
+terminal emulator library. (Some DomTerm support is built-in regardless.)
+
+If you use this option along with @code{--with-javafx}
+then creating a new @ref{REPL Console,REPL} window
+will create a DomTerm window.
+
+As an optional convenience, you can use the @code{domterm.jar}
+in the Kawa binary distribution.
+
address@hidden @code{--with-servlet}
address@hidden @address@hidden
+Build support for @ref{Servlets,servlets}, which are used in web servers.
+This requires the @code{servlet-api.jar} (available various places including
address@hidden://tomcat.apache.org/,Tomcat} or
address@hidden://glassfish.java.net/,Glassfish}),
+for @code{javax.servlet.Servlet} and related classes.
+If this class isn't in your classpath, specify its location
+as @address@hidden For example:
address@hidden
+./configure --with-servlet=/path/to/servlet-api.jar
address@hidden example
+
address@hidden @code{--enable-jemacs}
+Build JEmacs (enable Emacs-like text editor) and support (a subset of)
+the Emacs Lisp language. JEmacs is a proof of concept - not really
+usable or maintained.
+
address@hidden @code{--with-javafx}
address@hidden @address@hidden
address@hidden @address@hidden
+Set this flag to enable the convenience features
+for @ref{Building JavaFX applications,JavaFX}.
+The JavaFX classes are included in JDK 8 (but not OpenJDK 8),
+and you don't need to specify @address@hidden or @address@hidden
+For JDK 7 you need to specify @address@hidden
+(the path to @code{javafx.rt}) or @address@hidden
+(the value of the @code{$JAVA_HOME}).
+
address@hidden @address@hidden
+Build for the Android platform.
+This requires @ref{Building for Android,special instructons}.
+
address@hidden @code{--enable-kawa-frontend}
+If you have the GNU @samp{readline} library installed, you might try
+adding the @samp{--enable-kawa-frontend} flag.
+This will build the
address@hidden front-end program, which provides input-line editing
+and an input history. You can get @samp{readline} from archives
+of GNU programs, including @uref{ftp://www.gnu.org/}.
+
+Note that using JLine, enabled by @code{--with-jline3},
+is now recommended instead of using the @code{readline} frontend.
+
+You may need to specify to @code{make} where to find
+the @code{readline} include files (with @code{READLINE_INCLUDE_PATH})
+and the library (with @code{READINE_LIB_PATH}).
+For example on OS/X you need to do:
address@hidden
+make READLINE_INCLUDE_PATH=-I/usr/local/unix/readline/include \
+ READLINE_LIB_PATH=-L/usr/local/unix/readline/lib
address@hidden example
address@hidden table
+
address@hidden
address@hidden Building on Windows using MinGW
+
+The Kawa @code{configure} and @code{make} process assumes Unix-like
+tools, which you can get from @uref{http://mingw.org, the MinGW project}.
+Download the MingGW Installation Manager, and use it to install
+at least @code{mingw-developer-toolkit}.
+(Also installing @code{msys-groff} avoids a minor problem
+building the documentation.)
+
+The @code{C:\MinGW\msys\1.0\msys.bat} script creates a command window
+with the @code{bash} shell and the @code{PATH} set up as needed.
+Alternatively, you can use the standard Windows command prompt
+if you set your @code{PATH} as described in
@uref{http://mingw.org/wiki/Getting_Started, here}.
+
address@hidden Building on Windows using Cygwin
+
+The free @uref{http://sourceware.org/cygwin/,Cygwin}
+environment can be used for building Kawa: The Kawa configure script
+recognizes Cygwin, and modifies the classpath to use Windows-style
+path separators.
+
+Beyond the base packages, you probably want to install @code{autoconf},
address@hidden, @code{git}, @code{texinfo}, @code{groff},
address@hidden, and @code{diffutils}.
+
+Cygwin (unlike MinGW) has a current version of @code{makeinfo}, but
+an undiagnosed bug still prevents building @code{kawa.info}.
+You can work around that problem with @code{touch doc/kawa.info}.
+
address@hidden Building the documentation
+
address@hidden Plain HTML documentation
+
+You can build a plain HTML version of the documentation
+(using @code{makeinfo} from the @code{texinfo} distribution):
address@hidden
+cd doc && make kawa-html/index.html
address@hidden example
+
+In this case, point your browser at
address@hidden:/@var{kawa_srcdir}/doc/kawa-html/index.html}.
+
address@hidden Fancier HTML documentation
+
+To build the documentation in a nicer form suitable for a web-site
+you need @code{makeinfo} @emph{and} the DocBook XSLT tools
+(and to have run @code{configure} with
+the @code{--with-docbook-stylesheet} option):
address@hidden
+cd doc && make web/index.html
address@hidden example
+
+You can then point your browser at
@code{file:/@var{kawa_srcdir}/doc/web/index.html}.
+
address@hidden Using ebook readers or the --browse-manual option
+
+To build an @code{EPUB} file suitable for ebook readers,
+as well as enabling support for the
address@hidden,@code{kawa --browse-manual} option}, do:
+
address@hidden
+cd doc && make kawa-manual.epub
address@hidden example
+
+This also requires the DocBook XSLT tools.
+
address@hidden Building a printable PDF file
+
+To build a @code{pdf} file suitable for printing or online viewing do:
address@hidden
+cd doc && make kawa.pdf
address@hidden example
+
+The resulting @code{kawa.pdf} is somewhat unsatisfactory - when viewed online,
+links aren't clickable. Furthermore, box drawing characters are missing.
+
address@hidden Build Kawa using @code{ant}
+
+Kawa now includes an Ant buildfile (@code{build.xml}).
address@hidden://ant.apache.org, Ant} is a part of the Apache
+Jakarta project.
+If you don't hava Ant installed,
+get it from @uref{http://ant.apache.org/bindownload.cgi}.
+The build is entirely Java based and works equally well on *nix, Windows,
+and presumably most any other operating system.
+
+Once Ant has been installed and configured (you may need to set the
address@hidden, and @code{ANT_HOME} environment variables), you should
+be able to change to the directory containing the @code{build.xml} file,
+and invoke the @samp{ant} command. With the default settings, a
+successful build will result in a @address@hidden in the
+current directory.
+
+There are a few Ant "targets" of interest (they can be supplied on the
+Ant command line):
+
address@hidden @code
address@hidden all
+This is the default, it does @code{classes} and @code{jar}.
address@hidden classes
+Compiles all the files into @code{*.class} files into the directory
+specified by the @code{build.dir} property.
address@hidden jar
+Builds a jar into into the directory
+specified by the @code{dist.dir} property.
address@hidden runw
+Run Kawa in a GUI window.
address@hidden clean
+Deletes all files generated by the build, including the jar.
address@hidden table
+
+There is not yet a @code{test} target for running the testsuite.
+
+There are various ``properties" that control what @code{ant} does. You can
+override these on the command line or by editing the
address@hidden file in the same directory as @code{build.xml}.
+For example, the @code{build.dir} property tells @code{ant} where to
+build temporary files, and where to leave the resulting @code{.jar}
+file. For example, to leave the generated files in the sub-directory
+named @code{BUILD} do:
address@hidden
+ant -Dbuild.dir=BUILD
address@hidden example
+A sample @code{build.properties} is provided and it contains
+comments explaining many of the options.
+
+Here are a few general properties that help to customize your build:
address@hidden @code
address@hidden build.dir
+Path to put the temporary files used for building.
address@hidden dist.dir
+Path to put the resulting jar file.
address@hidden version.local
+A suffix to add to the version label for your customized version.
address@hidden debug
+Whether (true/false) the Javac "-g" option is enabled.
address@hidden optimize
+Whether (true/false) the Javac "-O" option is enabled.
address@hidden table
+
+Here are some Kawa-specific ones (all @code{true}/@code{false}):
address@hidden, @code{with-references}, @code{with-awt},
address@hidden, @code{enable-jemacs}, and @code{enable-servlet}>
+See the sample @code{build.properties} for more information on these.
+
+If you change any of the build properties, you will generally want to do
+an @samp{ant clean} before building again as the build is often not able to
+notice that kind of change. In the case of changing a directory path,
+you would want to do the @code{clean} before changing the path.
+
+A special note for NetBeans users:
+For some reason the build-tools target which compiles an Ant task won't
+compile with the classpath provided by NetBeans.
+You may do @samp{ant build-tools} from the command line outside of NetBeans,
+in which case you will not want to use the @code{clean} target as that
+will delete the tool files as well.
+You can use the @code{clean-build} and/or @code{clean-dist}
+targets as appropriate. Alternatively you can add @code{ant.jar} to the
address@hidden classpath by copying or linking it into a @code{lib/ext}
+directory in Kawa's source directory (the one containing the @code{build.xml}
+file).
+
address@hidden
address@hidden Compiling Kawa to native code with GCJ
+
address@hidden GCJ is no longer supported. This section is for historial
+reference, or if someone enhances GCJ enough to support Kawa.}
+
+The GNU Compiler for the Java(tm) Programming Language
+(@uref{http://gcc.gnu.org/java/,GCJ}) is part of the
+GNU Compiler Collection (@uref{http://gcc.gnu.org/,GCC}).
+It can compile Java source or bytecode
+files into native code on supported systems.
+Version 4.1 or later of GCC is recommended,
+and only Intel x86-based Linux/GNU system have been tested with Kawa.
+
+First, get and install GCC. Set @code{PREFIX} to where
+you want to install GCJ, and configure it with these options:
address@hidden
+./configure --enable-threads --enable-languages=c++,java --prefix $PREFIX
+make bootstrap
+make install
address@hidden example
+Make sure @code{gcj} is in your path and refers to the newly-installed
+version, and if needed, set @code{LD_LIBRARY_PATH} to point to the
+directory where @code{libgcj.so} was installed:
address@hidden
+PATH=$PREFIX/bin:$PATH
+LD_LIBRARY_PATH=$PREFIX/lib
+export LD_LIBRARY_PATH
address@hidden example
+
+To build Kawa, you need to specify @code{--with-gcj} to
address@hidden which tells it to use GCJ.
address@hidden
+./configure --with-gcj --prefix $PREFIX
address@hidden example
+Then as before:
address@hidden
+make
+make install
address@hidden example
+
+Alternatively, you can use configure option
address@hidden This allows gcj to automatically
+find the kawa shared libraries from the @code{.jar} file.
address@hidden ignore
+
address@hidden Tutorial
address@hidden Kawa Scheme Tutorial
+
address@hidden is obviously incomplete, but it may be useful,
+especially if you're starting with Kawa from scratch.}
+If you're new to Scheme you might also check out one of these tutorials:
+Takafumi Shido's
address@hidden://www.shido.info/lisp/idx_scm_e.html,Yet Another Scheme
Tutorial};
address@hidden dead link Greg Badross
@uref{http://www.cs.washington.edu/education/courses/341/99suq/lectures/scheme/,lecture
notes};
+Dorai Sitaram's
@uref{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme-Z-H-1.html,Teach
Yourself Scheme in Fixnum Days}; or
+Paul Wilson's
@uref{ftp://ftp.cs.utexas.edu/pub/garbage/cs345/schintro-v14/schintro_toc.html,An
Introduction to Scheme and its Implementation}.
+
address@hidden
+* Tutorial - Introduction:: Introduction
+* Tutorial - Booleans:: Booleans
+* Tutorial - Numbers:: Numbers
+* Tutorial - Functions:: Functions
+* Tutorial - Variables:: Variables
+* Tutorial - Pictures:: Pictures
+* Tutorial - Sequences:: Lists and sequences
+* Tutorial - Objects:: Creating and using objects
+* Tutorial - Types:: Types and declarations
+* Tutorial - Exceptions and errors::
+* Tutorial - Classes:: Classes
+* Tutorial - Other Java features::
address@hidden menu
+
address@hidden Tutorial - Introduction
address@hidden Introduction
+You've heard about all the hot scripting languages
+-- you might even be tired of hearing about them.
+But Kawa offers you something different than the
+scripting-language @i{du-jour} can.
+You may be interested in one that runs on the Java virtual machine,
+either because you have to interact with other Java tools,
+or because you like having access to all the Java packages out there.
+Or maybe you don't care about Java, but you care about performance.
+If so, let me tell you about Kawa, which is actually one of the
+very oldest language implementations running on the Java Virtual Machine,
+dating back to 1996.
+
+The Kawa language is a dialect/implementation of the Scheme language.
+(The Kawa project also supports other languages, including
address@hidden://www.w3.org/XML/Query,XQuery}
+and @uref{http://jemacs.sourceforge.net,Emacs Lisp},
+as well as tools for implementing mew programming languages,
+but we won't cover that in this tutorial.)
+
address@hidden://www.schemers.org/,Scheme}
+is an established language with many
address@hidden://community.schemewiki.org/?scheme-faq-standards#implementations,implementations},
+a @uref{http://www.schemers.org/Documents/Standards/,standard} specification
+(the traditional @uref{http://www.schemers.org/Documents/Standards/R5RS/,R5RS},
address@hidden://www.r6rs.org/,R6RS} which was ratified in 2007,
+and @uref{http://www.r7rs.org/,R7RS} which was ratified in 2013),
+and is used by universities for both teaching and research.
+Scheme also has a reputation for being difficult to learn,
+with a weird parenthesis-heavy syntax,
+and hard-to-understand concepts like
@uref{http://en.wikipedia.org/wiki/Continuation,continuations}.
+Luckily, you don't need to understand continuations!
+(Kawa doesn't fully implement them anyway.)
+
+The following assumes that Kawa is already installed on your computer;
+if not see these @ref{Installation,installation instructions}.
+Running the @code{kawa} command in interactive mode
+is a good way start learning Kawa:
address@hidden
+$ @kbd{kawa}
+#|kawa:1|# @kbd{}
address@hidden example
+If you don't have @code{kawa} but you have a
+Kawa ``jar'' and you have Java installed you can instead do:
+
address@hidden
+$ @kbd{java -jar address@hidden
+#|kawa:1|# @kbd{}
address@hidden example
+
+The prompt string has the form of a Scheme comment,
+to make it easier to cut-and-paste.
+Kawa is expecting you type in an expression or command,
+which it will evaluate, and then print out the result.
+For example, a quoted string is a simple expression that evaluates to a
+string value, which will print as itself, before printing the next prompt:
+
address@hidden
+#|kawa:1|# @kbd{"Hello, world!"}
+Hello, world!
+#|kawa:2|# @kbd{}
address@hidden example
address@hidden Thus the Kawa equivalent of the traditional
address@hidden @uref{http://en.wikipedia.org/wiki/Hello_world,``hello world''}
is trivial.
+
+The most noticable difference from most other programming languages
+is that Scheme uses ``prefix'' notation for function calls.
+For example Kawa has a function @code{max} which returns the
+largest value of the arguments.
+Instead of @code{max(5, 7, 3)}
+you write @code{(max 5 7 3)}:
+
address@hidden
+(max 5 7 3) @result{} 7
address@hidden example
+
+(We use the @address@hidden symbol above to indicate that
+the expression @code{(max 5 7 3)} evaluates to the
+value @code{7}.)
+
+The prefix notation may feel a bit weird, but you quickly
+get used to it, and it has some advantages.
+One is consistency: What are special infix operators in most languages
+are just regular functions in Scheme.
+For example, addition is just a regular function call,
+and @code{+} is just a regular function name:
address@hidden
+(+ 2.5 1.2) @result{} 3.7
address@hidden example
+
+The same prefix notation is used for special operations like assignments:
address@hidden
+#|kawa:1|# @kbd{(set! sqrt-of-2 (sqrt 2))}
+#|kawa:2|# @kbd{sqrt-of-2}
+1.4142135623730951
address@hidden example
+
address@hidden Tutorial - Booleans
address@hidden Booleans
+
+Scheme uses the syntax @code{#t} and @code{#f}
+for Boolean true and false value, respectively. For example, the
+``less-than'' function is named @code{<}.
+Its result is true if the first argument is less than the second (or, if
+there are more than two arguments, that they are in increasing order):
address@hidden
+(< 3 4) @result{} #t
+(< -3 -4) @result{} #f
+(< 2 3 5 7 11)) @result{} #t
address@hidden example
+
+The @code{if} special form takes two or three sub-expressions:
+It evaluates the first expression.
+If that is true it evaluates the second expression;
+otherwise it evaluates the third expression, if provided:
address@hidden
+(if (< 3 4) (+ 5 5) (+ 5 6)) @result{} 10
address@hidden example
+
+We call @code{if} a special form rather than a function,
+because for a function all the arguments are evaluated before the
+function is called, but in a special form that is not neceassarily the case.
+
+In addition to @code{#t} any value except @code{#f}
+counts as ``true'' when evaluating the first expression of an @code{if}:
+
address@hidden
+(if 0 (+ 5 5) (+ 5 6)) @result{} 11
address@hidden example
+
+You can use @code{and}, @code{or},
+and @code{not} to create complex boolean expressions.
+Of these @code{and} and @code{or}
+are special forms that only evaluate as many of the sub-expressions as needed.
address@hidden
+(if (not (and (>= i 0) (<= i 9)))
+ (display "error"))
address@hidden example
+
+You can use the @code{cond} form as an alternative to
address@hidden:
address@hidden
+(cond ((< 3 3) 'greater)
+ ((> 3 3) 'less)
+ (else ’equal)) @result{} equal
address@hidden example
+
+The null value (written as @code{#!null} in Kawa or @code{null} in Java)
+is also considered as false.
+
address@hidden Tutorial - Numbers
address@hidden Numbers
+
address@hidden Exact integers and fractions
+
+Kawa has the usual syntax for decimal integers.
+Addition, subtraction, and multiplication
+are written using the usual @code{+},
address@hidden, and @code{*},
+but these are all prefix functions that take a variable number of arguments:
+
address@hidden
+(+ 1 2 3) @result{} 6
+(- 10 3 4) @result{} (- (- 10 3) 4) @result{} 3
+(* 2 -6) @result{} -12
address@hidden example
+
+Kawa has arbitrary-precision integers.
+
+Let us implement the @uref{http://en.wikipedia.org/wiki/Factorial,factorial}
function.
+Type in the following (we'll look at the syntax shortly):
address@hidden
+#|kawa:1|# @kbd{(define (factorial x)}
+#|(---:2|# @kbd{ (if (< x 1) 1}
+#|(---:3|# @kbd{ (* x (factorial (- x 1)))))}
address@hidden example
+
+(The prompt changes to indicate a continuation line.)
+This binds the name @code{factorial}
+to a new function, with formal parameter @code{x}.
+This new function is immediately compiled to Java bytecodes,
+and later a JIT compiler may compile it to native code.
+
+A few tests:
address@hidden
+#|kawa:4|# @kbd{(list (factorial 3) (factorial 4))}
+(6 24)
+#|kawa:5|# @kbd{(factorial 30)}
+265252859812191058636308480000000
address@hidden example
+
address@hidden Floating-point real numbers
+
+Given what was said above about being able to add, subtract and multiply
integers,
+the following may be unexpected:
+
address@hidden
+#|kawa:1|# (/ 2 3)
+2/3
+#|kawa:2|# (+ (/ 1 3) (/ 2 3))
+1
address@hidden example
+
+In many languages, dividing two integers, as 2/3, would result in 0. At best,
+the result would be a floating point number, similar to 0.666667. Instead,
+Kawa has a @emph{rational} number type, which holds the results of divisions
address@hidden, as a proper fraction. Hence, adding one third to two thirds
+will always result in exactly one.
+
+Floating-point real numbers are known in Kawa as @emph{inexact} numbers, as
+they cannot be stored exactly. Consider:
+
address@hidden
+#|kawa:3|# (exact? 2/3)
+#t
+#|kawa:4|# (exact? 0.33333333)
+#f
+#|kawa:5|# (exact->inexact 2/3)
+0.6666666666666666
address@hidden example
+
+The first two examples check numbers for being @code{exact?}; there is a
+corresponding @code{inexact?} test. The last shows how an exact number can be
+converted to an inexact form.
+
+Numbers are converted between exact and inexact versions when required
+within operations or procedures:
+
address@hidden
+#|kawa:6|# (+ 0.33333333 2/3)
+0.9999999966666666
+#|kawa:7|# (inexact? (+ 0.33333333 2/3))
+#t
+#|kawa:8|# (sin 2/3)
+0.618369803069737
address@hidden example
+
address@hidden Complex numbers
+
+A @emph{complex} number is made from two parts: a @emph{real} part and an
address@hidden part. They are written @code{2+3i}. A complex number can
+be manipulated just like other numbers:
+
address@hidden
+#|kawa:9|# (+ 2+3i 5+2i)
+7+5i
+#|kawa:10|# (* 2+3i 4-3i)
+17+6i
+#|kawa:11|# (integer? (+ 2+3i -3i))
+#t
address@hidden example
+
+Notice how in the last example the result is an integer, which Kawa recognises.
+
+Kawa also includes @ref{Quaternions,quaternion} numbers.
+
address@hidden Units and dimensions
+
+In many applications, numbers have a @emph{unit}. For example, 5 might be
+a number of dollar bills, a weight on a scale, or a speed. Kawa enables us
+to represent numbers as @emph{quantities}: numbers along with their unit.
+For example, with weight, we might measure weight in pounds and ounces,
+where an ounce is 1/16 of a pound.
+
+Using Kawa, we can define units for our weight measurements, and specify the
+units along with numbers:
+
address@hidden
+#|kawa:12|# (define-base-unit pound "Weight")
+#|kawa:13|# (define-unit ounce 0.0625pound)
+#|kawa:14|# 3pound
+3.0pound
+#|kawa:15|# (+ 1pound 5ounce)
+1.3125pound
address@hidden example
+
+In this example we define a base unit, the pound, and a unit based on it, the
+ounce, which is valued at 0.0625 pounds (one sixteenth). Numbers can then be
+written along with their unit (making them quantities). Arithmetic is
possible
+with quantities, as shown in the last line, and Kawa will do the smart thing
+when combining units. In this case, 1 pound and 5 ounces is combined to make
+1.3125 pounds.
+
address@hidden Tutorial - Functions
address@hidden Functions
+
+To declare a new function use @code{define},
+which has the following form:
address@hidden
+(define (@var{function-name} @var{parameter-names}) @var{body})
address@hidden example
+
+This creates a new function named @var{function-name},
+which takes @var{parameter-names} as parameters.
+When the function is called, the @var{parameter-names}
+are initialized with the actual arguments. Then @var{body}
+is evaluated, and its value becomes the result of the call.
+
+For example, in the @code{factorial} function we looked at recently,
+the @var{function-name} is @code{factorial},
+and the @var{parameter-names} is @code{x}:
+
address@hidden
+(define (factorial x)
+ (if (< x 1) 1
+ (* x (factorial (- x 1)))))
address@hidden example
+
address@hidden Anonymous functions
+
address@hidden If you just evaluate a function nameA function is an actual
variable you can evaluate xxx
+
+An @emph{anonymous} function is simply a function which does not have a name.
+We define an anonymous function using a @dfn{lambda expression}, which has
+the following form:
address@hidden
+(lambda (@var{parameter-names}) @var{body})
address@hidden example
+
+The lambda expression has the @var{parameter-names} and @var{body} of a
+function, but it has no name. What is the point of this?
+
+An important example is creating a function to act on a list, perhaps using
address@hidden The @code{map} function takes two parameters: the first is a
+function which takes a value and returns a value; the second is a list. Here,
+we want to double every number in the list.
+
+The usual way of doing this is to create a named function, called
address@hidden, and then apply it to a list:
+
address@hidden
+#|kawa:1|# (define (double x)
+#|.....2|# (* 2 x))
+#|kawa:3|# (map double (list 1 2 3 4 5))
+(2 4 6 8 10)
address@hidden example
+
+Instead, anonymous functions make it easy to create a function to work on a
+list, without having to define it in advance:
+
address@hidden
+#|kawa:4|# (map (lambda (x) (* 2 x)) (list 1 2 3 4 5))
+(2 4 6 8 10)
+#|kawa:5|# (define y 3)
+#|kawa:6|# (map (lambda (x) (* x y)) (list 1 2 3 4 5))
+(3 6 9 12 15)
address@hidden example
+
+The first example shows the double example rewritten as an anonymous function.
+The second example shows how the anonymous function can be changed to
+fit the place in which it is used: here, the value of @var{y} determines the
+value by which the list values are multiplied.
+
+Notice that we can name our anonymous functions, in just the same way we
+name any value in Kawa, using @code{define}:
+
address@hidden
+(define double
+ (lambda (n)
+ (* 2 n)))
address@hidden example
+
+although more frequently we use the short-hand for defining functions, which we
+have already met:
+
address@hidden
+(define (double n)
+ (* 2 n))
address@hidden example
+
+Anonymous functions are ``first-class values'' in Kawa, and can be passed to
+other functions as arguments (like we did with @code{map}), and they can even
+be created and returned by functions as results.
+
address@hidden Optional, rest and keyword parameters
+
+You can declare a function that takes optional arguments,
+or a variable number of arguments. You can also use keyword parameters.
+
+The following function illustrates the use of @emph{optional} arguments. The
function
+identifies an optional argument @code{z}: if the function is called with 3
arguments, @code{z}
+will be bound to the third value, otherwise it will be @code{#f}.
+
address@hidden
+(define (addup x y #!optional z)
+ (if z
+ (+ x y z)
+ (+ x y)))
address@hidden example
+
+The following examples show @code{addup} applied to 2, 3 and invalid
arguments. It is an error to
+pass just one argument or more than three: @code{x} and @code{y} are
compulsory, but @code{z} is
+optional.
+
address@hidden
+#|kawa:12|# (addup 1 2)
+3
+#|kawa:13|# (addup 1 2 3)
+6
+#|kawa:14|# (addup 1)
+/dev/stdin:14:1: call to 'addup' has too few arguments (1; min=2, max=3)
+#|kawa:15|# (addup 1 2 3 4)
+/dev/stdin:15:1: call to 'addup' has too many arguments (4; min=2, max=3)
address@hidden example
+
+In this example, a better way to define the function would be to include a
+default value for @code{z}, for when its value is not given by the caller.
+This is done as follows, with the same behavior as above:
+
address@hidden
+(define (addup x y #!optional (z 0))
+ (+ x y z))
address@hidden example
+
+You can include as many optional parameters as you wish, after the
@code{#!optional}.
+
address@hidden arguments are an alternative way to pass an undefined number of
+arguments to a function. Here is @code{addup} written with rest arguments,
+notice the variable name after the . (dot):
+
address@hidden
+(define (addup x y . args)
+ (+ x y (apply + args)))
address@hidden example
+
+The @code{args} are simply a list of all remaining values. The following now
all work, as the
+function only requires a minimum of two numbers:
+
address@hidden
+#|kawa:4|# (addup 1 2)
+3
+#|kawa:5|# (addup 1 2 3)
+6
+#|kawa:6|# (addup 1 2 3 4 5 6 7 8)
+36
address@hidden example
+
+An alternative way to identify the rest args is with @code{#!rest}:
+
address@hidden
+(define (addup x y #!rest args)
+ (+ x y (apply + args)))
address@hidden example
+
+Finally, it can be useful to identify parameters by name and, for this, Kawa
+provides @emph{keyword} arguments. Consider the following function:
+
address@hidden
+(define (vector-3d #!key x y z)
+ (make-vector x y z))
+#|kawa:40|# (vector-3d #:x 2 #:z 3 #:y 4)
+#(2 4 3)
address@hidden example
+
address@hidden is defined with three keyword arguments: @code{x}, @code{y}, and
@code{z}. When the
+function is called, we identify the name for each value by writing @code{#:}
at the start of the name.
+This allows us to write the arguments in any order. Keyword parameters can
also be given default
+values, as with optional parameters. Keyword parameters with no default
value, and no value in the caller,
+will get the value @code{#f}.
+
+In the caller, keywords are symbols with @code{#:} at the front (or @code{:} at
+the end): @ref{Keywords,read more here}.
+
+All these extended types of arguments are available both for ``named'' and for
``anonymous'' functions.
+Optional, rest and keyword arguments can be mixed together, along with the
usual arguments.
+For details @ref{Extended formals,read more here.}
+
address@hidden Tutorial - Variables
address@hidden Variables
+
+You can declare a variable using a @code{!} form.
+This takes a variable name, and an expression. It declares a new
+variable with the given name, and gives it the value of the expression.
address@hidden
+#|kawa:1|# (! binary-kilo 1024)
+#|kawa:2|# (! binary-mega (* binary-kilo binary-kilo))
+#|kawa:3|# binary-mega
+1048576
address@hidden example
+
+If you prefer, you can use @code{define} instead of @code{!}:
+
address@hidden
+#|kawa:1|# @kbd{(define binary-kilo 1024)}
+#|kawa:2|# @kbd{(define binary-mega (* binary-kilo binary-kilo))}
+#|kawa:3|# @kbd{binary-mega}
+1048576
address@hidden example
+
+The advantage of using @code{define} is that it is portable
+to other Scheme implementations.
+The advantages of using @code{!} is that it is shorter;
+it generalizes to patterns (see later);
+and it guards against accidentally ``shadowing'' a variable
+by a nested variable with the same name.
+
+A @code{!} (or @code{define}) typed into the command-line
+defines a top-level variable.
+
+You can also declare local variables, which are variables defined for
+a given block of code. For example, in the following code @code{let}
+is used to set up a local binding of @code{x} to 3: this does not affect
+the outer binding of @code{x} to 5:
+
address@hidden
+(define x 5)
+
+(let ((x 3))
+ (display x)) @result{} 3
+
+(display x) @result{} 5
address@hidden example
+
+Alternative forms for defining local variables are
address@hidden, @code{let*}, or @code{letrec}/@code{letrec*}.
+
+The differences are in the order in which definitions are made.
address@hidden evaluates all its definitions in the environment holding
+at the start of the @code{let} statement. In the following example,
+the local variables are defined using values from the global variables:
+
address@hidden
+(define x 5)
+(define y 2)
+
+(let ((x (+ 2 y)) ; uses value of global y, i.e. 2
+ (y (+ 3 x))) ; uses value of global x, i.e. 5
+ (display (list x y))) @result {} (4 8)
address@hidden example
+
address@hidden instead evaluates each definition in the environment holding
+at the start of the @code{let*} statement, along with all @emph{previous}
+local definitions. In the following example, @code{y} is now defined with the
address@hidden value of @code{x}:
+
address@hidden
+(define x 5)
+(define y 2)
+
+(let* ((x (+ 2 y)) ; uses value of global y, i.e. 2
+ (y (+ 3 x))) ; uses value of local x, i.e. 4
+ (display (list x y))) @result {} (4 7)
address@hidden example
+
address@hidden/letrec*} are similar, but allow the definition of recursive
+functions:
+
address@hidden
+(letrec ((is-even? (lambda (n) (and (not (= 1 n))
+ (or (zero? n)
+ (is-odd? (- n 1))))))
+ (is-odd? (lambda (n) (and (not (zero? n))
+ (or (= 1 n)
+ (is-even? (- n 1)))))))
+ (display (is-even? 11))) @result {} #f
address@hidden example
+
address@hidden Tutorial - Pictures
address@hidden Composable pictures
+
+The @code{pictures} library lets you create geometric shapes
+and images, and combine them in interesting ways.
+You first need to import the library:
address@hidden
+(import (kawa pictures))
address@hidden example
+The easiest way to use and learn the library
+is with a suitable REPL, where you can type
+expressions that evaluate to pictures values,
+and view the resulting pictures directly on the console.
+The easiest way is to start the @code{kawa} command with the @code{-w}
+flag. Alternatively, you can use
+a @ref{Using DomTerm,DomTerm}-based terminal emulator
+such as @code{qtdomterm} (which is shown in the image below),
+and then the @code{kawa} command.
+
address@hidden/domterm-pictures-1}
+
+The above image shows two simple examples: a filled
+circle (radius 30 pixels, color magenta), and a non-filled rotated rectangle
+(color maroon 3-pixel wide strokes).
+
+See @ref{Composable pictures} for details and more examples.
+
address@hidden Shapes and coordinates
+
+A @dfn{shape} is a geometrical figure consisting of
+one or more curves and lines. One kind of shape is a circle;
+you can create one with the @code{circle} procedure,
+specifying the radius in ``pixels''.
+
address@hidden
+#|kawa:1|# @kbd{(import (kawa pictures))}
+#|kawa:2|# @kbd{(circle 30)}
address@hidden/fill-circ-1}
address@hidden example
+It you print a shape, it will show it as a thin black curve.
+
+A @dfn{point} has two real-numbered parts: the point's x-coordinate,
+and its y-coordinate.
+The x-coordinate increases as you move right along the page/screen,
+while the y-coordinate increases as you move @emph{down}.
+(Unlike traditional mathematics, where
+the y-coordinate increases as you go up.)
+The unit distance is one ``pixel'', which is defined as CSS or HTML.
+You can create a point with @code{&P} operator.
+For example:
address@hidden
+&P[30 20]
address@hidden example
+is a point 30 pixels right and 20 pixels down from the origin point.
+To create a circle centered on that point do @code{(center 30 &P[30 20])}.
+
+The expression @code{(rectangle &P[10 20] &P[50 40])} creates
+a rectangle whose upper left corner is (10,20) and whose
+lower right corner is (50,40).
+
+A @dfn{dimension} is a pair, a width and height,
+and is written:
address@hidden
+&address@hidden @var{height}]
address@hidden example
+In addition to being used for sizes,
+a dimension is also used for relative offsets.
+For example, the previous rectangle could also
+be written @code{(rectangle &P[10 20] &D[40 20])}.
+
+You can use @code{line} to create a line.
+More generally, if you specify @var{n} points you get a
address@hidden of @var{n-1} line segments:
address@hidden
+#|kawa:3|# @kbd{(line &P[10 20] &P[50 60] &P[90 0])}
address@hidden/polyline-1}
address@hidden example
+The same line using dimensions for relative offsets:
address@hidden
+#|kawa:4|# @kbd{(line &P[10 20] &D[40 20] &D[40 -60])}
address@hidden example
+
+A @dfn{closed shape} is one whose end point is the same as its start point.
+The @code{polygon} function creates one using straight line segments
address@hidden
+#|kawa:5|# @kbd{(polygon &P[10 20] &P[50 60] &P[90 0])}
address@hidden/polygon-1}
address@hidden example
+
address@hidden Colors and filling
+
+You can override the default color (black) using the
address@hidden procedure, which takes a color and a picture
+to produce a new picture:
address@hidden
+#|kawa:6|# @kbd{(with-paint 'red (circle 32))}
address@hidden example
+
+The first argument can be either one of the standard CSS/HTML5 color
+names (such as @code{'red} or @code{'medium-slate-blue}),
+or an integer representing an sRGB color, usually written
+as a hex literal in the form @code{#xRRGGBB}:
address@hidden
+#|kawa:7|# @kbd{(with-paint #x0808FF (circle 32))}
address@hidden example
+
+The name @code{with-paint} is because the first argument
+can be not just a color, but a general ``paint'', such as
+a gradient or a background image. However, we won't go into that.
+
+If the shape is closed, you can ``fill'' its inside:
address@hidden
+(fill (circle 32))
address@hidden example
+
+You can change the color using @code{with-paint}:
address@hidden
+(with-paint 'goldenrod (fill (circle 32)))
address@hidden example
+or as an extra argument to @code{fill}:
address@hidden
+(fill 'goldenrod (circle 32))
address@hidden example
+
+draw TODO
+
address@hidden Images
+An image is a picture represented as a rectangular grid of color values.
+It may be a photograph from a camera, or be created by a painting
+program like Photoshop or gimp.
+You can use @code{image-read} to read an image from a file,
+typically a @code{.png} or @code{.jpg} file.
+
address@hidden
+#|kawa:10|# @kbd{(define img1 (image-read
"http://pics.bothner.com/2013/Cats/06t.jpg";))}
+#|kawa:11|# @kbd{img1}
address@hidden/image-cat-1a}
address@hidden example
+
address@hidden Transforms TODO
+
address@hidden
+#|kawa:12|# @kbd{(scale 0.6 (rotate 30 img1))}
address@hidden/image-cat-1b}
address@hidden example
+
address@hidden Combining and adjusting pictures TODO
+
address@hidden Using and combining pictures TODO
+
address@hidden Tutorial - Sequences
address@hidden Lists and sequences
+
+A @dfn{sequence} is a generalized array or list:
+Zero or more values treated as a compound value.
+Sequences have certain common operations, including indexing and iteration.
+(@i{Technical note:} Sequences generally implement the @code{java.util.List}
+interface, but Kawa will also treat strings and native
+Java arrays as sequences.)
+
address@hidden Lists
+
+In traditional Lisp-family languages, the @dfn{list} is the
+most important kind of sequence.
+(Don't confuse Java's @code{List} interface with Kawa's use of the
+word @i{list}. They're related, in that a Kawa ``list'' implements
+the @code{List} interface, so any @i{list} is also @code{List},
+but not vice versa.)
+
+A list is implemented as a chain of linked @dfn{pairs}.
+You can create a constant list by quoting a parenthesized list:
address@hidden
+'(3 4 (10 20 30) "a string")
address@hidden example
+
+See @ref{Lists} for details and operations.
+
address@hidden Vectors
+
+A @dfn{vector} is a sequence that is implemented by storing the elements
+side-by-side in memory.
+A vector uses less space than a list of the same length,
+and is generally more efficient than a list.
+
+To create a vector you can use a bracketed list:
address@hidden
+(! vec1 ['A 'B 'C 'D 'E 'F])
address@hidden example
+This creates a vector of 6 symbols and binds it to @code{vec1}.
+To select an element you can use the traditional
address@hidden procedure:
address@hidden
+(vector-ref vec1 3) @result{} 'D
address@hidden example
+Alternatively, in Kawa you can use function-call notation:
address@hidden
+(vec1 3) @result{} 'D
address@hidden example
+
+You can also create a vector using the traditional @code{vector} constructor:
address@hidden
+(! vec2 (vector 'A 'B 'C 'D 'E 'F))
address@hidden example
+There is one important difference between @code{vec1} and @code{vec2}:
+You can modify @code{vec2} by changing some or all of its elements.
+You can't do that for @code{vec1}.
+(We say that @code{vec1} is an @dfn{immutable} or @dfn{constant} vector,
+while @code{vec1} is a @dfn{mutable} or @dfn{modifiable} vector.)
+To change an element use either the traditional @code{vector-set!}
+procedure, or function-call notation:
address@hidden
+(vector-set! vec2 2 'Y)
+(set! (vec2 4) 'Z)
+vec2 @result{} ['A 'B 'Y 'D 'Z 'F]
+(vector-set! vec1 2 'Y) @result{} @i{throws exception}
address@hidden example
+
+See @ref{Vectors} for details and operations.
+
address@hidden Java arrays and primitive vectors
+
+See @ref{Array operations, Using Java arrays} for examples.
+
address@hidden Indexing of general sequences
+
+You can use function-call notation to index a generalized sequence,
+whether it is a list, vector, any @code{java.util.List},
+native Java array, or string:
address@hidden
+((list 'A 'B 'C 'D) 2) @result{} 'C
+("abcdef" 3) @result{} @result{}
+(! farr (float[] 1.5 3 4.5)) ;; native Java array
+(farr 2) @result{} 4.5
address@hidden example
+
+Note that indexing a list with an index @var{i} will be slow, since it
+has to step through the list @var{i} times. (So don't do that!)
+
address@hidden Ranges
+
+A @dfn{range} is a sequence of numbers in order,
+spaced uniformly apart. Usually, these are (exact) integers
+that increase by one. The usual notation is:
address@hidden
address@hidden <: @var{end}]
address@hidden example
+This is the sequence of integers starting with the integer @var{start}
+(inclusive) and ending with the integer @var{end} (exclusive).
+For example @code{[3 <: 7]} is the sequence @code{[3 4 5 6]}.
+
+The @samp{<:} is a keyword; the @code{<} is a mnemonic for the
+set of integers that are @code{<} the end value 6.
+You can also use @code{<=:} if you want to include the upper bound:
address@hidden <=: 8]} is @code{[4 5 6 7 8]}.
+
+You can use @code{>=:} or @code{>:} for a decreasing range.
address@hidden >=: 1]} or @code{[5 >: 0]} both evaluate to @code{[5 4 3 2 1]}.
+You can also specifify a step value: @code{[1 by: 2 <=: 9]},
+which evaluates to @code{[1 3 5 7 9]}.
+(@ref{Ranges,Details here}.)
+
address@hidden Using vector and ranges indexes
+
+If an index is a sequence of integers,
+the result is a new sequence (of the same type)
+selecting only the elements matching the index values.
+For example:
address@hidden
+#|kawa:2|# @kbd{(vec1 [3 5 2])}
+#(D F C)
address@hidden example
+In general, @code{((V1 V2) I)} is @code{(V1 (V2 I))}.
+
+You can use a range to create a slice - a contiguous subset of a list.
address@hidden
+#|kawa:3|# @kbd{(vec1 [2 <: 6])}
+#(C D E F)
address@hidden example
+
+A range is different from a vector integer in that you can use
+a range as the index in the LHS of a set!:
+
address@hidden
+#|kawa:4|# @kbd{(set! (vec1 [2 <: 4]) #(a b c d e))}
+#|kawa:5|# @kbd{vec1}
+#(A B a b c d e E F)
address@hidden example
+
+Notice how the number of replaced elements can be different
+then the number of elements in the replacement value.
+I.e. you can do insertion and deletion this way.
+
address@hidden
+#|kawa:7|# @kbd{(! str1 (string-copy "ABCDEF"))}
+#|kawa:8|# @kbd{(set! (str1 [2 <: 5]) "98")}
+AB98F
address@hidden example
+
address@hidden Tutorial - Objects
address@hidden Creating and using objects
+
+An @dfn{object} is a value that has the following features:
address@hidden
address@hidden
+class - each object is an instance of a specific class,
+making it part of the class hierarchy, which is an important
+aspect of the type system;
address@hidden
+properties - various fields and methods, depending on the class;
address@hidden
+identity - it is distinct from all other objects,
+even if all the properties are the same.
address@hidden itemize
+
+We later discuss @ref{Tutorial - Classes,how to write a new class}.
+Here we assume you're using an existing class, which
+could be written in Java or Scheme.
+
address@hidden Creating a new object
+
+To create a new object of class @code{T} you call @code{T} as if it
+were a function, passing it the various constructor arguments:
address@hidden
+(java.io.File "src" "build.xml")
address@hidden example
+
+If there are keyword arguments they are used to initialize
+the corresponding named properties:
address@hidden
+(! button1 (javax.swing.JButton text: "Do it!" tool-tip-text: "do it"))
address@hidden example
+This create a new @code{JButton} object (using @code{JButton}'s
+default constructor), and sets the @code{text} and @code{tool-tip-text}
+properties (by calling @code{JButton}'s @code{setText}
+and @code{setToolTipText} methods).
+If there are constructor arguments, they must come before the keywords.
+
+For objects that have components or elements, you
+can list these at the end. For example:
address@hidden
+(java.util.ArrayList 11 22 33)
address@hidden example
+This creates a fresh @code{java.util.ArrayList} (using the
+default constructor), and then calls the @code{add} method 3 times.
+
+If you prefer you can use the @code{make} procedure,
+but that only handle simple constructor calls:
address@hidden
+(make java.io.File "src" "build.xml")
address@hidden example
+
+See @ref{Allocating objects} for details.
+
address@hidden Calling instance methods
+
+Given an object @var{obj} of a class that has a method @var{meth},
+you can call it with argumens @var{v1} ... @var{v2} using @ref{Colon notation}:
address@hidden
+(@var{obj}:@var{meth} @var{v1} ... @var{v2})
address@hidden example
+For example:
address@hidden
+(button1:paintImmediately 10 10 30 20)
address@hidden example
+
+If you prefer, you can use the @code{invoke} procedure,
+normally with a quoted method name:
address@hidden
+(invoke button1 'paintImmediately 10 10 30 20)
address@hidden example
+You need to use @code{invoke} (rather than colon notation)
+if @var{obj} is a @code{Class} or a type expression, or its class
+implements @code{gnu.mapping.HasNamedParts}.
+
+See @ref{Method operations} for details.
+
address@hidden Accessing properties
+
+If @var{obj} has a field or property named @var{fld} you can also use colon
+notation:
address@hidden
address@hidden:@var{fld}
address@hidden example
+
+You use the same syntax whether @var{fld} is an actual field in the
+object, or a @dfn{property} (in the Java Beans sense). The
+latter is implemented using a getter/setter pair:
+Methods named @address@hidden and @address@hidden, respectively.
+For example:
address@hidden
+button1:tool-tip-text
address@hidden example
+is equivalent to:
address@hidden
+(button1:getToolTipText)
address@hidden example
+
+You can also change a field or property using colon notation:
address@hidden
+(set! @var{obj}:@var{fld} @var{value})
address@hidden example
+For example:
address@hidden
+(set! button1:tool-tip-text "really do it!")
address@hidden example
+This is equivalent to:
address@hidden
+(button1:setToolTipText "really do it!")
address@hidden example
+
+Instead of colon notation, you can use the @code{field} procedure.
+
+See @ref{Field operations} for details.
+
address@hidden Static fields and methods
+
+Kawa views static properties and methods as
+properties and methods of the class itself.
+To call a static method use the syntax:
address@hidden
+(@var{clas}:@var{meth} @var{v1} ... @var{vn})
address@hidden example
+For example:
address@hidden
+(java.math.BigDecimal:valueOf 12345 2) @result{} 123.45
address@hidden example
+
+To access a static field do @address@hidden:@var{fld}}. For example:
address@hidden
+java.awt.Color:RED
address@hidden example
+
+You can also use the @code{static-field} and @code{invoke-static} procedures.
+
address@hidden Tutorial - Types
address@hidden Types and declarations
+
+A @dfn{type} is a named value for a set
+of objects with related properties.
+For example, @code{vector} is the type for standard Scheme vectors.
+You can use a type to specify that a variable can only have
+values of the specified type:
+
address@hidden
+#|kawa:5|# @kbd{(define v ::vector #(3 4 5))}
+#|kawa:6|# @kbd{v}
+#(3 4 5)
+#|kawa:7|# @kbd{(set! v 12)}
+/dev/stdin:7:1: warning - cannot convert literal (of type gnu.math.IntNum) to
vector
+Value (12) for variable 'v' has wrong type (gnu.math.IntNum) (gnu.math.IntNum
cannot be cast to gnu.lists.FVector)
+ at atInteractiveLevel$7.run(stdin:7)
+ at gnu.expr.ModuleExp.evalModule(ModuleExp.java:302)
+ at kawa.Shell.run(Shell.java:275)
+ at kawa.Shell.run(Shell.java:186)
+ at kawa.Shell.run(Shell.java:167)
+ at kawa.repl.main(repl.java:870)
+Caused by: java.lang.ClassCastException: gnu.math.IntNum cannot be cast to
gnu.lists.FVector
+ ... 6 more
address@hidden example
+
+Using a type specification catches errors, and makes your programs
+more readable. It can also allow the Kawa compiler to generate code
+that runs faster.
+
+You can use a type to check that a value is an instance of the type,
+using either the @code{instance?} function:
+
address@hidden
+(instance? #(3 4 5) vector) @result{} #t
+(instance? '(3 4 5) vector) @result{} #f
address@hidden example
+
+As a convenience, you can use a type-name followed by a address@hidden'':
address@hidden
+(@var{type}? @var{val}) == (instance? @var{val} @var{type})
address@hidden example
+
+You can ``call'' a type as if it were a function,
+which constructs a new instance of the type.
+The following example shows how to construct a normal Scheme vector,
+and a Java array of ints:
+
address@hidden
+|kawa:1|# (vector )
+#()
+#|kawa:2|# (instance? (vector ) vector)
+#t
+#|kawa:3|# (define x (int[] 1 2 3))
+#|kawa:4|# x
+[1 2 3]
+#|kawa:5|# (instance? x int[])
+#t
address@hidden example
+
+A fully-qualified Java class is a type name.
+So are the names of Java primitive types.
+So are Java array types, as shown above.
+
+e.g. a JFrame is constructed by using its class name as a function:
+
address@hidden
+#|kawa:6|# (javax.swing.JFrame )
+javax.swing.JFrame[frame0,0,25,0x0,invalid,hidden,layout=java.awt.BorderLayout,
+title=,resizable,normal,defaultCloseOperation=HIDE_ON_CLOSE,
+rootPane=javax.swing.JRootPane[,0,0,0x0,invalid,
+layout=javax.swing.JRootPane$RootLayout,alignmentX=0.0,alignmentY=0.0,border=,
+flags=16777673,maximumSize=,minimumSize=,preferredSize=],rootPaneCheckingEnabled=true]
address@hidden example
+
+A type is a true run-time value:
+
address@hidden
+(define mytypes (list vector list string))
+(instance? #(3 4 5) (car mytypes) @result{} #t
address@hidden example
+
+The @code{define-alias} form is useful for defining shorter names
+for types, like a generalization of Java's @code{import} statement:
+
address@hidden
+(define-alias jframe javax.swing.JFrame)
address@hidden example
+
address@hidden Tutorial - Exceptions and errors
address@hidden Exceptions and errors
+
+Kawa supports the exception framework and forms
+from R6RS and R7RS. See @ref{Exceptions} for details.
+
address@hidden Native exception handling
+
+You can also work with native Java exceptions at a low level.
+
+The @code{primitive-throw} procedure throws a @code{Throwable} value.
+It is implemented just like Java's @code{throw}.
address@hidden
+(primitive-throw (java.lang.IndexOutOfBoundsException "bad index"))
address@hidden example
+
+You can catch an exception with the @code{try-catch} syntax. For example:
address@hidden
+(try-catch
+ (do-a-bunch-of-stuff)
+ (ex java.lang.Throwable
+ (format #f "caught ~a~%~!" ex)
+ (exit)))
address@hidden example
+
+A @code{try-finally} does the obvious:
address@hidden
+(define (call-with-port port proc)
+ (try-finally
+ (proc port)
+ (close-port port)))
address@hidden example
+
+Both @code{try-catch} and @code{try-finally} are
+expression forms that can return values, while the corresponding
+Java forms are statements that cannot return values.
+
address@hidden Tutorial - Classes
address@hidden Classes
+
+See @ref{Defining new classes} for the gory details; no tutorial yet.
+
address@hidden Tutorial - Other Java features
address@hidden Other Java features
+
address@hidden Import
+
+The @code{import} form can be used to avoid having to write
+fully-qualified class names. For example:
address@hidden
+(import (class java.util
+ Map
+ (HashMap HMap)))
address@hidden example
+This defines aliases for two classes in the @code{java.util} package,
+one with renaming:
address@hidden is an alias for @code{java.util.Map},
+and @code{HMap} is an alias for @code{java.util.HashMap}.
+
+The @code{class} keyword is needed because the @code{import}
+form is also used for Kawa's module system.
+See @ref{importing-class-names} and @ref{Importing} for details.
+
address@hidden Synchronized blocks
+
+You can use a @code{synchronized} expression:
+
address@hidden
+(synchronized obj form1 ... formn)
address@hidden example
+This waits until it can get an exclusive lock on @var{obj}
+and then evaluates @var{form1} through @var{formn}.
+Unlike Java, this is an expression and returns the value of @var{formn}.
+
address@hidden Annotations
+
+You can write annotation declarations - see @ref{Annotations} for details.
+
+Kawa does not yet support annotations on types,
+or declaring new annotation classes.
+
address@hidden Reference Documentation
+
address@hidden Running
address@hidden How to start up and run Kawa
+
+The easiest way to start up Kawa is to run the @samp{kawa} program.
+This finds your Java interpreter, and sets up @samp{CLASSPATH} correctly.
+If you have installed Kawa such that @code{$PREFIX/bin} is in your
@code{$PATH},
+just do:
address@hidden
+kawa
address@hidden example
+However, @samp{kawa} only works if you have a Unix-like environment.
+On some platforms, @samp{kawa} is a program that uses the GNU
address@hidden library to provide input line editing.
+
+To run Kawa manually, you must start a Java Virtual Machine.
+How you do this depends on the Java implementation.
+For Oracle's JDK, and some other implementations, you must have the
+Java evaluator (usually named @code{java}) in your @code{PATH}.
+You must also make sure that the @code{kawa/repl.class} file,
+the rest of the Kawa packages, and the standard Java
+packages can be found by searching CLASSPATH.
address@hidden Java}.
+
+Then you do:
address@hidden
+java kawa.repl
address@hidden example
+
+In either case, you will then get the @samp{#|kawa:1|#} prompt,
+which means you are
+in the Kawa read-eval-print-loop. If you type a Scheme
+expression, Kawa will evaluate it. Kawa will then print the
+result (if there is a non-"void" result).
+
address@hidden
+* Options:: Command-line arguments
+* Scripts:: Running Command Scripts
+* REPL Console:: The REPL (read-eval-print-loop) console
+* Exiting:: Exiting Kawa
+* Compiling:: Compiling to byte-code
address@hidden menu
+
address@hidden Options, Scripts, Running, Running
address@hidden Command-line arguments
+
address@hidden options
+You can pass various flags to Kawa, for example:
address@hidden
+kawa -e '(display (+ 12 4))(newline)'
address@hidden example
+or:
address@hidden
+java kawa.repl -e '(display (+ 12 4))(newline)'
address@hidden example
+Either causes Kawa to print @samp{16}, and then exit.
+
+At startup, Kawa executes an init file from the user's home
+directory.
+The init file is named @code{.kawarc.scm} on Unix-like systems
+(those for which the file separator is @code{'/'}),
+and @code{kawarc.scm} on other systems.
+This is done before the read-eval-print loop
+or before the first @code{-f} or @code{-c} argument. (It is not run
+for a @code{-e} command, to allow you to set options to override
+the defaults.)
+
address@hidden Argument processing
+
+Kawa processes the command-line arguments in order.
+Options (which either start with @samp{-} or contain a @samp{=})
+may ``use up'' one or more command arguments.
+Some of the options (@samp{-c}, @samp{-e}, @samp{-f}, @samp{-s},
address@hidden, @code{-w}, @samp{--}, @code{--browse-manual})
+are @dfn{action options}; others set various properties.
+
+When all the command-line arguments have been ``used up''
+and if no action options have been seen,
+then Kawa enters an interactive read-eval-print loop.
+(If an action option has been seen, we're done.)
+
+If the next command-line argument is not an option
+(does not start with @samp{-} nor contains a @samp{=})
+then we're done if we've seen an action option (and the
+last action option wasn't preceded by @code{--with-arg-count}).
+(Presumably any remaining arguments were command-line-arguments
+used by the action option.)
+
+Otherwise, the first remaining argument names either a
+file that is read and evaluated, or a compiled class.
+In the former case, the whole file is read and compiled as a module
+before being loaded (unlike the @code{-f} flag which reads and
+evaluates the file command by command.)
+If the argument is the fully-qualified name of a class,
+then the class is loaded, an instance allocated,
+and its @code{run} method invoked. If the class was compiled from
+a Kawa Scheme module, then invoking @code{run} has the
+effect of evaluating the module body.
+The @code{command-line-arguments} vector is set to any remaining
+arguments after the file/class name.
+(This can be overridden with the @code{--with-arg-count} option.
+Command-line processing continues if there are any further arguments.)
+
address@hidden General options
+
address@hidden @code
address@hidden -e @var{expr}
+Kawa evaluates @var{expr}, which contains one or more Scheme expressions.
+Does not cause the @code{~/.kawarc.scm} init file to be run.
address@hidden -c @var{expr}
+Same as @samp{-e @var{expr}}, except that it
+does cause the @code{~/.kawarc.scm} init file to be run.
address@hidden -f @var{filename-or-url}
+Kawa reads and evaluates expressions from the file named
+by @var{filename-or-url}. If the latter is @samp{-},
+standard input is read (with no prompting). Otherwise,
+it is equivalent to evaluating @samp{(load "@var{filename-or-url}")}.
+The @var{filename-or-url} is interpreted as a URL
+if it is absolute - it starts with a "URI scheme" like @code{http:}.
address@hidden -s
address@hidden --
+The remaining arguments (if any) are passed to @samp{command-line-arguments}
+and (the @code{cdr} of) @code{(command-line}),
+and an interactive read-eval-print loop is started.
+This uses the same "console" as where you started up Kawa;
+use @samp{-w} to get a new window.
address@hidden --script @var{filename-or-url}
address@hidden address@hidden @var{filename-or-url}
+The global variable @samp{command-line-arguments} is set to the remaining
+arguments (if any).
+Kawa reads and evaluates expressions from the file named
+by @var{filename-or-url}.
+If @code{script} is followed by an integer @var{N},
+then @var{N} lines are skipped first.
+
+Skipping some initial lines is useful if you want to have a non-Kawa
+preamble before the actual Kawa code.
+One use for this is for Kawa shell scripts (@pxref{Scripts}).
+
address@hidden -w
address@hidden address@hidden
+Creates a new top-level window, and runs an interactive read-eval-print
+in the new window. See @ref{New-Window}.
+Same as @code{-e (scheme-window #t)}.
+You can specify multiple @samp{-w} options, and also use @samp{-s}.
address@hidden --help
+Prints out some help.
address@hidden --version
+Prints out the Kawa version number, and then exits.
+
+If Kawa was built with a @code{.git} repository present,
+also prints the result of @code{git describe}.
address@hidden
address@hidden --browse-manual
address@hidden address@hidden
+Browse a local copy of the documentation (this manual).
+
+This creates a mini web-server that reads
+from @code{doc/kawa-manual.epub}, which is
+included in the binary distributions, but not built by default from source.
+
+If no @var{command} is specified, creates a new window or tab
+in your default web browser.
+If @var{command} is a string containing @code{%U},
+then Kawa replaces @code{%U} with a URL that references itself,
+and then executes the resulting command.
+If @var{command} does not contain @code{%U}, then
address@hidden becomes @address@hidden" %U"}.
+For example to use the Firefox browser to browse the manual do either of:
address@hidden
+kawa --browse-manual=firefox
+kawa --browse-manual="firefox %U"
address@hidden example
+
address@hidden --server @var{portnum}
+Start a server listening from connections on the specified @var{portnum}.
+Each connection using the Telnet protocol causes a new read-eval-print-loop
+to start. This option allows you to connect using any
+Telnet client program to a remote "Kawa server".
address@hidden address@hidden
+This option is used before an action option (such as @code{-f}).
+The @var{argc} arguments after the action become the
+value of the @code{command-line-arguments} during the action.
+When the action is finished, command-line-processing resumes
+after skipping the @var{argc} arguments.
+
+For example:
address@hidden
+$ kawa -f a.scm -f b.scm x y
address@hidden example
+When evaluating @code{a.scm} the @code{command-line-arguments}
+by default is @emph{all} the remaining arguments: @code{["-f" "b.scm" "x"
"y"]}.
+Then @code{b.scm} is evaluated with @code{command-line-arguments}
+set to @code{["x" "y"]}
+
address@hidden
+$ kawa --with-arg-count=0 -f a.scm -f b.scm x y
address@hidden example
+In this case @code{a.scm} is evaluated with @code{command-line-arguments}
+set to the empty vector @code{[]}, and then @code{b.scm} is evaluated with
@code{command-line-arguments}
+set to @code{["x" "y"]}
+
address@hidden
+$ kawa --with-arg-count=4 -f a.scm -f b.scm x y
address@hidden example
+In this case @code{a.scm} is evaluated with @code{command-line-arguments}
+set to @code{["-f" "b.scm" "x" "y"]}. Since command-line processing
+skips the arguments specified by @code{--with-arg-count=4},
+in this case @code{b.scm} is not evaluated.
address@hidden table
+
address@hidden Options for language selection
+
address@hidden @code
address@hidden --scheme
+Set the default language to Scheme.
+(This is the default unless you select another language,
+or you name a file with a known extension on the command-line.)
address@hidden --r5rs
address@hidden --r6rs
address@hidden --r7rs
+Provide better compatibility with the specified Scheme standards.
+(This is a work-in-progress.)
+For example @code{--r6rs} aims to disable Kawa extensions
+that conflict with R6RS. It does not aim to disable all extensions,
+only incompatible extensions.
+These extensions disable the colon operator and keyword literals,
+as well as the use of initial @samp{@@} as a splicing operator.
+The address@hidden'' exponent suffix of a number literal creates a
+floating-point double, rather than a @code{BigInteger}.
+Selecting @code{--r5rs} makes symbols by default
+case-insensitive.
address@hidden --elisp
address@hidden --emacs
address@hidden --emacs-lisp
+Set the default language to Emacs Lisp.
+(The implementation is quite incomplete.)
address@hidden --lisp
address@hidden --clisp
address@hidden --clisp
address@hidden --commonlisp
address@hidden --common-lisp
+Set the default language to CommonLisp.
+(The implementation is @emph{very} incomplete.)
address@hidden --krl
+Set the default language to KRL. See @ref{KRL}.
address@hidden --brl
+Set the default language to KRL, in BRL-compatibility mode. See @ref{KRL}.
address@hidden --xquery
+Set the default language to the draft XML Query language.
+See the @uref{http://www.gnu.org/software/qexo/,Kawa-XQuery page}
+for more information.
address@hidden --xslt
+Set the default language to XSLT (XML Stylesheet Language Transformations).
+(The implementation is @emph{very} incomplete.)
+See the @uref{http://www.gnu.org/software/qexo/xslt.html,Kawa-XSLT page}
+for more information.
address@hidden --pedantic
+Try to follow the approprate language specification to the letter,
+even in corner cases, and even if it means giving up some
+Kawa convenience features. This flag so far only affects
+the XQuery parser, but that will hopefully change.
address@hidden table
+
address@hidden Options for warnings and errors
+
address@hidden @code
address@hidden @address@hidden
address@hidden @address@hidden
address@hidden @code{warn-undefined-variable}
address@hidden --warn-undefined-variable
+Emit a warning if the code references a variable which is neither in
+lexical scope nor in the compile-time dynamic (global) environment.
+This is useful for catching typos.
+(A @code{define-variable} form can be used to silence warnings.
+It declares to the compiler that a variable is to be resolved dynamically.)
+This defaults to on;
+to turn it off use the @code{--no-warn-undefined-variable} flag.
address@hidden warn-unknown-member
address@hidden --warn-unknown-member
+Emit a warning if the code references a named member (field or method)
+for which there is no match in the compile-time type of the receiver.
+This defaults to on;
+to turn it off use the @code{--no-warn-unknown-member} flag.
address@hidden warn-invoke-unknown-method
address@hidden --warn-invoke-unknown-method
+Emit a warning if the @code{invoke} function calls a named method
+for which there is no matching method in the compile-time type of the receiver.
+This defaults to the value of @code{--warn-unknown-member},
+to turn it off use the @code{--no-warn-invoke-unknown-method} flag.
address@hidden warn-unused
address@hidden --warn-unused
+Emit a warning if a variable is unused or code never executed. This defaults
+to on; to turn it off use the @code{--no-warn-unused} flag.
address@hidden warn-unreachable
address@hidden --warn-unreachable
+Emit a warning if the code can never be executed. This defaults to on;
+to turn it off use the @code{--no-warn-unreachable} flag.
address@hidden warn-void-used
address@hidden --warn-void-used
+Emit a warning if an expression depends on an expression
+that is void (always has zero values), including call to @code{void}
+functions and method. Also warn if an expression depends on a
+conditional (@code{if}) that has no ``else'' clause.
+Examples include using the value of @code{set-car!} as
+an argument to a function, or to initialize a variable.
+This defaults to on;
+to turn it off use the @code{--no-warn-void-used} flag.
address@hidden warn-as-error
address@hidden --warn-as-error
+Treat a compilation warning as if it were an error and halt compilation.
address@hidden table
+
+An option can be followed by a value, as
+in @code{--warn-invoke-unknown-method=no}.
+For boolean options, the values @code{yes}, @code{true}, @code{on}, or @code{1}
+enable the option, while @code{no}, @code{false}, @code{off},
+or @code{0} disable it.
+You can also negate an option by prefixing it with @code{no-}:
+The option @code{--no-warn-unknown-member}
+is the same as @code{--warn-unknown-member=no}.
+
+These options can also be used in the module source, using
address@hidden or @code{with-compile-options}.
+(In that case they override the options on the command line.)
+
address@hidden Options for setting variables
+
address@hidden @code
address@hidden @address@hidden
+Set the global variable with the specified @var{name} to the given @var{value}.
+The type of the @var{value} is currently unspecified; the plan is for it
+to be like XQuery's @dfn{untyped atomic} which can be coerced as needed.
address@hidden @address@hidden@address@hidden@var{value}
+Set the global variable with the specified namespace uri and
+namespace-local name to the given value.
address@hidden table
+
+These options are processed when invoking the @code{kawa}
+application (i.e. the @code{kawa.repl} application).
+If you want a Kawa application compiled with @code{--main}
+to process these these assignments, call the
address@hidden utility function.
+
address@hidden @code
address@hidden address@hidden@var{variable-value}
+Sets the JVM property @var{variable-name} to @var{variable-value},
+using the @code{setProperty} method of @code{java.lang.System}.
address@hidden table
+
address@hidden Options for the REPL console
+
address@hidden @asis
address@hidden @code{--console}
address@hidden @code{--no-console}
+Usually Kawa can detect when the standard input port is a ``console''
+or ``terminal'', but these are useful for overriding that detection.
+The @code{--console} flag is useful when the standard input is a pipe,
+but you want to direct Kawa to treat it as an interactive terminal.
+The @code{--no-console} flag was useful for older pre-Java-6
+implementations that did not have the @code{java.lang.Console} class.
address@hidden @code{console:address@hidden
address@hidden @code{console:address@hidden|@code{no}]
address@hidden @code{console:address@hidden|@code{no}]
+See the @ref{REPL Console} section.
address@hidden @code{console:address@hidden
address@hidden @code{console:address@hidden
+Initialize @ref{input-prompt1,@code{input-promp1} and @code{input-prompt2}},
respectively.
address@hidden table
+See also the @code{--output-format} flag.
+
address@hidden Options for controlling output formatting
+
address@hidden @code{--output-format}
address@hidden @code
address@hidden --output-format @var{format}
address@hidden --format @var{format}
+Change the default output format to that specified by @var{format}.
+See @ref{Named output formats} for more information and a list.
address@hidden table
+
address@hidden @code
address@hidden out:address@hidden
+The number base (radix) to use by default when printing rational numbers.
+Must be an integer between 2 and 36, and the default is of course 10.
+For example the option @code{out:base=16} produces hexadecimal output.
+Equivalent to setting the @code{*print-base*} variable.
address@hidden out:radix=no|yes
+If true, prints an indicator of the radix used when printing rational numbers.
+The default is @code{no}.
+Equivalent to setting the @code{*print-radix*} variable.
address@hidden out:address@hidden
+If @code{out:doctype-system} is specified then a @code{DOCTYPE} declaration
+is written before writing a top-level XML element, using
+the specified @var{system-identifier}.
address@hidden out:address@hidden
+Ignored unless @code{out:doctype-system} is also specified,
+in which case the @var{public-identifier} is written
+as the public identifiers of the @code{DOCTYPE} declaration.
address@hidden out:address@hidden
+Controls whether extra line breaks and indentation are added
+when printing XML.
+If @var{kind} is @code{always} or @code{yes} then newlines and
+appropriate indentation are added before and after each element.
+If @var{kind} is @code{pretty} then the pretty-printer is used
+to only add new lines when an element otherwise won't fit on a single line.
+If @var{kind} is @code{no} (the default) then no extra line breaks
+or indentation are added.
address@hidden out:address@hidden
address@hidden out:address@hidden
+Specifies the maximum number of number of columns in a line
+when the pretty-printer decides where to break a line.
+(The two options are equivalent.)
address@hidden table
+
address@hidden Options for compiling and optimizing
+
address@hidden @code
address@hidden --target @var{version}
+The @var{version} can be a JDK or Java specification version:
address@hidden, @code{6}, or @code{7}.
+The JDK versions @code{1.5} and @code{1.6} are equivalent to @code{5}
+or @code{6}, respectively.
+Specify a JVM (classfile) version to target. This is useful
+if (for example) you use Java 6, but want to create @code{.class} files
+that can run on Java 5. In that case specify @code{--target 5}.
address@hidden table
+
+The following options control which calling conventions are used:
address@hidden @code
address@hidden --full-tailcalls
+Use a calling convention that supports proper tail recursion.
address@hidden --no-full-tailcalls
+Use a calling convention that does not support proper tail recursion.
+Self-tail-recursion (i.e. a recursive call to the current function)
+is still implemented correctly, assuming that the called function
+is known at compile time.
address@hidden --no-inline
+Disable inlining of known functions and methods.
+The generated code runs slower, but you can more reliably trace procedures.
+Normally Kawa will assume that a procedure @code{fn}
+declared using a @code{(define (fn args) body)} form is constant,
+assuming it isn't modified in the current module. However, it is
+possible some other module might modify the binding of @code{fn}.
+You can use the @code{--no-inline} to disable the assumption that @code{fn}
+is constant.
address@hidden table
+
+The default is currently @code{--no-full-tailcalls} because
+it is usually faster.
+It is also closer to the Java call model, so may be better for people
+primarily interested in using Kawa for scripting Java systems.
+
+Both calling conventions can co-exist: Code compiled
+with @code{--full-tailcalls} can call code compiled
+with @code{--no-full-tailcalls} and vice versa.
+
+These options can also be used in the module source, using
address@hidden or @code{with-compile-options}.
+(In that case they override the options on the command line.)
+
+The options @samp{-C}, @samp{-d}, @samp{-T}, @samp{-P}, @samp{--main}
address@hidden, and @code{--servlet} are used to compile a Scheme file;
+see @ref{Files compilation}.
+The options @samp{--module-static}, @code{--module-nonstatic},
address@hidden, and @code{--module-static-run}
+control how a module is mapped to a Java class; see
@ref{static-or-non-modules}.
+The option @samp{--connect @var{portnum}} is only used by
+the @samp{kawa} front-end program.
+
address@hidden Options for debugging
+
+The following options are useful if you want to debug or understand
+how Kawa works.
address@hidden @code
address@hidden --debug-dump-zip
+Normally, when Kawa loads a source file, or evaluates a non-trivial expression,
+it generates new internal Java classes but does not write them out. This
+option asks it to write out generated classes in a @samp{.zip} archive
+whose name has the prefix @samp{kawa-zip-dump-}.
address@hidden --debug-print-expr
+Kawa translates source language forms into an internal @code{Expression}
+data structure. This option causes that data structure to be written out
+in a readable format to the standard output.
address@hidden --debug-print-final-expr
+Similar to the previous option, but prints out the @code{Expression} after
+various transformations and optimizations have been done, and just before
+code generation.
address@hidden --debug-syntax-pattern-match
+Prints logging information to standard error when a @code{syntax-rules}
+or @code{syntax-case} pattern matches.
address@hidden --debug-error-prints-stack-trace
+Prints a stack trace with any error found during compilation.
address@hidden --debug-warning-prints-stack-trace
+Prints a stack trace with any warning found during compilation.
address@hidden table
+
address@hidden Options for web servers
+
+JDK 6 (or later) includes a complete web server library.
+
address@hidden @code
address@hidden --http-auto-handler @var{context-path} @var{appdir}
+Register a web application handler that uses files
+in the directory @var{appdir} to handle HTTP (web) requests
+containing the given @var{context-path}. That is it handles
+requests that start with @code{http://localhost:@address@hidden
+(This assumes the @var{context-path} starts with a @code{/}.)
address@hidden page scripts}.
address@hidden --http-start @var{port}
+Start the web server, listing on the specified @var{port}.
address@hidden table
+
address@hidden Options for the JVM
+
+The @code{kawa} front-end can pass options to the @code{java} launcher,
+using @code{-J} or @code{-D} options.
+These must be given @emph{before} any other arguments.
+For example:
address@hidden
+kawa -J-Xms48m -Dkawa.command.name=foo foo.scm
address@hidden example
+is equivalent to (ignoring classpath issues):
address@hidden
+java -Xms48m -Dkawa.command.name=foo kawa.repl foo.scm
address@hidden example
+You can also pass a @code{-D} option (but not a @code{-J} option) after the
+class name, in which case it is processed by the Kawa command-line processor
+rather than the @code{java} launcher. The effect is normally the same.
+
address@hidden @code
address@hidden address@hidden
+Passes the @var{jvm-option} to the @code{java} command,
+before the class-name (@code{kawa.repl}) and Kawa options.
address@hidden address@hidden@var{variable-value}
+Sets the JVM property @var{variable-name} to @var{variable-value}.
+Equivalent to @address@hidden@var{variable-value}}.
address@hidden table
+
address@hidden Scripts
address@hidden Running Command Scripts
+
+If you write a Kawa application, it is convenient to be able
+to execute it directly (from the command line or clicking an icon, say),
+without have to explicitly run @code{kawa} or @code{java}.
+On Unix-like systems the easiest way to do this is to
+write a small shell script that runs your Kawa application.
+
+For modest-sized applications it is convenient if the shell script
+and the Kawa code can be in the same file.
+Unix-like systems support a mechanism where a @dfn{script} can
+specify a program that should execute it. The convention
+is that the first line of the file should start with the two characters
address@hidden followed by the absolute path of the program that should
+process (interpret) the script.
+
+(Windows has @dfn{batch files}, which are similar.)
+
+This convention works well for script languages that use @samp{#}
+to indicate the start of a comment, since the interpreter will
+automatically ignore the line specifying the interpreter filename.
+Scheme, however, uses @samp{#} as a multi-purpose prefix,
+and Kawa specifically uses @samp{#!} as a prefix for
+various @ref{Special named constants} such as @code{#!optional}.
+
+Kawa does recognize the three-character sequence @samp{#!/} at the
+beginning of a file as special, and ignores it.
+Here is an example:
address@hidden
+#!/usr/local/bin/kawa
+(format #t "The command-line was:address@hidden address@hidden" (command-line))
address@hidden example
+
+If you copy this text to a file named @code{/home/me/bin/scm-echo},
+set the execute permission, and make sure it is in your @code{PATH},
+then you can execute it just by naming it on command line:
address@hidden
+$ chmod +x /home/me/bin/scm-echo
+$ PATH=/home/me/bin:$PATH
+$ scm-env a b
+The command-line was: "/home/me/bin/scm-echo" "a" "b"
address@hidden example
+The system kernel will automatically execute @code{kawa}, passing it the
+filename as an argument.
+
+Note that the full path-name of the @code{kawa} interpreter
+must be hard-wired into the script. This means you may have to edit
+the script depending on where Kawa is installed on your system.
+Another possible problem is that the interpreter must be an
+actual program, not a shell script. Depending on how you configure
+and install Kawa, @code{kawa} can be a real program or a script.
+You can avoid both problems by the @code{env} program, available on
+most modern Unix-like systems:
+
address@hidden
+#!/usr/bin/env kawa
+(format #t "The command-line was:address@hidden address@hidden" (command-line))
address@hidden example
+
+This works the same way, but assumes @code{kawa} is in the
+command @code{PATH}.
+
address@hidden Setting kawa options in the script
+
+If you need to specify extra arguments to @code{kawa},
+you can run arbitrary shell command inside Scheme block comments.
+Here is an example:
address@hidden
+#!/bin/sh
+#|
+exec kawa out:base=16 out:radix=yes "$0" "$*"
+|#
+(format #t "The command-line is:address@hidden address@hidden" (command-line))
+(display "It has ")
+(display (apply + (map string-length (command-line))))
+(display " characters.")
+(newline)
address@hidden example
+
+The trick is to hide the shell code from Kawa inside
+a @code{#|...|#} block-comment. The start of the block comment
+is a line starting with a @code{#}, so it is treated as a comment by the shell.
+You can then invoke @code{kawa} (or @code{java} directly)
+as you prefer, setting up class-path and jars as needed,
+and passing whatever arguments you want.
+(The shell replaces the @code{"$0"} by the name of the script, and
+replaces the @code{"$@@"} by the remaining arguments passed to the script.)
+You need to make sure the shell finishes before it reaches
+the end of the block comment or the Scheme code, which would confuse it.
+The example uses @code{exec}, which tells the shell to @emph{replace}
+itself by @var{kawa};
+an alternative is to use the shell @code{exit} command.
+
+If you copy the above file to @code{/tmp/sch-echo} and make
+that file executable, you can run it directly:
address@hidden
+$ /tmp/scm-echo "a b" "c d"
+The command-line is: "/tmp/scm-echo" "a b c d".
+It has #x14 characters.
address@hidden example
+
+When the Kawa reader sees the initial @code{#/} it sets
+the command name to the file name, so it can be used by a future
+call to @code{(command-name)}. If you want to override
+this you can use the @address@hidden option.
+
+Using comments this way has the advantage that you have the
+option of running the script ``manually'' if you prefer:
address@hidden
+$ kawa /tmp/scm-echo out:base=8 "x y"
+The command-line is: "/tmp/scm-echo" "out:base=8" "x y".
+It has 26 characters.
address@hidden example
+
address@hidden Other ways to pass options using meta-arg or --script
+
+An argument consisting of just a @code{\} (backslash)
+causes Kawa to read the @emph{second} line looking for
+options. (Quotes and backslashes work like in the shell.)
+These replace the backslash in the command line.
+
+This is a less verbose mechanism, but it requires an
+absolute path to @code{kawa}, due to shell limitations.
+
address@hidden
+#!/usr/bin/kawa \
+ --scheme --full-tailcalls
+(format #t "The command-line is:address@hidden address@hidden" (command-line))
address@hidden example
+
+In this case the effective command line received by Kawa will
+be @code{--scheme}, @code{--full-tailcalls}, followed by the
+script filename, followed by other arguments specified when
+running the script.
+
+The backslash used this way originated in
address@hidden://www.scsh.net, scsh} where it is called the @dfn{meta-arg}.
+(Unlike scsh, Kawa's @code{#!} is not a block comment,
+but a rest-of-line, though the backslash causes the following line
+to also be skipped.)
+
+An alternative method is to use the @code{--script2} option,
+which tells Kawa to execute the script after ignoring
+the initial two lines. For example:
+
address@hidden
+#!/bin/sh
+exec kawa --commonlisp out:base=16 --script2 "$0" "$@@"
+(setq xx 20) (display xx) (newline)
address@hidden example
+
+This is slightly more compact than using block-comments as shown earlier,
+but it has the disadvantage that you can't explicitly
+use @code{kawa} or @code{java} to run the script unless you
+make sure to pass it the @code{--script2} option.
+
address@hidden Scripts for compiled code
+If you compile your Kawa application to class files (or better:
+a @code{jar} file), you probably still want to write a small
+shell script to set things up. Here is one method:
+
address@hidden
+#!/bin/sh
+export CLASSPATH=/my/path
+exec kawa -Dkawa.command.name="$0" foo "$@@"
address@hidden example
+
+Using the @code{kawa} front-end is a convenience, since it automatically
+sets up the paths for the Kawa classes, and (if enabled) it
+provides readline support for the default input port.
+
+Setting the @code{kawa.command.name} property to @code{"$0"}
+(the filename used to invoke the script) enables
address@hidden(command-line}) to use the script name as the command name.
+
+You can invoke @code{java} directly, which is necessary when
+running a @code{jar} file:
+
address@hidden
+#!/bin/sh
+exec java -cp /path/to/kawa -Dkawa.command.name="$0" foo.jar "$@@"
address@hidden example
+
address@hidden
+(It is in principle possible to compile a Kawa application to
+``a native executable'', for example using @code{gcj}.
+However, this is no longer supported, as gcj is no longer
+being actively developed.)
address@hidden ignore
+
address@hidden REPL Console
address@hidden The REPL (read-eval-print-loop) console
+
+The read-eval-print-loop (REPL) console is a convenient way to
+do simple programming, test out things, and experiment.
+As the name implies, the REPL repeatedly (in a loop)
+prints out a prompt, reads an input command, evaluates it, then prints the
result.
+
+The REPL is started when you invoke the @code{kawa} command
+with no arguments. For example:
+
address@hidden
+$ @kbd{kawa}
+#|kawa:1|# @kbd{(define pi (* 2 (asin 1)))}
+#|kawa:2|# @kbd{(list pi (sqrt pi))}
+(3.141592653589793 1.7724538509055159)
+#|kawa:3|# @kbd{}
address@hidden example
+
+The colors and styles used for the prompt and the user input
+depend on user preference and the capabilities of the console device.
+(If you read this on a color screen you should see pale green for the
+prompt and pale yellow for the user input;
+this matches the defaults for the DomTerm console.)
+
+You can @ref{Prompts,change the prompt string} if you want.
+The default format depends on the (programming) language used;
+the one shown above is used for Scheme.
+It has the form of a comment, which can be convenient for copying
+and pasting lines.
+
+You can @ref{Named output formats,change the output formatting} with
+the @code{--output-format} command-line option.
+
+The basic console has few frills, but should work in any enviroment
+where you have a console or terminal. It has no dependencies,
+except the kawa @code{.jar} file (and Java):
address@hidden
+$ @kbd{java address@hidden
+#|kawa:2|# @kbd{}
address@hidden example
+
+On rare occason you may need to specify the @code{--console} flag.
+
address@hidden Input line editing and history
+
+When typing a command in a console it is helpful to go back
+and correct mistakes, repeat and edit previous commands, and so on.
+How well you can do this varies a lot depending on which tools you use.
+Kawa delegates input editing to an external tool.
+The recommended and default input-editing tool is
+the @uref{https://github.com/jline/jline3,JLine3 library},
+which is bundled with the Kawa binary distribution.
+
+JLine3 handles the normal editing comands, including arrow keys
+for moving around in the input, and deleting with backspace or delete.
+In general, JLine3 uses the same keybindings as GNU readline,
+which are based on Emacs key-bindings.
+
+You can use the up-arrow to move to previous commands in the
+input history and down-arrow to go forwards.
+Control-R (``reverse search'' searches backwards in the history
+for a previous command that contains the search string.
+
+Multi-line commands are treated as a unit by JLine3:
+If Kawa determines that input is ``incomplete'' it will
+ask for continuation lines - and you can go back and edit previous
+lines in the same command.
+You can explicitly create a multi-line command with Escape-Space.
+An entry in the command history may be multiple lines.
+
+Tab-completion works for Kawa-Scheme identifiers: If you type TAB
+after an identifier, Kawa will present a list of possible completions.
+
+There are multiple alternatives to using JLine3.
+You can use GNU readline (if you configured with
@code{--enable-kawa-frontend}).
+You can use a front-end program like @code{rlfe} or @code{fep}.
+You can use Emacs shell or scheme mode.
+You can also use DomTerm in line-edit mode, where the browser handles
+the editing.
+
address@hidden @asis
address@hidden @code{console:address@hidden|@code{no}]
+Disable (with @code{no}) or enable (with @code{yes}, which is the default)
+input line editing with JLine.
address@hidden @code{console:console:address@hidden|@code{no}]
+Enable (with @code{yes}) mouse click reporting from
+most xterm-like terminals to JLine, which means you
+can move the input cursor with the mouse.
+This is disabled by default because it conflicts with other useful mouse
+actions (text selection using drag; middle-button paste; right-button
+context menu; and wheel mouse scrolling).
+If you enable mouse-reporting, on most terminals you can get the
+standard behavior when pressing the shift key. E.g. to enable selection,
+drag with the shift key pressed. (However, mouse-wheel scrolling
+may not work even with shift pressed.)
address@hidden table
+
address@hidden
address@hidden Running a Command Interpreter in a new Window
+
+Instead of using an existing terminal window for Kawa's REPL console,
+you can request a new window.
+The command-line options @code{-w} creates a new window.
+Kawa also creates a new window when it needs to create a REPL
+(for example if invoked with no options) and it is not running
+in a console.
+
+You have a number of options for how the window appears and
+what it supports, controlled by text following @code{-w}.
+All except @code{-wswing} (and @code{-wconsole}) use DomTerm,
+so they depend on some kind of web browser technology.
+All except @code{-wswing} by default use JLine3 input editing,
+if available.
+
address@hidden @asis
address@hidden @code{-w}
+Pick the default/preferred console implementation.
+You can specify your preference with the @code{console:type=} option,
+which is followed by one of the options below (without the @code{"-w"} prefix),
+It can also be list of options separated by semi-colons, in which
+case they are tried in order.
+
+The current default (it may change) is as if you specified:
address@hidden
+console:type="google-chrome;browser;javafx;swing;console"
address@hidden example
+
address@hidden @code{-wbrowser}
+Creates a Kawa window or tab in your preferred desktop browser.
+Kawa starts a builtin HTTP and WebSocket server to communicate with the
browser.
address@hidden @address@hidden
+Uses @var{command} to display the Kawa REPL.
+The @var{command} should include the pattern @code{%U}, which Kawa replaces
+with a URL that it listens to.
+(Alternatively, it can use the pattern @code{%W}, which Kawa replaces
+with the port number of its WebSocket server. However, this feature may be
removed.)
+If the is no @code{%} in the @var{command}, Kawa add @code{" %U"}.
+Thus @code{-wbrowser=firefox} is the same as @code{-wbrowser="firefox %U"}.
address@hidden @code{-wgoogle-chrome}
+Creates a new Google Chrome window in ``app mode'' - i.e. with no location or
menu bar.
+This is the same as @code{-wbrowser="google-chrome --app=%U"}.
address@hidden @code{-wqtdomterm}
+Uses the @code{QtDomTerm} application.
+Same as @code{-wbrowser="qtdomterm --connect localhost:%W"}, where @code{%W}
+is the port of the WebSocke server that Kawa starts.
address@hidden @code{-wjavafx}
+Creates a new window using JavaFX WebView, which runs in the same JVM as Kawa.
+While this doesn't currently have much in the way of Kawa-specific menus
+or other features, it has the most potential for adding them in the future.
+However, it does require JavaFX, which is not always available,
+and which does not see a lot of love from Oracle. (It uses an old version of
WebKit.)
address@hidden @code{-wswing}
+Create a console using the Swing toolkit.
+This is the old implementation of @code{-w}.
+It is deprecated because it only supports the builtin Swing line editing.
+(I.e. neither DomTerm or JLine3 features are available, though
+``printing'' @ref{Composable pictures,pictures} does work.)
address@hidden @code{-wserve}
address@hidden @address@hidden
+Starts up an HTTP server (along with a WebSocket server),
+but does not automatically create any browser windows.
+Instead you can use any modern browser to load
@code{http://localhost:@var{port}/}.
+If @var{port} is not specified, the systems selects it (and prints it out).
address@hidden @code{-wconsole}
+Same as @code{"--"} - i.e. it uses the existing console.
address@hidden @code{console:address@hidden
+Specify the behavior of plain @code{-w}.
address@hidden table
+
address@hidden DomTerm}
address@hidden Using DomTerm
+
address@hidden://domterm.org,DomTerm} is a family of terminal emulators that use
+the DomTerm JavaScript library.
+
+You can either have Kawa start DomTerm:
address@hidden
+$ kawa @var{options} -w
address@hidden example
+or start a DomTerm terminal emulator and have it start Kawa:
address@hidden
+$ domterm kawa @var{options} --
address@hidden example
+(You can also start a shell in a @code{domterm} window, and then start
@code{kawa}.)
+
+Either approach works and both give you the benefits of DomTerm:
address@hidden
address@hidden
+A xterm/ansi-compatible terminal emulator,
+which means you can use (for example) JLine3 for input editing.
address@hidden
+You can ``print'' images, @ref{Composable pictures,pictures}, or HTML elements.
address@hidden
+Pretty-printing is handled by the terminal,
+which means line-breaking is re-computed when window width changes.
address@hidden
+Hide/show buttons allow you to temporarily hide/unhide the output from a
specific command.
address@hidden
+You can save a session as an HTML file,
+which can be viewed later.
+(Still with dynamic line-breaking and pretty-printing, as well as working
hide/show buttons.)
+The file is actually XHTML, so it can be processed with XML-reading tools.
address@hidden
+Distinct styles for prompts, input, error output and regular output,
+which can be customized with CSS.
address@hidden itemize
+
+For now it is recommended to use both DomTerm and JLine3.
+
address@hidden Procedure domterm-load-stylesheet stylesheet [name]
+The string @var{stylesheet} should be a literal CSS stylesheet
+which is downloaded into the current DomTerm console.
+The new stylesheet is given the attribute @address@hidden,
+where @var{name} defaults to @code{"Kawa"}. If there is an
+existing stylesheey whose @code{name} attribute is @var{name},
+it is replaced.
+In this example we change the background color to light gray:
address@hidden
+(domterm-load-stylesheet "div.domterm @{ background-color: address@hidden")
address@hidden example
address@hidden deffn
+
address@hidden Exiting
address@hidden Exiting Kawa
+Kawa normally keeps running as long as there is an active
+read-eval-print loop still awaiting input or there is an unfinished
+other computation (such as requested by a @samp{-e} or @samp{-f} option).
+
+To close a read-eval-print-loop, you can type the special
+literal @code{#!eof} at top level. This is recognized as end-of-file.
+Typing an end-of-file character (normally ctrl-D under Unix)
+should also work, but that depends on your operating system
+and terminal interface.
+
+If the read-eval-print-loop
+is in a new window, you can select @samp{Close} from the @samp{File} menu.
+
+To exit the entire Kawa session, call the
address@hidden the current process,@code{exit} procedure} (with 0 or 1 integer
arguments).
+
address@hidden Compiling, , , Running
address@hidden Compiling to byte-code
+
+All Scheme functions and source files are invisibly compiled
+into internal Java byte-codes.
+(A traditional interpreter is used for macro-expansion.
+Kawa used to also interpret ``simple'' expressions in interactive mode,
+but always compiling makes things more consistent, and allows for
+better stack traces on errors.)
+
+To save speed when loading large Scheme source files, you probably
+want to pre-compile them and save them on your local disk.
+There are two ways to do this.
+
+You can compile a Scheme source file to a single archive file.
+You do this using the @code{compile-file} function.
+The result is a single file that you can move around and @code{load}
+just like the @code{.scm} source file. You just specify the name
+of the archive file to the @code{load} procedure.
+Currently, the archive is a "zip" archive and has extension ".zip";
+a future release will probably use "Java Archive" (jar) files.
+The advantage of compiling to an archive is that it is simple
+and transparent.
+
+Alternatively, you can compile a Scheme source file to a
+collection of @samp{.class} files.
+You then use the standard Java class loading mechanism to load the code.
+The compiled class files do have to be installed somewhere
+in the @code{CLASSPATH}.
+
address@hidden
+* Files compilation:: Compiling to a set of .class files
+* Archive compilation:: Compiling to an archive file
+* Compiling using Ant::
+* Application compilation:: Compiling to a standalone application
+* Applet compilation:: Compiling to an applet
+* Compiling to executable:: Compiling to a native executable
address@hidden menu
+
address@hidden Files compilation
address@hidden Compiling to a set of .class files
+
+Invoking @samp{kawa} (or @samp{java kawa.repl}) with
+the @samp{-C} flag will compile
+a @samp{.scm} source file into one or more @samp{.class} files:
address@hidden
+kawa --main -C myprog.scm
address@hidden example
+
+You run it as follows:
address@hidden
+kawa [-d @var{outdirectory}] [-P @var{prefix}] [-T @var{topname}] [--main |
--applet | --servlet] -C @var{infile} ...
address@hidden example
+
+Note the @samp{-C} must come last, because @samp{Kawa} processes the
+arguments and options in order,
+
+Here:
address@hidden @code
address@hidden -C @var{infile} ...
+The Scheme source files we want to compile.
address@hidden -d @var{outdirectory}
+The directory under which the resulting @samp{.class} files will be.
+The default is the current directory.
address@hidden -P @var{prefix}
+A string to prepend to the generated class names.
+The default is the empty string.
address@hidden -T @var{topname}
+The name of the "top" class - i.e. the one that contains the code
+for the top-level expressions and definitions.
+The default is generated from the @var{infile} and @var{prefix}.
address@hidden --main
+Generate a @code{main} method so that the resulting "top" class can
+be used as a stand-alone application. @xref{Application compilation}.
address@hidden --applet
+The resulting class inherits from @code{java.applet.Applet},
+and can be used as an applet. @xref{Applet compilation}.
address@hidden --servlet
+The resulting class implements @code{javax.servlet.http.HttpServlet},
+and can be used as a servlet in a servlet container like Tomcat.
address@hidden table
+
+When you actually want to load the classes, the @var{outdirectory}
+must be in your @samp{CLASSPATH}.
+You can use the @code{require} syntax or the @code{load} function to load the
code,
+by specifying the top-level class, either as a file name
+(relative to @var{outdirectory}) or as a class name.
+E.g. if you did:
address@hidden
+kawa -d /usr/local/share/java -P my.lib. -T foo -C foosrc.scm
address@hidden example
+you can use either:
address@hidden
+(require my.lib.foo)
address@hidden example
+or:
address@hidden
+(load "my.lib.foo")
address@hidden example
+Using @code{require} is preferred as it imports the definitions
+from @code{my.lib.foo} into the compile-time environment,
+while @code{load} only imports the definitions into the run-time environment.
+
+If you are compiling a Scheme source file (say @samp{foosrc.scm})
+that uses macros defined in some other file (say @samp{macs.scm}),
+you need to make sure the definitions are visible to the compiler.
+One way to do that is with the @samp{-f}:
address@hidden
+kawa -f macs.scm -C foosrc.scm
address@hidden example
+
+Many of the options @ref{Options,,described earlier} are
+relevant when compiling. Commonly used options include language selection,
+the @code{--warn-xxx} options, and @code{--full-tailcalls}.
+
address@hidden Archive compilation
address@hidden Compiling to an archive file
+
address@hidden Procedure compile-file source-file compiled-archive
+Compile the @var{source-file}, producing a @code{.zip} archive
address@hidden
+
+
+For example, to byte-compile a file @samp{foo.scm} do:
address@hidden
+(compile-file "foo.scm" "foo")
address@hidden example
+
+This will create @samp{foo.zip}, which contains
+byte-compiled JVM @code{.class} files.
+You can move this file around, without worrying about class paths.
+To load the compiled file, you can later @code{load} the
+named file, as in either @code{(load "foo")} or @code{(load "foo.zip")}.
+This should have the same effect as
+loading @samp{foo.scm}, except you will get the faster byte-compiled versions.
address@hidden deffn
+
address@hidden Compiling using Ant
address@hidden Compiling using Ant
address@hidden kawac
+Many Java projects use @uref{http://ant.apache.org, Ant}
+for building Java projects. Kawa includes a @code{<kawac>}
+Ant task that simplifies compiling Kawa source files to classes.
+See the @code{build.xml} in the Kawa source distribution for examples.
+See the @uref{ant-kawac.html, @code{kawac} task documentation} for details.
+
address@hidden Application compilation
address@hidden Compiling to a standalone application
+
+A Java application is a Java class with a special method
+(whose name is @code{main}). The application can be invoked directly
+by naming it in the Java command.
+If you want to generate an application from a Scheme program,
+create a Scheme source file with the definitions you need, plus
+the top-level actions that you want the application to execute.
+
+For example, assuming your Scheme file is
address@hidden, you have two ways at your disposal to
+compile this Scheme program to a standalone application:
address@hidden
address@hidden
+Compile
+in the regular way described in the previous section, but add the
address@hidden option.
address@hidden
+kawa --main -C MyProgram.scm
address@hidden example
+
+The @code{--main} option will compile all Scheme programs
+received in arguments to standalone applications.
address@hidden
+Compile
+in the regular way decribed in the previous section, but add the
address@hidden: #t} module compile option to your module.
address@hidden
+;; MyProgram.scm
+(module-name <myprogram>)
+(module-compile-options main: #t)
address@hidden example
+
address@hidden
+kawa -C MyProgram.scm
address@hidden example
+
+This way you can compile multiple Scheme programs at once, and
+still control which one(s) will compile to standalone application(s).
address@hidden enumerate
+
+Both methods will create a @code{MyProgram.class} which you can either
address@hidden (as described in the previous section), or invoke as an
application:
address@hidden
+java MyProgram address@hidden
address@hidden example
+Your Scheme program can access the command-line arguments @var{args}
+by using the global variable @samp{command-line-arguments},
+or the R6RS function @samp{command-line}.
+
+If there is no explicit @code{module-export} in a module compiled
+with @code{--main} then no names are exported. (The default
+otherwise is for all names to be exported.)
+
address@hidden Applet compilation, Compiling to executable, Application
compilation, Compiling
address@hidden Compiling to an applet
+An applet is a Java class that inherits from @code{java.applet.Applet}.
+The applet can be downloaded and run in a Java-capable web-browser.
+To generate an applet from a Scheme program, write the Scheme
+program with appropriate definitions of the functions @samp{init},
address@hidden, @samp{stop} and @samp{destroy}. You must declare these
+as zero-argument functions with a @code{<void>} return-type.
+
+Here is an example, based on the scribble applet in Flanagan's
+"Java Examples in a Nutshell" (O'Reilly, 1997):
address@hidden
+(define-private last-x 0)
+(define-private last-y 0)
+
+(define (init) :: void
+ (let ((applet (this)))
+ (applet:addMouseListener
+ (object (java.awt.event.MouseAdapter)
+ ((mousePressed e)
+ (set! last-x (e:getX))
+ (set! last-y (e:getY)))))
+ (applet:addMouseMotionListener
+ (object (java.awt.event.MouseMotionAdapter)
+ ((mouseDragged e)
+ (let ((g (applet:getGraphics))
+ (x (e:getX))
+ (y (e:getY)))
+ (g:drawLine last-x last-y x y)
+ (set! last-x x)
+ (set! last-y y)))))))
+
+(define (start) :: void (format #t "called start.~%~!"))
+(define (stop) :: void (format #t "called stop.~%~!"))
+(define (destroy) :: void (format #t "called destroy.~%~!"))
address@hidden example
+
+You compile the program with the @samp{--applet} flag in addition to the
+normal @samp{-C} flag:
address@hidden
+java kawa.repl --applet -C scribble.scm
address@hidden example
+
+You can then create a @samp{.jar} archive containing your applet:
address@hidden
+jar cf scribble.jar scribble*.class
address@hidden example
+
+Finally, you create an @samp{.html} page referencing your applet
+and its support @code{jar}s:
address@hidden
+<html><head><title>Scribble testapp</title></head>
+<body><h1>Scribble testapp</h1>
+You can scribble here:
+<br>
+<applet code="scribble.class" archive="scribble.jar, address@hidden" width=200
height=200>
+Sorry, Java is needed.</applet>
+</body></html>
address@hidden example
+
+The problem with using Kawa to write applets is that the Kawa @code{.jar}
+file is quite big, and may take a while to download over a network connection.
+Some possible solutions:
+
address@hidden
address@hidden
+Try to strip out of the Kawa @code{.jar} any classes your
+applet doesn't need.
address@hidden
+Java 2 provides a mechanism to install a
@uref{http://java.sun.com/docs/books/tutorial/ext/basics/download.html,
+download extension}.
address@hidden
+Consider some alternative to applets, such as
address@hidden://java.sun.com/products/javawebstart/,Java Web Start}.
address@hidden itemize
+
address@hidden Compiling to executable, , Applet compilation, Compiling
address@hidden Compiling to a native executable
+
+In the past it was possible to compile a Scheme program to native code using
GCJ.
+However, using GCJ with Kawa is no longer supported,
+as GCJ is no longer being actively maintained.
+
address@hidden
+You can compile your Scheme program to native code using GCJ,
+as long as you have built Kawa using GCJ.
+
+First, you need to compile the Scheme code to a set of @code{.class} files;
+see @ref{Files compilation}.
address@hidden
+kawa --main -C myprog.scm
address@hidden example
+
+Then to create an executable @code{myprog} do:
address@hidden
+gckawa --main=myprog myprog*.class -o myprog
address@hidden example
+
+The @code{gckawa} is a simple shell script that calls @code{gcj}.
+The reason for the wildcard in @code{myprog*.class} is that sometimes
+Kawa will generate some helper classes in addition to @code{myprog.class}.
+The @code{--main} option tell @code{gcj} which class contains
+the @code{main} method it should use. The @code{-o} option names
+the resulting executable program. The @code{-lkawa} option tells
+the linker it should link with the kawa shared library, and
+the @code{-L$PREFIX/bin} option tells the linker where it can
+find that library.
address@hidden ignore
+
address@hidden Syntax
address@hidden Syntax
+
address@hidden
+* Syntax notation::
+* Lexical and datum syntax::
+* Lexical syntax::
+* Datum syntax::
+* Hash-prefixed forms::
+* Primitive expression syntax::
+* Colon notation:: Property access using colon notation
+* Bodies::
+* Syntax and conditional compilation::
+* Macros::
+* Named quasi-literals::
address@hidden menu
+
address@hidden Syntax notation, Lexical and datum syntax, , Syntax
address@hidden Notation
+
+The formal syntax for Kawa Scheme is written in an extended @acronym{BNF}.
+Non--terminals are written @var{like-this}. Case is insignificant
+for non--terminal names.
+Literal text (terminals) are written @stxlit{like this}.
+
+All spaces in the grammar are for legibility.
address@hidden @meta{Empty} stands for the empty string.
+
+The following extensions to @acronym{BNF} are used to make the
+description more concise: @address@hidden or @address@hidden
+both mean zero or more occurrences of @meta{thing},
+and @address@hidden means at least one @meta{thing}.
+
+Some non-terminal names refer to the Unicode scalar values of the same
+name: @meta{character-tabulation} (U+0009), @meta{linefeed} (U+000A),
address@hidden (U+000D), @meta{line-tabulation} (U+000B),
address@hidden (U+000C), @meta{space} (U+0020), @meta{next-line}
+(U+0085), @meta{line-separator} (U+2028), and @meta{paragraph-separator}
+(U+2029).
+
address@hidden Lexical and datum syntax, Lexical syntax, Syntax notation, Syntax
address@hidden Lexical and datum syntax
+
+The syntax of Scheme code is organized in three levels:
+
address@hidden
address@hidden
+the @emph{lexical syntax} that describes how a program text is split
+into a sequence of lexemes,
+
address@hidden
+the @emph{datum syntax}, formulated in terms of the lexical syntax, that
+structures the lexeme sequence as a sequence of @emph{syntactic data},
+where a syntactic datum is a recursively structured entity,
+
address@hidden
+the @emph{program syntax} formulated in terms of the datum syntax,
+imposing further structure and assigning meaning to syntactic data.
address@hidden enumerate
+
+Syntactic data (also called @emph{external representations}) double as a
+notation for objects, and the @func{read} and
address@hidden procedures can be used for reading and writing syntactic data,
+converting between their textual representation and the corresponding
+objects. Each syntactic datum represents a corresponding
address@hidden value}. A syntactic datum can be used in a program to obtain the
+corresponding datum value using @code{quote}.
address@hidden FIXME (@ref{base expressions quotation}).
+
+Scheme source code consists of syntactic data and (non--significant)
+comments. Syntactic data in Scheme source code are called @emph{forms}.
+(A form nested inside another form is called a @emph{subform}.)
+Consequently, Scheme's syntax has the property that any sequence of
+characters that is a form is also a syntactic datum representing some
+object. This can lead to confusion, since it may not be obvious out of
+context whether a given sequence of characters is intended to be a
+representation of objects or the text of a program. It is also a source
+of power, since it facilitates writing programs such as interpreters or
+compilers that treat programs as objects (or vice versa).
+
+A datum value may have several different external representations. For
+example, both @code{#e28.000} and @code{#x1c} are syntactic data
+representing the exact integer object 28, and the syntactic data
address@hidden(8 13)}, @code{( 08 13 )}, @code{(8 . (13 . ()))} all represent a
+list containing the exact integer objects 8 and 13. Syntactic data that
+represent equal objects (in the sense of @func{equal?})
+are always equivalent as forms of a program.
+
+Because of the close correspondence between syntactic data and datum
+values, we sometimes uses the term @emph{datum} for either a
+syntactic datum or a datum value when the exact meaning is apparent from
+the context.
+
address@hidden An implementation must not extend the lexical or datum syntax in
any
address@hidden way, with one exception: it need not treat the syntax
address@hidden @code{#!<identifier>}, for any <identifier> (@ref{lex syntax
address@hidden identifiers}) that is not @code{r6rs}, as a syntax violation,
and it may
address@hidden use specific @code{#!}--prefixed identifiers as flags indicating
that
address@hidden subsequent input contains extensions to the standard lexical or
datum
address@hidden syntax. The syntax @code{#!r6rs} may be used to signify that
the input
address@hidden afterward is written with the lexical syntax and datum syntax
described
address@hidden by this report. @code{#!r6rs} is otherwise treated as a comment;
address@hidden @ref{lex syntax whitespace and comments}.
+
address@hidden Lexical syntax, Datum syntax, Lexical and datum syntax, Syntax
address@hidden Lexical syntax
+
+The lexical syntax determines how a character sequence is split into a
+sequence of lexemes, omitting non--significant portions such as comments
+and whitespace. The character sequence is assumed to be text according
+to the @uref{http://unicode.org/,Unicode standard}.
+Some of the lexemes, such as
+identifiers, representations of number objects, strings etc., of the
+lexical syntax are syntactic data in the datum syntax, and thus
+represent objects. Besides the formal account of the syntax, this
+section also describes what datum values are represented by these
+syntactic data.
+
+The lexical syntax, in the description of comments, contains a forward
+reference to @meta{datum}, which is described as part of the datum
+syntax. Being comments, however, these @meta{datum}s do not play a
+significant role in the syntax.
+
+Case is significant except in representations of booleans, number
+objects, and in hexadecimal numbers specifying Unicode scalar values.
+For example, @code{#x1A} and @code{#X1a} are equivalent. The identifier
address@hidden is, however, distinct from the identifier @code{FOO}.
+
address@hidden Formal account
+
address@hidden
address@hidden may occur on either side of any lexeme, but not
+within a lexeme.
+
address@hidden, @code{.}, @meta{number}s, @meta{character}s, and
address@hidden, must be terminated by a @meta{delimiter} or by the end
+of the input.
+
address@hidden The following two characters are reserved for future extensions
to the
address@hidden language: @address@hidden @}}
+
address@hidden
address@hidden @stxref{identifier} | @var{boolean} | @stxref{number}
+ | @var{character} | @stxref{string}
+ | @stxlit{(} | @stxlit{)} | @stxlit{[} | @stxlit{]} | @stxlit{#(}
+ | @stxlit{'} | @stxlit{`} | @stxlit{,} | @stxlit{,@@} | @stxlit{.}
+ | @stxlit{#'} | @stxlit{#`} | @stxlit{#,} | @stxlit{#,@@}
address@hidden @stxlit{(} | @stxlit{)} | @stxlit{[} | @stxlit{]} | @stxlit{"}
| @stxlit{;} | @stxlit{#}
+ | @stxref{whitespace}
address@hidden display
+
+((UNFINISHED))
+
address@hidden Line endings
+
+Line endings are significant in Scheme in single--line comments
+and within string literals.
+In Scheme source code, any of the line endings in @meta{line-ending}
+marks the end of a line. Moreover, the two--character line endings
address@hidden @meta{linefeed} and @meta{carriage-return}
address@hidden each count as a single line ending.
+
+In a string literal, a @meta{line-ending} not preceded by a @code{\}
+stands for a linefeed character, which is the standard line--ending
+character of Scheme.
+
address@hidden Whitespace and comments
+
address@hidden
address@hidden @var{space} | @var{character-tabulation}
address@hidden @stxref{intraline-whitespace}
+ | @var{linefeed} | @var{line-tabulation} | @var{form-feed}
+ | @var{carriage-return} | @var{next-line}
+ | @i{any character whose category is Zs, Zl, or Zp}
address@hidden @var{linefeed} | @var{carriage return}
+ | @var{carriage-return} @var{linefeed} | @var{next-line}
+ | @var{carriage-return} @var{next-line} | @var{line-separator}
address@hidden @stxlit{;} all subsequent characters up to a @var{line-ending}
+ or @var{paragraph-separator}
+ | @stxref{nested-comment}
+ | @stxlit{#;} @stxref{interlexeme-space} @stxref{datum}
+ | @stxref{shebang-comment}
address@hidden @stxlit{#|} @stxref{comment-text} @stxref{comment-cont}*
@stxlit{|#}
address@hidden character sequence not containing @stxlit{#|} or @stxlit{|#}
address@hidden @stxref{nested-comment} @stxref{comment-text}
address@hidden @stxref{whitespace} | @stxref{comment}
address@hidden @address@hidden
address@hidden display
+
+As a special case the characters @stxlit{#!/} are treated as starting a
comment,
+but only at the beginning of file. These characters are used on
+Unix systems as an @uref{http://en.wikipedia.org/wiki/Shebang_(Unix), Shebang
interpreter directive}.
+The Kawa reader skips the entire line.
+If the last non-whitespace character is @address@hidden
+(backslash) then the following line is also skipped, and so on.
address@hidden
address@hidden @stxlit{#!} @var{absolute-filename} text up to non-escaped
@var{line-ending}
address@hidden display
+
address@hidden
address@hidden characters are spaces, linefeeds, carriage returns,
+character tabulations, form feeds, line tabulations, and any other
+character whose category is Zs, Zl, or Zp. Whitespace is used for
+improved readability and as necessary to separate lexemes from each
+other. Whitespace may occur between any two lexemes, but not within a
+lexeme. Whitespace may also occur inside a string, where it is
+significant.
+
+The lexical syntax includes several comment forms. In all cases,
+comments are invisible to Scheme, except that they act as delimiters,
+so, for example, a comment cannot appear in the middle of an identifier
+or representation of a number object.
+
+A semicolon (@code{;}) indicates the start of a line comment. The
+comment continues to the end of the line on which the semicolon appears.
+
+Another way to indicate a comment is to prefix a @stxref{datum}
+with @code{#;}, possibly with
address@hidden before the @meta{datum}. The comment consists
+of the comment prefix @code{#;} and the @meta{datum} together. This
+notation is useful for ``commenting out'' sections of code.
+
+Block comments may be indicated with properly nested @code{#|} and
address@hidden|#} pairs.
address@hidden
+#|
+ The FACT procedure computes the factorial of a
+ non-negative integer.
+|#
+(define fact
+ (lambda (n)
+ ;; base case
+ (if (= n 0)
+ #;(= n 1)
+ 1 ; identity of *
+ (* n (fact (- n 1))))))
address@hidden example
+
address@hidden The lexeme @code{#!r6rs}, which signifies that the program text
that
address@hidden follows is written with the lexical and datum syntax described
in this
address@hidden report, is also otherwise treated as a comment.
+
address@hidden Identifiers
+
address@hidden
address@hidden @stxref{initial} @stxref{subsequent}*
+ | @stxref{peculiar-identifier}
address@hidden @stxref{constituent} | @stxref{special-initial}
+ | @stxref{inline-hex-escape}
address@hidden @stxlit{a} | @stxlit{b} | @stxlit{c} | ... | @stxlit{z}
+ | @stxlit{A} | @stxlit{B} | @stxlit{C} | ... | @stxlit{Z}
address@hidden @stxref{letter}
+ | @i{any character whose Unicode scalar value is greater than
+ 127, and whose category is Lu, Ll, Lt, Lm, Lo, Mn,
+ Nl, No, Pd, Pc, Po, Sc, Sm, Sk, So, or Co}
address@hidden @stxlit{!} | @stxlit{$} | @stxlit{%} | @stxlit{&} | @stxlit{*} |
@stxlit{/} | @stxlit{<} | @stxlit{=}
+ | @stxlit{>} | @stxlit{?} | @stxlit{^} | @stxlit{_} | @stxlit{~}
address@hidden @stxref{initial} | @stxref{digit}
+ | @i{any character whose category is Nd, Mc, or Me}
+ | @stxref{special-subsequent}
address@hidden @stxlit{0} | @stxlit{1} | @stxlit{2} | @stxlit{3} | @stxlit{4} |
@stxlit{5} | @stxlit{6} | @stxlit{7} | @stxlit{8} | @stxlit{9}
address@hidden @stxlit{0} | @stxlit{1} | @stxlit{2} | @stxlit{3} | @stxlit{4} |
@stxlit{5} | @stxlit{6} | @stxlit{7}
address@hidden @stxref{digit}
+ | @stxlit{a} | @stxlit{A} | @stxlit{b} | @stxlit{B} | @stxlit{c} |
@stxlit{C} | @stxlit{d} | @stxlit{D} | @stxlit{e} | @stxlit{E} | @stxlit{f} |
@stxlit{F}
address@hidden @stxlit{+} | @stxlit{-} | @stxlit{.} | @stxlit{@@}
address@hidden @stxref{inline-hex-escape}
+ | @address@hidden
+ | @stxref{multi-escape-sequence}
address@hidden @address@hidden@stxlit{;}
address@hidden @stxref{hex-digit}+
address@hidden @stxlit{|address@hidden@address@hidden|}
address@hidden @i{any character except} @stxlit{|} @i{or} @address@hidden
+ | @stxref{inline-hex-escape} | @stxref{mnemonic-escape} |
@address@hidden|}
+
address@hidden @i{any character except @code{x}}
address@hidden @stxlit{+} | @stxlit{-} | @stxlit{...} | @stxlit{->}
@address@hidden
address@hidden display
+
+Most identifiers allowed by other programming languages are also
+acceptable to Scheme. In general, a sequence of letters, digits, and
+``extended alphabetic characters'' is an identifier when it begins with
+a character that cannot begin a representation of a number object. In
+addition, @code{+}, @code{-}, and @code{...} are identifiers, as is a
+sequence of letters, digits, and extended alphabetic characters that
+begins with the two--character sequence @code{->}. Here are some
+examples of identifiers:
+
address@hidden
+lambda q soup
+list->vector + V17a
+<= a34kTMNs ->-
+the-word-recursion-has-many-meanings
address@hidden example
+
+Extended alphabetic characters may be used within identifiers as if they
+were letters. The following are extended alphabetic characters:
+
address@hidden
+! $ % & * + - . / < = > ? @@ ^ _ ~
address@hidden example
+
+Moreover, all characters whose Unicode scalar values are greater than
+127 and whose Unicode category is Lu, Ll, Lt, Lm, Lo, Mn, Mc, Me, Nd,
+Nl, No, Pd, Pc, Po, Sc, Sm, Sk, So, or Co can be used within
+identifiers. In addition, any character can be used within an
+identifier when specified using an @meta{escape-sequence}. For example,
+the identifier @code{H\x65;llo} is the same as the identifier
address@hidden
+
+Kawa supports two additional non-R6RS ways of making
+identifiers using special characters, both taken from Common Lisp:
+Any character (except @code{x}) following a backslash is treated
+as if it were a @var{letter};
+as is any character between a pair of vertical bars.
+
address@hidden , and the identifier @code{\x3BB;} is the same as the
address@hidden identifier $\lambda$.
+
+Identifiers have two uses within Scheme programs:
address@hidden
address@hidden
+Any identifier may be used as a @ref{variable-reference,,variable}
+or as a @ref{macro-reference,,syntactic keyword}.
address@hidden
+When an identifier appears as or with in @ref{literal-expression,,literal},
+it is being used to denote a @ref{Simple symbols,,symbol}.
address@hidden itemize
+
+In contrast with older versions of Scheme, the syntax distinguishes
+between upper and lower case in identifiers and in characters
+specified via their names, but not in numbers, nor in inline hex
+escapes used in the syntax of identifiers, characters, or strings.
+The following directives give explicit control over case folding.
+
address@hidden Syntax #!fold-case
address@hidden Syntax #!no-fold-case
+
+These directives may appear anywhere comments are permitted and are
+treated as comments, except that they affect the reading of subsequent
+data. The @code{#!fold-case} directive causes the @code{read}
+procedure to case-fold (as if by @code{string-foldcase}) each
+identifier and character name subsequently read from the same
+port. The @code{#!no-fold-case} directive causes the @code{read}
+procedure to return to the default, non-folding behavior.
address@hidden deffn
+
+Note that colon @code{:} is treated specially for
address@hidden notation, colon notation} in Kawa Scheme,
+though it is a @var{special-initial} in standard Scheme (R6RS).
+
address@hidden Numbers
+
+((INCOMPLETE))
+
address@hidden
address@hidden ((TODO))
+ | @stxref{quantity}
address@hidden @stxref{digit}+ @stxref{optional-exponent}
+ | @stxlit{.} @stxref{digit}+ @stxref{optional-exponent}
+ | @stxref{digit}+ @stxlit{.} @stxref{digit}+ @stxref{optional-exponent}
address@hidden display
+
address@hidden
address@hidden @i{empty}
+ | @stxref{exponent-marker} @stxref{optional-sign} @stxref{digit}+
address@hidden @stxlit{e} | @stxlit{s} | @stxlit{f} | @stxlit{d} | @stxlit{l}
address@hidden display
+The letter used for the exponent in a floating-point literal determines
+its type:
address@hidden @asis
address@hidden @stxlit{e}
+Returns a @code{gnu.math.DFloat} - for example @code{12e2}.
+Note this matches the default when there is no @stxref{exponent-marker}.
address@hidden @stxlit{s} or @stxlit{f}
+Returns a primitive @code{float} (or @code{java.lang.Float}
+when boxed as an object) - for example @code{12s2} or @code{12f2}.
address@hidden @stxlit{d}
+Returns a primitive @code{double} (or @code{java.lang.Double} when boxed)
+- for example @code{12d2}.
address@hidden @stxlit{l}
+Returns a @code{java.math.BigDecimal} - for example @code{12l2}.
address@hidden table
address@hidden
address@hidden @i{empty} | @stxlit{+} | @stxlit{-}
address@hidden @stxlit{0} | @stxlit{1}
address@hidden @stxlit{0} | @stxlit{1} | @stxlit{2} | @stxlit{3} | @stxlit{4} |
@stxlit{5} | @stxlit{6} | @stxlit{7}
address@hidden @stxref{digit}
address@hidden @stxref{digit-10} | @stxlit{a} | @stxlit{b} | @stxlit{c} |
@stxlit{d} | @stxlit{e} | @stxlit{f}
address@hidden display
+
address@hidden Datum syntax, Hash-prefixed forms, Lexical syntax, Syntax
address@hidden Datum syntax
+
+The datum syntax describes the syntax of syntactic data in terms of a
+sequence of @meta{lexeme}s, as defined in the lexical syntax.
+
+The following grammar describes the syntax of syntactic data in terms of
+various kinds of lexemes defined in the grammar in section ``Lexical
+Syntax'':
+
address@hidden
address@hidden @stxref{defining-datum}
+ | @stxref{nondefining-datum}
+ | @stxref{defined-datum}
address@hidden @stxref{lexeme-datum}
+ | @stxref{compound-datum}
+
address@hidden @stxref{boolean} | @meta{number}
+ | @stxref{character} | @stxref{string} | @stxref{symbol}
address@hidden @stxref{identifier}
address@hidden @stxref{list} | @stxref{vector} | @stxref{uniform-vector} |
@stxref{array-literal} | @stxref{extended-string-literal} | @stxref{xml-literal}
address@hidden @stxlit{(address@hidden@stxlit{)}
+ | @stxlit{(address@hidden@stxref{datum}} @stxlit{.} @address@hidden)}
+ | @stxref{abbreviation}
address@hidden @stxlit{#(address@hidden@address@hidden)}
address@hidden display
address@hidden FIXME: add to abbrev-prefix: @stxlit{#,} | @stxlit{#,@@}
+
address@hidden labels}
address@hidden Datum labels
+
address@hidden
address@hidden @address@hidden@stxlit{=}
address@hidden @address@hidden@stxref{nondefining-datum}
address@hidden @address@hidden@stxlit{#}
address@hidden @address@hidden
address@hidden display
+
+The lexical syntax @address@hidden@meta{datum}} reads the
+same as @meta{datum}, but also results in @meta{datum} being
+labelled by @meta{n}, which must a sequence of digits.
+
+The lexical syntax @address@hidden serves as a reference to some
+object labelled by @address@hidden; the result is the same object
+(in the sense of @code{eq?}) as the @address@hidden
+
+Together, these syntaxes permit the notation of structures
+with shared or circular substructure.
+
address@hidden
+(let ((x (list 'a 'b 'c)))
+ (set-cdr! (cddr x) x)
+ x) @result{} #0=(a b c . #0#)
address@hidden example
+
+The scope of a datum label is the portion of the outermost
+datum in which it appears that is to the right of the label.
+Consequently, a reference @address@hidden can occur
+only after a label @address@hidden;
+it is an error to attempt a forward reference.
+In addition, it is an error if the reference appears as the labelled
+object itself (as in @address@hidden@var{n}#}), because the object
+labelled by @address@hidden is not well defined in this case.
+
+
+
address@hidden Abbreviations
+
address@hidden
address@hidden @stxref{r6rs-abbreviation} | @stxref{kawa-abbreviation}
address@hidden @stxref{abbrev-prefix} @stxref{datum}
address@hidden @stxlit{'} | @stxlit{`} | @stxlit{,} | @stxlit{,@@}
+ | @stxlit{#'} | @stxlit{#`}
address@hidden XXX
address@hidden display
+
+The following abbreviations are expanded at read-time:
+
address@hidden @asis
address@hidden @stxlit{'address@hidden
+means @stxlit{(quote} @address@hidden)}.
+
address@hidden @address@hidden
+means @stxlit{(quasiquote} @address@hidden)}.
+
address@hidden @stxlit{,address@hidden
+means @stxlit{(unquote} @address@hidden)}.
+
address@hidden @stxlit{,@@address@hidden
+means @stxlit{(unquote-splicing} @address@hidden)}.
+
address@hidden @stxlit{#'address@hidden
+means @stxlit{(syntax} @address@hidden)}.
+
address@hidden @address@hidden
+means @stxlit{(quasisyntax} @address@hidden)}.
+
address@hidden @stxlit{#,address@hidden
+means @stxlit{(unsyntax} @address@hidden)}.
+This abbreviation is currently only recognized when nested inside an explicit
address@hidden@meta{datum} form,
+because of a conflict with SRFI-10 named constructors.
+
address@hidden @stxlit{#,@@address@hidden
+means @stxlit{(unsyntax-splicing} @address@hidden)}.
+
address@hidden @address@hidden:address@hidden
+means @stxlit{($lookup$} @meta{datum1} @stxlit{(quasiquote} @address@hidden))}.
address@hidden notation}.
+
address@hidden @address@hidden address@hidden
+means @stxlit{($bracket-list$} @meta{expression} address@hidden)}.
+
address@hidden @address@hidden@meta{expression} address@hidden
+means @stxlit{($bracket-apply$} @meta{operator} @meta{expression}
address@hidden)}.
+
address@hidden table
+
address@hidden Hash-prefixed forms
address@hidden Hash-prefixed forms
+
+A number of different special forms are indicated by an
+initial hash (number) symbols (@code{#}).
+Here is a table summarizing them.
+
+Case is ignored for the character followed the @code{#}.
+Thus @code{#x} and @code{#X} are the same.
+
address@hidden @asis
address@hidden @stxlit{#:address@hidden
+Guile-style @ref{Keywords,keyword} syntax.
address@hidden @stxlit{#\\}
address@hidden, Character literals, Character literals}.
address@hidden @stxlit{#!}
address@hidden named constants}.
address@hidden @address@hidden
+Equivalent to @code{(quasisyntax @var{datum})}.
+Convenience syntax for syntax-case macros.
address@hidden @stxlit{#'address@hidden
+Equivalent to @code{(syntax @var{datum})}.
+Convenience syntax for syntax-case macros.
address@hidden @stxlit{#,address@hidden
+Equivalent to @code{(unsyntax @var{datum})}.
+Currently only recognized when inside a @address@hidden form.
+Convenience syntax for syntax-case macros.
address@hidden @stxlit{#,(address@hidden @var{datum} address@hidden)}
+Special named constructors.
+This syntax is deprecated, because it conflicts with @code{unsyntax}.
+It is only recognized when @emph{not} in a @address@hidden form.
address@hidden @stxlit{#,@@address@hidden
+Equivalent to @code{(unsyntax-splicing @var{datum})}.
address@hidden @stxlit{#(}
+A vector.
address@hidden @stxlit{#|}
+Start of nested-comment.
address@hidden @stxlit{#/address@hidden@stxlit{/}
address@hidden expressions}.
address@hidden @stxlit{#<}
address@hidden literals}.
address@hidden @stxlit{#;address@hidden
+A datum comment - the @var{datum} is ignored.
+(An @var{interlexeme-space} may appear before the @var{datum}.)
address@hidden @address@hidden@address@hidden
+A reference definition, allowing cyclic and shared structure.
+Equivalent to the @var{datum}, but also defines an association between
+the integer @var{number} and that @var{datum}, which can be
+used by a subsequent @address@hidden form.
address@hidden @address@hidden@stxlit{#}
+A back-reference, allowing cyclic and shared structure.
address@hidden @address@hidden@address@hidden
+An @ref{array-literals,array literal},
+for a multi-dimensional array of rank @var{R}.
address@hidden @stxlit{#b}
+A binary (base-2) number.
address@hidden @stxlit{#d}
+A decimal (base-10) number.
address@hidden @stxlit{#e}
+A prefix to treat the following number as exact.
address@hidden @stxlit{#f}
address@hidden @stxlit{#false}
+The standard boolean false object.
address@hidden @address@hidden@stxlit{(address@hidden address@hidden)}
+A uniform vector of floating-point numbers.
+The parameter @var{n} is a precision, which can be 32 or 64.
address@hidden vectors}.
address@hidden @stxlit{#i}
+A prefix to treat the following number as inexact.
address@hidden @stxlit{#o}
+An octal (base-8) number.
address@hidden @address@hidden@stxlit{r}
+A number in the specified @var{base} (radix).
address@hidden @address@hidden@stxlit{(address@hidden address@hidden)}
+A uniform vector of signed integers.
+The parameter @var{n} is a precision, which can be 8, 16, 32, or 64.
address@hidden vectors}.
address@hidden @stxlit{#t}
address@hidden @stxlit{#true}
+The standard boolean true object.
address@hidden @address@hidden@stxlit{(address@hidden address@hidden)}
+A uniform vector of unsigned integers.
+The parameter @var{n} is a precision, which can be 8, 16, 32, or 64.
address@hidden vectors}.
address@hidden @stxlit{#x}
+A hexadecimal (base-16) number.
address@hidden table
+
+The follow named constructor forms are supported:
+
address@hidden @asis
address@hidden @stxlit{#,(path} @address@hidden)}
address@hidden @stxlit{#,(filepath} @address@hidden)}
address@hidden @stxlit{#,(URI} @address@hidden)}
address@hidden @stxlit{#,(symbol} @var{local-name} address@hidden
address@hidden@stxlit{)}
address@hidden @stxlit{#,(symbol} @var{local-name} @address@hidden)}
address@hidden @stxlit{#,(namespace} @var{uri} address@hidden@stxlit{)}
address@hidden @stxlit{#,(duration} @address@hidden)}
address@hidden table
+
address@hidden Primitive expression syntax
address@hidden Primitive expression syntax
+
address@hidden
address@hidden @stxref{literal-expression} | @stxref{variable-reference}
+ | @stxref{procedure-call} | TODO
address@hidden display
+
address@hidden
address@hidden Literal expressions
+
address@hidden
address@hidden @stxlit{(quote} @address@hidden)}
+ | @stxlit{'} @stxref{datum}
+ | @var{constant}
address@hidden @var{number} | @meta{boolean} | @meta{character} | @meta{string}
address@hidden display
+
address@hidden(quote @var{datum})} evaluates to @var{datum},
+which may be any external representation of a Scheme object.
+This notation is used to include literal constants in Scheme code.
address@hidden
+(quote a) @result{} a
+(quote #(a b c)) @result{} #(a b c)
+(quote (+ 1 2)) @result{} (+ 1 2)
address@hidden example
+
address@hidden(quote @var{datum})} may be abbreviated as @code{'@var{datum}}.
+The two notations are equivalent in all respects.
address@hidden
+’a @result{} a
+’#(a b c) @result{} #(a b c)
+’() @result{} ()
+’(+ 1 2) @result{} (+ 1 2)
+’(quote a) @result{} (quote a)
+’’a @result{} (quote a)
address@hidden example
+
+Numerical constants, string constants, character constants,
+bytevector constants, and boolean constants evaluate to
+themselves; they need not be quoted.
+
address@hidden
+145932 @result{} 145932
+#t @result{} #t
+"abc" @result{} "abc"
address@hidden example
address@hidden #vu8(2 24 123) @result{} #vu8(2 24 123)
+
+Note that @ref{Keywords,keywords} need to be quoted,
+unlike some other Lisp/Scheme dialect, including Common Lisp,
+and earlier versions of Kawa. (Kawa currently evaluates a non-quoted
+keyword as itself, but that will change.)
+
address@hidden
address@hidden Variable references
+
address@hidden
address@hidden @stxref{identifier}
address@hidden display
+An expression consisting of a variable is a variable reference if it is
+not a macro use (see below). The value of the variable reference is the
+value stored in the location to which the variable is bound. It is a
+syntax violation to reference an unbound variable.
+
+The following example assumes the base library has been
+imported:
+
address@hidden
+(define x 28)
+x @result{} 28
address@hidden example
+
address@hidden Procedure calls
+
address@hidden
address@hidden @stxlit{(address@hidden @stxref{operand} @dots{})
address@hidden @stxref{expression}
address@hidden @stxref{expression}
+ | @stxref{keyword} @stxref{expression}
+ | @code{@@} @stxref{expression}
+ | @code{@@:} @stxref{expression}
address@hidden display
+
+A procedure call consists of expressions for the procedure to be called
+and the arguments to be passed to it, with enclosing parentheses. A
+form in an expression context is a procedure call if @meta{operator} is
+not an identifier bound as a syntactic keyword.
+
+When a procedure call is evaluated, the operator and operand expressions
+are evaluated (in an unspecified order) and the resulting procedure is
+passed the resulting arguments.
+
address@hidden
+(+ 3 4) @result{} 7
+((if #f + *) 3 4) @result{} 12
address@hidden example
+
+The syntax @stxref{keyword} @var{expression} is a @dfn{keyword argument}.
+This is a mechanism for specifying arguments using a name rather than position,
+and is especially useful for procedures with many optional paramaters.
+Note that @stxref{keyword} must be literal, and cannot be the
+result from evaluating a non-literal expression.
+(This is a change from previous versions of Kawa,
+and is different from Common Lisp and some other Scheme dialects.)
+
+An expression prefixed by @code{@@} or @code{@@:} is
+a splice argument. The following expression must evaluate to an
+``argument list'' (see @ref{Application and Arguments Lists} for details);
+each element in the argument
+becomes a separate argument when call the @var{operator}.
+(This is very similar to the ``spread'' operator is EcmaScript 6.)
+
address@hidden Colon notation
address@hidden Property access using colon notation
+
+The @dfn{colon notation} accesses named parts (properties) of a value.
+It is used to get and set fields, call methods, construct compound symbols,
+and more.
+Evaluating the form @address@hidden:@var{property}}
+evaluates the @address@hidden then it extracts the named @address@hidden of
the result.
+
address@hidden
address@hidden @address@hidden:address@hidden
address@hidden @stxref{expression}
address@hidden @stxref{identifier} | @stxlit{,address@hidden
address@hidden display
+
+The @var{property-name} is usually a literal name,
+but it can be an unquoted @var{expression} (i.e. following a @code{,}),
+in which case the name is evaluated at run-time.
+No separators are allowed on either side of the colon.
+
+The input syntax @address@hidden:@var{part}} is translated by
+the Scheme reader to the internal representation @code{($lookup$ @var{owner}
(quasiquote @var{part}))}.
+
address@hidden Part lookup rules
+
+Evaluation proceeds as follows.
+First @var{property-owner-expression} is
+evaluated to yield an @var{owner} object.
+Evaluating the @var{property-name} yields a @var{part} name,
+which is a simple symbol: Either
+the literal @var{identifier}, or the result of evaluating the
+property-name @var{expression}.
+If the @var{expression} evaluates to a string, it is converted to
+a symbol, as if using @code{string->symbol}.
+
address@hidden
address@hidden
+If the @var{owner} implements @code{gnu.mapping.HasNamedParts},
+then the result is that of invoking the @code{get} method of the @var{owner}
+with the @var{part} name as a parameter.
+
+As a special case of this rule, if @var{owner} is a
address@hidden, then the result is the
address@hidden,compound symbol in that namespace}.
address@hidden
+If @var{owner} is a @code{java.lang.Class} or a @code{gnu.bytecode.ObjectType},
+the result is the static member named @var{part}
+(i.e. a static field, method, or member class).
address@hidden
+If @var{owner} is a @code{java.lang.Package} object, we get the member
+class or sub-package named @var{part}.
address@hidden
+Otherwise, we look for a named member (instance member or field).
+
+Note you can't use colon notation to invoke instance methods
+of a @code{Class}, because it will match a previous rule.
+For example if you want to invoke the @code{getDeclaredMethod}
+method of the @code{java.util.List} , you can't write
@code{(java.util.List:getDeclaredMethod} because that will look for a static
method in @code{java.util.List}.
address@hidden itemize
+
+If the colon form is on the left-hand-side of an assignment (@code{set!}),
+then the named part is modified as appropriate.
+
address@hidden We will look into examples and details below.
address@hidden @subsection The @code{HasNamedParts} case
address@hidden @subsection Static parts of classes and packages
address@hidden @subsection Instance parts
+
address@hidden Specific cases
+
+Some of these are deprecated;
+more compact and readable forms are usually preferred.
+
address@hidden Invoking methods
+
address@hidden
address@hidden(address@hidden@stxlit{:address@hidden @var{arg} address@hidden)}
address@hidden(address@hidden@stxlit{:address@hidden @var{instance} @var{arg}
address@hidden)}
address@hidden(address@hidden@stxlit{:address@hidden @var{arg} address@hidden)}
address@hidden(*:address@hidden @var{instance} @var{arg} address@hidden)}
address@hidden display
+
+For details @pxref{Method operations}.
+
address@hidden Accessing fields
+
address@hidden
address@hidden@stxlit{:address@hidden
address@hidden@stxlit{:address@hidden
address@hidden(address@hidden@stxlit{:address@hidden @address@hidden)}
address@hidden display
+
+For details @pxref{Field operations}.
+
address@hidden Type literal
+
address@hidden
address@hidden(address@hidden@stxlit{:<>)}
address@hidden display
+Returns the @var{type}.
+Deprecated; usually you can just write:
address@hidden
address@hidden
address@hidden example
+
address@hidden Type cast
+
address@hidden
address@hidden(address@hidden@stxlit{:address@hidden@atchar{}} @address@hidden)}
address@hidden display
+Performs a cast.
+Deprecated; usually you can just write:
address@hidden
+->@var{type}
address@hidden example
+
address@hidden Type test
+
address@hidden
address@hidden(address@hidden@stxlit{:instanceof?} @address@hidden)}
address@hidden display
+
+Deprecated; usually you can just write:
address@hidden
+(@var{type}? @var{expression})
address@hidden example
+
address@hidden New object construction
+
address@hidden
address@hidden(address@hidden@stxlit{:new} @var{arg} address@hidden)}
address@hidden display
+
+Deprecated; usually you can just write:
address@hidden
address@hidden(address@hidden @var{arg} address@hidden)}
address@hidden display
+
address@hidden Getting array length
+
address@hidden
address@hidden@stxlit{:length}
address@hidden(address@hidden@stxlit{:.length)}
address@hidden display
+
+
address@hidden Bodies
address@hidden Programs and Bodies
+
address@hidden units}
address@hidden Program units
+
+A @meta{program-unit} consists of a sequence of definitions and expressions.
+
address@hidden
address@hidden @address@hidden address@hidden
+ | @stxref{statements}
address@hidden @address@hidden
address@hidden @var{definition} | @stxref{expression} | @stxlit{(begin}
@address@hidden @stxlit{)}
address@hidden display
+
+Typically a @meta{program-unit} corresponds to a single source file
+(i.e.a named file in the file system). Evaluating a @meta{program-unit}
+first requires the Kawa processor to analyze
+the whole @meta{program-unit} to determine which names are defined by the
+definitions, and then evaluates each @meta{statement} in order in the context
+of the defined names. The value of an @meta{expression} is normally
+discarded, but may be printed out instead, depending on the evaluating context.
+
+The read-eval-print-loop (REPL) reads one or more lines until it gets
+a valid @meta{program-unit}, and evaluates it as above, except that the
+values of expressions are printed to the console (as if using the
address@hidden function). Then the REPL reads and evaluates
+another @meta{program-unit}, and so on. A definition in an earlier
address@hidden is remembered and is visible in a later @meta{program-unit}
+unles it is overridden.
+
address@hidden encoding specifier
address@hidden coding specifier
+A comment in the first 2 lines of a source file may contain an encoding
+specification. This can be used to tell the reader what kind of character
+set encoding is used for the file. This only works for a character
+encoding that is compatible with ASCII (in the sense that if the
+high-order bit is clear then it's an ASCII character),
+and that are no non-ASCI characters in the lines upto and including
+the encoding specification.
+A basic example is:
address@hidden
+;; -*- coding: utf-8 -*-
address@hidden example
+In general any string that matches the following regular expression works:
address@hidden
+coding[:=]\s*([-a-zA-Z0-9]+)
address@hidden example
+
address@hidden Libraries
+
address@hidden library}
+A @meta{program-unit} may contain @meta{library-definitions}.
+In addition, any @meta{statements} in @meta{program-unit} comprise
+an @dfn{implicit library}, in that it can be given a name, and referenced
+from other libraries.
+Certain names defined in the @meta{program-unit} can be exported,
+and then they can be imported by other libraries.
+For more information @pxref{Module classes}.
+
+It is recommended but not required that:
address@hidden
address@hidden
+There should be at most one @meta{library-definition} in a @meta{program-unit}.
address@hidden
+The @meta{library-name} of the @meta{library-definition} should
+match the name of the source file. For example:
address@hidden
+(define-library (foo bar) ...)
address@hidden example
+should be in a file named @code{foo/bar.scm}.
address@hidden
+If there is a @meta{library-definition}, there should
+be no extra @meta{statements} - i.e no implicit library definition.
+(It is disallowed to @code{export} any definitions from the
+implicit library if there is also a @meta{library-definition}.)
address@hidden itemize
+Following these recommendations makes it easier to locate
+and organize libraries.
+However, having multiple libraries in a single @meta{program-unit}
+is occasionally useful for source distribution and for testing.
+
address@hidden Bodies
+
+The @meta{body} of a @func{lambda}, @func{let}, @func{let*},
address@hidden, @func{let*-values}, @func{letrec}, or @func{letrec*}
+expression, or that of a definition with a body consists of zero or more
+definitions or expressions followed by a final expression.
+(Standard Scheme requires that all definitions precede all expressions.)
+
address@hidden
address@hidden @address@hidden
address@hidden display
+
+Each identifier defined by a definition is local to the @meta{body}.
+That is, the identifier is bound, and the region of the binding is the
+entire @meta{body}.
+Example:
+
address@hidden
+(let ((x 5))
+ (define foo (lambda (y) (bar x y)))
+ (define bar (lambda (a b) (+ (* a b) a)))
+ (foo (+ x 3)))
address@hidden 45
address@hidden example
+
+When @func{begin}, @func{let-syntax}, or @func{letrec-syntax} forms
+occur in a body prior to the first expression, they are spliced into the
+body. Some or all of the body, including portions wrapped in
address@hidden, @func{let-syntax}, or @func{letrec-syntax} forms, may be
+specified by a macro use.
+
+An expanded @meta{body} containing variable definitions can be
+converted into an equivalent @func{letrec*} expression.
+(If there is a definition following expressions you may need to
+convert the expressions to dummy definitions.) For example,
+the @func{let} expression in the above example is equivalent to
+
address@hidden
+(let ((x 5))
+ (letrec* ((foo (lambda (y) (bar x y)))
+ (bar (lambda (a b) (+ (* a b) a))))
+ (foo (+ x 3))))
address@hidden example
+
+
address@hidden Syntax and conditional compilation
address@hidden Syntax and conditional compilation
+
address@hidden Feature testing
+
address@hidden Syntax cond-expand @address@hidden address@hidden(else}
address@hidden)}]
address@hidden
address@hidden @stxlit{(address@hidden @address@hidden)}
address@hidden @i{fff-rec}
address@hidden @stxref{feature-identifier}
+ | @stxlit{(and} @address@hidden@stxlit{)}
+ | @stxlit{(or} @address@hidden@stxlit{)}
+ | @stxlit{(not} @address@hidden)}
+ | @stxlit{(library} @address@hidden)}
address@hidden a symbol which is the name or alias of a SRFI
address@hidden display
+
+The @code{cond-expand} form tests for the existence of features at
+macro-expansion time. It either expands into the body of one of its
+clauses or signals an error during syntactic
+processing. @code{cond-expand} expands into the body of the first clause
+whose feature requirement is currently satisfied; the @code{else}
+clause, if present, is selected if none of the previous clauses is
+selected.
+
+The implementation has a set of
+feature identifiers which are ``present'', as well as a set
+of libraries which can be imported.
+The value of a
address@hidden is determined by replacing each
address@hidden by @code{#t} if it is present
+(and @code{#f} otherwise);
+replacing @code{(library @meta{library-name})}
+by @code{#t} if @meta{library-name} is importable (and @code{#f} otherwise);
+and then evaluating the resulting expression as a Scheme boolean expression
+under the normal interpretation of @code{and}, @code{or}, and @code{not}.
+
+Examples:
address@hidden
+(cond-expand
+ ((and srfi-1 srfi-10)
+ (write 1))
+ ((or srfi-1 srfi-10)
+ (write 2))
+ (else))
address@hidden example
+
address@hidden
+(cond-expand
+ (command-line
+ (define (program-name) (car (argv)))))
address@hidden example
+
+The second example assumes that @code{command-line} is an alias for some
+feature which gives access to command line arguments. Note that an error
+will be signaled at macro-expansion time if this feature is not present.
+
+You can use @code{java-6}, @code{java-7}, @code{java-8},
+or @code{java-9} to check if the underlying Java
+is a specific version or newer.
+For example the name @code{java-7} matches for
+either Java 7, Java 8, or newer, as
+reported by @code{System} property @code{"java.version"}.
+
+You can use @code{class-exists:@var{ClassName}} to check
+if @address@hidden exists at compile-time.
+The identifier @code{class-exists:org.example.MyClass}
+is roughly equivalent to the test @code{(library (org example MyClass))}.
+(The latter has some special handling for @code{(srfi ...)} as well
+as builtin Kawa classes.)
address@hidden deffn
+
address@hidden Procedure features
+Returns a list of feature identifiers which @code{cond-expand}
+treats as true.
+This not a complete list - for example @code{class-exists:@var{ClassName}}
+feature identifiers are not included.
+It is an error to modify this list.
+Here is an example of what @code{features} might return:
address@hidden
+(features) @result{}
+(complex exact-complex full-unicode java-7 java-6 kawa
+ ratios srfi-0 srfi-4 srfi-6 srfi-8 srfi-9 srfi-11
+ srfi-16 srfi-17 srfi-23 srfi-25 srfi-26 srfi-28 srfi-30
+ srfi-39 string-normalize-unicode threads)
address@hidden example
address@hidden deffn
+
address@hidden File inclusion
+
address@hidden
address@hidden
address@hidden Syntax include @atleastone{path}
address@hidden Syntax include-relative @atleastone{path}
address@hidden Syntax include-ci @atleastone{path}
+These take one or more path names expressed as string literals,
+find corresponding files, read the contents of the files in the specified order
+as if by repeated applications of @code{read}, and effectively
+replace the @code{include} with a @code{begin} form
+containing what was read from the files.
+
+You can control the search path used for @code{include}
+by setting the @code{kawa.include.path} property. For example:
address@hidden
+$ kawa -Dkawa.include.path="|:/opt/kawa-includes"
address@hidden example
+The special @code{"|"} path element means to search
+relative to the directory containing the including source file.
+The default search path is @code{"|:."} which means to first
+search the directory containing the including source file,
+and then search the directory specified by @code{(current-path)}.
+
+The search path for @code{include-relative} prepends @code{"|"}
+before the search path used by @code{include}, so it always
+searches first the directory containing the including source file.
+Note that if the default search path is used then @code{include}
+and @code{include-relative} are equivalent; there is only a difference
+if the @code{kawa.include.path} property changes the default.
+
+Using @code{include-ci} is like @code{include}, except that it reads each
+file as if it began with the @code{#!fold-case} directive.
address@hidden deffn
+
address@hidden Macros
address@hidden Macros
address@hidden
+
+Libraries and top--level programs can define and use new kinds of
+derived expressions and definitions called @emph{syntactic abstractions}
+or @emph{macros}. A syntactic abstraction is created by binding a
+keyword to a @emph{macro transformer} or, simply, @emph{transformer}.
+
+The transformer determines how a use of the macro (called a @emph{macro
+use}) is transcribed into a more primitive form.
+
+Most macro uses have the form:
+
address@hidden
+(@meta{keyword} @meta{datum} @dots{})
address@hidden example
address@hidden
+where @meta{keyword} is an identifier that uniquely determines the kind
+of form. This identifier is called the @emph{syntactic keyword}, or
+simply @emph{keyword}. The number of @meta{datum}s and the syntax of
+each depends on the syntactic abstraction.
+
+Macro uses can also take the form of improper lists, singleton
+identifiers, or @func{set!} forms, where the second subform of the
address@hidden is the keyword:
+
address@hidden
+(@meta{keyword} @meta{datum} @dots{} . @meta{datum})
address@hidden
+(set! @meta{keyword} @meta{datum})
address@hidden example
+
+The @func{define-syntax}, @func{let-syntax} and @func{letrec-syntax}
+forms create bindings for keywords, associate them with macro
+transformers, and control the scope within which they are visible.
+
+The @func{syntax-rules} and @func{identifier-syntax} forms create
+transformers via a pattern language. Moreover, the @func{syntax-case}
+form allows creating transformers via arbitrary Scheme code.
+
+Keywords occupy the same name space as variables. That is, within the
+same scope, an identifier can be bound as a variable or keyword, or
+neither, but not both, and local bindings of either kind may shadow
+other bindings of either kind.
+
+Macros defined using @func{syntax-rules} and @func{identifier-syntax}
+are ``hygienic'' and ``referentially transparent'' and thus preserve
+Scheme's lexical scoping.
+
address@hidden
address@hidden
+If a macro transformer inserts a binding for an identifier (variable or
+keyword) not appearing in the macro use, the identifier is in effect
+renamed throughout its scope to avoid conflicts with other identifiers.
+
address@hidden
+If a macro transformer inserts a free reference to an identifier, the
+reference refers to the binding that was visible where the transformer
+was specified, regardless of any local bindings that may surround the
+use of the macro.
address@hidden itemize
+
+Macros defined using the @func{syntax-case} facility are also hygienic
+unless @func{datum->syntax} is used.
+
+Kawa supports most of the @code{syntax-case} feature.
+
+Syntax definitions are valid wherever definitions are.
+They have the following form:
+
address@hidden Syntax define-syntax keyword @stxref{transformer-spec}
+The @var{keyword} is a identifier, and @var{transformer-spec}
+is a function that maps syntax forms to syntax forms,
+usually an instance of @code{syntax-rules}.
+If the @code{define-syntax} occurs at the top level, then the top-level
+syntactic environment is extended by binding the @var{keyword}
+to the specified transformer, but existing references to any top-level
+binding for @var{keyword} remain unchanged. Otherwise, it is an
address@hidden syntax definition}, and is local to the @var{body}
+in which it is defined.
+
address@hidden
+(let ((x 1) (y 2))
+ (define-syntax swap!
+ (syntax-rules ()
+ ((swap! a b)
+ (let ((tmp a))
+ (set! a b)
+ (set! b tmp)))))
+ (swap! x y)
+ (list x y)) @result{} (2 1)
address@hidden example
+
+Macros can expand into definitions in any context that permits them.
+However, it is an error for a definition to define an identifier
+whose binding has to be known in order to determine the meaning
+of the definition itself, or of any preceding definition that belongs
+to the same group of internal definitions.
address@hidden deffn
+
address@hidden Syntax define-syntax-case name @stxlit{(address@hidden)}
@stxlit{(}pattern address@hidden)} ...
+A convenience macro to make it easy to define @code{syntax-case}-style macros.
+Defines a macro with the given @var{name} and list of @var{literals}.
+Each @var{pattern} has the form of a @code{syntax-rules}-style pattern,
+and it is matched against the macro invocation syntax form.
+When a match is found, the corresponding @var{expr} is evaluated.
+It must evaluate to a syntax form,
+which replaces the macro invocation.
address@hidden
+(define-syntax-case macro-name (literals)
+ (pat1 result1)
+ (pat2 result2))
address@hidden example
+is equivalent to:
address@hidden
+(define-syntax macro-name
+ (lambda (form)
+ (syntax-case form (literals)
+ (pat1 result1)
+ (pat2 result2))))
address@hidden example
address@hidden deffn
+
address@hidden Syntax define-macro @stxlit{(}name address@hidden)} form ...
address@hidden form is deprecated.}
+Functionally equivalent to @code{defmacro}.
address@hidden deffn
+
address@hidden Syntax defmacro name lambda-list form ...
address@hidden form is deprecated.}
+Instead of
address@hidden
+(defmacro (@var{name} ...)
+ (let ... `(... ,@var{exp} ...)))
address@hidden example
+you should probably do:
address@hidden
+(define-syntax-case @var{name} ()
+ ((_ ...) (let #`(... #,@var{exp} ...))))
address@hidden example
+and instead of
address@hidden
+(defmacro (@var{name} ... @var{var} ...) `(... @var{var} ...))
address@hidden example
+you should probably do:
address@hidden
+(define-syntax-case @var{name} ()
+ ((_ ... @var{var} ...) #`(... @var{var} ...))
address@hidden example
+
+Defines an old-style macro a la Common Lisp,
+and installs @code{(lambda @var{lambda-list} @var{form} ...)}
+as the expansion function for @var{name}.
+When the translator sees an application of @var{name},
+the expansion function is called with the rest of the application
+as the actual arguments. The resulting object must be a Scheme
+source form that is futher processed (it may be repeatedly macro-expanded).
address@hidden deffn
+
address@hidden Procedure gentemp
+Returns a new (interned) symbol each time it is called.
+The symbol names are implementation-dependent.
+(This is not directly macro-related, but is often used in conjunction
+with @code{defmacro} to get a fresh unique identifier.)
address@hidden deffn
+
address@hidden Procedure expand form
+The result of evaluating @var{form} is treated as a Scheme expression,
+syntax-expanded to internal form, and then converted back to (roughly)
+the equivalent expanded Scheme form.
+
+This can be useful for debugging macros.
+
+To access this function, you must first @code{(require 'syntax-utils)}.
address@hidden
+(require 'syntax-utils)
+(expand '(cond ((> x y) 0) (else 1))) @result{} (if (> x y) 0 1)
address@hidden example
address@hidden deffn
+
address@hidden Pattern language
+
+A @meta{transformer-spec} is an expression that evaluates to a
+transformer procedure, which takes an input form and returns a
+resulting form. You can do general macro-time compilation with such a
+procedure, commonly using @code{syntax-case} (which is documented
+in the R6RS library specification).
+However, when possible it is better to use the simpler
+pattern language of @code{syntax-rules}:
+
address@hidden
address@hidden
+ @stxlit{(syntax-rules (} @address@hidden @stxlit{)} @address@hidden@stxlit{)}
+ | @stxlit{(syntax-rules} @stxref{ellipsis} @stxlit{(} @address@hidden
@stxlit{)} @address@hidden@stxlit{)}
+ | @stxref{expression}
address@hidden @stxlit{(address@hidden @address@hidden)}
address@hidden @stxref{identifier}
address@hidden @stxref{identifier}
address@hidden display
+
+An instance of @code{syntax-rules} produces a new
+macro transformer by specifying a sequence of hygienic
+rewrite rules. A use of a macro whose keyword is associated
+with a transformer specified by @code{syntax-rules} is matched
+against the patterns contained in the @meta{syntax-rule}s
+beginning with the leftmost syntax rule . When a match is
+found, the macro use is transcribed hygienically according
+to the template.
+The optional @meta{ellipsis} species a symbol used to indicate
+repetition; it defaults to @code{...} (3 periods).
+
address@hidden
address@hidden
+ @stxref{identifier} | @stxref{constant} | @stxref{list-pattern} |
@stxref{vector-pattern}
address@hidden @stxlit{(} @address@hidden @stxlit{)}
+ | @stxlit{(} @stxref{syntax-pattern} @address@hidden @stxlit{.}
@stxref{syntax-pattern} @stxlit{)}
+ | @stxlit{(} @address@hidden @stxref{syntax-pattern} @stxref{ellipsis}
@address@hidden @stxlit{)}
+ | @stxlit{(} @address@hidden @stxref{syntax-pattern} @stxref{ellipsis}
@address@hidden @stxlit{.} @address@hidden)}
address@hidden @stxlit{#(} @address@hidden @stxlit{)}
+ | @stxlit{#(} @address@hidden @stxref{syntax-pattern} @stxref{ellipsis}
@address@hidden @stxlit{)}
address@hidden display
+
+An identifier appearing within a pattern can be an underscore
+(@code{_}), a literal identifier listed in the list of @meta{tr-literal}s,
+or the @meta{ellipsis}. All other identifiers appearing within a
+pattern are pattern variables.
+
+The outer @var{syntax-list} of the pattern in a @meta{syntax-rule}
+must start with an identifier. It is not involved in the matching and
+is considered neither a pattern variable nor a literal identifier.
+
+Pattern variables match arbitrary input elements and are
+used to refer to elements of the input in the template.
+It is an error for the same pattern variable to appear more
+than once in a @meta{syntax-pattern}.
+
+Underscores also match arbitrary input elements but are
+not pattern variables and so cannot be used to refer to
+those elements. If an underscore appears in the literals
+list, then that takes precedence and underscores in the
+pattern match as literals. Multiple underscores can
+appear in a @meta{syntax-pattern}.
+
+Identifiers that appear in @code{(@address@hidden)} are interpreted
+as literal identifiers to be matched against corresponding
+elements of the input. An element in the input matches a
+literal identifier if and only if it is an identifier and either
+both its occurrence in the macro expression and its occurrence
+in the macro definition have the same lexical binding,
+or the two identifiers are the same and both have no lexical
+binding.
+
+A subpattern followed by ellipsis can match zero or
+more elements of the input, unless ellipsis appears in the
+literals, in which case it is matched as a literal.
+
+More formally, an input expression @var{E} matches a pattern @var{P}
+if and only if:
address@hidden @bullet
address@hidden
address@hidden is an underscore (@stxlit{_}); or
address@hidden
address@hidden is a non-literal identifier; or
address@hidden
address@hidden is a literal identifier and @var{E} is an identifier with the
+same binding; or
address@hidden
address@hidden is a list @stxlit{(address@hidden@sub{1}} ...
@address@hidden@stxlit{)} and
address@hidden is a list of @var{n} elements
+that match @address@hidden through @address@hidden, respectively; or
address@hidden
address@hidden is an improper list
address@hidden(address@hidden@sub{1}} ... @address@hidden @stxlit{.}
@address@hidden@stxlit{)} and
address@hidden is a list or improper list of @var{n} or more elements that
+match @address@hidden through @address@hidden, respectively,
+and whose @var{n}th tail matches @address@hidden; or
address@hidden
address@hidden is of the form
address@hidden(address@hidden@sub{1}} ... @address@hidden @address@hidden
@var{ellipsis} @address@hidden ... @address@hidden@stxlit{)} where @var{E} is a
proper list of @var{n} elements,
+ the first @var{k} of which match @address@hidden through @address@hidden,
+respectively, whose
+next @var{n-k-l} elements each match @address@hidden, and whose remaining
address@hidden elements match @address@hidden through @address@hidden; or
address@hidden
address@hidden is of the form
address@hidden(address@hidden@sub{1}} ... @address@hidden @address@hidden
@var{ellipsis} @address@hidden ... @address@hidden @stxlit{.}
@address@hidden@stxlit{)}
+where @var{E} is a list or improper list of @var{n} elements,
+the first @var{k} of which match @address@hidden through @address@hidden,
+whose next @var{n-k-l} elements each match @address@hidden, and whose
+remaining @var{l} elements match @address@hidden through @address@hidden,
+and whose @var{n}th and final @code{cdr} matches @address@hidden; or
address@hidden
address@hidden is a vector of the form
address@hidden(address@hidden@sub{1}} ... @address@hidden@stxlit{)} and @var{E}
is a
+vector of @var{n} elements that match @address@hidden through @address@hidden;
or
address@hidden
address@hidden is of the form
address@hidden(address@hidden@sub{1}} ... @address@hidden @address@hidden
@var{ellipsis} @address@hidden ... @address@hidden@stxlit{)}
+where @var{E} is a vector of @var{n} elements the first
address@hidden of which match @address@hidden through @address@hidden,
+whose next @var{n-k-l} elements each match @address@hidden,
+and whose remaining @var{l} elements match @address@hidden
+through @address@hidden; or
address@hidden
address@hidden is a constant and E is equal to @var{P} in the sense of the
address@hidden procedure.
address@hidden itemize
+
+It is an error to use a macro keyword, within the scope of
+its binding, in an expression that does not match any of
+the patterns.
address@hidden
address@hidden @stxref{identifier} | @stxref{constant}
+ | @stxlit{(address@hidden@address@hidden)}
+ | @stxlit{(address@hidden @address@hidden @stxlit{.}
@stxref{syntax-template} @stxlit{)}
+ | @stxlit{(} @stxref{ellipsis} @address@hidden)}
address@hidden @stxref{syntax-template} address@hidden
address@hidden display
+
+When a macro use is transcribed according to the template
+of the matching @meta{syntax-rule}, pattern variables that occur
+in the template are replaced by the elements they match in
+the input. Pattern variables that occur in subpatterns followed
+by one or more instances of the identifier @meta{ellipsis} are
+allowed only in subtemplates that are followed by as many
+instances of @meta{ellipsis} . They are replaced in the output by
+all of the elements they match in the input, distributed as
+indicated. It is an error if the output cannot be built up
+as specified.
+
+Identifiers that appear in the template but are not pattern
+variables or the identifier @meta{ellipsis} are inserted into the output
+as literal identifiers. If a literal identifier is inserted as a
+free identifier then it refers to the binding of that identifier
+within whose scope the instance of @code{syntax-rules} appears.
+If a literal identifier is inserted as a bound identifier then
+it is in effect renamed to prevent inadvertent captures of
+free identifiers.
+
+A template of the
+form @stxlit{(address@hidden @address@hidden)} is
+identical to @meta{template}, except that @meta{ellipses}
+within the template have no special meaning.
+That is, any @meta{ellipses} contained within
address@hidden are treated as ordinary identifiers. In particular,
+the template @stxlit{(address@hidden @address@hidden)}
+produces a single @meta{ellipsis}. This allows syntactic
+abstractions to expand into code containing ellipses.
+
address@hidden
+(define-syntax be-like-begin
+ (syntax-rules ()
+ ((be-like-begin name)
+ (define-syntax name
+ (syntax-rules ()
+ ((name expr (... ...))
+ (begin expr (... ...))))))))
+
+(be-like-begin sequence)
+(sequence 1 2 3 4) @result{} 4
address@hidden example
+
address@hidden Identifier predicates
+
address@hidden Procedure {identifier?} @var{obj}
+Return @true{} if @var{obj} is an identifier, i.e., a syntax object
+representing an identifier, and @false{} otherwise.
+
+The @func{identifier?} procedure is often used within a fender to verify
+that certain subforms of an input form are identifiers, as in the
+definition of @code{rec}, which creates self--contained recursive
+objects, below.
+
address@hidden
+(define-syntax rec
+ (lambda (x)
+ (syntax-case x ()
+ ((_ x e)
+ (identifier? #'x)
+ #'(letrec ((x e)) x)))))
+
+(map (rec fact
+ (lambda (n)
+ (if (= n 0)
+ 1
+ (* n (fact (- n 1))))))
+ '(1 2 3 4 5)) @result{} (1 2 6 24 120)
+
+(rec 5 (lambda (x) x)) @result{} exception
address@hidden example
address@hidden deffn
+
+
+The procedures @func{bound-identifier=?} and @func{free-identifier=?}
+each take two identifier arguments and return @true{} if their arguments
+are equivalent and @false{} otherwise. These predicates are used to
+compare identifiers according to their @emph{intended use} as free
+references or bound identifiers in a given context.
+
address@hidden Procedure {bound-identifier=?} @vari{id} @varii{id}
address@hidden and @varii{id} must be identifiers.
+
+The procedure @func{bound-identifier=?} returns @true{} if a binding for
+one would capture a reference to the other in the output of the
+transformer, assuming that the reference appears within the scope of the
+binding, and @false{} otherwise.
+
+In general, two identifiers are @func{bound-identifier=?} only if both
+are present in the original program or both are introduced by the same
+transformer application (perhaps implicitly, see @func{datum->syntax}).
+
+The @func{bound-identifier=?} procedure can be used for detecting
+duplicate identifiers in a binding construct or for other preprocessing
+of a binding construct that requires detecting instances of the bound
+identifiers.
address@hidden deffn
+
address@hidden Procedure {free-identifier=?} @vari{id} @varii{id}
address@hidden and @varii{id} must be identifiers.
+
+The @func{free-identifier=?} procedure returns @true{} if and only if
+the two identifiers would resolve to the same binding if both were to
+appear in the output of a transformer outside of any bindings inserted
+by the transformer. (If neither of two like--named identifiers resolves
+to a binding, i.e., both are unbound, they are considered to resolve to
+the same binding.)
+
+Operationally, two identifiers are considered equivalent by
address@hidden if and only the topmost matching substitution
+for each maps to the same binding or the identifiers have the same name
+and no matching substitution.
+
+The @func{syntax-case} and @func{syntax-rules} forms internally use
address@hidden to compare identifiers listed in the literals
+list against input identifiers.
+
address@hidden
+(let ((fred 17))
+ (define-syntax a
+ (lambda (x)
+ (syntax-case x ()
+ ((_ id) #'(b id fred)))))
+ (define-syntax b
+ (lambda (x)
+ (syntax-case x ()
+ ((_ id1 id2)
+ #`(list
+ #,(free-identifier=? #'id1 #'id2)
+ #,(bound-identifier=? #'id1 #'id2))))))
+ (a fred))
+ @result{} (#t #f)
address@hidden example
+
+The following definition of unnamed @func{let} uses
address@hidden to detect duplicate identifiers.
+
address@hidden
+(define-syntax let
+ (lambda (x)
+ (define unique-ids?
+ (lambda (ls)
+ (or (null? ls)
+ (and (let notmem? ((x (car ls)) (ls (cdr ls)))
+ (or (null? ls)
+ (and (not (bound-identifier=? x (car ls)))
+ (notmem? x (cdr ls)))))
+ (unique-ids? (cdr ls))))))
+ (syntax-case x ()
+ ((_ ((i v) ...) e1 e2 ...)
+ (unique-ids? #'(i ...))
+ #'((lambda (i ...) e1 e2 ...) v ...)))))
address@hidden example
+
+The argument @code{#'(i ...)} to @func{unique-ids?} is guaranteed to be
+a list by the rules given in the description of @func{syntax} above.
+
+With this definition of @func{let}:
+
address@hidden
+(let ((a 3) (a 4)) (+ a a)) @result{} @i{syntax error}
address@hidden example
+
+However,
address@hidden
+(let-syntax
+ ((dolet (lambda (x)
+ (syntax-case x ()
+ ((_ b)
+ #'(let ((a 3) (b 4)) (+ a b)))))))
+ (dolet a))
address@hidden 7
address@hidden example
+
address@hidden
+since the identifier @code{a} introduced by @func{dolet} and the
+identifier @code{a} extracted from the input form are not
address@hidden
+
+Rather than including @code{else} in the literals list as before, this
+version of @func{case} explicitly tests for @code{else} using
address@hidden
+
address@hidden
+(define-syntax case
+ (lambda (x)
+ (syntax-case x ()
+ ((_ e0 ((k ...) e1 e2 ...) ...
+ (else-key else-e1 else-e2 ...))
+ (and (identifier? #'else-key)
+ (free-identifier=? #'else-key #'else))
+ #'(let ((t e0))
+ (cond
+ ((memv t '(k ...)) e1 e2 ...)
+ ...
+ (else else-e1 else-e2 ...))))
+ ((_ e0 ((ka ...) e1a e2a ...)
+ ((kb ...) e1b e2b ...) ...)
+ #'(let ((t e0))
+ (cond
+ ((memv t '(ka ...)) e1a e2a ...)
+ ((memv t '(kb ...)) e1b e2b ...)
+ ...))))))
address@hidden example
+
+With either definition of @func{case}, @code{else} is not recognized as
+an auxiliary keyword if an enclosing lexical binding for @code{else}
+exists. For example,
+
address@hidden
+(let ((else @false{}))
+ (case 0 (else (write "oops")))) @result{} @i{syntax error}
address@hidden example
+
address@hidden
+since @code{else} is bound lexically and is therefore not the same
address@hidden that appears in the definition of @func{case}.
address@hidden deffn
+
address@hidden Syntax-object and datum conversions
+
address@hidden Procedure {syntax->datum} @var{syntax-object}
address@hidden {Deprecated procedure} {syntax-object->datum} @var{syntax-object}
+Strip all syntactic information from a syntax object and returns the
+corresponding Scheme datum.
+
+Identifiers stripped in this manner are converted to their symbolic
+names, which can then be compared with @func{eq?}. Thus, a predicate
address@hidden might be defined as follows.
+
address@hidden
+(define symbolic-identifier=?
+ (lambda (x y)
+ (eq? (syntax->datum x)
+ (syntax->datum y))))
address@hidden example
address@hidden deffn
+
address@hidden Procedure {datum->syntax} @var{template-id} @var{datum}
address@hidden
address@hidden {Deprecated procedure} {datum->syntax-object} @var{template-id}
@var{datum}
address@hidden must be a template identifier and @var{datum} should
+be a datum value.
+
+The @func{datum->syntax} procedure returns a syntax-object
+representation of @var{datum} that contains the same contextual
+information as @var{template-id}, with the effect that the syntax object
+behaves as if it were introduced into the code when @var{template-id}
+was introduced.
+
+If @var{srcloc} is specified (and neither @code{#f} or @code{#!null}),
+it specifies the file position (including line number) for the result.
+In that case it should be a syntax object representing
+a list; otherwise it is currently ignored, though future extensions
+may support other ways of specifying the position.
+
+The @func{datum->syntax} procedure allows a transformer to ``bend''
+lexical scoping rules by creating @emph{implicit identifiers} that
+behave as if they were present in the input form, thus permitting the
+definition of macros that introduce visible bindings for or references
+to identifiers that do not appear explicitly in the input form. For
+example, the following defines a @func{loop} expression that uses this
+controlled form of identifier capture to bind the variable @code{break}
+to an escape procedure within the loop body. (The derived
address@hidden form is like @func{let} but binds pattern variables.)
+
address@hidden
+(define-syntax loop
+ (lambda (x)
+ (syntax-case x ()
+ ((k e ...)
+ (with-syntax
+ ((break (datum->syntax #'k 'break)))
+ #'(call-with-current-continuation
+ (lambda (break)
+ (let f () e ... (f)))))))))
+
+(let ((n 3) (ls '()))
+ (loop
+ (if (= n 0) (break ls))
+ (set! ls (cons 'a ls))
+ (set! n (- n 1))))
address@hidden (a a a)
address@hidden example
+
+Were @code{loop} to be defined as:
+
address@hidden
+(define-syntax loop
+ (lambda (x)
+ (syntax-case x ()
+ ((_ e ...)
+ #'(call-with-current-continuation
+ (lambda (break)
+ (let f () e ... (f))))))))
address@hidden example
+
address@hidden
+the variable @code{break} would not be visible in @code{e ...}.
+
+The datum argument @var{datum} may also represent an arbitrary Scheme
+form, as demonstrated by the following definition of @func{include}.
+
address@hidden
+(define-syntax include
+ (lambda (x)
+ (define read-file
+ (lambda (fn k)
+ (let ((p (open-file-input-port fn)))
+ (let f ((x (get-datum p)))
+ (if (eof-object? x)
+ (begin (close-port p) '())
+ (cons (datum->syntax k x)
+ (f (get-datum p))))))))
+ (syntax-case x ()
+ ((k filename)
+ (let ((fn (syntax->datum #'filename)))
+ (with-syntax (((exp ...)
+ (read-file fn #'k)))
+ #'(begin exp ...)))))))
address@hidden example
+
address@hidden(include "filename")} expands into a @func{begin} expression
+containing the forms found in the file named by @code{"filename"}. For
+example, if the file @file{flib.ss} contains:
+
address@hidden
+(define f (lambda (x) (g (* x x))))
address@hidden example
+
address@hidden
+and the file @file{glib.ss} contains:
+
address@hidden
+(define g (lambda (x) (+ x x)))
address@hidden example
+
address@hidden
+the expression:
+
address@hidden
+(let ()
+ (include "flib.ss")
+ (include "glib.ss")
+ (f 5))
address@hidden example
+
address@hidden
+evaluates to @code{50}.
+
+The definition of @func{include} uses @func{datum->syntax} to convert
+the objects read from the file into syntax objects in the proper lexical
+context, so that identifier references and definitions within those
+expressions are scoped where the @func{include} form appears.
+
+Using @func{datum->syntax}, it is even possible to break hygiene
+entirely and write macros in the style of old Lisp macros. The
address@hidden procedure defined below creates a transformer
+that converts its input into a datum, calls the programmer's procedure
+on this datum, and converts the result back into a syntax object scoped
+where the original macro use appeared.
+
address@hidden
+(define lisp-transformer
+ (lambda (p)
+ (lambda (x)
+ (syntax-case x ()
+ ((kwd . rest)
+ (datum->syntax #'kwd
+ (p (syntax->datum x))))))))
address@hidden example
address@hidden deffn
+
address@hidden Signaling errors in macro transformers
+
address@hidden Syntax syntax-error message @arbno{args}
+The @meta{message} and @meta{args} are treated similary as for
+the @code{error} procedure. However, the error is reported
+when the @code{syntax-error} is expanded.
+This can be used as a @code{syntax-rules}
+template for a pattern that is an invalid use of the
+macro, which can provide more descriptive error messages.
+The @meta{message} should be a string literal, and the @var{args}
+arbitrary (non-evalualted) expressions providing additional information.
+
address@hidden
+(define-syntax simple-let
+ (syntax-rules ()
+ ((_ (head ... ((x . y) val) . tail)
+ body1 body2 ...)
+ (syntax-error "expected an identifier but got" (x . y)))
+ ((_ ((name val) ...) body1 body2 ...)
+ ((lambda (name ...) body1 body2 ...)
+ val ...))))
address@hidden example
address@hidden deffn
+
address@hidden Procedure report-syntax-error location message
+This is a procedure that can be called at macro-expansion time
+by a syntax transformer function.
+(In contrast @code{syntax-error} is a syntax form used in the
+expansion result.)
+The @var{message} is reported as a compile-time error message.
+The @var{location} is used for the source location (file name and
+line/column numbers): In general it can be a @code{SourceLocator} value;
+most commonly it is a syntax object for a sub-list of the input form
+that is erroneous.
+The value returned by @code{report-syntax-error} is an
+instance of @code{ErrorExp}, which supresses further compilation.
+
address@hidden
+(define-syntax if
+ (lambda (x)
+ (syntax-case x ()
+ ((_ test then)
+ (make-if-exp #'test #'then #!null))
+ ((_ test then else)
+ (make-if-exp #'test #'then #'else))
+ ((_ e1 e2 e3 . rest)
+ (report-syntax-error #'rest
+ "too many expressions for 'if'"))
+ ((_ . rest)
+ (report-syntax-error #'rest
+ "too few expressions for 'if'")))))
address@hidden example
+In the above example, one could use the source form @code{x} for the
+location, but using @code{#'rest} is more accurate. Note that the following
+is incorrect, because @code{e1} might not be a pair, in which case
+we don't have location information for it (due to a Kawa limitation):
address@hidden
+ (syntax-case x ()
+ ...
+ ((_ e1)
+ (report-syntax-error
+ #'e1 ;; @i{poor location specifier}
+ "too few expressions for 'if'")))))
address@hidden example
address@hidden deffn
+
address@hidden Convenience forms
+
address@hidden Syntax with-syntax ((@var{pattern} @stxref{expression}) @dots{})
@stxref{body}
+The @func{with-syntax} form is used to bind pattern variables, just as
address@hidden is used to bind variables. This allows a transformer to
+construct its output in separate pieces, then put the pieces together.
+
+Each @var{pattern} is identical in form to a @func{syntax-case}
+pattern. The value of each @var{expression} is computed and
+destructured according to the corresponding @var{pattern}, and pattern
+variables within the @var{pattern} are bound as with
address@hidden to the corresponding portions of the value within
address@hidden
+
+The @func{with-syntax} form may be defined in terms of
address@hidden as follows.
+
address@hidden
+(define-syntax with-syntax
+ (lambda (x)
+ (syntax-case x ()
+ ((_ ((p e0) ...) e1 e2 ...)
+ (syntax (syntax-case (list e0 ...) ()
+ ((p ...) (let () e1 e2 ...))))))))
address@hidden example
+
+The following definition of @func{cond} demonstrates the use of
address@hidden to support transformers that employ recursion
+internally to construct their output. It handles all @func{cond} clause
+variations and takes care to produce one-armed @func{if} expressions
+where appropriate.
+
address@hidden
+(define-syntax cond
+ (lambda (x)
+ (syntax-case x ()
+ ((_ c1 c2 ...)
+ (let f ((c1 #'c1) (c2* #'(c2 ...)))
+ (syntax-case c2* ()
+ (()
+ (syntax-case c1 (else =>)
+ (((else e1 e2 ...) #'(begin e1 e2 ...))
+ ((e0) #'e0)
+ ((e0 => e1)
+ #'(let ((t e0)) (if t (e1 t))))
+ ((e0 e1 e2 ...)
+ #'(if e0 (begin e1 e2 ...)))))
+ ((c2 c3 ...)
+ (with-syntax ((rest (f #'c2 #'(c3 ...))))
+ (syntax-case c1 (=>)
+ ((e0) #'(let ((t e0)) (if t t rest)))
+ ((e0 => e1)
+ #'(let ((t e0)) (if t (e1 t) rest)))
+ ((e0 e1 e2 ...)
+ #'(if e0
+ (begin e1 e2 ...)
+ rest)))))))))))
address@hidden example
address@hidden deffn
+
address@hidden Syntax quasisyntax @var{template}
address@hidden {Auxiliary Syntax} unsyntax
address@hidden {Auxiliary Syntax} unsyntax-splicing
+The @func{quasisyntax} form is similar to @func{syntax}, but it allows
+parts of the quoted text to be evaluated, in a manner similar to the
+operation of @func{quasiquote}.
+
+Within a @func{quasisyntax} @var{template}, subforms of @func{unsyntax}
+and @func{unsyntax-splicing} forms are evaluated, and everything else is
+treated as ordinary template material, as with @func{syntax}.
+
+The value of each @func{unsyntax} subform is inserted into the output in
+place of the @func{unsyntax} form, while the value of each
address@hidden subform is spliced into the surrounding list or
+vector structure. Uses of @func{unsyntax} and @func{unsyntax-splicing}
+are valid only within @func{quasisyntax} expressions.
+
+A @func{quasisyntax} expression may be nested, with each
address@hidden introducing a new level of syntax quotation and each
address@hidden or @func{unsyntax-splicing} taking away a level of
+quotation. An expression nested within @emph{n} @func{quasisyntax}
+expressions must be within @emph{n} @emph{unsyntax} or
address@hidden expressions to be evaluated.
+
+As noted in @stxref{abbreviation}, @address@hidden is equivalent to
address@hidden(quasisyntax @var{template})}, @code{#,@var{template}} is
+equivalent to @code{(unsyntax @var{template})}, and
address@hidden,@@@var{template}} is equivalent to @code{(unsyntax-splicing
address@hidden)}. @emph{Note} that for backwards compatibility,
+you should only use @code{#,@var{template}} inside a literal @address@hidden
form.
+
+The @func{quasisyntax} keyword can be used in place of
address@hidden in many cases. For example, the definition of
address@hidden shown under the description of @func{with-syntax} above can
+be rewritten using @func{quasisyntax} as follows.
+
address@hidden
+(define-syntax case
+ (lambda (x)
+ (syntax-case x ()
+ ((_ e c1 c2 ...)
+ #`(let ((t e))
+ #,(let f ((c1 #'c1) (cmore #'(c2 ...)))
+ (if (null? cmore)
+ (syntax-case c1 (else)
+ ((else e1 e2 ...)
+ #'(begin e1 e2 ...))
+ (((k ...) e1 e2 ...)
+ #'(if (memv t '(k ...))
+ (begin e1 e2 ...))])
+ (syntax-case c1 ()
+ (((k ...) e1 e2 ...)
+ #`(if (memv t '(k ...))
+ (begin e1 e2 ...)
+ #,(f (car cmore)
+ (cdr cmore))))))))))))
address@hidden example
+
address@hidden ((Unknown if this works))
address@hidden Uses of @func{unsyntax} and @func{unsyntax-splicing} with zero
or more
address@hidden than one subform are valid only in splicing (list or vector)
contexts.
address@hidden @code{(unsyntax @var{template} @dots{})} is equivalent to
address@hidden @code{(unsyntax @var{template}) ...}, and
@code{(unsyntax-splicing
address@hidden @var{template} ...)} is equivalent to @code{(unsyntax-splicing
address@hidden @var{template}) ...}. These forms are primarily useful as
intermediate
address@hidden forms in the output of the @func{quasisyntax} expander.
address@hidden
address@hidden @quotation
address@hidden @emph{Note:} Uses of @func{unsyntax} and
@func{unsyntax-splicing} with
address@hidden zero or more than one subform enable certain idioms, such as
address@hidden @code{#,@@#,@@}, which has the effect of a doubly indirect
splicing when
address@hidden used within a doubly nested and doubly evaluated
@func{quasisyntax}
address@hidden expression.
address@hidden @end quotation
address@hidden deffn
+
address@hidden
address@hidden:} Any @func{syntax-rules} form can be expressed with
address@hidden by making the @func{lambda} expression and
address@hidden expressions explicit, and @func{syntax-rules} may be
+defined in terms of @func{syntax-case} as follows.
+
address@hidden
+(define-syntax syntax-rules
+ (lambda (x)
+ (syntax-case x ()
+ ((_ (lit ...) ((k . p) t) ...)
+ (for-all identifier? #'(lit ... k ...))
+ #'(lambda (x)
+ (syntax-case x (lit ...)
+ ((_ . p) #'t) ...))))))
address@hidden example
address@hidden quotation
+
address@hidden Named quasi-literals
address@hidden Named quasi-literals
+
+Traditional Scheme has only a few kinds of values,
+and thus only a few builtin kinds of literals.
+Modern Scheme allows defining new types,
+so it is desirable to have a mechanism for defining literal values
+for the new types.
+
+Consider the @address@hidden,,URI}} type.
+You can create a new instance of a @code{URI} using a
+constructor function:
address@hidden
+(URI "http://example.com/";)
address@hidden example
+This isn't too bad, though the double-quote characters are an ugly distraction.
+However, if you need to construct the string it gets messy:
address@hidden
+(URI (string-append base-uri "icon.png"))
address@hidden example
+
+Instead use can write:
address@hidden
+&address@hidden://example.com/@}
address@hidden example
+or:
address@hidden
+&address@hidden&address@hidden
address@hidden example
+
+This syntax is translated by the Scheme reader
+to the more familiar but more verbose equivalent forms:
address@hidden
+($construct$:URI "http://example.com/";)
+($construct$:URI $<<$ base-uri $>>$ "icon.png")
address@hidden example
+So for this to work there just needs to be a definition
+of @code{$construct$:URI}, usually a macro.
+Normal scope rules apply; typically you'd define @code{$construct$:URI} in
+a module.
+
+The names @code{$<<$} and @code{$>>$} are bound to unique zero-length strings.
+They are used to allow the implementation of @code{$construct$:URI}
+to determine which arguments are literal and which come from
+escaped expressions.
+
+If you want to define your own @code{$construct$:@var{tag}},
+or to read motivation and details, see the
address@hidden://srfi.schemers.org/srfi-108/srfi-108.html, SRFI 108}
specification.
+
address@hidden
address@hidden
+ @stxlit{&} @stxref{cname} @address@hidden address@hidden @address@hidden
@address@hidden
+ | @stxlit{&} @stxref{cname} @stxlit{[} @address@hidden @address@hidden
address@hidden @address@hidden @address@hidden
address@hidden @stxref{identifier}
address@hidden
+ @i{any character except} @stxlit{&address@hidden,} @address@hidden @i{or}
@address@hidden
+ | @address@hidden @address@hidden @address@hidden
+ | @stxref{char-ref}
+ | @stxref{entity-ref}
+ | @stxref{special-escape}
+ | @stxref{enclosed-part}
+ | @stxref{extended-datum-literal}
address@hidden display
+
address@hidden FIXME May rename: Control structure
address@hidden Program structure
address@hidden Program structure
+
+See @ref{program units} for some notes on
+structure of an entire source file.
+
address@hidden
+* Boolean values::
+* Conditionals::
+* Variables and Patterns::
+* Definitions::
+* Local binding constructs::
+* Lazy evaluation::
+* Threads::
+* Exceptions:: Exception handling
address@hidden menu
+
address@hidden Boolean values
address@hidden Boolean values
+
+The standard boolean objects for true and false are written as @code{#t} and
@code{#f}.
+Alternatively, they may be written @code{#true} and @code{#false},
+respectively.
+
address@hidden
address@hidden @stxlit{#t} | @stxlit{#f} | @stxlit{#true} | @stxlit{#false}
address@hidden display
+
+What really matters,
+though, are the objects that the Scheme conditional expressions (@code{if},
address@hidden, @code{and}, @code{or}, @code{when}, @code{unless}, @code{do})
+treat as true or
+false. The phrase ``a true value'' (or sometimes just ``true'')
+means any object treated as true by the conditional expressions, and the
phrase ``a false value'' (or ``false'') means any
+object treated as false by the conditional expressions.
+
+Of all the ``proper Scheme'' values, only @code{#f} counts as false in
+conditional expressions. All other Scheme values, including @code{#t},
+count as true. A @var{test-expression} is an expression evaluated
+in this manner for whether it is true or false.
+
+In addition the null value @code{#!null} (in Java written as @code{null})
+is also considered false. Also, if you for some strange reason create a
+fresh @code{java.lang.Boolean} object whose @code{booleanValue()}
+returns @code{false}, that is also considered false.
+
address@hidden:} Unlike some other dialects of Lisp, Scheme distinguishes
address@hidden and the empty list from each other and from the symbol
address@hidden
+
+Boolean constants evaluate to themselves, so they do not
+need to be quoted in programs.
+
address@hidden
+#t @result{} #t
+#true @result{} #t
+#f @result{} #f
+#false @result{} #f
+'#f @result{} #f
address@hidden example
+
address@hidden Type boolean
+The type of boolean values.
+As a type conversion, a true value is converted to @code{#t},
+while a false value is converted to @code{#f}.
+Represented as a primitive Java @code{boolean}
+or @code{kawa.lang.Boolean} when converted to an object.
address@hidden deffn
+
address@hidden Procedure boolean? obj
+The @code{boolean?} predicate returns @code{#t} if @var{obj}
+is either @code{#t} or @code{#f}, and returns @code{#f} otherwise.
address@hidden
+(boolean? #f) @result{} #t
+(boolean? 0) @result{} #f
+(boolean? '()) @result{} #f
address@hidden example
address@hidden deffn
+
address@hidden Procedure not obj
+The @code{not} procedure returns @code{#t} if @var{obj} is false,
+and returns @code{#f} otherwise.
+
address@hidden
+(not #t) @result{} #f
+(not 3) @result{} #f
+(not (list 3)) @result{} #f
+(not #f) @result{} #t
+(not ’()) @result{} #f
+(not (list)) @result{} #f
+(not ’nil) @result{} #f
address@hidden example
address@hidden deffn
+
address@hidden Procedure boolean=? boolean1 boolean2 boolean3 ...
+Returns @code{#t} if all the arguments are booleans and all are @code{#t}
+or all are @code{#f}.
address@hidden deffn
+
address@hidden Conditionals
address@hidden Conditionals
+
address@hidden
address@hidden @stxref{expression}
address@hidden @stxref{expression}
address@hidden @stxref{expression}
address@hidden display
+
address@hidden Syntax if @stxref{test-expression} @stxref{consequent}
@stxref{alternate}
address@hidden Syntax if @stxref{test-expression} @stxref{consequent}
+
+An @func{if} expression is evaluated as follows:
+first, @meta{test-expression} is
+evaluated. If it yields a true value, then @meta{consequent} is
+evaluated and its values are returned. Otherwise @meta{alternate} is
+evaluated and its values are returned. If @meta{test} yields @false{}
+and no @meta{alternate} is specified, then the result of the expression
+is unspecified.
+
address@hidden
+(if (> 3 2) 'yes 'no) @result{} yes
+(if (> 2 3) 'yes 'no) @result{} no
+(if (> 3 2)
+ (- 3 2)
+ (+ 3 2)) @result{} 1
+(if #f #f) @result{} unspecified
address@hidden example
+
+The @meta{consequent} and @meta{alternate} expressions are in tail
+context if the @func{if} expression itself is.
address@hidden deffn
+
address@hidden Syntax cond @address@hidden
address@hidden Syntax cond @address@hidden @stxlit{(else}
@address@hidden@stxlit{)}
+
address@hidden
address@hidden @stxlit{(address@hidden @address@hidden)}
+ | @stxlit{(address@hidden @stxlit{=>} @address@hidden)}
address@hidden display
+
+A @func{cond} expression is evaluated by evaluating the @meta{test-expression}s
+of successive @meta{cond-clause}s in order until one of them
+evaluates to a true value. When a @meta{test-expression} evaluates to a true
+value, then the remaining @meta{expression}s in its @meta{cond-clause}
+are evaluated in order, and the results of the last @meta{expression} in
+the @meta{cond-clause} are returned as the results of the entire
address@hidden expression.
+If the selected @meta{cond-clause} contains only the @meta{test-expression}
and no
address@hidden, then the value of the @meta{test-expression} is returned as the
+result. If the selected @meta{cond-clause} uses the @code{=>} alternate
+form, then the @meta{expression} is evaluated. Its value must be a
+procedure. This procedure should accept one argument; it is called on
+the value of the @meta{test-expression} and the values returned by this
procedure
+are returned by the @func{cond} expression.
+
+If all @meta{test-expression}s evaluate to @false{}, and there is no
@code{else}
+clause, then the conditional expression returns unspecified values; if
+there is an @code{else} clause, then its @meta{expression}s are
+evaluated, and the values of the last one are returned.
+
address@hidden
+(cond ((> 3 2) 'greater)
+ ((< 3 2) 'less)) @result{} greater
+
+(cond ((> 3 3) 'greater)
+ ((< 3 3) 'less)
+ (else 'equal)) @result{} equal
+
+(cond ('(1 2 3) => cadr)
+ (else #f)) @result{} 2
address@hidden example
+
+For a @meta{cond-clause} of one of the following forms:
address@hidden
+(@meta{test} @address@hidden)
+(else @stxref{expression} @address@hidden)
address@hidden example
+
address@hidden
+the last @meta{expression} is in tail context if the @func{cond} form
+itself is. For a @meta{cond clause} of the form:
+
address@hidden
+(@meta{test} => @meta{expression})
address@hidden example
+
address@hidden
+the (implied) call to the procedure that results from the evaluation of
address@hidden is in tail context if the @func{cond} form itself
+is.
address@hidden deffn
+
address@hidden Syntax case @stxref{case-key} @address@hidden
address@hidden Syntax case @stxref{case-key} @address@hidden
@stxref{case-else-clause}
+
address@hidden
address@hidden @stxref{expression}
address@hidden @stxlit{((address@hidden@address@hidden)}
@address@hidden@stxlit{)}
+ | @stxlit{((address@hidden@address@hidden)} @stxlit{=>} @address@hidden)}
address@hidden @stxlit{(else} @address@hidden@stxlit{)}
+ | @stxlit{(else =>} @address@hidden)}
address@hidden display
+
+Each @meta{datum} is an external representation of some object.
+Each @meta{datum} in the entire @code{case} expression should be distinct.
+
+A @func{case} expression is evaluated as follows.
+
address@hidden
address@hidden
+The @meta{case-key} is evaluated and its result is compared using
address@hidden against the data represented by the @meta{datum}s of
+each @meta{case-clause} in turn, proceeding in order from left to
+right through the set of clauses.
+
address@hidden
+If the result of evaluating @meta{case-key} is equivalent to a datum of a
address@hidden, the corresponding @meta{expression}s are evaluated
+from left to right and the results of the last expression in the
address@hidden are returned as the results of the @func{case}
+expression. Otherwise, the comparison process continues.
address@hidden
+If the result of evaluating @meta{key} is different from every datum in
+each set, then if there is an @meta{case-else-clause} its expressions are
+evaluated and the results of the last are the results of the @func{case}
+expression; otherwise the result of @func{case} expression is unspecified.
address@hidden enumerate
+
+If the selected @meta{case-clause} or @meta{case-else-clause}
+uses the @code{=>} alternate
+form, then the @meta{expression} is evaluated. It is an error if
+its value is not a procedure accepting one argument. This
+procedure is then called on the value of the @meta{key} and the
+values returned by this procedure are returned by the @code{case}
+expression.
+
address@hidden
+(case (* 2 3)
+ ((2 3 5 7) 'prime)
+ ((1 4 6 8 9) 'composite)) @result{} composite
+(case (car '(c d))
+ ((a) 'a)
+ ((b) 'b)) @result{} unspecified
+(case (car '(c d))
+ ((a e i o u) 'vowel)
+ ((w y) 'semivowel)
+ (else => (lambda (x) x))) @result{} c
address@hidden example
+
+The last @meta{expression} of a @meta{case clause} is in tail context if
+the @func{case} expression itself is.
address@hidden deffn
+
address@hidden
address@hidden Syntax match @stxref{match-key} @stxref{expression}
@address@hidden
+The @code{match} form is a generalization of @code{case} using
@stxref{pattern}s,
address@hidden
address@hidden @stxref{expression}
address@hidden
+ @stxlit{(} @stxref{pattern} address@hidden @stxref{body} @stxlit{)}
address@hidden display
+The @var{match-key} is evaluated,
+Then the @var{match-clause}s are tried in order.
+The first @var{match-clause} whose @var{pattern} matches (and
+the @var{guard}, if any, is true), is selected,
+and the corresponding @var{body} evaluated.
+It is an error if no @var{match-clause} matches.
address@hidden
+(match value
+ (0 (found-zero))
+ (x #!if (> x 0) (found-positive x))
+ (x #!if (< x 0) (found-negative x))
+ (x::symbol (found-symbol x))
+ (_ (found-other)))
address@hidden example
+
+One @code{case} feature is not (yet) directly supported by @code{match}:
+Matching against a list of values.
+However, this is easy to simulate using a guard using @code{memq},
address@hidden, or @code{member}:
address@hidden
+;; compare similar example under case
+(match (car '(c d))
+ (x #!if (memv x '(a e i o u)) ’vowel)
+ (x #!if (memv x '(w y)) ’semivowel)
+ (x x))
address@hidden example
address@hidden deffn
+
address@hidden Syntax and @stxref{test-expression} @dots{}
+
+If there are no @meta{test-expression}s, @true{} is returned. Otherwise, the
address@hidden are evaluated from left to right until a
address@hidden returns @false{} or the last @meta{test-expression} is reached.
In the
+former case, the @func{and} expression returns @false{} without
+evaluating the remaining expressions. In the latter case, the last
+expression is evaluated and its values are returned.
+
address@hidden
+(and (= 2 2) (> 2 1)) @result{} #t
+(and (= 2 2) (< 2 1)) @result{} #f
+(and 1 2 'c '(f g)) @result{} (f g)
+(and) @result{} #t
address@hidden example
+
+The @func{and} keyword could be defined in terms of @func{if} using
address@hidden as follows:
+
address@hidden
+(define-syntax and
+ (syntax-rules ()
+ ((and) #t)
+ ((and test) test)
+ ((and test1 test2 ...)
+ (if test1 (and test2 ...) #t))))
address@hidden example
+
+The last @meta{test-expression} is in tail context if the @func{and}
+expression itself is.
address@hidden deffn
+
address@hidden Syntax or @stxref{test-expression} @dots{}
+If there are no @meta{test-expression}s, @false{} is returned. Otherwise, the
address@hidden are evaluated from left to right until a
address@hidden returns a true value @var{val} or the last
address@hidden is
+reached. In the former case, the @func{or} expression returns @var{val}
+without evaluating the remaining expressions. In the latter case, the
+last expression is evaluated and its values are returned.
+
address@hidden
+(or (= 2 2) (> 2 1)) @result{} #t
+(or (= 2 2) (< 2 1)) @result{} #t
+(or #f #f #f) @result{} #f
+(or '(b c) (/ 3 0)) @result{} (b c)
address@hidden example
+
+The @func{or} keyword could be defined in terms of @func{if} using
address@hidden as follows:
+
address@hidden
+(define-syntax or
+ (syntax-rules ()
+ ((or) #f)
+ ((or test) test)
+ ((or test1 test2 ...)
+ (let ((x test1))
+ (if x x (or test2 ...))))))
address@hidden example
+
+The last @meta{test-expression} is in tail context if the @func{or}
+expression itself is.
address@hidden deffn
+
+
address@hidden Syntax when @stxref{test-expression} form...
+If @var{test-expression} is true, evaluate each @var{form} in order,
+returning the value of the last one.
address@hidden deffn
+
address@hidden Syntax unless @stxref{test-expression} form...
+If @var{test-expression} is false, evaluate each @var{form} in order,
+returning the value of the last one.
address@hidden deffn
+
address@hidden Variables and Patterns
address@hidden Variables and Patterns
+
+An identifier can name either a type of syntax or a location
+where a value can be stored. An identifier that names a
+type of syntax is called a @dfn{syntactic keyword}
+(informally called a @dfn{macro}), and is said to be
address@hidden to a transformer for that syntax. An identifier that
+names a location is called a @dfn{variable} and is said to be @dfn{bound}
+to that location. The set of all visible bindings in effect at
+some point in a program is known as the @dfn{environment} in
+effect at that point. The value stored in the location to
+which a variable is bound is called the variable’s value.
+By abuse of terminology, the variable is sometimes said
+to name the value or to be bound to the value. This is
+not quite accurate, but confusion rarely results from this
+practice.
+
+Certain expression types are used to create new kinds of
+syntax and to bind syntactic keywords to those new syntaxes,
+while other expression types create new locations
+and bind variables to those locations. These expression
+types are called @dfn{binding constructs}.
+Those that bind syntactic keywords are discussed in @ref{Macros}.
+The most fundamental of the variable binding constructs is the
address@hidden,@code{lambda} expression},
+because all other variable binding constructs
+can be explained in terms of @code{lambda} expressions.
+Other binding constructs include the @ref{Definitions,@code{define} family},
+and the @ref{Local binding constructs,@code{let} family}.
+
+Scheme is a language with block structure. To each place
+where an identifier is bound in a program there corresponds
+a @dfn{region} of the program text within which the binding is visible.
+The region is determined by the particular binding construct that
+establishes the binding; if the binding is
+established by a @code{lambda} expression, for example, then its
+region is the entire @code{lambda} expression. Every mention of
+an identifier refers to the binding of the identifier that established
+the innermost of the regions containing the use.
+
+If there is no binding of the identifier whose region contains the use,
+then the use refers to the binding for the
+variable in the global environment, if any;
+if there is no binding for the identifier, it is said to be @dfn{unbound}.
+
address@hidden Patterns
+
+The usual way to bind variables is to match an incoming
+value against a @dfn{pattern}. The pattern contains variables
+that are bound to some value derived from the value.
address@hidden
+(! [x::double y::double] (some-expression))
address@hidden example
+In the above example, the pattern @code{[x::double y::double]}
+is matched against the incoming value that results from
+evaluating @code{(some-expression)}.
+That value is required to be a two-element sequence.
+Then the sub-pattern @code{x::double} is matched against
+element 0 of the sequence, which means it is coerced to a @code{double}
+and then the coerced value is matched against the sub-pattern @code{x}
+(which trivially succeeds). Similarly, @code{y::double} is matched
+against element 1.
+
+The syntax of patterns is a work-in-progress. (The focus until now
+has been in designing and implementing how patterns work in general,
+rather than the details of the pattern syntax.)
+
address@hidden
address@hidden @stxref{identifier}
+ | @stxlit{_}
+ | @stxref{pattern-literal}
+ | @stxlit{'address@hidden
+ | @stxref{pattern} @stxlit{::} @stxref{type}
+ | @stxlit{[} @address@hidden @stxlit{]}
address@hidden @stxref{pattern}
+ | @stxlit{@@} @stxref{pattern}
+ | @stxref{pattern} @stxlit{...}
+ | @stxref{guard}
address@hidden
+ @stxref{boolean} | number | @stxref{character} | @stxref{string}
address@hidden @stxlit{#!if} @stxref{expression}
address@hidden display
+
+This is how the specific patterns work:
+
address@hidden @asis
address@hidden @stxref{identifier}
+This is the simplest and most common form of pattern.
+The @var{identifier} is bound to a new variable
+that is initialized to the incoming value.
+
address@hidden @stxlit{_}
+This pattern just discards the incoming value.
+It is equivalent to a unique otherwise-unused @var{identifier}.
+
address@hidden @stxref{pattern-literal}
+Matches if the value is @code{equal?} to the @var{pattern-literal}.
+
address@hidden @stxlit{'address@hidden
+Matches if the value is @code{equal?} to the quoted @var{datum}.
+
address@hidden @stxref{pattern} @stxlit{::} @stxref{type}
+The incoming value is coerced to a value of the specified @var{type},
+and then the coerced value is matched against the address@hidden
+Most commonly the address@hidden is a plain @var{identifier},
+so the latter match is trivial.
+
address@hidden @stxlit{[} @address@hidden @stxlit{]}
+The incoming value must be a sequence (a list, vector or similar).
+In the case where each sub-pattern is a plain @var{pattern},
+then the number of sub-patterns must match the size of the sequence, and
+each sub-pattern is matched against the corresponding element of the sequence.
+More generally, each sub-pattern may match zero or more consequtive
+elements of the incoming sequence.
+
address@hidden @stxlit{#!if} @stxref{expression}
+No incoming value is used. Instead the @var{expression} is evaluated.
+If the result is true, matching succeeds (so far);
+otherwise the match fails.
+This form is called a
@uref{https://en.wikipedia.org/wiki/Guard_(computer_science),@dfn{guard}}.
address@hidden table
+
address@hidden Definitions
address@hidden Definitions
+
+A variable definition binds one or more identifiers and specifies
+an initial value for each of them. The simplest kind of
+variable definition takes one of the following forms:
+
address@hidden Syntax ! @stxref{pattern} @stxref{expression}
+Evaluate @stxref{expression}, and match the result against @var{pattern}.
+Defining variables in @stxref{pattern} becomes bound in the
+current (surrounding) scope.
+
+This is similar to @code{define-constant} except generalized to a
@var{pattern}.
address@hidden deffn
+
address@hidden Syntax define name address@hidden::} @stxref{type}]
@stxref{expression}
+Evaluate the @var{expression}, optionally converting it to @var{type},
+and bind the @var{name} to the result.
address@hidden deffn
+
address@hidden Syntax define (name @stxref{formal-arguments})
@arbno{(@stxref{annotation} | @stxref{option-pair})} @stxref{opt-return-type}
@stxref{body}
address@hidden Syntax define (name @stxlit{.} @stxref{rest-arg})
@arbno{(@stxref{annotation} | @stxref{option-pair})} @stxref{opt-return-type}
@stxref{body}
+
+Bind the @var{name} to a function definition. The form:
address@hidden
+(define (@var{name} @stxref{formal-arguments}) @address@hidden
@stxref{opt-return-type} @stxref{body})
address@hidden example
+is equivalent to:
address@hidden
+(define @var{name} (lambda @stxref{formal-arguments}) name: @var{name}
@address@hidden @stxref{opt-return-type} @stxref{body}))
address@hidden example
+while the form:
address@hidden
+(define (@var{name} . @stxref{rest-arg}) @address@hidden
@stxref{opt-return-type} @stxref{body})
address@hidden example
+is equivalent to:
address@hidden
+(define @var{name} (lambda @stxref{rest-arg}) name: @var{name} @address@hidden
@stxref{opt-return-type} @stxref{body}))
address@hidden example
+
+You can associate @ref{Annotations,annotations} with @var{name}.
+A field annotation will be associated with the generated field;
+a method annotation will be associated with the generated method(s).
address@hidden deffn
+
+In addition to @code{define} (which can take an optional type specifier),
+Kawa has some extra definition forms.
+
address@hidden Syntax define-private name address@hidden::} @stxref{type}] value
address@hidden Syntax define-private (name formals) body
+Same as @code{define}, except that @code{name} is not exported.
address@hidden deffn
+
address@hidden Syntax define-constant name address@hidden::} @stxref{type}]
value
address@hidden Syntax define-early-constant name [:: type] value
+Defines @var{name} to have the given @var{value}.
+The value is readonly, and you cannot assign to it.
+(This is not fully enforced.)
+
+If @code{define-early-constant} is used
address@hidden the @var{value} is a compile-time constant,
+then the compiler will create a @code{final} field with
+the given name and type, and evaluate @var{value}
+in the module's class initializer (if the definition
+is static) or constructor (if the definition is non-static),
+before other definitions and expressions.
+Otherwise, the @var{value} is evaluated in the module body
+where it appears.
+
+If the @var{value} is a compile-time constant,
+then the definition defaults to being static.
address@hidden deffn
+
address@hidden Syntax define-variable name address@hidden::} @stxref{type}]
[init]
+If @var{init} is specified and @var{name} does not have a global variable
+binding, then @var{init} is evaluated, and @var{name} bound to the result.
+Otherwise, the value bound to @var{name} does not change.
+(Note that @var{init} is not evaluated
+if @var{name} does have a global variable binding.)
+
+Also, declares to the compiler that @var{name} will be looked up
+in the per-thread dynamic environment. This can be useful for shutting up
+warnings from @code{--warn-undefined-variable}.
+
+This is similar to the Common Lisp @code{defvar} form.
+However, the Kawa version is (currently) only allowed at module level.
address@hidden deffn
+
+For @code{define-namespace} and @code{define-private-namespace}
+see @ref{Namespaces}.
+
address@hidden Local binding constructs
address@hidden Local binding constructs
+
+The binding constructs @code{let}, @code{let*}, @code{letrec},
+and @code{letrec*} give Scheme a block structure, like Algol 60.
+The syntax of these four constructs
+is identical, but they differ in the regions they establish
+for their variable bindings. In a @code{let} expression, the initial
+values are computed before any of the variables become
+bound; in a @code{let*} expression, the bindings and evaluations
+are performed sequentially; while in @code{letrec} and @code{letrec*}
+expressions, all the bindings are in effect while their initial
+values are being computed, thus allowing mutually recursive definitions.
address@hidden The let-values and let*-values con-
address@hidden structs are analogous to let and let* respectively, but
address@hidden are designed to handle multiple-valued expressions, bind-
address@hidden ing different identifiers to the returned values.
+
address@hidden Syntax let @stxlit{((address@hidden @address@hidden)}
address@hidden)} @stxref{body}
+Declare new local variables as found in the @meta{pattern}s.
+Each @var{pattern} is matched against the corresponding @var{init}.
+The @var{init}s are evaluated in the current environment (in left-to-right
+onder), the @var{variable}s in the @var{patterns}s are bound to fresh
+locations holding the matched results,
+the @var{body} is evaluated in the extended environment, and the values of
+the last expression of body are returned.
+Each binding of a variable has @var{body} as its region.
+
address@hidden
+(let ((x 2) (y 3))
+ (* x y)) @result{} 6
address@hidden example
+
address@hidden
+(let ((x 2) (y 3))
+ (let ((x 7)
+ (z (+ x y)))
+ (* z x))) @result{} 35
address@hidden example
+
+An example with a non-trivial pattern:
+
address@hidden
+(let (([a::double b::integer] (vector 4 5)))
+ (cons b a)) @result{} (5 . 4.0)
address@hidden example
address@hidden deffn
+
address@hidden Syntax let* @stxlit{((address@hidden address@hidden)}
address@hidden)} @stxref{body}
+
+The @code{let*} binding construct is similar to @code{let},
+but the bindings are performed sequentially from left to
+right, and the region of a @var{variable}s in a @var{pattern}
+is that part of the @code{let*} expression to the right of
+the @var{pattern}. Thus the second pattern is matched in an environment
+in which the bindings from the first pattern are visible, and so on.
+
address@hidden
+(let ((x 2) (y 3))
+ (let* ((x 7)
+ (z (+ x y)))
+ (* z x))) @result{} 70
address@hidden example
address@hidden deffn
+
address@hidden Syntax letrec @stxlit{((}variable address@hidden::}
@stxref{type}] address@hidden)} address@hidden)} @stxref{body}
address@hidden Syntax letrec* @stxlit{((}variable address@hidden::}
@stxref{type}] address@hidden)} address@hidden)} @stxref{body}
+The @var{variable}s are bound to fresh locations,
+each @var{variable} is assigned in left-to-right order
+to the result of the corresponding @var{init},
+the @var{body} is evaluated in the resulting environment,
+and the values of the last expression in body are returned.
+Despite the left-to-right evaluation and assignment order, each binding of a
address@hidden has the entire @code{letrec} or @code{letrec*}
+expression as its region,
+making it possible to define mutually recursive procedures.
+
+In Kawa @code{letrec} is defined as the same as @code{letrec*}.
+In standard Scheme the order of evaluation of the @var{init}s
+is undefined, as is the order of assignments.
+If the order matters, you should use @code{letrec*}.
+
+If it is not possible to evaluate each @var{init} without assigning
+or referring to the value of the corresponding @var{variable}
+or the variables that follow it, it is an error.
address@hidden
+(letrec ((even?
+ (lambda (n)
+ (if (zero? n)
+ #t
+ (odd? (- n 1)))))
+ (odd?
+ (lambda (n)
+ (if (zero? n)
+ #f
+ (even? (- n 1))))))
+ (even? 88))
+ @result{} #t
address@hidden example
address@hidden deffn
+
address@hidden Lazy evaluation
address@hidden Lazy evaluation
+
address@hidden evaluation} (or call-by-need) delays evaluating an expression
until it
+is actually needed; when it is evaluated, the result is saved so
+repeated evaluation is not needed.
address@hidden://en.wikipedia.org/wiki/Lazy_evaluation,Lazy evaluation}
+is a technique that can make some algorithms easier to express compactly
+or much more efficiently, or both. It is the normal evaluation mechanism
+for strict functional (side-effect-free) languages such as
address@hidden://www.haskell.org,Haskell}.
+However, automatic lazy evaluation is awkward to combine with side-effects
+such as input-output. It can also be difficult to implement
+lazy evaluation efficiently, as it requires more book-keeping.
+
+Kawa, like other Schemes, uses ``eager evaluation'' - an expression
+is normally evaluated immediately, unless it is wrapped in a special form.
+Standard Scheme has some basic building blocks for ``manual''
+lazy evaluation, using an explicit @code{delay} operator to
+indicate that an expression is to be evaluated lazily,
+yielding a @dfn{promise},
+and a @code{force} function to force evaluation of a promise.
+This functionality is enhanced in
address@hidden://srfi.schemers.org/srfi-45/srfi-45.html, SRFI 45},
+in R7RS-draft (based on SRFI 45),
+and @uref{http://srfi.schemers.org/srfi-41/srfi-41.html, SRFI 41} (lazy lists
aka streams).
+
+Kawa makes lazy evaluation easier to use, by @dfn{implicit forcing}:
+The promise is automatically evaluated (forced) when used in a
+context that requires a normal value, such as arithmetic needing a number.
+Kawa enhances lazy evaluation in other ways, including
+support for safe multi-threaded programming.
+
address@hidden Delayed evaluation
+
address@hidden Syntax delay @stxref{expression}
+The @code{delay} construct is used together with the procedure
address@hidden to implement @emph{lazy evaluation} or @emph{call by need}.
+
+The result of @code{(delay @var{expression})} is a
address@hidden which at some point in the future may be asked (by the
address@hidden procedure) to evaluate @var{expression}, and deliver the
+resulting value. The effect of @var{expression} returning multiple
+values is unspecified.
address@hidden deffn
+
address@hidden Syntax delay-force @stxref{expression}
address@hidden Syntax lazy @stxref{expression}
+The @code{delay-force} construct is similar to @code{delay}, but it is expected
+that its argument evaluates to a promise.
+(Kawa treats a non-promise value as if it were a forced promise.)
+The returned
+promise, when forced, will evaluate to whatever the original
+promise would have evaluated to if it had been forced.
+
+The expression @code{(delay-force @meta{expression})} is
+conceptually similar to @code{(delay (force @meta{expression}))}, with
+the difference that forcing the result of @code{delay-force} will
+in effect result in a tail call to @code{(force @meta{expression})}, while
+forcing the result of @code{(delay (force @meta{expression}))} might
+not. Thus iterative lazy algorithms that might result in a
+long series of chains of @code{delay} and @code{force} can be rewritten
+using delay-force to prevent consuming unbounded space
+during evaluation.
+
+Using @code{delay-force} or @code{lazy} is equivalent.
+The name @code{delay-force} is from R7RS; the name @code{lazy}
+is from the older SRFI-45.
address@hidden deffn
+
address@hidden Procedure eager obj
+Returns a promise that when forced will return @var{obj}.
+It is similar to @code{delay}, but does not delay its argument;
+it is a procedure rather than syntax.
+
+The Kawa implementation just returns @var{obj} as-is.
+This is because Kawa treats as equivalent
+a value and forced promise evaluating to the value.
address@hidden deffn
+
address@hidden Procedure force promise
+The @func{force} procedure forces the value of @var{promise}.
+As a Kawa extension, if the @var{promise} is not a promise (a value that
+does not implement @code{gnu.mapping.Lazy}) then the argument is returned
unchanged.
+If no value has been computed for the promise, then a value is computed and
+returned. The value of the promise is cached (or ``memoized'') so that
+if it is forced a second time, the previously computed value is
+returned.
address@hidden
+(force (delay (+ 1 2))) @result{} 3
+
+(let ((p (delay (+ 1 2))))
+ (list (force p) (force p))) @result{} (3 3)
+
+(define integers
+ (letrec ((next
+ (lambda (n)
+ (cons n (delay (next (+ n 1)))))))
+ (next 0)))
+(define head
+ (lambda (stream) (car (force stream))))
+(define tail
+ (lambda (stream) (cdr (force stream))))
+
+(head (tail (tail integers))) @result{} 2
address@hidden example
+
+The following example is a mechanical transformation of
+a lazy stream-filtering algorithm into Scheme. Each call
+to a constructor is wrapped in @code{delay}, and each argument
+passed to a deconstructor is wrapped in @code{force}. The use
+of @code{(lazy ...)} instead of @code{(delay (force ...))} around
+the body of the procedure ensures that an ever-growing
+sequence of pending promises does not exhaust the heap.
+
address@hidden
+(define (stream-filter p? s)
+ (lazy
+ (if (null? (force s))
+ (delay ’())
+ (let ((h (car (force s)))
+ (t (cdr (force s))))
+ (if (p? h)
+ (delay (cons h (stream-filter p? t)))
+ (stream-filter p? t))))))
+
+(head (tail (tail (stream-filter odd? integers))))
+ @result{} 5
address@hidden example
+
address@hidden deffn
+
address@hidden Procedure force* promise
+Does @code{force} as many times as necessary to produce a non-promise.
+(A non-promise is a value that does not implement @code{gnu.mapping.Lazy},
+or if it does implement @code{gnu.mapping.Lazy} then forcing the value
+using the @code{getValue} method yields the receiver.)
+
+The @code{force*} function is a Kawa extension.
+Kawa will add implicit calls to @code{force*}
+in most contexts that need it, but you can also call it explicitly.
address@hidden deffn
+
+The following examples are not intended to illustrate good
+programming style, as @code{delay}, @code{lazy}, and @code{force} are mainly
+intended for programs written in the functional style.
+However, they do illustrate the property that only one value is
+computed for a promise, no matter how many times it is
+forced.
+
address@hidden
+(define count 0)
+(define p
+ (delay (begin (set! count (+ count 1))
+ (if (> count x)
+ count
+ (force p)))))
+(define x 5)
+p @result{} @emph{a promise}
+(force p) @result{} 6
+p @result{} @emph{a promise, still}
+(begin (set! x 10)
+ (force p)) @result{} 6
address@hidden example
+
address@hidden Implicit forcing
+
+If you pass a promise as an argument to a function like @code{sqrt}
+if must first be forced to a number. In general, Kawa does this
+automatically (implicitly) as needed, depending on the context.
+For example:
address@hidden
+(+ (delay (* 3 7)) 13) @result{} 34
address@hidden example
+
+Other functions,
+like @code{cons} have no problems with promises, and automatic forcing
+would be undesirable.
+
+Generally, implicit forcing happens for arguments that require a
+specific type, and does not happen for arguments that work on
address@hidden type (or @code{Object}).
+
+Implicit forcing happens for:
address@hidden
address@hidden
+arguments to arithmetic functions;
address@hidden
+the sequence and the index in indexing operations, like @code{string-ref};
address@hidden
+the operands to @code{eqv?} and @code{equal?} are forced,
+though the operands to @code{eq?} are not;
address@hidden
+port operands to port functions;
address@hidden
+the value to be emitted by a @code{display} but @emph{not} the
+value to be emitted by a @code{write};
address@hidden
+the function in an application.
address@hidden itemize
+
+Type membership tests, such as the @code{instance?} operation,
+generally do not force their values.
+
+The exact behavior for when implicit forcing happens is a work-in-progress:
+There are certainly places where implicit forcing doesn't happen while
+it should; there are also likely to be places where implicit forcing
+happens while it is undesirable.
+
+Most Scheme implementations are such that a forced promise behaves differently
+from its forced value, but some Scheme implementions are such that there is no
+means by which a promise can be operationally distinguished
+from its forced value.
+Kawa is a hybrid: Kawa tries to minimize the difference between
+a forced promise and its forced value, and may freely optimize
+and replace a forced promise with its value.
+
address@hidden Blank promises
+
+A @dfn{blank promise} is a promise that doesn't (yet) have
+a value @emph{or} a rule for calculating the value.
+Forcing a blank promise will wait forever, until some
+other thread makes the promise non-blank.
+
+Blank promises are useful as a synchronization mechanism -
+you can use it to safely pass data from one thread (the producer)
+to another thread (the consumer). Note that you can only
+pass one value for a given promise: To pass multiple values, you
+need multiple promises.
+
address@hidden
+(define p (promise))
+(future ;; Consumer thread
+ (begin
+ (do-stuff)
+ (define v (force promise)) ; waits until promise-set-value!
+ (do-stuff-with v)))
+;; Producer thread
+... do stuff ...
+(promise-set-value! p (calculate-value))
address@hidden example
+
address@hidden Constructor promise
+Calling @code{promise} as a zero-argument constructor
+creates a new blank promise.
+
+This calls the constructor for @code{gnu.mapping.Promise}.
+You can also create a non-blank promise, by setting one
+of the @code{value}, @code{alias}, @code{thunk}, or @code{exception}
properties.
+Doing so is equivalent to calling @code{promise-set-value!},
address@hidden, @code{promise-set-thunk!}, or
address@hidden on the resulting promise.
+For example: @code{(delay exp)} is equivalent to:
address@hidden
+(promise thunk: (lambda() exp))
address@hidden example
address@hidden deffn
+
+The following four procedures require that their first arguments
+be blank promises. When the procedure returns, the promise is
+no longer blank, and cannot be changed. This is because a
+promise is conceptually a placeholder for a single ``not-yet-known'' value;
+it is not a location that can be assigned multiple times.
+The former enables clean and safe (``declarative") use of multiple threads;
+the latter is much trickier.
+
address@hidden Procedure promise-set-value! promise value
+Sets the value of the @var{promise} to @var{value},
+which makes the @var{promise} forced.
address@hidden deffn
+
address@hidden Procedure promise-set-exception! promise exception
+Associate @var{exception} with the @var{promise}.
+When the @var{promise} is forced the @var{exception} gets thrown.
address@hidden deffn
+
address@hidden Procedure promise-set-alias! promise other
+Bind the @var{promise} to be an alias of @var{other}.
+Forcing @var{promise} will cause @var{other} to be forced.
address@hidden deffn
+
address@hidden Procedure promise-set-thunk! promise thunk
+Associate @var{thunk} (a zero-argument procedure) with the @var{promise}.
+The first time the @var{promise} is forced will causes the
address@hidden to be called, with the result (a value or an exception)
+saved for future calls.
address@hidden deffn
+
address@hidden Procedure make-promise obj
+The @code{make-promise} procedure returns a promise which,
+when forced, will return @var{obj}. It is similar to @code{delay}, but
+does not delay its argument: it is a procedure rather than
+syntax. If @var{obj} is already a promise, it is returned.
+
+Because of Kawa's implicit forcing, there is seldom a
+need to use @code{make-promise}, except for portability.
address@hidden deffn
+
address@hidden Lazy and eager types
+
address@hidden Type promise[T]
+This parameterized type is the type of promises that evaluate to
+an value of type @code{T}.
+It is equivalent to the Java interface @code{gnu.mapping.Lazy<T>}.
+The implementation class for promises is usually @code{gnu.mapping.Promise},
+though there are other classes that implement @code{Lazy},
+most notably @code{gnu.mapping.Future}, used for futures,
+which are promises evaluated in a separate thread.
address@hidden deffn
+
+Note the distinction between the types @code{integer}
+(the type of actual (eager) integer values), and @code{promise[integer]}
+(the type of (lazy) promises that evaluate to integer).
+The two are compatible: if a @code{promise[integer]} value is provided
+in a context requiring an @code{integer} then it is automatically
+evaluated (forced). If an @code{integer} value is provided
+in context requiring a @code{promise[integer]}, that conversion is basically
+a no-op (though the compiler may wrap the @code{integer}
+in a pre-forced promise).
+
+In a fully-lazy language there would be no distinction, or
+at least the promise type would be the default. However, Kawa is
+a mostly-eager language, so the eager type is the default.
+This makes efficient code-generation easier: If an expression
+has an eager type, then the compiler can generate code that
+works on its values directly, without having to check for laziness.
+
address@hidden Threads
address@hidden Threads
+
+There is a very preliminary interface to create parallel threads.
+The interface is similar to the standard @code{delay}/@code{force},
+where a thread is basically the same as a promise, except that
+evaluation may be in parallel.
+
address@hidden Syntax future expression
+Creates a new thread that evaluates @var{expression}.
+
+(The result extends @code{java.lang.Thread} and
+implements @code{gnu.mapping.Lazy}.)
address@hidden deffn
+
address@hidden Procedure force thread
+The standard @code{force} function is generalized to also work
+on threads. It waits for the thread's @var{expression} to finish
+executing, and returns the result.
address@hidden deffn
+
address@hidden Procedure runnable function
+Creates a new @code{Runnable} instance from a function.
+Useful for passing to Java code that expects a @code{Runnable}.
+You can get the result (a value or a thrown exception) using the
address@hidden method.
address@hidden deffn
+
address@hidden Syntax synchronized object form ...
+Synchronize on the given @var{object}. (This means getting an
+exclusive lock on the object, by acquiring its @dfn{monitor}.)
+Then execute the @var{form}s while holding the lock.
+When the @var{form}s finish (normally or abnormally by throwing
+an exception), the lock is released.
+Returns the result of the last @var{form}.
+Equivalent to the Java @code{synchronized} statement,
+except that it may return a result.
address@hidden deffn
+
address@hidden Exceptions
address@hidden Exception handling
+An @dfn{exception} is an object used to signal an error or
+other exceptional situation. The program or run-time system
+can @dfn{throw} the exception when an error is discovered.
+An exception handler is a program construct that registers
+an action to handle exceptions when the handler is active.
+
+If an exception is thrown and not handled then the
+read-eval-print-loop will print a stack trace, and bring
+you back to the top level prompt.
+When not running interactively, an unhandled exception
+will normally cause Kawa to be exited.
+
+In the Scheme exception model (as of R6RS and R7RS),
+exception handlers are one-argument procedures that determine
+the action the program takes when an exceptional situation is signaled.
+The system implicitly maintains a
+current exception handler in the dynamic environment.
+The program raises an exception by invoking the current
+exception handler, passing it an object encapsulating information
+about the exception. Any procedure accepting
+one argument can serve as an exception handler and any
+object can be used to represent an exception.
+
+The Scheme exception model is implemented on top of the Java VM's
+native exception model where the only objects that
+can be thrown are instances of @code{java.lang.Throwable}.
+Kawa also provides direct access to this native model,
+as well as older Scheme exception models.
+
address@hidden Procedure with-exception-handler handler thunk
+It is an error if @var{handler} does not accept one argument.
+It is also an error if @var{thunk} does not accept zero arguments.
+The @code{with-exception-handler} procedure returns the results
+of invoking @var{thunk}. The @var{handler} is installed as the current
+exception handler in the dynamic environment used for the
+invocation of @var{thunk}.
+
address@hidden
+(call-with-current-continuation
+ (lambda (k)
+ (with-exception-handler
+ (lambda (x)
+ (display "condition: ")
+ (write x)
+ (newline)
+ (k 'exception))
+ (lambda ()
+ (+ 1 (raise ’an-error))))))
+ @result{} exception
+ @i{and prints} condition: an-error
address@hidden example
+
address@hidden
+(with-exception-handler
+ (lambda (x)
+ (display "something went wrong\n"))
+ (lambda ()
+ (+ 1 (raise ’an-error))))
+ @i{prints} something went wrong
address@hidden example
+
+After printing, the second example then raises another exception.
+
address@hidden The @var{thunk} is inlined if it is a
+lambda expression. However, the @var{handler} cannot be inlined
+even if it is a lambda expression, because it could be called by
address@hidden Using the @code{guard} form is
+usually more efficient.
address@hidden deffn
+
address@hidden Procedure raise obj
+Raises an exception by invoking the current exception handler on @var{obj}.
+The handler is called with the same dynamic
+environment as that of the call to raise, except that the
+current exception handler is the one that was in place when
+the handler being called was installed. If the handler returns,
+then @var{obj} is re-raised in the same dynamic environment as the handler.
+
+If @var{obj} is an instance of @code{java.lang.Throwable},
+then @code{raise} has the same effect as @code{primitive-throw}.
address@hidden deffn
+
address@hidden Procedure raise-continuable obj
+Raises an exception by invoking the current exception handler on @var{obj}.
+The handler is called with the same dynamic
+environment as the call to @code{raise-continuable}, except
+that: (1) the current exception handler is the one that was
+in place when the handler being called was installed, and
+(2) if the handler being called returns, then it will again
+become the current exception handler.
+If the handler returns, the values it returns become the values
+returned by the call to @code{raise-continuable}.
+
address@hidden
+(with-exception-handler
+ (lambda (con)
+ (cond
+ ((string? con)
+ (display con))
+ (else
+ (display "a warning has been issued")))
+ 42)
+ (lambda ()
+ (+ (raise-continuable "should be a number")
+ 23)))
+ @i{prints:} should be a number
+ @result{} 65
address@hidden example
address@hidden deffn
+
address@hidden Syntax guard @var{variable} @address@hidden @stxref{body}
+The @meta{body} is evaluated with an exception handler that binds
+the raised object to @var{variable} and, within the scope of that binding,
+evaluates the clauses as if they were the clauses of a @code{cond} expression.
+That implicit @code{cond} expression is evaluated with
+the continuation and dynamic environment of the @code{guard}
+expression. If every cond-clause’s test evaluates to @code{#f}
+and there is no @code{else} clause, then @code{raise-continuable} is
+invoked on the raised object within the dynamic environment of the
+original call to @code{raise} or @code{raise-continuable},
+except that the current exception handler is that of the
address@hidden expression.
+
address@hidden
+(guard (condition
+ ((assq 'a condition) => cdr)
+ ((assq 'b condition)))
+ (raise (list (cons 'a 42))))
+ @result{} 42
address@hidden example
+
address@hidden
+(guard (condition
+ ((assq 'a condition) => cdr)
+ ((assq 'b condition)))
+ (raise (list (cons 'b 23))))
+ @result{} (b . 23)
address@hidden example
+
address@hidden Using @code{guard} is moderately efficient:
+there is some overhead compared to using native exception handling,
+but both the @var{body} and the handlers in the @var{cond-clause}
+are inlined.
address@hidden deffn
+
address@hidden Procedure dynamic-wind in-guard thunk out-guard
+All three arguments must be 0-argument procedures.
+First calls @var{in-guard}, then @var{thunk}, then @var{out-guard}.
+The result of the expression is that of @var{thunk}.
+If @var{thunk} is exited abnormally (by throwing an exception or
+invoking a continuation), @var{out-guard} is called.
+
+If the continuation of the dynamic-wind is re-entered (which
+is not yet possible in Kawa), the @var{in-guard} is called again.
+
+This function was added in R5RS.
address@hidden deffn
+
address@hidden Procedure read-error? obj
+Returns #t if @var{obj} is an object raised by the @code{read} procedure.
+(That is if @var{obj} is a @code{gnu.text.SyntaxException}.)
+
address@hidden deffn
address@hidden Procedure file-error? obj
+Returns #t if @var{obj} is an object raised by inability to open an input
+or output port on a file.
+(This includes @code{java.io.FileNotFoundException} as well
+as certain other exceptions.)
address@hidden deffn
+
address@hidden Simple error objects
+
address@hidden Procedure error message obj ...
+Raises an exception as if by calling @code{raise}
+on a newly allocated @dfn{simple error object},
+which encapsulates the information provided by @var{message}
+(which should a string), as well as any @var{obj} arguments,
+known as the irritants.
+
+The string representation of a simple error object is as if calling
address@hidden(format "#<ERROR address@hidden address@hidden>" @var{message}
@var{irritants})}.
+(That is the @var{message} is formatted as if with @code{display}
+while each irritant @var{obj} is formatted as if with @code{write}.)
+
+This procedure is part of SRFI-23, and R7RS.
+It differs from (and is incompatible with) R6RS's @code{error} procedure.
address@hidden deffn
+
address@hidden Procedure error-object? obj
+Returns @code{#t} if @var{obj} is a simple error object.
+Specifically, that @var{obj} is an instance of @code{kawa.lang.NamedException}.
+Otherwise, it returns @code{#f}.
address@hidden deffn
+
address@hidden Procedure error-object-message error-object
+Returns the message encapsulated by error-object,
+which must be a simple error object.
address@hidden deffn
+
address@hidden Procedure error-object-irritants error-object
+Returns a list of the irritants (other arguments)
+encapsulated by error-object, which must be a simple error object.
address@hidden deffn
+
address@hidden Named exceptions
+
+These functions associate a symbol with exceptions
+and handlers: A handler catches an exception if the symbol matches.
+
address@hidden Procedure catch key thunk handler
+Invoke @var{thunk} in the dynamic context of @var{handler} for
+exceptions matching @var{key}. If thunk throws to the symbol @var{key},
+then @var{handler} is invoked this way:
+
address@hidden
+(handler key args ...)
address@hidden example
+
address@hidden may be a symbol. The @var{thunk} takes no
+arguments. If @var{thunk} returns normally, that is the return value of
address@hidden
+
+Handler is invoked outside the scope of its own @code{catch}. If
address@hidden again throws to the same key, a new handler from further
+up the call chain is invoked.
+
+If the key is @code{#t}, then a throw to @emph{any} symbol will match
+this call to @code{catch}.
address@hidden deffn
+
address@hidden Procedure throw key arg ...
+Invoke the catch form matching @var{key}, passing the @var{arg}s to the
+current @var{handler}.
+
+If the key is a symbol it will match catches of the same
+symbol or of @code{#t}.
+
+If there is no handler at all, an error is signaled.
address@hidden deffn
+
address@hidden Native exception handling
+
address@hidden Procedure primitive-throw exception
+Throws the @var{exception}, which must be an instance of a sub-class
+of @code{java.lang.Throwable}.
address@hidden deffn
+
address@hidden Syntax try-finally body handler
+Evaluate @var{body}, and return its result.
+However, before it returns, evaluate @var{handler}.
+Even if @var{body} returns abnormally (by throwing an exception),
address@hidden is evaluated.
+
+(This is implemented just like Java's @address@hidden
+However, the current implementation does not duplicate the @var{handler}.)
address@hidden deffn
+
address@hidden Syntax try-catch body handler ...
+Evaluate @var{body}, in the context of the given @var{handler} specifications.
+Each @var{handler} has the form:
address@hidden
address@hidden @var{type} @var{exp} ...
address@hidden example
+If an exception is thrown in @var{body}, the first @var{handler}
+is selected such that the thrown exception is an instance of
+the @var{handler}'s @var{type}. If no @var{handler} is selected,
+the exception is propagated through the dynamic execution context
+until a matching @var{handler} is found. (If no matching @var{handler}
+is found, then an error message is printed, and the computation terminated.)
+
+Once a @var{handler} is selected,
+the @var{var} is bound to the thrown exception, and the @var{exp} in
+the @var{handler} are executed. The result of the @code{try-catch}
+is the result of @var{body} if no exception is thrown, or the
+value of the last @var{exp} in the selected @var{handler} if an
+exception is thrown.
+
+(This is implemented just like Java's @address@hidden)
address@hidden deffn
+
address@hidden Control features
address@hidden Control features
+
address@hidden
+* Mapping functions::
+* Multiple values::
address@hidden menu
+
address@hidden Mapping functions
address@hidden Mapping functions
+
+The procedures @code{string-for-each} and @code{string-map}
+are documented under @ref{Strings}.
+
+The procedure @code{string-cursor-for-each} is documented under @ref{String
Cursor API}.
+
address@hidden Procedure map @var{proc} address@hidden address@hidden ...
address@hidden Procedure for-each @var{proc} address@hidden address@hidden ...
+The @code{map} procedure applies @var{proc} element-wise to the elements
+of the @var{sequence}s and returns a list of the results, in order.
+The dynamic order in which @var{proc} is applied to
+the elements of the @var{sequence}s is unspecified.
+
+The @code{for-each} procedure does the same,
+but is executed for the side-effects of @var{proc}, whose result (if any)
+is discarded.
+Unlike @code{map}, @code{for-each} is guaranteed to call @var{proc}
+on the elements of the @var{sequences}s in order from the first element(s)
+to the last.
+The value returned by @code{for-each} is the void value.
+
+Each @var{sequence} must be a generalized sequence.
+(Traditionally, these arguments were restricted to lists,
+but Kawa allows sequences, including vectors, Java arrays, and strings.)
+If more than one @var{sequence} is given and not all
address@hidden have the same length, the procedure terminates when the
+shortest @var{sequence} runs out.
+The @var{sequence}s can be infinite (for example circular lists),
+but it is an error if all of them are infinite.
+
+The @var{proc} must be a procedure that accepts as many arguments
+as there are @var{sequence} arguments.
+It is an error for @var{proc} to mutate any of the @var{sequence}s.
+In the case of @code{map}, @var{proc} must return a single value.
+
address@hidden
+(map cadr '((a b) (d e) (g h)))
+ @result{} (b e h)
+
+(map (lambda (n) (expt n n))
+ '(1 2 3 4 5))
+ @result{} (1 4 27 256 3125)
+
+(map + ’(1 2 3) ’(4 5 6 7)) @result{} (5 7 9)
+
+(let ((count 0))
+ (map (lambda (ignored)
+ (set! count (+ count 1))
+ count)
+ '(a b)))
+ @result{} (1 2) @i{or} (2 1)
address@hidden example
+
+The result of @code{map} is a list, even if the arguments are non-lists:
address@hidden
+(map +
+ #(3 4 5)
+ (float[] 0.5 1.5))
+ @result{} (3.5 5.5)
address@hidden example
+
+To get a vector result, use @code{vector-map}.
+
address@hidden
+(let ((v (make-vector 5)))
+ (for-each (lambda (i)
+ (vector-set! v i (* i i)))
+ '(0 1 2 3 4))
+ v)
+ @result{} #(0 1 4 9 16)
address@hidden example
+
+A string is considered a sequence of @code{character} values
+(not 16-bit @code{char} values):
+
address@hidden
+(let ((v (make-vector 10 #\-)))
+ (for-each (lambda (i ch)
+ (vector-set! v i ch))
+ [0 <: ]
+ "Smile 😃!")
+ v)
+ @result{} #(#\S #\m #\i #\l #\e #\space #\x1f603 #\! #\- #\-)
address@hidden example
+
address@hidden These procedures are pretty well optimized.
+For each @var{sequence} the compiler will by default create an
+iterator.
address@hidden FUTURE (This can be done without object allocation XXXX)
+However, if the type of the @var{sequence} is known, the compiler will
+inline the iteration code.
address@hidden deffn
+
address@hidden Procedure vector-map @var{proc} @vari{sequence} @varii{sequence}
@dots{}
+Same as the @code{map} procedure, except the result is a vector.
+(Traditionally, these arguments were restricted to vectors,
+but Kawa allows sequences, including lists, Java arrays, and strings.)
+
address@hidden
+(vector-map cadr '#((a b) (d e) (g h)))
+ @result{} #(b e h)
+
+(vector-map (lambda (n) (expt n n))
+ '#(1 2 3 4 5))
+ @result{} #(1 4 27 256 3125)
+
+(vector-map + '#(1 2 3) ’#(4 5 6 7))
+ @result{} #(5 7 9)
+
+(let ((count 0))
+ (vector-map
+ (lambda (ignored)
+ (set! count (+ count 1))
+ count)
+ '#(a b)))
+ @result{} #(1 2) @i{or} #(2 1)
address@hidden example
address@hidden deffn
+
address@hidden Procedure vector-for-each @var{proc} @vari{vector}
@varii{vector} @dots{}
+Mostly the same as @code{for-each},
+however the arguments should be generalized vectors.
+Specifically, they should implement @code{java.util.List}
+(which both regular vectors and uniform vectors do).
+The @var{vectors} should also be efficiently indexable.
+
+(Traditionally, these arguments were restricted to vectors,
+but Kawa allows sequences, including lists, Java arrays, and strings.)
+
address@hidden
+(let ((v (make-list 5)))
+ (vector-for-each
+ (lambda (i) (list-set! v i (* i i)))
+ '#(0 1 2 3 4))
+ v)
+ @result{} (0 1 4 9 16)
address@hidden example
address@hidden deffn
+
address@hidden Multiple values
address@hidden Multiple values
+
+The multiple-value feature was added in R5RS.
+
address@hidden Procedure values object ...
+Delivers all of its arguments to its continuation.
address@hidden deffn
+
address@hidden Procedure call-with-values producer consumer
+Calls its @var{producer} argument with no arguments and a
+continuation that, when passed some values, calls the
address@hidden procedure with those values as arguments.
+
address@hidden
+(call-with-values (lambda () (values 4 5))
+ (lambda (a b) b))
+ @result{} 5
+
+(call-with-values * -) @result{} -1
address@hidden example
+
address@hidden If either the @var{producer} or @var{consumer} is a
+fixed-arity lambda expression, it is inlined.
address@hidden deffn
+
address@hidden Syntax define-values @stxref{formals} @stxref{expression}
+It is an error if a variable appears more than once in the
+set of @meta{formals}.
+
+The @meta{expression} is evaluated, and the @meta{formals}
+are bound to the return values in the same way that the @meta{formals} in
+a @code{lambda} expression are matched to the arguments in a procedure call.
+
address@hidden
+(define-values (x y) (integer-sqrt 17))
+(list x y) @result{} (4 1)
+(let ()
+ (define-values (x y) (values 1 2))
+ (+ x y))
+ @result{} 3
address@hidden example
address@hidden deffn
+
address@hidden Syntax let-values @stxlit{((address@hidden @address@hidden)}
address@hidden)} @stxref{body}
+Each @var{formals} should be a formal arguments list, as for a @code{lambda}.
+
+The @var{expression}s are evaluated in the current environment, the
+variables of the @var{formals} are bound to fresh locations, the return
+values of the @var{expression}s are stored in the variables, the
address@hidden is evaluated in the extended environment, and the values of
+the last expression of @var{body} are returned. The @var{body} is a
+"tail body", cf section 3.5 of the R5RS.
+
+The matching of each @var{formals} to values is as for the matching of
address@hidden to arguments in a @code{lambda} expression, and it is an
+error for an @var{expression} to return a number of values that does not
+match its corresponding @var{formals}.
address@hidden
+(let-values (((a b . c) (values 1 2 3 4)))
+ (list a b c)) @result{} (1 2 (3 4))
+
+(let ((a 'a) (b 'b) (x 'x) (y 'y))
+ (let-values (((a b) (values x y))
+ ((x y) (values a b)))
+ (list a b x y))) @result{} (x y a b)
address@hidden example
address@hidden deffn
+
address@hidden Syntax let*-values @stxlit{((address@hidden @address@hidden)}
address@hidden)} @stxref{body}
+
+Each @var{formals} should be a formal arguments list as for a
address@hidden expression.
+
address@hidden is similar to @code{let-values}, but the bindings are
+performed sequentially from left to right, and the region of a binding
+indicated by (@var{formals} @var{expression}) is that part of the
address@hidden expression to the right of the binding. Thus the
+second binding is done in an environment in which the first binding is
+visible, and so on.
address@hidden
+(let ((a 'a) (b 'b) (x 'x) (y 'y))
+ (let*-values (((a b) (values x y))
+ ((x y) (values a b)))
+ (list a b x y))) @result{} (x y x y)
address@hidden example
address@hidden deffn
+
address@hidden Syntax receive @stxref{formals} @stxref{expression} @stxref{body}
+This convenience
+form (from @uref{http://srfi.schemers.org/srfi-8/srfi-8.html, SRFI-8})
+is equivalent to:
address@hidden
+(let-values ((@var{formals} @var{expression})) @var{body})
address@hidden example
+For example:
address@hidden
+(receive a (values 1 2 3 4)
+ (reverse a)) @result{} (4 3 2 1)
+
+(receive (a b . c) (values 1 2 3 4)
+ (list a b c)) @result{} (1 2 (3 4))
+
+(let ((a 'a) (b 'b) (x 'x) (y 'y))
+ (receive (a b) (values x y)
+ (receive (x y) (values a b)
+ (list a b x y)))) @result{} (x y x y)
address@hidden example
address@hidden deffn
+
address@hidden Procedure values-append arg1 ...
+The values resulting from evaluating each argument are appended
+together.
address@hidden deffn
+
address@hidden Symbols and namespaces
address@hidden Symbols and namespaces
+
+An identifier is a name that appears in a program.
+
+A symbol is an object representing a string that cannot be
+modified. This string is called the symbol's name. Unlike strings, two
+symbols whose names are spelled the same way are indistinguishable.
+A symbol is immutable (unmodifiable) and normally viewed as atomic.
+Symbols are useful for many applications; for instance, they may be
+used the way enumerated values are used in other languages.
+
+In addition to the simple symbols of standard Scheme, Kawa
+also has compound (two-part) symbols.
+
address@hidden
+* Simple symbols::
+* Namespaces::
+* Keywords::
+* Special named constants::
address@hidden menu
+
address@hidden Simple symbols, Namespaces, , Symbols and namespaces
address@hidden Simple symbols
+
+Simple symbols have no properties other than their name, an immutable string.
+They have the useful property that two simple symbols
+are identical (in the sense of @func{eq?}, @func{eqv?} and
address@hidden) if and only if their names are spelled the same way. A
+symbol literal is formed using @func{quote}.
+
address@hidden Procedure {symbol?} @var{obj}
+Return @true{} if @var{obj} is a symbol, @false{} otherwise.
+
address@hidden
+(symbol? 'foo) @result{} #t
+(symbol? (car '(a b))) @result{} #t
+(symbol? "bar") @result{} #f
+(symbol? 'nil) @result{} #t
+(symbol? '()) @result{} #f
+(symbol? #f) @result{} #f
address@hidden example
address@hidden deffn
+
address@hidden Procedure {symbol->string} @var{symbol}
+Return the name of @var{symbol} as an immutable string.
+
address@hidden
+(symbol->string 'flying-fish) @result{} "flying-fish"
+(symbol->string 'Martin) @result{} "Martin"
+(symbol->string (string->symbol "Malvina")) @result{} "Malvina"
address@hidden example
address@hidden deffn
+
address@hidden Procedure {string->symbol} @var{string}
+Return the symbol whose name is @var{string}.
+
address@hidden
+(eq? 'mISSISSIppi 'mississippi)
address@hidden #f
+
+(string->symbol "mISSISSIppi")
address@hidden the symbol with name "mISSISSIppi"
+
+(eq? 'bitBlt (string->symbol "bitBlt"))
address@hidden #t
+
+(eq? 'JollyWog (string->symbol (symbol->string 'JollyWog)))
address@hidden #t
+
+(string=? "K. Harper, M.D."
+ (symbol->string (string->symbol "K. Harper, M.D.")))
address@hidden #t
address@hidden example
address@hidden deffn
+
address@hidden Namespaces, Keywords, Simple symbols, Symbols and namespaces
address@hidden Namespaces and compound symbols
+
+Different applications may want to use the same symbol
+to mean different things. To avoid such @dfn{name clashes}
+we can use @dfn{compound symbols}, which have two string parts:
+a @dfn{local name} and a @dfn{namespace URI}.
+The namespace-uri can be any string, but it is
+recommended that it have the form of an absolute
address@hidden://en.wikipedia.org/wiki/Uniform_Resource_Identifier,URI}.
+It would be too verbose to write the full URI all the
+time, so one usually uses a @dfn{namespace prefix}
+(namespace alias) as a short local alias to refer to a
+namespace URI.
+
+Compound symbols are usually written using the infix colon operator:
address@hidden
address@hidden@stxlit{:address@hidden
address@hidden example
+where @var{prefix} is a namespace alias bound
+to some (lexically-known) namespace URI.
+
+Compound symbols are used for namespace-aware XML processing.
+
address@hidden Namespace objects
+
+A @dfn{namespace} is a mapping from strings to symbols.
+The string is the local-name of the resulting symbol.
+A namespace is similar to a Common Lisp @dfn{package}.
+
+A namespace has a namespace-uri, which a string;
+it is recommended that it have the form of an absolute URI.
+A namespace may optionally have a prefix, which is a string used
+when printing out symbols belonging to the namespace.
+(If you want ``equivalent symbols'' (i.e. those that have the same
+local-name and same uri) to be the identical symbol object, then
+you should use namespaces whose prefix is the empty string.)
+
address@hidden Constructor namespace name [prefix]
+Return a namespace with the given @var{name} and @var{prefix}.
+If no such namespace exists, create it.
+The @var{namespace-name} is commonly a URI, especially when working with XML,
+in which case it is called a @var{namespace-uri}. However, any non-empty
+string is allowed.
+The prefix can be a string or a simple symbol.
+(If a symbol is used, then the symbol's local-name is used.)
+The default for @var{prefix} is the empty string.
+Multiple calls with the same arguments will yield the same namespace object.
address@hidden deffn
+
+The reader macro @code{#,namespace} is equivalent to the
address@hidden function, but it is invoked at read-time:
address@hidden
+#,(namespace "http://www.w3.org/1999/XSL/Transform"; xsl)
+(eq? #,(namespace "foo") (namespace "foo")) @result{} #t
address@hidden example
+
+The form @code{(,#namespace "" "")} returns the default @dfn{empty namespace},
+which is used for simple symbols.
+
address@hidden Procedure namespace-uri namespace
+Return the namespace-uri of the argument @var{namespace}, as a string.
address@hidden deffn
+
address@hidden Procedure namespace-prefix namespace
+Return the namespace prefix of the argument @var{namespace}, as a string.
address@hidden deffn
+
address@hidden Compound symbols
+
+A compound symbol is one that belongs to a namespace other than the
+default empty namespace, and (normally) has a non-empty namespace uri.
+(It is possible for a symbol to belong to a non-default namespace
+and have an empty namespace uri, but that is not recommended.)
+
address@hidden Constructor symbol local-name namespace-spec
address@hidden Constructor symbol local-name [uri [prefix]]
+Construct a symbol with the given @var{local-name} and namespace.
+If @var{namespace-spec} is a namespace object, then find (or, if needed,
+construct) a symbol with the given @var{local-name} belonging to the
+namespace. Multiple calls to @code{symbol} with the same namespace
+and @var{local-name} will yield the same symbol object.
+
+If uri is a string (optionally followed by a prefix),
+then:
address@hidden
+(symbol lname uri [prefix])
address@hidden example
+is equivalent to:
address@hidden
+(symbol lname (namespace uri [prefix]))
address@hidden example
+
+Using @code{#t} for the @var{namespace-spec} is equivalent to
+using the empty namespace @code{#,(namespace "")}.
+
+Using @code{#!null} or @code{#f} for the @var{namespace-spec}
+creates an @var{uninterned} symbol, which does not belong to
+any namespace.
address@hidden deffn
+
address@hidden Procedure symbol-local-name symbol
+Return the local name of the argument symbol, as an immutable string.
+(The string is interned, except in the case of an uninterned symbol.)
address@hidden deffn
+
address@hidden Procedure symbol-prefix symbol
+Return the prefix of the argument symbol, as an immutable
+(and interned) string.
address@hidden deffn
+
address@hidden Procedure symbol-namespace-uri symbol
+Return the namespace uri of the argument symbol, as an immutable
+(and interned) string.
address@hidden deffn
+
address@hidden Procedure symbol-namespace symbol
+Return the namespace object (if any) of the argument symbol.
+Returns @code{#!null} if the symbol is uninterned.
address@hidden deffn
+
address@hidden Procedure {symbol=?} @vari{symbol} @varii{symbol}
@variii{symbol} @dots{}
+Return @true{} if the symbols are equivalent as symbols,
+i.e., if their local-names and namespace-uris are the same.
+They may have different values of @code{symbol-prefix} and
@code{symbol-namespace}.
+If a symbol is uninterned (or is @code{#!null}) then @code{symbol=?}
+returns the same result as @code{eq?}.
address@hidden deffn
+
+Two symbols are @code{equal?} or @code{eqv?} if they're @code{symbol=?}.
+
address@hidden Namespace aliases
+
+A namespace is usually referenced using a shorter @dfn{namespace alias},
+which is is a lexical definition that binds a namespace prefix
+to a namespace object (and thus a namespace uri).
+This allows using compound symbols as identifiers in Scheme programs.
+
address@hidden Syntax define-namespace name namespace-name
+Defines @var{name} as a @dfn{namespace prefix} - a lexically scoped
+"nickname" for the namespace
+whose full name is @var{namespace-name}, which should be a non-empty
+string literal.
+It is customary for the string have syntactic form of
+an absolute
@uref{http://en.wikipedia.org/wiki/Uniform_Resource_Identifier,URI},
+but any non-empty string is acceptable and is used without
+further interpretation.
+
+Any symbols in the scope of this definitions that contain a colon, and
+where the part before the colon matches the @var{name} will be
+treated as being in the package/namespace whose global unique name
+is the @var{namespace-name}.
+
+Has mostly the same effect as:
address@hidden
+(define-constant @var{name} #,(namespace @var{namespace-name})
address@hidden example
+
+However, using @code{define-namespace} (rather than @code{define-constant})
+is recommended if you want to use compound symbols as names of
+variables, especially local variables, or if you want to quote
+compound symbols.
+
+Note that the prefix is only visible lexically: it is not
+part of the namespace, or thus indirectly the symbols, and
+so is not available when printing the symbol.
+You might consider using @code{define-xml-namespace} as an alternative.
+
+A namespace is similar to a Common Lisp package,
+and the @var{namespace-name} is like the name of the package.
+However, a namespace alias belongs to the lexical scope,
+while a Common Lisp package nickname is global
+and belongs to the package itself.
+
+If the namespace-name starts with the string @code{"class:"}, then the
address@hidden can be used for invoking Java methods
+(@pxref{Method operations}) and accessing fields (@pxref{Field operations}).
+
+You can use a namespace as an abbreviation or renaming of a
+class name, but as a matter of style @code{define-alias} is preferred.
address@hidden deffn
+
address@hidden Syntax define-private-namespace name namespace-name
+Same as @code{define-namespace}, but the prefix @var{name}
+is local to the current module.
address@hidden deffn
+
+For example, you might have a set of a geometry definitions
+defined under the namespace-uri @code{"http://foo.org/lib/geometry"}:
+
address@hidden
+(define-namespace geom "http://foo.org/lib/geometry";)
+(define (geom:translate x y)
+ (java.awt.geom.AffineTransform:getTranslateInstance x y))
+(define geom:zero (geom:translate 0 0))
+geom:zero
+ @result{} AffineTransform[[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]]
address@hidden example
+
+You could have some other definitions for complex math:
address@hidden
+(define-namespace complex "http://foo.org/lib/math/complex";)
+(define complex:zero +0+0i)
address@hidden example
+
+You can use a namespace-value directly in a compound name:
address@hidden
+(namespace "http://foo.org/lib/geometry";):zero
+ @result{} AffineTransform[[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]]
address@hidden example
+
+The variation @code{define-xml-namespace} is used for @ref{Creating XML nodes}.
+
address@hidden Syntax define-xml-namespace prefix "namespace-uri"
+Defines a namespace with prefix @var{prefix} and URI @var{namespace-uri}.
+This is similar to @code{define-namespace} but with two important differences:
address@hidden
address@hidden
+Every symbol in the namespace automatically maps to
+an element-constructor-type, as with the @code{html} namespace.
address@hidden
+The @var{prefix} is a component of the namespace object, and
+hence indirectly of any symbols belongining to the namespace.
address@hidden itemize
+
+Thus the definition is roughly equivalent to:
address@hidden
+(define-constant @var{name} #,(namespace @var{namespace-name name})
address@hidden example
+along with an infinite set of definitions, for every possible @var{tag}:
address@hidden
+(define (name:@var{tag} . rest) (apply make-element 'name:@var{tag} rest))
address@hidden example
+
address@hidden deffn
+
address@hidden
+$ kawa --output-format xml
+#|kawa:1|# @kbd{(define-xml-namespace na "Namespace1")}
+#|kawa:2|# @kbd{(define-xml-namespace nb "Namespace1")}
+#|kawa:3|# @kbd{(define xa (na:em "Info"))}
+#|kawa:4|# @kbd{xa}
+<na:em xmlns:na="Namespace1">Info</na:em>
+#|kawa:5|# @kbd{(define xb (nb:em "Info"))}
+#|kawa:6|# @kbd{xa}
+<nb:em xmlns:nb="Namespace1">Info</nb:em>
address@hidden example
+
+Note that the prefix is part of the qualified name
+(it is actually part of the namespace object),
+and it is used when printing the tag.
+Two qualified names (symbols) that have the same
+local-name and the same namespace-name are considered
+equal, even if they have different prefix. You can think of
+the prefix as annotation used when printing, but not
+otherwise part of the ``meaning'' of a compound symbol.
+They are the same object if they also have the same prefix.
+This is an important difference from traditional Lisp/Scheme symbols,
+but it is how XML QNames work.
address@hidden
+#|kawa:7|# (instance? xb na:em)
+true
+#|kawa:8|# (eq? 'na:em 'nb:em)
+false
+#|kawa:9|# (equal? 'na:em 'nb:em)
+true
+#|kawa:10|# (eqv? 'na:em 'nb:em)
+true
address@hidden example
+(Note that @code{#t} is printed as @code{true} when using XML formatting.)
+
+The predefined @code{html} prefix could be defined thus:
address@hidden
+(define-xml-namespace html "http://www.w3.org/1999/xhtml";)
address@hidden example
+
address@hidden Keywords, Special named constants, Namespaces, Symbols and
namespaces
address@hidden Keywords
+
+Keywords are similar to symbols.
+They are used mainly for specifying keyword arguments.
+
+Historically keywords have been self-evaluating (you did not need to
+quote them). This has changed: you must quote a keyword if you
+want a literal keyword value, and not quote it if it is used
+as a keyword argument.
+
address@hidden
address@hidden @address@hidden:}
+ | @stxlit{#:address@hidden
address@hidden display
+
+The two syntaxes have the same meaning: The former is nicer-looking;
+the latter is more portable (and required if you use the
address@hidden command-line flag).
+
address@hidden
address@hidden:}
+In r7rs and other Scheme standards the colon character
+does not have any special meaning, so @code{foo:} or @code{foo:bar}
+are just regular identifiers. Therefore some other Scheme variants
+that have keywords (including Guile and Racket) use the @code{#:} syntax.
+Kawa has some hacks so that @emph{most}
+standard Scheme programs that have colons in identifiers will work.
+However, for best compatibility, use the @code{--r7rs} command-line flag
+(which turns colon into a regular character in a symbol), and the
address@hidden:} syntax.
address@hidden quotation
+
+A keyword is a single token; therefore no whitespace is allowed between
+the @var{identifier} and the colon or after the @code{#:};
+these characters are not considered part of the name of the keyword.
+
address@hidden Procedure keyword? obj
+Return @code{#t} if @var{obj} is a keyword, and otherwise returns @code{#f}.
address@hidden deffn
+
address@hidden Procedure keyword->string keyword
+Returns the name of @var{keyword} as a string.
+The name does not include the final @code{#\:}.
address@hidden deffn
+
address@hidden Procedure string->keyword string
+Returns the keyword whose name is @var{string}.
+(The @var{string} does not include a final @code{#\:}.)
address@hidden deffn
+
address@hidden Special named constants, , Keywords, Symbols and namespaces
address@hidden Special named constants
+
address@hidden Constant #!optional
+Special self-evaluating literal used in lambda parameter lists
+before optional parameters.
address@hidden defvr
+
address@hidden Constant #!rest
+Special self-evaluating literal used in lambda parameter lists
+before the rest parameter.
address@hidden defvr
+
address@hidden Constant #!key
+Special self-evaluating literal used in lambda parameter lists
+before keyword parameters.
address@hidden defvr
+
address@hidden Constant #!eof
+The end-of-file object.
+
+Note that if the Scheme reader sees this literal at top-level,
+it is returned literally. This is indistinguishable from
+coming to the end of the input file. If you do not want to end reading,
+but want the actual value of @code{#!eof}, you should quote it.
address@hidden defvr
+
address@hidden Constant #!void
+The void value. Same as @code{(values)}.
+If this is the value of an expression in a read-eval-print loop,
+nothing is printed.
address@hidden defvr
+
address@hidden Constant #!null
+The Java @code{null} value. This is not really a Scheme value,
+but is useful when interfacing to low-level Java code.
address@hidden defvr
+
address@hidden Procedures, Numbers, Symbols and namespaces, Top
address@hidden Procedures
+
address@hidden
+* Application and Arguments Lists::
+* Procedure properties::
+* Generic procedures::
+* Extended formals::
+* Partial application::
address@hidden menu
+
address@hidden Application and Arguments Lists
address@hidden Application and Arguments Lists
+
+When a procedure is called, the actual argument expression are evaluated,
+and the resulting values becomes the actual argument list.
+This is then matched against the formal parameter list
+(in the procedure definition), and assuming they match,
+the procedure body is called.
+
address@hidden Arguments lists
+
+An argument list has three parts:
address@hidden @bullet
address@hidden
+Zero or more @dfn{prefix arguments}, each of which is a value.
+These typically get bound to named required or optional formal parameters,
+but can also get bound to patterns.
address@hidden
+Zero or more @dfn{keyword arguments}, each of which is a keyword
+(an identifier specified with keyword syntax) combined with a value.
+These are bound to either named keyword formal parameters, or
+bundled in with a rest parameter.
address@hidden
+Zero or more @dfn{postfix arguments}, each of which is a value.
+These are usually bound to a ``rest'' formal parameter, which
+receives any remaining arguments.
+
+If there are no keyword arguments, then it ambiguous where
+prefix arguments and and where postfix arguments start.
+This is normally not a problem: the called procedure can
+split them up however it wishes.
address@hidden itemize
+
+Note that all keyword arguments have to be grouped together:
+It is not allowed to have a keyword argument followed by a plain
+argument followed by a keyword argument.
+
+The argument list is constructed by evaluating the each @stxref{operand}
+of the @stxref{procedure-call} in order:
address@hidden @asis
address@hidden @var{expression}
+The @var{expression} is evaluated, yielding a single value
+that becomes a prefix or postfix argument.
address@hidden @var{keyword} @var{expression}
+The @var{expression} is evaluated. The resulting value combined
+with the @var{keyword} becomes a keyword argument.
address@hidden @stxlit{@@address@hidden
+The @var{expression} is evaluated.
+The result must be a sequence - a list, vector, or primitive array.
+The values of the sequence are appended to the resulting argument list.
+Keyword arguments are not allowed.
address@hidden @stxlit{@@:address@hidden
+The @var{expression} is evaluted.
+The result can be a sequence;
+a hash table (viewed as a collection of (keyword,value) pairs);
+or an @dfn{explicit argument list} object, which is a sequence of values
address@hidden keyword arguments.
+The values and keyword arguments
+are appended to the resulting argument list, though subject to the restriction
+that keyword arguments must be adjacent in the resulting argument list.
address@hidden table
+
address@hidden Explicit argument list objects
+
+Sometimes it is useful to create an argument list out of
+pieces, take argument lists apart, iterate over them,
+and generally treat an argument list as an actual first-class value.
+
+Explicit argument list objects can take multiple forms.
+The simplest is a sequence: a list, vector, or primitive array.
+Each element of the list becomes a value in the resulting argument list.
+
address@hidden
+(define v1 '(a b c))
+(define v2 (int[] 10 11 12 13))
+(list "X" @@v1 "Y" @@v2 "Z")
+ @result{} ("X" a b c "Y" 10 11 12 13 "Z")
address@hidden example
+
+Things get more complicated once keywords are involved.
+An explicit argument list with keywords is only allowed
+when using the @code{@@:} splicing form,
+not the @code{@@} form. It can be either
+a hash table (anything the implement @code{java.util.Map}
+or the types @code{arglist} or @code{argvector}.
+
address@hidden
address@hidden note:} An argument list with keywords is straightforward
+in Common Lisp and some Scheme implementations (including order versions of
+Kawa): It's just a list some of whose @code{car} cells are keyword objects.
+The problem with this model is neither a human or the compiler can
+reliably tell when an argument is a keyword, since any variable
+might have been assigned a keyword. This limits performance and
+error checking.
address@hidden quotation
+
+A hash table (anything the implement @code{java.util.Map})
+whose keys are strings or keyword objects is
+interpreted as a sequence of keyword arguments,
+using the hash-table keys and values.
+
address@hidden Type argvector
address@hidden Constructor argvector @address@hidden
+List of arguments represented as an immutable vector.
+A keyword argument takes two elements in this vector:
+A keyword object, followed by the value.
+
address@hidden
+(define v1 (argvector 1 2 k1: 10 k2: 11 98 99))
+(v1 4) @result{} 'k2
+(v1 5) @result{} 11
address@hidden example
+When @code{v1} is viewed as a vector it
+is equivalent to @code{(vector 1 2 'k1: 10 'k2: 11 98 99)}.
+(Note in this case the keywords need to be quoted, since
+the @code{vector} constructor does not take keyword arguments.)
+However, the @code{argvector} ``knows'' which arguments
+are actually keyword arguments, and can be examined using the
address@hidden(kawa arglist)} library discussed below:
+
address@hidden
+(arglist-key-count (argvector 1 x: 2 3)) @result{} 1
+(arglist-key-count (argvector 1 'x: 2 3)) @result{} 0
+(arglist-key-count (vector 1 'x: 2 3)) @result{} 0
address@hidden example
+
+In this case:
address@hidden
+(fun 'a @@:v1)
address@hidden example
+is equivalent to:
address@hidden
+(fun 'a 1 2 k1: 10 k2: 11 98 99)
address@hidden example
address@hidden deffn
+
address@hidden Type arglist
address@hidden Constructor arglist @address@hidden
+Similar to @code{argvector}, but compatible with @code{list}.
+If there are no keyword arguments, returns a plain list.
+If there is at least one keyword argument creates a special
address@hidden object that implements the
+usual @code{list} properties but internally wraps a @code{argvector}.
address@hidden deffn
+
address@hidden Argument list library
+
address@hidden
+(import (kawa arglist))
address@hidden example
+
+In the following, @var{args} is an @code{arglist} or @code{argvector}
+(or in general any object that implement @code{gnu.mapping.ArgList}).
+Also, @var{args} can be a generalized list, in which case it
+behaves like an @code{argvector} that has no keyword arguments.
+
address@hidden Procedure arglist-walk args proc
+Call @var{proc} once, in order, for each argument in @var{args}.
+The @var{proc} is called with two arguments,
+corresponding to @code{(arglist-key-ref @var{args} @var{i})}
+and @code{(arglist-arg-ref @var{args} @var{i})} for each @var{i} from 0
+up to @code{(arglist-arg-count @var{args})} (exclusive).
+I.e. the first argument is either @code{#!null} or the keyword (as a string);
+the second argument is the corresponding argument value.
+
address@hidden
+(define (print-arguments args #!optional (out (current-output-port)))
+ (arglist-walk args
+ (lambda (key value)
+ (if key (format out "key: ~a value: ~w~%" key value)
+ (format out "value: ~w~%" value)))))
address@hidden example
address@hidden deffn
+
address@hidden Procedure arglist-key-count args
+Return the number of keyword arguments.
address@hidden deffn
+
address@hidden Procedure arglist-key-start args
+Number of prefix arguments, which is the number of arguments before
+the first keyword argument.
address@hidden deffn
+
address@hidden Procedure arglist-arg-count args
+Return the number of non-keyword arguments.
+(The count includes neither the keywords nor the corresponding values.)
address@hidden deffn
+
address@hidden Procedure arglist-arg-ref args index
+Get the @var{index}'th argument value.
+The @var{index} counts keyword argument values, but not the keywords
themselves.
address@hidden
+(arglist-arg-ref (arglist 10 11 k1: -1 19) 2) @result{} -1
+(arglist-arg-ref (arglist 10 11 k1: -1 19) 3) @result{} 19
address@hidden example
address@hidden deffn
+
address@hidden Procedure arglist-key-ref args index
+The @var{index} counts arguments like @code{arglist-arg-ref} does.
+If this is a keyword argument, return the corresponding keyword
+(as a string); otherwise, return @code{#!null} (which counts are false).
address@hidden
+(arglist-key-ref (argvector 10 11 k1: -1 k2: -2 19) 3) @result{} "k2"
+(arglist-key-ref (argvector 10 11 k1: -1 k2: -2 19) 4) @result{} #!null
address@hidden example
address@hidden deffn
+
address@hidden Procedure arglist-key-index args key
+Search for a keyword matching @var{key} (which must be an interned string).
+If there is no such keyword, return -1.
+Otherwise return the keyword's index as as argument to @code{arglist-key-ref}.
address@hidden deffn
+
address@hidden Procedure arglist-key-value args key default
+Search for a keyword matching @var{key} (which must be an interned string).
+If there is no such keyword, return the @var{default}.
+Otherwise return the corresponding keyword argument's value.
address@hidden deffn
+
address@hidden Apply procedures
+
address@hidden Procedure apply proc @arbno{argi} argrest
address@hidden must be a sequence (list, vector, or string) or a
+primitive Java array.
+(This is an extension over standard Scheme, which requires that
address@hidden be a list.)
+Calls the @var{proc} (which must be a procedure), using as arguments
+the @var{argi}... values plus all the elements of @var{argrest}.
+
+Equivalent to: @code{(address@hidden @address@hidden
@code{@@address@hidden@code{)}.
address@hidden deffn
+
address@hidden Syntax constant-fold proc arg1 ...
+Same as @code{(@var{proc} @var{arg1} ...)}, unless @var{proc} and
+all the following arguments are compile-time constants.
+(That is: They are either constant, or symbols that have a global
+binding and no lexical binding.) In that case, @var{proc}
+is applied to the arguments at compile-time, and the result replaces
+the @code{constant-fold} form. If the application raises an exception,
+a compile-time error is reported.
+For example:
address@hidden
+(constant-fold vector 'a 'b 'c)
address@hidden example
+is equivalent to @code{(quote #(a b c))}, assuming @code{vector}
+has not been re-bound.
address@hidden deffn
+
address@hidden Procedure properties, Generic procedures, , Procedures
address@hidden Procedure properties
+
+You can associate arbitrary @dfn{properties} with any procedure.
+Each property is a (@var{key}, @var{value})-pair. Usually the
address@hidden is a symbol, but it can be any object.
+
+The system uses certain internal properties:
address@hidden'name} refers to the name used when a procedure is printed;
address@hidden'emacs-interactive} is used to implement Emacs @code{interactive}
+specification;
address@hidden'setter} is used to associate a @code{setter} procedure.
+
address@hidden Procedure procedure-property proc key [default]
+Get the property value corresponding to the given @var{key}.
+If @var{proc} has no property with the given @var{key},
+return @var{default} (which defaults to @code{#f}) instead.
address@hidden deffn
+
address@hidden Procedure set-procedure-property! proc key value
+Associate the given @var{value} with the @var{key} property of @var{proc}.
address@hidden deffn
+
+To change the print name of the standard @code{+} procedure (probably
+not a good idea!), you could do:
address@hidden
+(set-procedure-property! + 'name 'PLUS)
address@hidden example
+Note this @emph{only} changes the name property used for printing:
address@hidden
++ @result{} #<procedure PLUS>
+(+ 2 3) @result{} 5
+(PLUS 3 4) @result{} ERROR
address@hidden example
+
+As a matter of style, it is cleaner to use the @code{define-procedure}
+form, as it is a more declarative interface.
+
address@hidden Syntax define-procedure name [propname: propvalue] ... method ...
+Defines @var{name} as a compound procedure consisting of the
+specified @var{method}s, with the associated properties.
+Applying @var{name} select the "best" @var{method}, and applies that.
+See the following section on generic procedures.
+
+For example, the standard @code{vector-ref} procedure specifies
+one method, as well as the @code{setter} property:
address@hidden
+(define-procedure vector-ref
+ setter: vector-set!
+ (lambda (vector::vector k ::int)
+ (invoke vector 'get k)))
address@hidden example
address@hidden deffn
+
+You can also specify properties in the lambda body:
+
address@hidden
+(define (vector-ref vector::vector k ::int)
+ setter: vector-set!
+ (invoke vector 'get k))
address@hidden example
+
address@hidden Standard properties
+
address@hidden @code
address@hidden name
+The name of a procedure (as a symbol), which is used
+when the procedure is printed.
address@hidden setter
+Set the setter procedure associated with the procedure.
address@hidden validate-apply
address@hidden validate-xapply
+Used during the validation phase of the compiler.
address@hidden compile-apply
+Used during the bytecode-generation phase of the compiler:
+If we see a call to a known function with this property,
+we can emit custom bytecode for the call.
address@hidden table
+
address@hidden Generic procedures, Extended formals, Procedure properties,
Procedures
address@hidden Generic (dynamically overloaded) procedures
+
+A @dfn{generic procedure} is a collection of @dfn{method procedures}.
+(A "method procedure" is not the same as a Java method, but
+the terms are related.)
+You can call a generic procedure, which selects the "closest
+match" among the component method procedures: I.e. the most specific
+method procedure that is applicable given the actual arguments.
+
address@hidden
address@hidden:} The current implementation of selecting the "best" method
+is not reliable if there is more than one method.
+It can select depending on argument count, and it can select between
+primitive Java methods. However, selecting between different Scheme
+procedures based on parameter types should be considered experimental.
+The main problem is we can't determine the most specific
+method, so Kawa just tries the methods in order.
address@hidden quotation
+
address@hidden Procedure make-procedure [keyword: value]... method...
+Create a generic procedure given the specific methods.
+You can also specify property values for the result.
+
+The @var{keyword}s specify how the arguments are used.
+A @code{method:} keyword is optional and specifies that the following
+argument is a method.
+A @code{name:} keyword specifies the name of the resulting procedure,
+when used for printing.
+Unrecognized keywords are used to set the procedure properties of the result.
address@hidden
+(define plus10 (make-procedure foo: 33 name: 'Plus10
+ method: (lambda (x y) (+ x y 10))
+ method: (lambda () 10)))
address@hidden example
address@hidden deffn
+
address@hidden Extended formals
address@hidden Extended Formal Arguments List
+
+The formal arguments list of a lambda expression has some
+extensions over standard Scheme:
+Kawa borrows the extended formal argument list of DSSSL,
+and Kawa allows you to declare the type of the parameter.
+More generally, you can use @ref{Variables and Patterns,patterns}.
+
address@hidden
address@hidden @stxlit{(lambda} @stxref{formals} @address@hidden
@stxref{opt-return-type} @address@hidden)}
address@hidden @stxref{type}
address@hidden address@hidden::} @stxref{type}]
address@hidden display
+where
address@hidden
address@hidden @stxlit{(address@hidden@stxlit{)} | @stxref{rest-arg}
address@hidden display
+You can of course also use the extended format in a
@ref{Definitions,@code{define}}:
address@hidden
address@hidden(define (address@hidden @address@hidden)} address@hidden
@address@hidden)}
address@hidden example
address@hidden
address@hidden
+ @address@hidden address@hidden @stxref{optional-arg} ...]
(@stxref{rest-key-args} | @stxlit{.} @stxref{rest-arg})
address@hidden display
address@hidden
address@hidden @stxref{required-arg} |@stxref{guard}
address@hidden address@hidden @stxref{rest-arg}] address@hidden
@stxref{key-arg} ...]
+ | address@hidden @stxref{key-arg} ...] address@hidden @stxref{rest-arg}]
address@hidden @stxref{pattern} address@hidden::} @stxref{type}]
+ | @stxlit{(} @stxref{pattern} @stxlit{::} @address@hidden)}
address@hidden @var{variable} address@hidden::} @stxref{type}]
+ | @stxlit{(} @stxref{pattern} address@hidden::} @stxref{type}]
address@hidden address@hidden@stxlit{)}
address@hidden @var{variable}
address@hidden @var{variable} address@hidden::} @stxref{type}]
+ | @stxlit{(} @var{variable} address@hidden::} @stxref{type}]
address@hidden address@hidden @stxlit{)}
address@hidden @var{variable}
address@hidden display
+
+When the procedure is applied to a list of actual arguments, the formal and
+actual arguments are processed from left to right as follows:
+
address@hidden
address@hidden
+The @var{required-arg}s are matched against actual (pre-keyword) arguments
+in order, starting with the first actual argument.
+A @var{guard} is evaluated when it appears:
+If it evaluates to false, then matching fails.
+It shall be an error if there are fewer pre-keyword
+arguments then there are @var{req-arg}s.
address@hidden
+Next the @var{optional-arg}s are bound to remaining pre-keyword arguments.
+If there are fewer remaining pre-keyword arguments than there are
address@hidden, then the remaining @var{variable}s are bound
+to the corresponding @var{initializer}.
+If no @var{initializer} was specified, it defaults to @code{#f}.
+(TODO: If a @var{type} is specified the default for @var{initializer}
+is the default value of the @var{type}.)
+The @var{initializer} is evaluated in an
+environment in which all the previous formal parameters have been bound.
+If a @var{supplied-var} is specified, it has type boolean,
+and is set to true if there was an actual corresponding argument,
+and false if the initializer was evaluated.
address@hidden
+If there is a @var{rest-arg}, it is bound to a list of all the
+remaining actual arguments. These remaining actual arguments are also
+eligible to be bound to keyword arguments. If there is no
address@hidden and there are no @var{key-arg}s, then it shall
+be an error if there are any remaining actual arguments.
address@hidden
+If @code{#!key} was specified, then there shall be an even number of
+remaining actual arguments. These are interpreted as a series of pairs,
+where the first member of each pair is a keyword specifying the argument name,
+and the second is the corresponding value. It shall be an error if the first
+member of a pair is not a keyword. It shall be an error if the argument name
+is not the same as a variable in a @var{key-arg}s, unless there
+is a @var{rest-arg}. If the same argument name occurs more than once
+in the list of actual arguments, then the first value is used.
+If there is no actual argument for a particular @var{key-arg},
+then the variable is bound
+to the corresponding @var{initializer}, if one was specified, and
+otherwise to @code{#f}. The @var{initializer} is evaluated in an
+environment in which all the previous formal parameters have been bound.
address@hidden itemize
+
+If a @var{type} is specified, the corresponding actual argument (or
+the @var{initializer} default value) is coerced to the specified @var{type}.
+In the function body, the parameter has the specified type.
+
+If @var{rtype} (the first form of the function body) is an unbound
+identifier of the form @code{<TYPE>} (that is the first character
+is @samp{<} and the last is @samp{>}), then that specifies the
+function's return type. It is syntactic sugar for
address@hidden(as <TYPE> (begin BODY))}.
+
+You can set the @ref{Procedure properties,properties}
+of the resulting procedure using an @var{option-pair}. For example,
+to set the @code{setter} property of a procedure
+to @code{my-set-car} do the following:
address@hidden
+(define my-car
+ (lambda (arg) setter: my-set-car (primitive-car arg)))
address@hidden example
+
address@hidden Partial application
address@hidden Partial application
+
address@hidden Syntax cut slot-or-expr slot-or-expr* address@hidden<...>}]
+where each @var{slot-or-expr} is either an @var{expression} or
+the literal symbol @code{<>}.
+
+It is frequently necessary to specialize some of the parameters of a
+multi-parameter procedure. For example, from the binary operation @code{cons}
+one might want to obtain the unary operation
address@hidden(lambda (x) (cons 1 x))}.
+This specialization of parameters is also known
+as @dfn{partial application}, @dfn{operator section}, or @dfn{projection}.
+The macro @code{cut} specializes some of the parameters of its first
+argument. The parameters that are to show up as formal variables of the
+result are indicated by the symbol @code{<>}, pronouced as "slot".
+In addition, the symbol @code{<...>}, pronounced as "rest-slot", matches all
+residual arguments of a variable argument procedure.
+
+A @code{cut}-expression is transformed into
+a @var{lambda expression} with as many formal variables as there are
+slots in the list @var{slot-or-expr}*.
+The body of the resulting @var{lambda expression} calls
+the first @var{slot-or-expr} with arguments from the @var{slot-or-expr}* list
+in the order they appear. In case there is a rest-slot symbol, the resulting
+procedure is also of variable arity, and the body calls the first
address@hidden with remaining arguments provided to the actual call of the
+specialized procedure.
+
+Here are some examples:
+
address@hidden(cut cons (+ a 1) <>)} is the same as @address@hidden(lambda (x2)
(cons (+ a 1) x2))}}
+
address@hidden(cut list 1 <> 3 <> 5)} is the same as @address@hidden(lambda (x2
x4) (list 1 x2 3 x4 5))}}
+
address@hidden(cut list)} is the same as @address@hidden(lambda () (list))}}
+
address@hidden(cut list 1 <> 3 <...>)} is the same as @address@hidden(lambda
(x2 . xs) (apply list 1 x2 3 xs))}}
+
+The first argument can also be a slot, as one should expect in Scheme:
address@hidden(cut <> a b)} is the same as @address@hidden(lambda (f) (f a b))}}
address@hidden deffn
+
address@hidden Syntax cute slot-or-expr slot-or-expr* address@hidden<...>}]
+The macro @code{cute} (a mnemonic for "cut with evaluated non-slots") is
+similar to @code{cut}, but it evaluates the non-slot expressions at the
+time the procedure is specialized, not at the time the specialized
+procedure is called.
+
+For example
address@hidden(cute cons (+ a 1) <>)} is the same as
address@hidden@code{(let ((a1 (+ a 1))) (lambda (x2) (cons a1 x2)))}}
+
+As you see from comparing this example with the first example above, the
address@hidden will evaluate @code{(+ a 1)} once,
+while the @code{cut}-variant will
+evaluate it during every invocation of the resulting procedure.
+
address@hidden deffn
+
address@hidden Numbers, Characters and text, Procedures, Top
address@hidden Quantities and Numbers
+
+Kawa supports the full Scheme set of number operations with some extensions.
+
+Kawa converts between Scheme number types
+and Java number types as appropriate.
+
address@hidden
+* Numerical types::
+* Arithmetic operations::
+* Numerical input and output::
+* Quaternions::
+* Quantities::
+* Logical Number Operations::
+* Performance of numeric operations::
address@hidden menu
+
address@hidden Numerical types
address@hidden Numerical types
+
+Mathematically, numbers are arranged into a tower of subtypes
+in which each level is a subset of the level before it:
+number; complex number; real number; rational number; integer.
+
+For example, @code{3} is an integer. Therefore @code{3} is also a rational,
+a real, and a complex number. The same is true of the
+Scheme numbers that model 3. For Scheme numbers, these
+types are defined by the predicates @code{number?}, @code{complex?},
address@hidden, @code{rational?}, and @code{integer?}.
+
+There is no simple relationship between a number’s type
+and its representation inside a computer. Although most
+implementations of Scheme will offer at least two different
+representations of 3, these different representations denote
+the same integer.
+
+Scheme’s numerical operations treat numbers as abstract
+data, as independent of their representation as possible.
+Although an implementation of Scheme may use multiple
+internal representations of numbers, this ought not to be
+apparent to a casual programmer writing simple programs.
+
address@hidden Type number
+The type of Scheme numbers.
address@hidden deffn
+
address@hidden Type quantity
+The type of quantities optionally with units.
+This is a sub-type of @code{number}.
address@hidden deffn
+
address@hidden Type complex
+The type of complex numbers.
+This is a sub-type of @code{quantity}.
address@hidden deffn
+
address@hidden Type real
+The type of real numbers.
+This is a sub-type of @code{complex}.
address@hidden deffn
+
address@hidden Type rational
+The type of exact rational numbers.
+This is a sub-type of @code{real}.
address@hidden deffn
+
address@hidden Type integer
+The type of exact Scheme integers.
+This is a sub-type of @code{rational}.
address@hidden deffn
+
+Kawa allows working with expressions of ``primitive'' types,
+which are supported by the JVM without object allocation,
+and using builtin arithmetic. Using these types may be much
+faster, assuming the compiler is able to infer
+that the variable or expression has primitive type.
+
address@hidden Type long
address@hidden Type int
address@hidden Type short
address@hidden Type byte
+These are fixed-sized primitive signed exact integer types,
+of respectively 64, 32, 18, and 8 bits.
+If a value of one of these types needs to be converted to an
+object, the standard classes @code{java.lang.Long}, @code{java.lang.Integer},
address@hidden, or @code{java.lang.Byte}, respectively, are used.
address@hidden deffn
+
address@hidden Type ulong
address@hidden Type uint
address@hidden Type ushort
address@hidden Type ubyte
+These are fixed-sized primitive unsigned exact integer types,
+of respectively 64, 32, 18, and 8 bits.
+These are presented at runtime using the corresponding
+signed types (@code{long}, @code{int}, @code{short}, or @code{byte}).
+However, for arithmetic the Kawa compiler generates code to perform the
+``mathematically correct'' result, truncated to an unsigned result
+rather than signed.
+If a value of one of these types needs to be converted to an
+object, the classes @code{gnu.math.ULong}, @code{gnu.math.UInt},
address@hidden, or @code{gnu.math.UByte} is used.
address@hidden deffn
+
address@hidden Type double
address@hidden Type float
+These are fixed-size primitive inexact floating-point real types,
+using the standard 64-bit or 32-bit IEEE representation.
+If a value of one of these types needs to be converted to an
+object, the standard classes @code{java.lang.Double},
+or @code{java.lang.Float} is used.
address@hidden deffn
+
address@hidden Exactness
address@hidden exactness
+It is useful to distinguish between numbers that are represented
+exactly and those that might not be. For example,
+indexes into data structures must be known exactly, as
+must some polynomial coefficients in a symbolic algebra
+system. On the other hand, the results of measurements
+are inherently inexact, and irrational numbers may be approximated
+by rational and therefore inexact approximations.
+In order to catch uses of inexact numbers where exact numbers
+are required, Scheme explicitly distinguishes
+exact from inexact numbers. This distinction is orthogonal
+to the dimension of type.
+
address@hidden exact complex number
address@hidden inexact complex number
+A Scheme number is @dfn{exact} if it was written as an exact
+constant or was derived from exact numbers using only exact operations.
+A number is @dfn{inexact} if it was written as
+an inexact constant, if it was derived using inexact ingredients,
+or if it was derived using inexact operations. Thus
+inexactness is a contagious property of a number.
+In particular, an @dfn{exact complex number} has an exact real part
+and an exact imaginary part; all other complex numbers
+are @dfn{inexact complex numbers}.
+
+If two implementations produce exact results for a computation
+that did not involve inexact intermediate results, the
+two ultimate results will be mathematically equal. This
+is generally not true of computations involving inexact
+numbers since approximate methods such as floating-point
+arithmetic may be used, but it is the duty of the implementation
+to make the result as close as practical to the
+mathematically ideal result.
+
+Rational operations such as @code{+} should always produce exact
+results when given exact arguments. If the operation
+is unable to produce an exact result, then it may either
+report the violation of an implementation restriction or it
+may silently coerce its result to an inexact value.
+
+Except for @code{exact}, the operations described in this section
+must generally return inexact results when given any inexact arguments.
+An operation may, however, return an
+exact result if it can prove that the value of the result is
+unaffected by the inexactness of its arguments. For example,
+multiplication of any number by an exact zero may
+produce an exact zero result, even if the other argument is inexact.
+
+Specifically, the expression @code{(* 0 +inf.0)} may return @code{0},
+or @code{+nan.0}, or report that inexact numbers are not supported,
+or report that non-rational real numbers are not supported,
+or fail silently or noisily in other implementation-specific ways.
+
+The procedures listed below will always return exact integer
+results provided all their arguments are exact integers
+and the mathematically expected results are representable
+as exact integers within the implementation:
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden/},
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden/},
address@hidden,
address@hidden
+
address@hidden Numerical promotion and conversion
+
+When combining two values of different numeric types,
+the values are converted to the first line in the following
+that subsumes (follows) both types. The computation is done using
+values of that type, and so is the result.
+For example adding a @code{long} and a @code{float} converts the former
+to the latter, yielding a @code{float}.
+
+Note that @code{short}, @code{byte}, @code{ushort}, @code{ubyte}
+are converted to @code{int} regardless, even in the case of
+a single-operand operation, such as unary negation.
+Another exception is trancendental functions (such as @code{cos}),
+where integer operands are converted to @code{double}.
+
address@hidden
address@hidden
address@hidden subsumes @code{short}, @code{byte}, @code{ushort}, @code{ubyte}.
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden (i.e. @code{gnu.math.IntNum})
address@hidden
address@hidden (i.e. @code{gnu.math.RatNum})
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden (i.e. @code{gnu.math.RealNum})
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden itemize
+
+When comparing a primitive signed integer value with a primitive unsigned
+integer (for example @code{<} applied to a @code{int} and a @code{ulong})
+the mathemically correct result is computed, as it converting both
+operands to @code{integer}.
+
address@hidden Arithmetic operations
address@hidden Arithmetic operations
+
address@hidden Procedure {real-valued?} @var{obj}
address@hidden Procedure {rational-valued?} @var{obj}
address@hidden Procedure {integer-valued?} @var{obj}
+These numerical type predicates can be applied to any kind of argument.
+The @func{real-valued?} procedure returns @true{} if the object is a
+number object and is equal in the sense of @code{=} to some real number
+object, or if the object is a NaN, or a complex number object whose real
+part is a NaN and whose imaginary part is zero in the sense of
address@hidden The @func{rational-valued?} and @func{integer-valued?}
+procedures return @true{} if the object is a number object and is equal
+in the sense of @code{=} to some object of the named type, and otherwise
+they return @false{}.
+
address@hidden
+(real-valued? +nan.0) @result{} #t
+(real-valued? +nan.0+0i) @result{} #t
+(real-valued? -inf.0) @result{} #t
+(real-valued? 3) @result{} #t
+(real-valued? -2.5+0.0i) @result{} #t
+
+(real-valued? -2.5+0i) @result{} #t
+(real-valued? -2.5) @result{} #t
+(real-valued? #e1e10) @result{} #t
+
+(rational-valued? +nan.0) @result{} #f
+(rational-valued? -inf.0) @result{} #f
+(rational-valued? 6/10) @result{} #t
+(rational-valued? 6/10+0.0i) @result{} #t
+(rational-valued? 6/10+0i) @result{} #t
+(rational-valued? 6/3) @result{} #t
+
+(integer-valued? 3+0i) @result{} #t
+(integer-valued? 3+0.0i) @result{} #t
+(integer-valued? 3.0) @result{} #t
+(integer-valued? 3.0+0.0i) @result{} #t
+(integer-valued? 8/4) @result{} #t
address@hidden example
+
address@hidden
address@hidden:} These procedures test whether a given number object can be
+coerced to the specified type without loss of numerical accuracy.
+Specifically, the behavior of these predicates differs from the behavior
+of @func{real?}, @func{rational?}, and @func{integer?} on complex number
+objects whose imaginary part is inexact zero.
address@hidden quotation
+
address@hidden
address@hidden:} The behavior of these type predicates on inexact number
+objects is unreliable, because any inaccuracy may affect the result.
address@hidden quotation
address@hidden deffn
+
address@hidden Procedure exact-integer? z
+Returns @code{#t} if @var{z} is both exact and an integer; otherwise
+returns @code{#f}.
address@hidden
+(exact-integer? 32) @result{} #t
+(exact-integer? 32.0) @result{} #t
+(exact-integer? 32/5) @result{} #f
address@hidden example
address@hidden deffn
+
address@hidden Procedure {finite?} @var{z}
+Returns @code{#t} if @var{z} is finite real number
+(i.e. an infinity and not a NaN),
+or if @var{z} is a complex number
+whose real and imaginary parts are both finite.
address@hidden
+(finite? 3) @result{} #t
+(finite? +inf.0) @result{} #f
+(finite? 3.0+inf.0i) @result{} #f
address@hidden example
address@hidden deffn
+
address@hidden Procedure {infinite?} @var{z}
+Return @code{#t} if @var{z} is
+an infinite real number (@code{+int.0} or @code{-inf.0}),
+or if @var{z} is a complex number where either
+real or imaginary parts or both are infinite.
address@hidden
+(infinite? 5.0) @result{} #f
+(infinite? +inf.0) @result{} #t
+(infinite? +nan.0) @result{} #f
+(infinite? 3.0+inf.0i) @result{} #t
address@hidden example
address@hidden deffn
+
address@hidden Procedure {nan?} @var{z}
+For a real numer returns whether its is a NaN;
+for a complex number if the real or imaginary parts or both is a NaN.
address@hidden
+(nan? +nan.0) @result{} #t
+(nan? 32) @result{} #f
+(nan? +nan.0+5.0i) @result{} #t
+(nan? 1+2i) @result{} #f
address@hidden example
address@hidden deffn
+
+
address@hidden Procedure + @var{z} @dots{}
address@hidden Procedure * @var{z} @dots{}
+These procedures return the sum or product of their arguments.
+
address@hidden
+(+ 3 4) @result{} 7
+(+ 3) @result{} 3
+(+) @result{} 0
+(+ +inf.0 +inf.0) @result{} +inf.0
+(+ +inf.0 -inf.0) @result{} +nan.0
+
+(* 4) @result{} 4
+(*) @result{} 1
+(* 5 +inf.0) @result{} +inf.0
+(* -5 +inf.0) @result{} -inf.0
+(* +inf.0 +inf.0) @result{} +inf.0
+(* +inf.0 -inf.0) @result{} -inf.0
+(* 0 +inf.0) @result{} +nan.0
+(* 0 +nan.0) @result{} +nan.0
+(* 1.0 0) @result{} 0.0
address@hidden example
+
+For any real number object @var{x} that is neither infinite nor NaN:
+
address@hidden
+(+ +inf.0 @var{x}) @result{} +inf.0
+(+ -inf.0 @var{x}) @result{} -inf.0
address@hidden example
+
+For any real number object @var{x}:
+
address@hidden
+(+ +nan.0 @var{x}) @result{} +nan.0
address@hidden example
+
+For any real number object @var{x} that is not an exact 0:
+
address@hidden
+(* +nan.0 @var{x}) @result{} +nan.0
address@hidden example
+
address@hidden If any of these procedures are applied to mixed non--rational
real and
address@hidden non--real complex arguments, they either raise an exception with
address@hidden condition type @code{&implementation-restriction} or return an
address@hidden unspecified number object.
+
+The behavior of @code{-0.0} is illustrated by the following examples:
+
address@hidden
+(+ 0.0 -0.0) @result{} 0.0
+(+ -0.0 0.0) @result{} 0.0
+(+ 0.0 0.0) @result{} 0.0
+(+ -0.0 -0.0) @result{} -0.0
address@hidden example
address@hidden deffn
+
address@hidden Procedure - @var{z}
address@hidden Procedure - @vari{z} @varii{z} @variii{z} @dots{}
+With two or more arguments, this procedures returns the difference of
+its arguments, associating to the left. With one argument, however, it
+returns the negation (additive inverse) of its argument.
+
address@hidden
+(- 3 4) @result{} -1
+(- 3 4 5) @result{} -6
+(- 3) @result{} -3
+(- +inf.0 +inf.0) @result{} +nan.0
address@hidden example
+
address@hidden If this procedure is applied to mixed non--rational real and
non--real
address@hidden complex arguments, it either raises an exception with condition
type
address@hidden @code{&implementation-restriction} or returns an unspecified
number
address@hidden object.
+
+The behavior of @code{-0.0} is illustrated by the following examples:
+
address@hidden
+(- 0.0) @result{} -0.0
+(- -0.0) @result{} 0.0
+(- 0.0 -0.0) @result{} 0.0
+(- -0.0 0.0) @result{} -0.0
+(- 0.0 0.0) @result{} 0.0
+(- -0.0 -0.0) @result{} 0.0
address@hidden example
address@hidden deffn
+
address@hidden Procedure / @var{z}
address@hidden Procedure / @vari{z} @varii{z} @variii{z} @dots{}
+If all of the arguments are exact, then the divisors must all be
+nonzero. With two or more arguments, this procedure returns the
+quotient of its arguments, associating to the left. With one argument,
+however, it returns the multiplicative inverse of its argument.
+
address@hidden
+(/ 3 4 5) @result{} 3/20
+(/ 3) @result{} 1/3
+(/ 0.0) @result{} +inf.0
+(/ 1.0 0) @result{} +inf.0
+(/ -1 0.0) @result{} -inf.0
+(/ +inf.0) @result{} 0.0
+(/ 0 0) @result{} exception &assertion
+(/ 3 0) @result{} exception &assertion
+(/ 0 3.5) @result{} 0.0
+(/ 0 0.0) @result{} +nan.0
+(/ 0.0 0) @result{} +nan.0
+(/ 0.0 0.0) @result{} +nan.0
address@hidden example
+
+If this procedure is applied to mixed non--rational real and non--real
+complex arguments, it either raises an exception with condition type
address@hidden&implementation-restriction} or returns an unspecified number
+object.
address@hidden deffn
+
address@hidden Procedure floor/ x y
address@hidden Procedure truncate/ x y
address@hidden Procedure div-and-mod x y
address@hidden Procedure div0-and-mod0 x y
+These procedures implement number--theoretic integer division.
+They accept two real numbers @var{x} and @var{y} as operands,
+where @var{y} must be nonzero.
+In all cases the result is two values @var{q} (an integer) and @var{r} (a real)
+that satisfy the equations:
address@hidden
address@hidden = @var{q} * @var{y} + @var{r}
address@hidden = @var{rounding-op}(@var{x}/@var{y})
address@hidden example
+The result is inexact if either argument is inexact.
+
+For @code{floor/} the @var{rounding-op} is the @code{floor} function (below).
address@hidden
+(floor/ 123 10) @result{} 12 3
+(floor/ 123 -10) @result{} -13 -7
+(floor/ -123 10) @result{} -13 7
+(floor/ -123 -10) @result{} 12 -3
address@hidden example
+
+For @code{truncate/} the @var{rounding-op} is the @code{truncate} function.
address@hidden
+(truncate/ 123 10) @result{} 12 3
+(truncate/ 123 -10) @result{} -12 3
+(truncate/ -123 10) @result{} -12 -3
+(truncate/ -123 -10) @result{} 12 -3
address@hidden example
+
+For @code{div-and-mod} the @var{rounding-op} is either @code{floor}
+(if @var{y} is positive) or @code{ceiling} (if @var{y} is negative).
+We have:
address@hidden
+0 <= @var{r} < |@var{y}|
address@hidden example
address@hidden
+(div-and-mod 123 10) @result{} 12 3
+(div-and-mod 123 -10) @result{} -12 3
+(div-and-mod -123 10) @result{} -13 7
+(div-and-mod -123 -10) @result{} 13 7
address@hidden example
+
+For @code{div0-and-mod0} the @var{rounding-op} is the @code{round} function,
+and @code{r} lies within a half--open interval centered on zero.
address@hidden
+-|@var{y}/2| <= @var{r} < |@var{y}/2|
address@hidden example
+
address@hidden
+(div0-and-mod0 123 10) @result{} 12 3
+(div0-and-mod0 123 -10) @result{} -12 3
+(div0-and-mod0 -123 10) @result{} -12 -3
+(div0-and-mod0 -123 -10) @result{} 12 -3
+(div0-and-mod0 127 10) @result{} 13 -3
+(div0-and-mod0 127 -10) @result{} -13 -3
+(div0-and-mod0 -127 10) @result{} -13 3
+(div0-and-mod0 -127 -10) @result{} 13 3
address@hidden example
+
+The inconsistent naming is for historical reasons: @code{div-and-mod}
+and @code{div0-and-mod0} are from R6RS, while @code{floor/} and
address@hidden/} are from R7RS.
address@hidden deffn
+
address@hidden Procedure floor-quotient x y
address@hidden Procedure truncate-quotient x y
address@hidden Procedure div x y
address@hidden Procedure div0 x y
+These procedures return the quotient part (first value)
+of respectively @code{floor/}, @code{truncate/},
address@hidden, and @code{div0-and-mod0}.
address@hidden deffn
+
address@hidden Procedure floor-remainder x y
address@hidden Procedure truncate-remainder x y
address@hidden Procedure mod x y
address@hidden Procedure mod0 x y
+These procedures return the remainder part (second value)
+of respectively @code{floor/}, @code{truncate/},
address@hidden, and @code{div0-and-mod0}.
+
+As a Kawa extension @var{y} may be zero, in which case the result is @var{x}:
address@hidden
+(mod 123 0) @result{} 123 ;; Kawa extension
address@hidden example
address@hidden deffn
+
address@hidden Procedure quotient x y
address@hidden Procedure remainder x y
address@hidden Procedure modulo x y
+These are equivalent to @code{truncate-quotient},
address@hidden, and @code{floor-remainder}, respectively.
+These are provided for backward compatibility.
address@hidden
+(remainder 13 4) @result{} 1
+(remainder -13 4) @result{} -1
+(remainder 13 -4) @result{} 1
+(remainder -13 -4) @result{} -1
+(remainder -13 -4.0) @result{} -1.0
+(modulo 13 4) @result{} 1
+(modulo -13 4) @result{} 3
+(modulo 13 -4) @result{} -4
+(modulo -13 -4) @result{} -1
address@hidden example
address@hidden deffn
+
address@hidden Procedure abs @var{x}
+Returns the absolute value of its argument.
+
address@hidden
+(abs -7) @result{} 7
+(abs -inf.0) @result{} +inf.0
address@hidden example
address@hidden deffn
+
address@hidden Procedure gcd @vari{n} @dots{}
address@hidden Procedure lcm @vari{n} @dots{}
+These procedures return the greatest common divisor or least common
+multiple of their arguments. The result is always non--negative.
+The arguments must be integers; if an argument is inexact, so is the result.
+
address@hidden
+(gcd 32 -36) @result{} 4
+(gcd) @result{} 0
+(lcm 32 -36) @result{} 288
+(lcm 32.0 -36) @result{} 288.0 ; inexact
+(lcm) @result{} 1
address@hidden example
address@hidden deffn
+
address@hidden Procedure numerator @var{q}
address@hidden Procedure denominator @var{q}
+These procedures return the numerator or denominator of their argument;
+the result is computed as if the argument was represented as a fraction
+in lowest terms. The denominator is always positive. The denominator
+of @code{0} is defined to be @code{1}.
+The arguments must be integers; if an argument is inexact, so is the result.
+
address@hidden
+(numerator (/ 6 4)) @result{} 3
+(denominator (/ 6 4)) @result{} 2
+(denominator (inexact (/ 6 4))) @result{} 2.0
address@hidden example
address@hidden deffn
+
address@hidden Procedure floor @var{x}
address@hidden Procedure ceiling @var{x}
address@hidden Procedure truncate @var{x}
address@hidden Procedure round @var{x}
+These procedures return inexact integer objects for inexact arguments
+that are not infinities or NaNs, and exact integer objects for exact
+rational arguments.
+
address@hidden @code
address@hidden floor
+Returns the largest integer object not larger than @var{x}.
+
address@hidden ceiling
+Returns the smallest integer object not smaller than @var{x}.
address@hidden truncate
+Returns the integer object closest to @var{x} whose absolute value is
+not larger than the absolute value of @var{x}.
+
address@hidden round
+Returns the closest integer object to @var{x}, rounding to even when
address@hidden represents a number halfway between two integers.
address@hidden table
+
+If the argument to one of these procedures is inexact, then the result
+is also inexact. If an exact value is needed, the result should be
+passed to the @func{exact} procedure.
+
+Although infinities and NaNs are not integer objects, these procedures
+return an infinity when given an infinity as an argument, and a NaN when
+given a NaN.
+
address@hidden
+(floor -4.3) @result{} -5.0
+(ceiling -4.3) @result{} -4.0
+(truncate -4.3) @result{} -4.0
+(round -4.3) @result{} -4.0
+
+(floor 3.5) @result{} 3.0
+(ceiling 3.5) @result{} 4.0
+(truncate 3.5) @result{} 3.0
+(round 3.5) @result{} 4.0
+
+(round 7/2) @result{} 4
+(round 7) @result{} 7
+
+(floor +inf.0) @result{} +inf.0
+(ceiling -inf.0) @result{} -inf.0
+(round +nan.0) @result{} +nan.0
address@hidden example
address@hidden deffn
+
address@hidden Procedure rationalize @vari{x} @varii{x}
+The @func{rationalize} procedure returns a number object representing
+the @emph{simplest} rational number differing from @vari{x} by no more
+than @varii{x}.
+
+A rational number @emph{r_1} is @emph{simpler} than another rational
+number @emph{r_2} if @code{r_1 = p_1/q_1} and @code{r_2 = p_2/q_2} (in
+lowest terms) and @code{|p_1| <= |p_2|} and @code{|q_1| <= |q_2|}. Thus
address@hidden/5} is simpler than @code{4/7}.
+
+Although not all rationals are comparable in this ordering (consider
address@hidden/7} and @code{3/5}) any interval contains a rational number that
+is simpler than every other rational number in that interval (the
+simpler @code{2/5} lies between @code{2/7} and @code{3/5}).
+
+Note that @code{0 = 0/1} is the simplest rational of all.
address@hidden
+(rationalize (exact .3) 1/10) @result{} 1/3
+(rationalize .3 1/10) @result{} #i1/3 ; approximately
+
+(rationalize +inf.0 3) @result{} +inf.0
+(rationalize +inf.0 +inf.0) @result{} +nan.0
address@hidden (rationalize 3 +inf.0) @result{} 0.0
address@hidden example
+
+The first two examples hold only in implementations whose inexact real
+number objects have sufficient precision.
address@hidden deffn
+
address@hidden Procedure exp @var{z}
address@hidden Procedure log @var{z}
address@hidden Procedure log @vari{z} @varii{z}
address@hidden Procedure sin @var{z}
address@hidden Procedure cos @var{z}
address@hidden Procedure tan @var{z}
address@hidden Procedure asin @var{z}
address@hidden Procedure acos @var{z}
address@hidden Procedure atan @var{z}
address@hidden Procedure atan @vari{x} @varii{x}
+These procedures compute the usual transcendental functions.
+
+The @func{exp} procedure computes the address@hidden exponential of
address@hidden
+The @func{log} procedure with a single argument computes the natural
+logarithm of @var{z} (@strong{not} the base--10 logarithm); @code{(log
address@hidden @varii{z})} computes the address@hidden logarithm of @vari{z}.
+
+The @func{asin}, @func{acos}, and @func{atan} procedures compute
+arcsine, arccosine, and arctangent, respectively. The two--argument
+variant of @func{atan} computes:
+
address@hidden
+(angle (make-rectangular @varii{x} @vari{x}))
address@hidden example
+
+These procedures may return inexact results even when given exact
+arguments.
address@hidden
+(exp +inf.0) @result{} +inf.0
+(exp -inf.0) @result{} 0.0
+(log +inf.0) @result{} +inf.0
+(log 0.0) @result{} -inf.0
+(log 0) @result{} exception &assertion
+(log -inf.0) @result{} +inf.0+3.141592653589793i ; approximately
+(atan -inf.0) @result{} -1.5707963267948965 ; approximately
+(atan +inf.0) @result{} 1.5707963267948965 ; approximately
+(log -1.0+0.0i) @result{} 0.0+3.141592653589793i ; approximately
+(log -1.0-0.0i) @result{} 0.0-3.141592653589793i ; approximately
+ ; if -0.0 is distinguished
address@hidden example
address@hidden deffn
+
address@hidden Procedure sinh z
address@hidden Procedure cosh z
address@hidden Procedure tanh z
address@hidden Procedure asinh z
address@hidden Procedure acosh z
address@hidden Procedure atanh z
+The hyperbolic functions.
address@hidden deffn
+
address@hidden Procedure square z
+Returns the square of @var{z}.
+This is equivalent to @code{(* @var{z} @var{z})}.
address@hidden
+(square 42) @result{} 1764
+(square 2.0) @result{} 4.0
address@hidden example
address@hidden deffn
+
address@hidden Procedure sqrt @var{z}
+Returns the principal square root of @var{z}. For rational @var{z}, the
+result has either positive real part, or zero real part and
+non--negative imaginary part. The value of @code{(sqrt @var{z})} could be
+expressed as:
+
address@hidden
+e^((log z)/2)
address@hidden example
+
+The @func{sqrt} procedure may return an inexact result even when given
+an exact argument.
+
address@hidden
+(sqrt -5) @result{} 0.0+2.23606797749979i ; approximately
+(sqrt +inf.0) @result{} +inf.0
+(sqrt -inf.0) @result{} +inf.0i
address@hidden example
+
+Note that if the argument is a primitive number (such as @code{double}) or an
+instance of the corresponding boxed class (such as @code{java.lang.Double})
+then we use the real-number version of @code{sqrt}:
address@hidden
+(sqrt (->double -5)) @result{} NaN
address@hidden example
+That is, we get different a result for @code{java.lang.Double}
+and @code{gnu.math.DFloNum}, even for arguments that are numerically equal
+in the sense of @code{=}.
+This is so that the compiler can use the @code{java.lang.Math.sqrt}
+method without object allocation when the argument is a @code{double}
+(and because we want @code{double} and @code{java.lang.Double} to behave
+consistently).
address@hidden deffn
+
address@hidden Procedure exact-integer-sqrt @var{k}
+The @func{exact-integer-sqrt} procedure returns two non--negative exact
+integer objects @emph{s} and @emph{r} where @address@hidden = s^2 + r} and
address@hidden@var{k} < (s+1)^2}.
+
address@hidden
+(exact-integer-sqrt 4) @result{} 2 0 ; two return values
+(exact-integer-sqrt 5) @result{} 2 1 ; two return values
address@hidden example
address@hidden deffn
+
address@hidden Numerical input and output
address@hidden Numerical input and output
+
address@hidden Procedure number->string z [radix]
+
+The procedure @code{number->string} takes a number and a
+radix and returns as a string an external representation
+of the given number in the given radix such that
address@hidden
+(let ((number number)
+ (radix radix))
+ (eqv? number
+ (string->number (number->string number radix)
+ radix)))
address@hidden example
+is true. It is an error if no possible result makes this expression true.
+
+If present, @var{radix} must be an exact integer
+in the range 2 to 36, inclusive.
+If omitted, @var{radix} defaults to 10.
+
+If @var{z} is inexact, the @var{radix} is 10, and the above expression
+can be satisfied by a result that contains a decimal point,
+then the result contains a decimal point and is expressed
+using the minimum number of digits (exclusive of exponent
+and trailing zeroes) needed to make the above expression;
+otherwise the format of the result is unspecified.
+
+The result returned by @code{number->string} never contains an
+explicit radix prefix.
+
address@hidden:}
+The error case can occur only when @var{z} is not a complex
+number or is a complex number with a non-rational real or
+imaginary part.
+
address@hidden:} If @var{z} is an inexact number and the @var{radix} is 10,
+then the above expression is normally satisfied by a result containing
+a decimal point. The unspecified case allows for infinities, NaNs,
+and unusual representations.
+
address@hidden deffn
+
address@hidden Procedure string->number string [radix]
+Returns a number of the maximally precise representation
+expressed by the given @var{string}. It is an error if @var{radix} is not
+an exact integer in the range 2 to 26, inclusive.
+
+If supplied, @var{radix} is a default radix that will be overridden
+ if an explicit radix prefix is present in the string (e.g.
address@hidden"#o177"}). If @var{radix} is not supplied, then the default
@var{radix}
+is 10. If @var{string} is not a syntactically valid notation for a
+number, or would result in a number that the implementation cannot represent,
+then @code{string->number} returns @code{#f}.
+An error is never signaled due to the content of @var{string}.
+
address@hidden
+(string->number "100") @result{} 100
+(string->number "100" 16) @result{} 256
+(string->number "1e2") @result{} 100.0
+(string->number "#x100" 10) @result{} 256
address@hidden example
+
address@hidden deffn
+
+
address@hidden Quaternions
address@hidden Quaternions
+
+Kawa extends the Scheme numeric tower to include
address@hidden://en.wikipedia.org/wiki/Quaternion,quaternions} as a proper
+superset of the complex numbers. Quaternions provide a convenient
+notation to represent
address@hidden://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation,rotations
in three-dimensional space},
+and are therefore commonly found in applications such as computer
+graphics, robotics, and spacecraft engineering. The Kawa quaternion API
+is modeled after
address@hidden://www.ccs.neu.edu/home/dorai/squat/squat.html,this} with some
+additions.
+
+A quaternion is a number that can be expressed in the form
address@hidden, where @code{w}, @code{x}, @code{y}, and @code{z} are
+real, and @code{i}, @code{j}, and @code{k} are imaginary units
+satisfying @address@hidden = address@hidden = address@hidden = ijk = -1}. The
magnitude of a
+quaternion is defined to be its Euclidean norm when viewed as a point in
address@hidden@sup{4}}.
+
+The real--part of a quaternion is also called its @samp{scalar}, while
+the i--part, j--part, and k--part taken together are also called its
address@hidden A quaternion with zero j--part and k--part is an
+ordinary complex number. (If the i--part is also zero, then it is a
+real). A quaternion with zero real--part is called a
address@hidden quaternion}.
+
+The reader syntax for number literals has been extended to support both
+rectangular and polar (hyperspherical) notation for quaternions. The
+rectangular notation is as above, i.e. @code{w+xi+yj+zk}. The polar
+notation takes the form @code{r@@t%u&v}, where @code{r} is the
+magnitude, @code{t} is the first angle, and @code{u} and @code{v} are
+two other angles called the ``colatitude'' and ``longitude''.
+
+The rectangular coordinates and polar coordinates are related by the
+equations:
address@hidden
address@hidden = @var{r} * cos @var{t}
address@hidden = @var{r} * sin @var{t} * cos @var{u}
address@hidden = @var{r} * sin @var{t} * sin @var{u} * cos @var{v}
address@hidden = @var{r} * sin @var{t} * sin @var{u} * sin @var{v}
address@hidden example
+With either notation, zero elements may be omitted.
+
address@hidden Procedure make-rectangular @var{w} @var{x}
address@hidden Procedure make-rectangular @var{w} @var{x} @var{y} @var{z}
+These procedures construct quaternions from Cartesian coordinates.
address@hidden deffn
+
address@hidden Procedure make-polar @var{r} @var{t}
address@hidden Procedure make-polar @var{r} @var{t} @var{u} @var{v}
+These procedures construct quaternions from polar coordinates.
address@hidden deffn
+
address@hidden Procedure + @var{q} @dots{}
address@hidden Procedure - @var{q} @dots{}
address@hidden Procedure * @var{q} @dots{}
address@hidden Procedure / @var{q}
address@hidden Procedure / @vari{q} @varii{q} @variii{q} @dots{}
address@hidden Procedure expt @vari{q} @varii{q}
address@hidden Procedure exp @var{q}
address@hidden Procedure log @var{q}
address@hidden Procedure sqrt @var{q}
address@hidden Procedure sin @var{q}
address@hidden Procedure cos @var{q}
address@hidden Procedure tan @var{q}
address@hidden Procedure asin @var{q}
address@hidden Procedure acos @var{q}
address@hidden Procedure atan @var{q}
+All of the arithmetic and transcendental functions defined for complex
+arguments have been extended to support quaternions.
+
+Quaternion multiplication is not commutative, so there are two possible
+interpretations of @code{(/ q1 q2)} which would yield different results:
+either @code{(* q1 (/ q2))}, or @code{(* (/ q2) q1)}. Division in this
+implementation has been defined such that @code{(/ q1 q2 ...)} is
+equivalent to @code{(* q1 (/ q2) ...)}, but it is recommended to
+use reciprocals (unary @code{/}) and multiplication.
address@hidden deffn
+
address@hidden Procedure real-part @var{q}
+Return the real--part of @var{q}.
+
address@hidden
+(real-part 0) @result{} 0
+(real-part -i) @result{} 0
+(real-part 1+2i-3j+4k) @result{} 1
address@hidden example
address@hidden deffn
+
address@hidden Procedure imag-part @var{q}
+Return the i--part of @var{q}.
+
address@hidden
+(imag-part 0) @result{} 0
+(imag-part -i) @result{} -1
+(imag-part 1+2i-3j+4k) @result{} 2
address@hidden example
address@hidden deffn
+
address@hidden Procedure magnitude @var{q}
+Return the Euclidean norm of @var{q}. If @var{q} is @code{a+bi+cj+dk},
+then @code{(magnitude q)} is
address@hidden(sqrt (apply + (map square (list a b c d))))}
address@hidden deffn
+
address@hidden Procedure angle @var{q}
+Return the angle of @var{q}.
address@hidden deffn
+
address@hidden The @code{(kawa quaternions)} module
+
+The following additional functionality is made available by doing one
+of:
address@hidden
+(require 'quaternions) ;; or
+(import (kawa quaternions))
address@hidden example
+
address@hidden Alias quaternion
+An alias for @code{gnu.math.Quaternion}, useful for type declarations.
address@hidden deffn
address@hidden Procedure {quaternion?} @var{x}
+Return @true{} if @var{x} is a quaternion, i.e. an ordinary number, and
address@hidden otherwise.
+
address@hidden
+(quaternion? 0) @result{} #t
+(quaternion? -i) @result{} #t
+(quaternion? 1+2i-3j+4k) @result{} #t
+(quaternion? 10.0m) @result{} #f
+(quaternion? "x") @result{} #f
address@hidden example
address@hidden deffn
+
address@hidden Procedure jmag-part @var{q}
+Return the j--part of @var{q}.
+
address@hidden
+(jmag-part 0) @result{} 0
+(jmag-part -i) @result{} 0
+(jmag-part 1+2i-3j+4k) @result{} -3
address@hidden example
address@hidden deffn
address@hidden Procedure kmag-part @var{q}
+
address@hidden
+(kmag-part 0) @result{} 0
+(kmag-part -i) @result{} 0
+(kmag-part 1+2i-3j+4k) @result{} 4
address@hidden example
address@hidden deffn
+
address@hidden Procedure complex-part @var{q}
+Return the projection of @var{q} into the complex plane:
address@hidden(+ (real-part q) (* +i (imag-part q)))}
+
address@hidden
+(complex-part 0) @result{} 0
+(complex-part -i) @result{} -1i
+(complex-part 1+2i-3j+4k) @result{} 1+2i
address@hidden example
address@hidden deffn
address@hidden Procedure vector-part @var{q}
+Return the vector--part of @var{q}.
+
address@hidden
+(vector-part 0) @result{} 0
+(vector-part -i) @result{} -1i
+(vector-part 1+2i-3j+4k) @result{} +2i-3j+4k
address@hidden example
address@hidden deffn
+
address@hidden Procedure unit-quaternion @var{q}
+Return a quaternion of unit magnitude with the same direction as
address@hidden If @var{q} is zero, return zero. This is like a 4D version of
+a signum function.
+
address@hidden
+(unit-quaternion 0) @result{} 0
+(unit-quaternion -i) @result{} -1i
+(unit-quaternion 1+2i-3j+4k) @result{}
0.18257418583505536+0.3651483716701107i-0.5477225575051661j+0.7302967433402214k
address@hidden example
address@hidden deffn
+
address@hidden Procedure unit-vector @var{q}
+Return the vector--part of @var{q}, scaled to have magnitude 1. If the
+vector--part is zero, then return zero.
+
address@hidden
+(unit-vector 0) @result{} 0
+(unit-vector -i) @result{} -1i
+(unit-vector 1+2i-3j+4k) @result{}
+0.3713906763541037i-0.5570860145311556j+0.7427813527082074k
address@hidden example
address@hidden deffn
+
address@hidden Procedure colatitude @var{q}
+Return the colatitude of @var{q}.
address@hidden deffn
+
address@hidden Procedure longitude @var{q}
+Return the longitude of @var{q}.
address@hidden deffn
+
address@hidden Procedure {vector-quaternion?} @var{obj}
+Return @true{} if @var{obj} is a vector quaternion, i.e. a quaternion
+with zero real--part.
address@hidden deffn
+
address@hidden Procedure make-vector-quaternion @var{x} @var{y} @var{z}
+Construct vector quaternion @code{xi+yj+zk}. This is equivalent to
address@hidden(make-rectangular 0 x y z)}.
address@hidden deffn
+
address@hidden Procedure {vector-quaternion->list} @var{vq}
+Return a newly allocated list of the x, y, and z components of
address@hidden This is equivalent to
address@hidden(list (imag-part vq) (jmag-part vq) (kmag-part vq))}.
address@hidden deffn
+
address@hidden Procedure dot-product @vari{q} @varii{q}
+For two vector quaternions @vari{q} = @code{ai+bj+ck} and @varii{q} =
address@hidden, return @code{ad + be + cf}. This is equal to the
address@hidden dot product for vectors @math{(a,b,c)} and @math{(d,e,f)},
+and is also equal to @code{(- (real-part (* q1 q2)))}. It is an error
+if either @vari{q} or @varii{q} has a non-zero real--part.
address@hidden deffn
+
address@hidden Procedure cross-product @vari{q} @varii{q}
+For two vector quaternions @vari{q} = @code{ai+bj+ck} and @varii{q} =
address@hidden, return the @math{R^3} cross product for vectors
address@hidden(a,b,c)} and @math{(d,e,f)}, which is equal to
address@hidden(vector-part (* q1 q2))}. It is an error
+if either @vari{q} or @varii{q} has a non-zero real--part.
address@hidden deffn
+
address@hidden Procedure conjugate @var{q}
+Return @code{(+ (real-part q) (* -1 (vector-part q)))}.
+
address@hidden
+(conjugate 0) @result{} 0
+(conjugate -i) @result{} +1i
+(conjugate 1+2i-3j+4k) @result{} 1-2i+3j-4k
address@hidden example
address@hidden deffn
+
address@hidden The @code{(kawa rotations)} module
+
+The @code{(kawa rotations)} library provides a set of functions which
+use unit quaternions to represent 3D spatial rotations. To use these
+functions, the library must be imported:
address@hidden
+(import (kawa rotations))
address@hidden example
+
+These functions normalize their quaternion inputs as needed to be of
+length 1.
+
address@hidden Rotation Representation Conversions
+
+Conversions to and from several alternate representations of rotations
+are supported.
+
+The set of unit quaternions provides a double covering of all
+possible 3D rotations: @code{q} and @code{-q} represent the same
+rotation. Most other representations also have multiple numerical
+values which map to the same rotation (for example, the rotation about
address@hidden by @code{angle} is the same as the rotation about
address@hidden by @code{-angle+2pi}). Therefore, these functions do
+not necessarily act as inverses in the sense of @func{equal?}.
+Furthermore, rotations involve trigonometric functions, so there will
+typically be some floating point error: @code{(acos (cos 0.1))} returns
+0.09999999999999945, which is very close to 0.1 but not exact.
+
address@hidden Rotation Matrices
+
address@hidden Procedure {quaternion->rotation-matrix} @var{q}
address@hidden Procedure {rotation-matrix->quaternion} @var{m}
+
+The @func{quaternion->rotation-matrix} procedure returns a 3x3 rotation
+matrix representing the same rotation as @var{q}. The rotation matrix
+is instantiated as a @ref{Arrays,SRFI-25 multi-dimensional array} backed
+by an @ref{Uniform vectors,f64vector}.
+
+The @func{rotation-matrix->quaternion} procedure performs the reverse
+operation, producing an equivalent unit quaternion for the rotation
+matrix (multi-dimensional array) @var{m}.
+
address@hidden
+(rotation-matrix->quaternion (quaternion->rotation-matrix -1)) @result{} 1.0
address@hidden example
address@hidden deffn
+
address@hidden Axis-Angle Representation
+
address@hidden Procedure rotation-axis @var{q}
address@hidden Procedure rotation-angle @var{q}
address@hidden Procedure rotation-axis/angle @var{q}
+
+The @func{rotation-axis} procedure returns the axis of rotation of the
+quaternion @var{q} as a unit-length vector quaternion. If the axis of
+rotation is not well-defined (the angle of rotation is 0), then
address@hidden is arbitrarily chosen as the axis.
+
+The @func{rotation-angle} procedure returns the corresponding angle of
+rotation. Note that this is not the same as the result of the
address@hidden procedure.
+
+The @func{rotation-axis/angle} procedure returns the rotation axis and
+angle as multiple values.
+
address@hidden
+(let* ((q 1/2+1/2i+1/2j+1/2k)
+ (ar (rotation-angle q))
+ (ad (java.lang.Math:toDegrees ar))
+ (exact-ad (exact ad)))
+ (rationalize exact-ad 1/10)) @result{} 120
address@hidden example
address@hidden deffn
+
address@hidden Procedure {make-axis/angle} @var{axis-vec} @var{angle}
address@hidden Procedure {make-axis/angle} @var{axis-x} @var{axis-y}
@var{axis-z} @var{angle}
+
+The @func{make-axis/angle} procedure returns a quaternion representing
+the given axis/angle rotation. The axis is specified as either a single
+vector quaternion argument @var{axis-vec}, or as three reals
address@hidden, @var{axis-y}, and @var{axis-z}.
address@hidden deffn
+
address@hidden Procedure rotx @var{angle}
address@hidden Procedure roty @var{angle}
address@hidden Procedure rotz @var{angle}
+
+The procedures @func{rotx}, @func{roty}, and @func{rotz} return
+quaternions representing rotations about the X-, Y-, and Z-axes.
address@hidden deffn
+
address@hidden Intrinsic Angle Sets
+
+The intrinsic angle sets represent arbitrary rotations as a sequence of
+three rotations about coordinate frame axes attached to the rotating
+body (i.e. the axes rotate with the body).
+
+There are twelve possible angle sets which neatly divide into two groups
+of six. The six with same first and third axes are also known as
+``Euler angles''. The six with different first and third axes are also
+known as ``Tait-Bryan angles''.
+
address@hidden Procedure intrinsic-xyx @var{q}
address@hidden Procedure intrinsic-xzx @var{q}
address@hidden Procedure intrinsic-yxy @var{q}
address@hidden Procedure intrinsic-yzy @var{q}
address@hidden Procedure intrinsic-zxz @var{q}
address@hidden Procedure intrinsic-zyz @var{q}
+
+These functions decompose the rotation represented by @var{q} into Euler
+angles of the given set (XYX, XZX, YXY, YZY, ZXZ, or ZYZ) and returns
+the three angles as multiple values. The middle angle will be in the
+range [0,pi]. If it is on the edges of that range (within 1.0E-12 of 0
+or pi), such that the first and third axes are colinear, then the first
+angle will be set to 0.
+
address@hidden
+(intrinsic-zyz (* (rotz 0.3) (roty 0.8) (rotz -0.6))) @result{}
0.3000000000000001 0.7999999999999999 -0.5999999999999999
address@hidden example
address@hidden deffn
+
address@hidden Alias euler-xyx
address@hidden Alias euler-xzx
address@hidden Alias euler-yxy
address@hidden Alias euler-yzy
address@hidden Alias euler-zxz
address@hidden Alias euler-zyz
+Aliases for the corresponding @code{intrinsic-} procedures.
address@hidden deffn
+
address@hidden Procedure intrinsic-xyz @var{q}
address@hidden Procedure intrinsic-xzy @var{q}
address@hidden Procedure intrinsic-yxz @var{q}
address@hidden Procedure intrinsic-yzx @var{q}
address@hidden Procedure intrinsic-zxy @var{q}
address@hidden Procedure intrinsic-zyx @var{q}
+
+These functions decompose the rotation represented by @var{q} into
+Tait-Bryan angles of the given set (XYZ, XZY, YXZ, YZX, ZXY, or ZYX) and
+returns the three angles as multiple values. The middle angle will be
+in the range [-pi/2,pi/2]. If it is on the edges of that range, such
+that the first and third axes are colinear, then the first angle will be
+set to 0.
address@hidden deffn
+
address@hidden Alias tait-bryan-xyz
address@hidden Alias tait-bryan-xzy
address@hidden Alias tait-bryan-yxz
address@hidden Alias tait-bryan-yzx
address@hidden Alias tait-bryan-zxy
address@hidden Alias tait-bryan-zyx
+Aliases for the corresponding @code{intrinsic-} procedures.
address@hidden deffn
+
address@hidden Procedure make-intrinsic-xyx @var{alpha} @var{beta} @var{gamma}
address@hidden Procedure make-intrinsic-xzx @var{alpha} @var{beta} @var{gamma}
address@hidden Procedure make-intrinsic-yxy @var{alpha} @var{beta} @var{gamma}
address@hidden Procedure make-intrinsic-yzy @var{alpha} @var{beta} @var{gamma}
address@hidden Procedure make-intrinsic-zxz @var{alpha} @var{beta} @var{gamma}
address@hidden Procedure make-intrinsic-zyz @var{alpha} @var{beta} @var{gamma}
+
+These functions return quaternions representing the given Euler angle
+rotations.
address@hidden deffn
+
address@hidden Alias make-euler-xyx
address@hidden Alias make-euler-xzx
address@hidden Alias make-euler-yxy
address@hidden Alias make-euler-yzy
address@hidden Alias make-euler-zxz
address@hidden Alias make-euler-zyz
+Aliases for the corresponding @code{make-intrinsic-} procedures.
+
address@hidden
+(let-values (((a b c) (euler-xyx (make-euler-xyx 1.0 0.0 2.0))))
+ (list a b c)) @result{} (0.0 0.0 3.0)
address@hidden example
address@hidden deffn
+
address@hidden Procedure make-intrinsic-xyz @var{alpha} @var{beta} @var{gamma}
address@hidden Procedure make-intrinsic-xzy @var{alpha} @var{beta} @var{gamma}
address@hidden Procedure make-intrinsic-yxz @var{alpha} @var{beta} @var{gamma}
address@hidden Procedure make-intrinsic-yzx @var{alpha} @var{beta} @var{gamma}
address@hidden Procedure make-intrinsic-zxy @var{alpha} @var{beta} @var{gamma}
address@hidden Procedure make-intrinsic-zyx @var{alpha} @var{beta} @var{gamma}
+
+These functions return quaternions representing the given Tait-Bryan
+angle rotations.
address@hidden deffn
+
address@hidden Alias make-tait-bryan-xyz
address@hidden Alias make-tait-bryan-xzy
address@hidden Alias make-tait-bryan-yxz
address@hidden Alias make-tait-bryan-yzx
address@hidden Alias make-tait-bryan-zxy
address@hidden Alias make-tait-bryan-zyx
+Aliases for the corresponding @code{make-intrinsic-} procedures.
address@hidden deffn
+
address@hidden Extrinsic Angle Sets
+
+The extrinsic angle sets represent arbitrary rotations as a sequence of
+three rotations about fixed-frame axes (i.e. the axes do not rotate with
+the body).
+
+There are twelve possible extrinsic angle sets, and each is the dual of
+an intrinsic set. The extrinsic rotation about axes @code{A}, @code{B},
+and @code{C} by angles @code{a}, @code{b}, and @code{c} is the same as
+the intrinsic rotation about axes @code{C}, @code{B}, and @code{A} by
+angles @code{c}, @code{b}, and @code{a}, with the order of the three
+axes reversed.
+
address@hidden Procedure extrinsic-xyx @var{q}
address@hidden Procedure extrinsic-xyz @var{q}
address@hidden Procedure extrinsic-xzx @var{q}
address@hidden Procedure extrinsic-zxy @var{q}
address@hidden Procedure extrinsic-yxy @var{q}
address@hidden Procedure extrinsic-yxz @var{q}
address@hidden Procedure extrinsic-yzx @var{q}
address@hidden Procedure extrinsic-yzy @var{q}
address@hidden Procedure extrinsic-zxy @var{q}
address@hidden Procedure extrinsic-zxz @var{q}
address@hidden Procedure extrinsic-zyx @var{q}
address@hidden Procedure extrinsic-zyz @var{q}
+
+These functions decompose the rotation represented by @var{q} into
+extrinsic angles of the given set and returns the three angles as
+multiple values.
address@hidden deffn
+
address@hidden Procedure make-extrinsic-xyx @var{gamma} @var{beta} @var{alpha}
address@hidden Procedure make-extrinsic-xyz @var{gamma} @var{beta} @var{alpha}
address@hidden Procedure make-extrinsic-xzx @var{gamma} @var{beta} @var{alpha}
address@hidden Procedure make-extrinsic-xzy @var{gamma} @var{beta} @var{alpha}
address@hidden Procedure make-extrinsic-yxy @var{gamma} @var{beta} @var{alpha}
address@hidden Procedure make-extrinsic-yxz @var{gamma} @var{beta} @var{alpha}
address@hidden Procedure make-extrinsic-yzx @var{gamma} @var{beta} @var{alpha}
address@hidden Procedure make-extrinsic-yzy @var{gamma} @var{beta} @var{alpha}
address@hidden Procedure make-extrinsic-zxy @var{gamma} @var{beta} @var{alpha}
address@hidden Procedure make-extrinsic-zxz @var{gamma} @var{beta} @var{alpha}
address@hidden Procedure make-extrinsic-zyx @var{gamma} @var{beta} @var{alpha}
address@hidden Procedure make-extrinsic-zyz @var{gamma} @var{beta} @var{alpha}
+
+These functions return quaternions representing the given extrinsic
+angle rotations.
address@hidden deffn
+
address@hidden Alias rpy
address@hidden Alias make-rpy
+Aliases for @func{extrinsic-xyz} and @func{make-extrinsic-xyz}.
+
address@hidden
+(let ((r (make-rpy 0.12 -0.23 0.34)))
+ (let-values (((a b c) (tait-bryan-zyx r)))
+ (list a b c))) @result{} (0.3400000000000001 -0.2300000000000001
0.12000000000000002)
address@hidden example
address@hidden deffn
+
address@hidden Rotation Operations
+
address@hidden Procedure rotate-vector @var{rq} @var{vq}
+Applies the rotation represented by quaternion @var{rq} to the vector
+represented by vector quaternion @var{vq}, and returns the rotated
+vector. This is equivalent to @code{(* rq vq (conjugate rq))} for
+normalized @var{rq}.
+
address@hidden
+(rotate-vector +k +2i) @result{} -2i
+(rotate-vector 1/2+1/2i+1/2j+1/2k +i+2j+3k) @result{} +3.0i+1.0j+2.0k
address@hidden example
address@hidden deffn
+
address@hidden Procedure make-rotation-procedure @var{rq}
+A partial application of @func{rotate-vector}. Returns a
+single-argument procedure which will take a vector quaternion argument
+and rotate it by @var{rq}. The returned procedure closes over both
address@hidden and its conjugate, so this will likely be more efficient than
address@hidden at rotating many vectors by the same rotation.
address@hidden deffn
+
address@hidden Quantities
address@hidden Quantities and Units
+
+As a super-class of numbers, Kawa also provides quantities.
+A @dfn{quantity} is a product of a @dfn{unit} and a pure number.
+The number part can be an arbitrary complex number.
+The unit is a product of integer powers of base units,
+such as meter or second.
+
+Quantity literals have the following syntax:
address@hidden
address@hidden @stxref{optional-sign} @stxref{decimal} @stxref{unit-term}
address@hidden @stxref{unit-term}]... address@hidden/} @stxref{unit-term}]
address@hidden @stxref{unit-name} address@hidden @stxref{digit}+]
address@hidden @stxref{letter}+
address@hidden display
+Some examples are @code{10pt} (10 points), @code{5s} (5 seconds),
+and @code{4cm^2} (4 square centimeters).
+
+Note the @var{quantity} syntax is not recognized by the reader.
+Instead these are read as symbols.
+Assuming there is no lexical binding the for the symbol, it will be
+rewritten at compile-time into an expression. For example @code{4cm^2}
+is transformed into:
address@hidden
+(* 4.0 (expt unit:cm 2))
address@hidden example
+
address@hidden Procedure quantity? object
+True iff @var{object} is a quantity. Note that all numbers are
+quantities, but not the other way round.
+Currently, there are no quantities that are not numbers.
+To distinguish a plain unit-less number from a quantity,
+you can use @code{complex?}.
address@hidden deffn
address@hidden FIXME Using @code{complex?} as the test would erroneously
classify
address@hidden @code{1+j} as non-plain. The right test would be
@code{quaternion?},
address@hidden though that requires importing the (kawa quaternions) module.
+
address@hidden Procedure quantity->number q
+Returns the pure number part of the quantity @var{q}, relative to
+primitive (base) units.
+If @var{q} is a number, returns @var{q}.
+If @var{q} is a unit, yields the magitude of @var{q} relative to base units.
address@hidden deffn
+
address@hidden Procedure quantity->unit q
+Returns the unit of the quantity @var{q}.
+If @var{q} is a number, returns the empty unit.
address@hidden deffn
+
address@hidden Procedure make-quantity x unit
+Returns the product of @var{x} (a pure number) and @var{unit}.
+You can specify a string instead of @var{unit}, such as @code{"cm"}
+or @code{"s"} (seconds).
address@hidden deffn
+
address@hidden Syntax define-base-unit unit-name dimension
+Define @var{unit-name} as a base (primitive) unit,
+which is used to measure along the specified @var{dimension}.
address@hidden
+(define-base-unit dollar "Money")
address@hidden example
address@hidden deffn
+
address@hidden Syntax define-unit unit-name expression
+Define @var{unit-name} as a unit (that can be used in literals)
+equal to the quantity @var{expression}.
address@hidden
+(define-unit cent 0.01dollar)
address@hidden example
+The @var{unit-name} is declared in the @code{unit} namespace,
+so the above is equivalent to:
address@hidden
+(define-constant unit:cent (* 0.01 unit:dollar))
address@hidden example
address@hidden deffn
+
address@hidden Angles
+
+The following angle units are dimensionless, with no base unit.
+
+Some procedures treat a unit-less real number as if it were in radians
+(which mathematicians prefer);
+some procedures (such as @code{rotate}) treat a unit-less real number
+as if it were in degrees
+(which is common in Web and other standards).
+
address@hidden Unit rad
+A unit for angles specified in radians.
+A full circle is 2*pi radians.
+Note that @code{(= 1.5 1.5rad)} is true,
+while @code{(eqv? 1.5 1.5rad)} is false.
address@hidden deffn
+
address@hidden Unit deg
+A unit for angles specified in degrees.
+A full circle is 360 degrees.
address@hidden deffn
+
address@hidden Unit grad
+A unit for angles specified in gradians.
+A full circle is 400 gradians.
address@hidden deffn
+
address@hidden Logical Number Operations
address@hidden Logical Number Operations
+
+These functions operate on the 2's complement binary representation
+of an exact integer.
+
address@hidden Procedure bitwise-not i
+Returns the bit-wise logical inverse of the argument.
+More formally, returns the exact integer whose two's
+complement representation is the one's complement of the two's
+complement representation of @var{i}.
address@hidden deffn
+
address@hidden Procedure bitwise-and i ...
address@hidden Procedure bitwise-ior i ...
address@hidden Procedure bitwise-xor i ...
+These procedures return the exact integer that is the bit-wise
+``and'', ``inclusive or'', or ``exclusive or'' of the two's
+complement representations of their arguments.
+If they are passed only one argument, they return that argument.
+If they are passed no arguments, they return the integer
+that acts as identity for the operation: -1, 0, or 0, respectively.
address@hidden deffn
+
address@hidden Procedure bitwise-if i1 i2 i3
+
+Returns the exact integer that is the bit-wise ``if'' of the twos
+complement representations of its arguments, i.e. for each bit, if it
+is 1 in i1, the corresponding bit in i2 becomes the value of the
+corresponding bit in the result, and if it is 0, the corresponding bit
+in i3 becomes the corresponding bit in the value of the result. This
+is equivaent to the following computation:
address@hidden
+(bitwise-ior (bitwise-and i1 i2)
+ (bitwise-and (bitwise-not i1) i3))
address@hidden example
address@hidden deffn
+
address@hidden Procedure bitwise-bit-count i
+If i is non-negative, returns the number of 1 bits in the twos complement
+representation of i. Otherwise it returns the result of the following
+computation:
address@hidden
+(bitwise-not (bitwise-bit-count (bitwise-not i)))
address@hidden example
address@hidden deffn
+
address@hidden Procedure bitwise-length i
+Returns the number of bits needed to represent i if it is positive,
+and the number of bits needed to represent @code{(bitwise-not @var{i})}
+if it is negative, which is the exact integer that is the result of the
+following computation:
address@hidden
+(do ((result 0 (+ result 1))
+ (bits (if (negative? i)
+ (bitwise-not i)
+ ei)
+ (bitwise-arithmetic-shift bits -1)))
+ ((zero? bits)
+ result))
address@hidden example
+This is the number of bits needed to represent @var{i} in an unsigned field.
address@hidden deffn
+
address@hidden Procedure bitwise-first-bit-set i
+Returns the index of the least significant 1 bit in the twos complement
+representation of i. If i is 0, then - 1 is returned.
address@hidden
+(bitwise-first-bit-set 0) @result{} -1
+(bitwise-first-bit-set 1) @result{} 0
+(bitwise-first-bit-set -4) @result{} 2
address@hidden example
address@hidden deffn
+
address@hidden Procedure bitwise-bit-set? i1 i2
+Returns @code{#t} if the i2'th bit (where @var{i2} must be non-negative)
+is 1 in the two's complement representation of @var{i1}, and @code{#f}
+otherwise. This is the result of the following computation:
address@hidden
+(not (zero?
+ (bitwise-and
+ (bitwise-arithmetic-shift-left 1 i2)
+ i1)))
address@hidden example
address@hidden deffn
+
address@hidden Procedure bitwise-copy-bit i bitno replacement-bit
+Returns the result of replacing the @var{bitno}'th bit of @var{i}
+by @var{replacement-bit}, where @var{bitno} must be non-negative,
+and @var{replacement-bit} must be either 0 or 1.
+This is the result of the following computation:
address@hidden
+(let* ((mask (bitwise-arithmetic-shift-left 1 bitno)))
+ (bitwise-if mask
+ (bitwise-arithmetic-shift-left replacement-bit bitno)
+ i))
address@hidden example
address@hidden deffn
+
address@hidden Procedure bitwise-bit-field n start end
+Returns the integer formed from the (unsigned) bit-field
+starting at @var{start} and ending just before @var{end}.
+Same as:
address@hidden
+(let ((mask
+ (bitwise-not
+ (bitwise-arithmetic-shift-left -1 @var{end}))))
+ (bitwise-arithmetic-shift-right
+ (bitwise-and @var{n} mask)
+ @var{start}))
address@hidden example
address@hidden deffn
+
address@hidden Procedure bitwise-copy-bit-field to start end from
+Returns the result of replacing in @var{to} the bits at positions from
@var{start} (inclusive) to @var{end} (exclusive) by the bits in @var{from} from
position 0 (inclusive) to position @var{end} - @var{start} (exclusive).
+Both @var{start} and @var{start} must be non-negative,
+and @var{start} must be less than or equal to @var{start}.
+
+This is the result of the following computation:
address@hidden
+(let* ((mask1
+ (bitwise-arithmetic-shift-left -1 start))
+ (mask2
+ (bitwise-not
+ (bitwise-arithmetic-shift-left -1 end)))
+ (mask (bitwise-and mask1 mask2)))
+ (bitwise-if mask
+ (bitwise-arithmetic-shift-left from
+ start)
+ to))
address@hidden example
address@hidden deffn
+
address@hidden Procedure bitwise-arithmetic-shift i j
+Shifts @var{i} by @var{j}.
+It is a ``left'' shift if @address@hidden>0}, and
+a ``right'' shift if @address@hidden<0}.
+The result is equal to @code{(floor (* @var{i} (expt 2 @var{j})))}.
+
+Examples:
address@hidden
+(bitwise-arithmetic-shift -6 -1) @result{}-3
+(bitwise-arithmetic-shift -5 -1) @result{} -3
+(bitwise-arithmetic-shift -4 -1) @result{} -2
+(bitwise-arithmetic-shift -3 -1) @result{} -2
+(bitwise-arithmetic-shift -2 -1) @result{} -1
+(bitwise-arithmetic-shift -1 -1) @result{} -1
address@hidden example
address@hidden deffn
+
address@hidden Procedure bitwise-arithmetic-shift-left i amount
address@hidden Procedure bitwise-arithmetic-shift-right i amount
+The @var{amount} must be non-negative
+The @code{bitwise-arithmetic-shift-left} procedure returns the same
+result as @code{bitwise-arithmetic-shift},
+and @code{(bitwise-arithmetic-shift-right @var{i} @var{amount})} returns the
+same result as @code{(bitwise-arithmetic-shift @var{i} (- @var{amount}))}.
+
+If @var{i} is a primitive integer type,
+then @var{amount} must be less than the number of bits in the
+promoted type of @var{i} (32 or 64).
+If the type is unsigned, an unsigned (logic) shift is
+done for @code{bitwise-arithmetic-shift-right},
+rather than a signed (arithmetic) shift.
address@hidden deffn
+
address@hidden Procedure bitwise-rotate-bit-field n start end count
+Returns the result of cyclically permuting in @var{n} the bits at positions
+from @var{start} (inclusive) to @var{end} (exclusive) by
address@hidden bits towards the more significant bits,
address@hidden and @var{end} must be non-negative,
+and @var{start} must be less than or equal to @var{end}.
+This is the result of the following computation:
address@hidden
+(let* ((n ei1)
+ (width (- end start)))
+ (if (positive? width)
+ (let* ((count (mod count width))
+ (field0
+ (bitwise-bit-field n start end))
+ (field1 (bitwise-arithmetic-shift-left
+ field0 count))
+ (field2 (bitwise-arithmetic-shift-right
+ field0
+ (- width count)))
+ (field (bitwise-ior field1 field2)))
+ (bitwise-copy-bit-field n start end field))
+ n))
address@hidden example
address@hidden deffn
+
address@hidden Procedure bitwise-reverse-bit-field i start end
+Returns the result obtained from @var{i} by reversing the order of the bits at
positions from @var{start} (inclusive) to @var{end} (exclusive),
+where @var{start} and @var{end} must be non-negative,
+and @var{start} must be less than or equal to @var{end}.
address@hidden
+(bitwise-reverse-bit-field #b1010010 1 4) @result{} 88 ; #b1011000
address@hidden example
address@hidden deffn
+
address@hidden Procedure logop op x y
+Perform one of the 16 bitwise operations of @var{x} and @var{y},
+depending on @var{op}.
address@hidden deffn
+
address@hidden Procedure logtest i j
+Returns true if the arguments have any bits in common.
+Same as @code{(not (zero? (bitwise-and @var{i} @var{j})))},
+but is more efficient.
address@hidden deffn
+
address@hidden SRFI-60 Logical Number Operations
+
+Kawa supports SRFI-60 ``Integers as Bits'' as well, although we
+generally recommend using the R6RS-compatible functions instead when
+possible. Unless noted as being a builtin function, to use these you
+must first @code{(require 'srfi-60)} or @code{(import (srfi :60))}
+(or @code{(import (srfi :60 integer-bits))}).
+
address@hidden Procedure logand i ...
+Equivalent to @code{(bitwise-and @var{i} ...)}. Builtin.
address@hidden deffn
+
address@hidden Procedure logior i ...
+Equivalent to @code{(bitwise-ior @var{i} ...)}. Builtin.
address@hidden deffn
+
address@hidden Procedure logxor i ...
+Equivalent to @code{(bitwise-xor @var{i} ...)}. Builtin.
address@hidden deffn
+
address@hidden Procedure lognot i
+Equivalent to @code{(bitwise-not @var{i})}. Builtin.
address@hidden deffn
+
address@hidden Procedure bitwise-merge mask i j
+Equivalent to @code{(bitwise-if @var{mask} @var{i} @var{j})}.
address@hidden deffn
+
address@hidden Procedure any-bits-set? i j
+Equivalent to @code{(logtest @var{i} @var{j})}.
address@hidden deffn
+
address@hidden Procedure logcount i
address@hidden Procedure bit-count i
+Count the number of 1-bits in @var{i}, if it is non-negative.
+If @var{i} is negative, count number of 0-bits.
+Same as @code{(bitwise-bit-count @var{i})} if @var{i} is non-negative.
+Builtin as @func{logcount}.
address@hidden deffn
+
address@hidden Procedure integer-length i
+Equivalent to @code{(bitwise-length @var{i})}. Builtin.
address@hidden deffn
+
address@hidden Procedure log2-binary-factors i
address@hidden Procedure first-set-bit i
+Equivalent to @code{(bitwise-first-bit-set @var{i})}.
address@hidden deffn
+
address@hidden Procedure logbit? pos i
address@hidden Procedure bit-set? pos i
+Equivalent to @code{(bitwise-bit-set? @var{i} @var{pos})}.
address@hidden deffn
+
address@hidden Procedure copy-bit bitno i bool
+Equivalent to @code{(bitwise-copy-bit @var{i} @var{bitno} (if @var{bool} 1
0))}.
address@hidden deffn
+
address@hidden Procedure bit-field n start end
+Equivalent to @code{(bitwise-bit-field @var{n} @var{start} @var{end})}.
address@hidden deffn
+
address@hidden Procedure copy-bit-field to from start end
+Equivalent to @code{(bitwise-copy-bit-field @var{to} @var{start} @var{end}
@var{from})}.
address@hidden deffn
+
address@hidden Procedure arithmetic-shift i j
+Equivalent to @code{(bitwise-arithmetic-shift @var{i} @var{j})}. Builtin.
address@hidden deffn
+
address@hidden Procedure ash i j
+Alias for @code{arithmetic-shift}. Builtin.
address@hidden deffn
+
address@hidden Procedure rotate-bit-field n count start end
+Equivalent to @code{(bitwise-rotate-bit-field @var{n} @var{start} @var{end}
@var{count})}.
address@hidden deffn
+
address@hidden Procedure reverse-bit-field i start end
+Equivalent to @code{(bitwise-reverse-bit-field @var{i} @var{start} @var{end})}.
address@hidden deffn
+
address@hidden Procedure integer->list @var{k} address@hidden
address@hidden Procedure list->integer @var{list}
+The @func{integer->list} procedure returns a list of @var{length}
+booleans corresponding to the bits of the non-negative integer @var{k},
+with @code{#t} for @code{1} and @code{#f} for @code{0}. @var{length}
+defaults to @code{(bitwise-length @var{k})}. The list will be in order
+from MSB to LSB, with the value of @code{(odd? @var{k})} in the last
+car.
+
+The @func{list->integer} procedure returns the integer corresponding to
+the booleans in the list @var{list}.
+The @func{integer->list} and @func{list->integer} procedures are
+inverses so far as @func{equal?} is concerned.
address@hidden deffn
+
address@hidden Procedure booleans->integer bool1 ...
+Returns the integer coded by the @var{bool1} ... arguments.
+Equivalent to @code{(list->integer (list @var{bool1} ...))}.
address@hidden deffn
+
address@hidden Deprecated Logical Number Operations
+
+This older function is still available, but we
+recommend using the R6RS-compatible function.
+
address@hidden Procedure bit-extract n start end
+Equivalent to @code{(bitwise-bit-field @var{n} @var{start} @var{end})}.
address@hidden deffn
+
address@hidden Performance of numeric operations
address@hidden Performance of numeric operations
+
+Kawa can generally do a pretty good job of generating
+efficient code for numeric operations, at least when
+it knows or can figure out the types of the operands.
+
+The basic operations @code{+}, @code{-}, and @code{*}
+are compiled to single-instruction bytecode if both
+operands are @code{int} or @code{long}.
+Likewise, if both operands are floating-point (or
+one is floating-point and the other is rational),
+then single-instruction @code{double} or @code{float}
+instructions are emitted.
+
+A binary operation involving an infinite-precision @code{integer}
+and a fixed-size @code{int} or @code{long} is normally
+evaluated by expanding the latter to @code{integer}
+and using @code{integer} arithmetic. An exception is
+an integer literal whose
+value fits in an @code{int} or @code{long} - in that case
+the operation is done using @code{int} or @code{long}
+arithmetic.
+
+In general, integer literals have amorphous type.
+When used to infer the type of a variable, they have @code{integer} type:
address@hidden
+(let ((v1 0))
+ ... v1 has type integer ... )
address@hidden example
+However, a literal whose value fits in the @code{int} or @code{long} range
+is implicitly viewed @code{int} or @code{long} in certain contexts,
+primarily method overload resolution and binary arithmetic
+(as mentioned above).
+
+The comparison functions @code{<}, @code{<=}, @code{=},
address@hidden>}, and @code{=>} are also optimized to single instriction
+operations if the operands have appropriate type.
+However, the functions @code{zero?}, @code{positive?}, and @code{negative?}
+have not yet been optimized.
+Instead of @code{(positive? x)} write @code{(> x 0)}.
+
+There are a number of integer division and modulo operations.
+If the operands are @code{int} or @code{long}, it is faster
+to use @code{quotient} and @code{remainder} rather
+than @code{div} and @code{mod} (or @code{modulo}).
+If you know the first operand is non-negative and the second is positive,
+then use @code{quotient} and @code{remainder}.
+(If an operand is an arbitrary-precision @code{integer},
+then it dosn't really matter.)
+
+The logical operations @code{bitwise-and}, @code{bitwise-ior},
address@hidden, @code{bitwise-not}, @code{bitwise-arithmetic-shift-left},
address@hidden are compiled
+to single bitcode instructions if the operands are @code{int} or @code{long}.
+Avoid @code{bitwise-arithmetic-shift} if the sign of the shift is known.
+If the operands are arbitrary-precision @code{integer},
+a library call is needed, but run-time type dispatch is avoided.
+
address@hidden Characters and text, Data structures, Numbers, Top
address@hidden Characters and text
+
address@hidden
+* Characters::
+* Character sets::
+* Strings::
+* String literals::
+* Unicode:: Unicode character classes and conversions
+* Regular expressions::
address@hidden menu
+
address@hidden Characters
address@hidden Characters
+
+Characters are objects that represent human-readable characters
+such as letters and digits. More precisely, a character
+represents a @uref{http://www.unicode.org/glossary/#unicode_scalar_value,
+Unicode scalar value}. Each character has an integer value
+in the range @code{0} to @code{#x10FFFF}
+(excluding the range @code{#xD800} to @code{#xDFFF}
+used for @uref{http://www.unicode.org/glossary/#surrogate_code_point,
Surrogate Code Points}).
+
address@hidden
address@hidden:}
+Unicode distinguishes
+between glyphs, which are printed for humans to read, and characters,
+which are abstract entities that map to glyphs (sometimes in a way
+that’s sensitive to surrounding characters). Furthermore, different
+sequences of scalar values sometimes correspond to the same
+character. The relationships among scalar, characters, and glyphs are
+subtle and complex.
+
+Despite this complexity, most things that a literate human would call
+a ``character'' can be represented by a single Unicode scalar value
+(although several sequences of Unicode scalar values may represent
+that same character). For example, Roman letters, Cyrillic letters,
+Hebrew consonants, and most Chinese characters fall into this
+category.
+
+Unicode scalar values exclude the range @code{#xD800} to @code{#xDFFF},
+which are part of the range of Unicode @dfn{code points}.
+However, the Unicode code points in this range, the so-called
address@hidden, are an artifact of the UTF-16 encoding, and can only
+appear in specific Unicode encodings, and even then only in pairs that
+encode scalar values. Consequently, all characters represent code
+points, but the surrogate code points do not have representations as
+characters.
address@hidden quotation
+
address@hidden Type character
+A Unicode code point - normally a Unicode scalar value,
+but could be a surrogate.
+This is implemented using a 32-bit @code{int}.
+When an object is needed (i.e. the @dfn{boxed} representation),
+it is implemented an instance of @code{gnu.text.Char}.
address@hidden deffn
+
address@hidden Type character-or-eof
+A @code{character} or the specical @code{#!eof} value (used to indicate
+end-of-file when reading from a port).
+This is implemented using a 32-bit @code{int},
+where the value -1 indicates end-of-file.
+When an object is needed, it is implemented an instance of
address@hidden or the special @code{#!eof} object.
address@hidden deffn
+
address@hidden Type char
+A UTF-16 code unit. Same as Java primitive @code{char} type.
+Considered to be a sub-type of @code{character}.
+When an object is needed, it is implemented as an instance
+of @code{java.lang.Character}. Note the unfortunate inconsistency
+(for historical reasons) of @code{char} boxed as @code{Character}
+vs @code{character} boxed as @code{Char}.
address@hidden deffn
+
+Characters are written using the notation
address@hidden@var{character} (which stands for the given @var{character};
address@hidden@var{hex-scalar-value} (the character whose scalar value
+is the given hex integer);
+or @address@hidden (a character with a given name):
+
address@hidden can't use @stxlit because of slash
address@hidden
address@hidden @address@hidden@var{any-character}
+ | @address@hidden @meta{character-name}
+ | @address@hidden @stxref{hex-scalar-value}
+ | @address@hidden @stxref{hex-scalar-value}
address@hidden display
+
+The following @meta{character-name} forms are recognized:
address@hidden @code
address@hidden @b{#\alarm}
address@hidden - the alarm (bell) character
address@hidden @b{#\backspace}
address@hidden
address@hidden @b{#\delete}
address@hidden @b{#\del}
address@hidden @b{#\rubout}
address@hidden - the delete or rubout character
address@hidden @b{#\escape}
address@hidden @b{#\esc}
address@hidden
address@hidden @b{#\newline}
address@hidden @b{#\linefeed}
address@hidden - the linefeed character
address@hidden @b{#\null}
address@hidden @b{#\nul}
address@hidden - the null character
address@hidden @b{#\page}
address@hidden - the formfeed character
address@hidden @b{#\return}
address@hidden - the carriage return character
address@hidden @b{#\space}
address@hidden - the preferred way to write a space
address@hidden @b{#\tab}
address@hidden - the tab character
address@hidden @b{#\vtab}
address@hidden - the vertical tabulation character
address@hidden @b{#\ignorable-char}
+A special @code{character} value, but it is not a Unicode code point.
+It is a special value returned when an index refers to the second
address@hidden (code point) of a surrogate pair, and which should be ignored.
+(When writing a @code{character} to a string or file,
+it will be written as one or two @code{char} values.
+The exception is @code{#\ignorable-char}, for which zero
address@hidden values are written.)
address@hidden table
+
address@hidden Procedure {char?} @var{obj}
+Return @true{} if @var{obj} is a character, @false{} otherwise.
+(The @var{obj} can be any character, not just a 16-bit @code{char}.)
address@hidden deffn
+
address@hidden Procedure {char->integer} @var{char}
address@hidden Procedure {integer->char} @var{sv}
address@hidden should be a Unicode scalar value, i.e., a non--negative exact
+integer object in @code{[0, #xD7FF] union [#xE000, #x10FFFF]}.
+(Kawa also allows values in the surrogate range.)
+
+Given a character, @func{char->integer} returns its Unicode scalar value
+as an exact integer object. For a Unicode scalar value @var{sv},
address@hidden>char} returns its associated character.
+
address@hidden
+(integer->char 32) @result{} #\space
+(char->integer (integer->char 5000)) @result{} 5000
+(integer->char #\xD800) @result{} throws ClassCastException
address@hidden example
+
address@hidden A call to @code{char->integer} is compiled as
+casting the argument to a @code{character}, and then re-interpreting
+that value as an @code{int}.
+A call to @code{integer->char} is compiled as
+casting the argument to an @code{int}, and then re-interpreting
+that value as an @code{character}.
+If the argument is the right type, no code is emitted: the value is
+just re-interpreted as the result type.
address@hidden deffn
+
address@hidden Procedure {char=?} @vari{char} @varii{char} @variii{char} @dots{}
address@hidden Procedure {char<?} @vari{char} @varii{char} @variii{char} @dots{}
address@hidden Procedure {char>?} @vari{char} @varii{char} @variii{char} @dots{}
address@hidden Procedure {char<=?} @vari{char} @varii{char} @variii{char}
@dots{}
address@hidden Procedure {char>=?} @vari{char} @varii{char} @variii{char}
@dots{}
+These procedures impose a total ordering on the set of characters
+according to their Unicode scalar values.
+
address@hidden
+(char<? #\z #\ß) @result{} #t
+(char<? #\z #\Z) @result{} #f
address@hidden example
+
address@hidden This is compiled as if converting each
+argument using @code{char->integer} (which requires no code)
+and the using the corresponing @code{int} comparison.
address@hidden deffn
+
address@hidden Procedure digit-value char
+This procedure returns the numeric value (0 to 9) of its
+argument if it is a numeric digit (that is, if @code{char-numeric?}
+returns @code{#t}), or @code{#f} on any other character.
+
address@hidden
+(digit-value #\3) @result{} 3
+(digit-value #\x0664) @result{} 4
+(digit-value #\x0AE6) @result{} 0
+(digit-value #\x0EA6) @result{} #f
address@hidden example
+
address@hidden deffn
+
address@hidden Character sets
address@hidden Character sets
+
+Sets of characters are useful for text-processing code,
+including parsing, lexing, and pattern-matching.
address@hidden://srfi.schemers.org/srfi-14/srfi-14.html, SRFI 14} specifies
+a @code{char-set} type for such uses. Some examples:
+
address@hidden
+(import (srfi :14 char-sets))
+(define vowel (char-set #\a #\e #\i #\o #\u))
+(define vowely (char-set-adjoin vowel #\y))
+(char-set-contains? vowel #\y) @result{} #f
+(char-set-contains? vowely #\y) @result{} #t
address@hidden example
+
+See the @uref{http://srfi.schemers.org/srfi-14/srfi-14.html, SRFI 14
specification} for details.
+
address@hidden Type char-set
+The type of character sets.
+In Kawa @code{char-set} is a type that can be used in type specifiers:
address@hidden
+(define vowely ::char-set (char-set-adjoin vowel #\y))
address@hidden example
address@hidden deffn
+
+Kawa uses @uref{https://en.wikipedia.org/wiki/Inversion_list,inversion lists}
for an efficient implementation, using Java @code{int} arrays
+to represents character ranges (inversions).
+The @code{char-set-contains?} function uses binary search,
+so it takes time proportional to the logarithm of the number of inversions.
+Other operations may take time proportional to the number of inversions.
+
address@hidden Strings
address@hidden Strings
+
+Strings are sequences of characters. The @emph{length} of a string is
+the number of characters that it contains, as an exact non-negative integer.
+The @emph{valid indices} of a string are the
+exact non-negative integers less than the length of the string.
+The first character of a
+string has index 0, the second has index 1, and so on.
+
+Strings are @emph{implemented} as a sequence of 16-bit @code{char} values,
+even though they're semantically a sequence of 32-bit Unicode code points.
+A character whose value is greater than @code{#xffff}
+is represented using two surrogate characters.
+The implementation allows for natural interoperability with Java APIs.
+However it does make certain operations (indexing or counting based on
+character counts) difficult to implement efficiently. Luckily one
+rarely needs to index or count based on character counts;
+alternatives are discussed below.
+
address@hidden istring
address@hidden mstring
+There are different kinds of strings:
address@hidden
address@hidden
+An @dfn{istring} is @emph{immutable}:
+It is fixed, and cannot be modified.
+On the other hand, indexing (e.g. @code{string-ref}) is efficient
(constant-time),
+while indexing of other string implementations takes time proportional
+to the index.
+
+String literals are istrings, as are the return values of
+most of the procedures in this chapter.
+
+An @dfn{istring} is an instance of the @code{gnu.lists.IString} class.
+
address@hidden
+An @dfn{mstring} is @emph{mutable}:
+You can replace individual characters (using @code{string-set!}).
+You can also change the @var{mstring}'s length by inserting
+or removing characters (using @code{string-append!} or @code{string-replace!}).
+
+An @dfn{mstring} is an instance of the @code{gnu.lists.FString} class.
+
address@hidden
+Any other object that implements the @code{java.lang.CharSequence} interface
+is also a string.
+This includes standard Java @code{java.lang.String}
+and @code{java.lang.StringBuilder} objects.
address@hidden itemize
+
+Some of the procedures that operate on strings ignore the
+difference between upper and lower case. The names of
+the versions that ignore case end with address@hidden (for “case
+insensitive”).
+
address@hidden
+Many of the following procedures (for example @code{string-append})
+return an immutable istring in Kawa,
+but return a ``freshly allocated'' mutable string in
+standard Scheme (include R7RS) as well as most Scheme implementations
+(including previous versions of Kawa).
+To get the ``compatibility mode'' versions of those procedures
+(which return mstrings),
+invoke Kawa with one the @code{--r5rs}, @code{--r6rs}, or @code{--r7rs}
+options, or you can @code{import} a standard library like @code{(scheme base)}.
+
address@hidden Type string
+The type of string objects.
+The underlying type is the interface @code{java.lang.CharSequence}.
+Immultable strings are @code{gnu.lists.IString} or @code{java.lang.String},
+while mutable strings are @code{gnu.lists.FString}.
address@hidden deffn
+
address@hidden Basic string procedures
+
address@hidden Procedure {string?} @var{obj}
+Return @true{} if @var{obj} is a string, @false{} otherwise.
address@hidden deffn
+
address@hidden Procedure {istring?} @var{obj}
+Return @true{} if @var{obj} is a istring (a immutable, constant-time-indexable
string); @false{} otherwise.
address@hidden deffn
+
address@hidden Constructor string @var{char} @dots{}
+Return a string composed of the arguments.
+This is analogous to @var{list}.
+
address@hidden The result is an istring,
+except in compatibility mode, when it is a new allocated mstring.
address@hidden deffn
+
address@hidden Procedure string-length @var{string}
+Return the number of characters in the given @var{string} as an exact
+integer object.
+
address@hidden If the @var{string} is not an istring,
+the calling @code{string-length} may take time proportional
+to the length of the @var{string},
+because of the need to scan for surrogate pairs.
address@hidden deffn
+
address@hidden Procedure string-ref @var{string} @var{k}
address@hidden must be a valid index of @var{string}. The @func{string-ref}
+procedure returns character @var{k} of @var{string} using zero--origin
+indexing.
+
address@hidden If the @var{string} is not an istring,
+then calling @code{string-ref} may take time proportional
+to @var{k} because of the need to check for surrogate pairs.
+An alternative is to use @code{string-cursor-ref}.
+If iterating through a string, use @code{string-for-each}.
address@hidden deffn
+
address@hidden Procedure string-null? @var{string}
+Is @var{string} the empty string?
+Same result as @code{(= (string-length @var{string}) 0)} but
+executes in O(1) time.
address@hidden deffn
+
address@hidden Procedure string-every pred string [start end])
address@hidden Procedure string-any pred string [start end])
+
+Checks to see if every/any character in @var{string} satisfies @var{pred},
+proceeding from left (index @var{start}) to right (index @var{end}). These
+procedures are short-circuiting: if @var{pred} returns false,
address@hidden does not call @var{pred} on subsequent characters;
+if @var{pred} returns true, @code{string-any} does not call @var{pred}
+on subsequent characters. Both procedures are ``witness-generating'':
address@hidden
address@hidden
+If @code{string-every} is given an empty interval (with @var{start} =
@var{end}),
+it returns @code{#t}.
address@hidden
+If @code{string-every} returns true for a non-empty interval
+(with @var{start} < @var{end}), the returned true value is the one returned by
the final call to the predicate on
address@hidden(string-ref @var{string} (- @var{end} 1))}.
address@hidden
+If @code{string-any} returns true, the returned true value is the one
+returned by the predicate.
address@hidden itemize
+
address@hidden:} The names of these procedures do not end with a question
+mark. This indicates a general value is returned instead of a simple
+boolean (@code{#t} or @code{#f}).
address@hidden deffn
+
address@hidden Immutable String Constructors
+
address@hidden Procedure string-tabulate proc len
+
+Constructs a string of size @var{len} by calling @var{proc} on
+each value from 0 (inclusive) to @var{len} (exclusive) to produce
+the corresponding element of the string.
+The procedure @var{proc} accepts an exact integer as its argument and returns
a character.
+The order in which @var{proc} is called on those indexes is not specifified.
+
address@hidden:} Although @code{string-unfold} is more general,
address@hidden is likely to run faster for the common special
+case it implements.
address@hidden deffn
+
address@hidden Procedure string-unfold stop? mapper successor seed [base
make-final]
address@hidden Procedure string-unfold-right stop? mapper successor seed [base
make-final]
+This is a fundamental and powerful constructor for strings.
address@hidden
address@hidden
address@hidden is used to generate a series of ``seed'' values from the initial
seed:
address@hidden, @code{(address@hidden @address@hidden)},
@code{(address@hidden@sup{2} @address@hidden)}, @code{(address@hidden@sup{3}
@address@hidden)}, ...
address@hidden
address@hidden tells us when to stop — when it returns true when applied to one
of these seed values.
address@hidden
address@hidden maps each seed value to the corresponding character(s) in the
result string, which are assembled into that string in left-to-right order. It
is an error for @var{mapper} to return anything other than a character or
string.
address@hidden
address@hidden is the optional initial/leftmost portion of the constructed
string, which defaults to the empty string @code{""}.
+It is an error if @var{base} is anything other than a character or string.
address@hidden
address@hidden is applied to the terminal seed value (on which @var{stop?}
returns true) to produce the final/rightmost portion of the constructed string.
It defaults to @code{(lambda (x) "")}.
+It is an error for @var{make-final} to return anything other than
+a character or string.
address@hidden itemize
+
address@hidden is the same as @code{string-unfold} except the
+results of @var{mapper} are assembled into the string in right-to-left order,
address@hidden is the optional rightmost portion of the constructed string, and
address@hidden produces the leftmost portion of the constructed string.
+
+You can use it @code{string-unfold} to convert a list to a string,
+read a port into a string, reverse a string, copy a string, and so forth.
+Examples:
address@hidden
+(define (port->string p)
+ (string-unfold eof-object? values
+ (lambda (x) (read-char p))
+ (read-char p)))
+
+(define (list->string lis)
+ (string-unfold null? car cdr lis))
+
+(define (string-tabulate f size)
+ (string-unfold (lambda (i) (= i size)) f add1 0))
address@hidden example
+To map @var{f} over a list @var{lis}, producing a string:
address@hidden
+(string-unfold null? (compose @var{f} car) cdr @var{lis})
address@hidden example
+
+Interested functional programmers may enjoy noting that
@code{string-fold-right}
+and @code{string-unfold} are in some sense inverses.
+That is, given operations @var{knull?}, @var{kar}, @var{kdr},
address@hidden, and @var{knil} satisfying
address@hidden
+(@var{kons} (@var{kar} x) (@var{kdr} x)) = x and (@var{knull?} @var{knil}) =
#t
address@hidden example
+then
address@hidden
+(string-fold-right @var{kons} @var{knil} (string-unfold @var{knull?} @var{kar}
@var{kdr} @var{x})) = @var{x}
address@hidden example
+and
address@hidden
+(string-unfold @var{knull?} @var{kar} @var{kdr} (string-fold-right @var{kons}
@var{knil} @var{string})) = @var{string}.
address@hidden example
+
+This combinator pattern is sometimes called an ``anamorphism.''
+
address@hidden deffn
+
address@hidden Selection
+
address@hidden Procedure substring @var{string} @var{start} @var{end}
address@hidden must be a string, and @var{start} and @var{end} must be
+exact integer objects satisfying:
+
address@hidden
+0 <= @var{start} <= @var{end} <= (string-length @var{string})
address@hidden example
+
+The @func{substring} procedure returns a newly allocated string formed
+from the characters of @var{string} beginning with index @var{start}
+(inclusive) and ending with index @var{end} (exclusive).
address@hidden deffn
+
address@hidden Procedure string-take string nchars
address@hidden Procedure string-drop string nchars
address@hidden Procedure string-take-right string nchars
address@hidden Procedure string-drop-right string nchars
address@hidden returns an immutable string containing the
+first @var{nchars} of @var{string};
address@hidden returns a string containing all but the first @var{nchars}
+of @var{string}.
address@hidden returns a string containing the last @var{nchars}
+of @var{string}; @code{string-drop-right} returns a string containing all
+but the last @var{nchars} of @var{string}.
+
address@hidden
+(string-take "Pete Szilagyi" 6) @result{} "Pete S"
+(string-drop "Pete Szilagyi" 6) @result{} "zilagyi"
+
+(string-take-right "Beta rules" 5) @result{} "rules"
+(string-drop-right "Beta rules" 5) @result{} "Beta "
address@hidden example
+It is an error to take or drop more characters than are in the string:
address@hidden
+(string-take "foo" 37) @result{} @i{error}
address@hidden example
address@hidden deffn
+
address@hidden Procedure string-pad string len [char start end]
address@hidden Procedure string-pad-right string len [char start end]
+Returns an istring of length @var{len} comprised of the characters
+drawn from the given subrange of @var{string},
+padded on the left (right) by as many occurrences of the
+character @var{char} as needed.
+If @var{string} has more than @var{len} chars, it is truncated on the
+left (right) to length @var{len}.
+The @var{char} defaults to @code{#\space}
address@hidden
+(string-pad "325" 5) @result{} " 325"
+(string-pad "71325" 5) @result{} "71325"
+(string-pad "8871325" 5) @result{} "71325"
address@hidden example
address@hidden deffn
+
address@hidden Procedure string-trim string [pred start end]
address@hidden Procedure string-trim-right string [pred start end]
address@hidden Procedure string-trim-both string [pred start end]
+Returns an istring obtained from the given subrange of @var{string}
+by skipping over all characters on the left / on the right / on both sides
that satisfy the second argument @var{pred}:
address@hidden defaults to @code{char-whitespace?}.
address@hidden
+(string-trim-both " The outlook wasn't brilliant, \n\r")
+ @result{} "The outlook wasn't brilliant,"
address@hidden example
address@hidden deffn
+
address@hidden String Comparisons
+
address@hidden Procedure {string=?} @vari{string} @varii{string}
@variii{string} @dots{}
+Return @true{} if the strings are the same length and contain the same
+characters in the same positions. Otherwise, the @func{string=?}
+procedure returns @false{}.
+
address@hidden
+(string=? "Straße" "Strasse") @result{} #f
address@hidden example
address@hidden deffn
+
+
address@hidden Procedure {string<?} @vari{string} @varii{string}
@variii{string} @dots{}
address@hidden Procedure {string>?} @vari{string} @varii{string}
@variii{string} @dots{}
address@hidden Procedure {string<=?} @vari{string} @varii{string}
@variii{string} @dots{}
address@hidden Procedure {string>=?} @vari{string} @varii{string}
@variii{string} @dots{}
+These procedures return @code{#t} if their arguments are (respectively):
+monotonically increasing, monotonically decreasing,
+monotonically non-decreasing, or monotonically nonincreasing.
+These predicates are required to be transitive.
+
+These procedures are the lexicographic extensions to strings of the
+corresponding orderings on characters. For example, @func{string<?} is
+the lexicographic ordering on strings induced by the ordering
address@hidden<?} on characters. If two strings differ in length but are
+the same up to the length of the shorter string, the shorter string is
+considered to be lexicographically less than the longer string.
+
address@hidden
+(string<? "z" "ß") @result{} #t
+(string<? "z" "zz") @result{} #t
+(string<? "z" "Z") @result{} #f
address@hidden example
address@hidden deffn
+
address@hidden Procedure string-ci=? @vari{string} @varii{string}
@variii{string} @dots{}
address@hidden Procedure string-ci<? @vari{string} @varii{string}
@variii{string} @dots{}
address@hidden Procedure string-ci>? @vari{string} @varii{string}
@variii{string} @dots{}
address@hidden Procedure string-ci<=? @vari{string} @varii{string}
@variii{string} @dots{}
address@hidden Procedure string-ci>=? @vari{string} @varii{string}
@variii{string} @dots{}
+These procedures are similar to @func{string=?}, etc.,
+but behave as if they applied @code{string-foldcase} to their arguments
+before invoking the corresponding procedures without @code{-ci}.
+
address@hidden
+(string-ci<? "z" "Z") @result{} #f
+(string-ci=? "z" "Z") @result{} #t
+(string-ci=? "Straße" "Strasse") @result{} #t
+(string-ci=? "Straße" "STRASSE") @result{} #t
+(string-ci=? "ΧΑΟΣ" "χαοσ") @result{} #t
address@hidden example
address@hidden deffn
+
address@hidden Conversions
+
address@hidden Procedure list->string @var{list}
+The @func{list->string} procedure returns an istring
+formed from the characters in @var{list}, in order.
+It is an error if any element of @var{list} is not a character.
+
address@hidden The result is an istring,
+except in compatibility mode, when it is an mstring.
address@hidden deffn
+
address@hidden Procedure reverse-list->string @var{list}
+An efficient implementation of @code{(compose list->text reverse)}:
address@hidden
+(reverse-list->text '(#\a #\B #\c)) @result{} "cBa"
address@hidden example
+This is a common idiom in the epilogue of string-processing loops
+that accumulate their result using a list in reverse order.
+(See also @code{string-concatenate-reverse} for the ``chunked'' variant.)
address@hidden deffn
+
address@hidden Procedure string->list @var{string} address@hidden address@hidden
+The @func{string->list} procedure returns a newly allocated list of the
+characters of @var{string} between @var{start} and @var{end}, in order.
+The @func{string->list} and @func{list->string} procedures are inverses
+so far as @func{equal?} is concerned.
address@hidden deffn
+
address@hidden Procedure vector->string vector [start [end]]
+The @code{vector->string} procedure returns a newly allocated
+string of the objects contained in the elements of @var{vector}
+between @var{start} and @var{end}.
+It is an error if any element of @var{vector} between @var{start}
+and @var{end} is not a character, or is a character forbidden in strings.
address@hidden
+(vector->string #(#\1 #\2 #\3)) @result{} "123"
+(vector->string #(#\1 #\2 #\3 #\4 #\5) 2 4) @result{} "34"
address@hidden example
address@hidden deffn
+
address@hidden Procedure string->vector string [start [end]]
+The @code{string->vector} procedure
+returns a newly created vector initialized to the elements
+of the string @var{string} between @var{start} and @var{end}.
address@hidden
+(string->vector "ABC") @result{} #(#\A #\B #\C)
+(string->vector "ABCDE" 1 3) @result{} #(#\B #\C)
address@hidden example
address@hidden deffn
+
address@hidden Procedure string-upcase @var{string}
address@hidden Procedure string-downcase @var{string}
address@hidden Procedure string-titlecase @var{string}
address@hidden Procedure string-foldcase @var{string}
+These procedures take a string argument and return a string result.
+They are defined in terms of Unicode's locale--independent case mappings
+from Unicode scalar--value sequences to scalar--value sequences. In
+particular, the length of the result string can be different from the
+length of the input string. When the specified result is equal in the
+sense of @func{string=?} to the argument, these procedures may return
+the argument instead of a newly allocated string.
+
+The @func{string-upcase} procedure converts a string to upper case;
address@hidden converts a string to lower case. The
address@hidden procedure converts the string to its case--folded
+counterpart, using the full case--folding mapping, but without the
+special mappings for Turkic languages. The @func{string-titlecase}
+procedure converts the first cased character of each word, and downcases
+all other cased characters.
+
address@hidden
+(string-upcase "Hi") @result{} "HI"
+(string-downcase "Hi") @result{} "hi"
+(string-foldcase "Hi") @result{} "hi"
+
+(string-upcase "Straße") @result{} "STRASSE"
+(string-downcase "Straße") @result{} "straße"
+(string-foldcase "Straße") @result{} "strasse"
+(string-downcase "STRASSE") @result{} "strasse"
+
+(string-downcase "Σ") @result{} "σ"
+; Chi Alpha Omicron Sigma:
+(string-upcase "ΧΑΟΣ") @result{} "ΧΑΟΣ"
+(string-downcase "ΧΑΟΣ") @result{} "χαος"
+(string-downcase "ΧΑΟΣΣ") @result{} "χαοσς"
+(string-downcase "ΧΑΟΣ Σ") @result{} "χαος σ"
+(string-foldcase "ΧΑΟΣΣ") @result{} "χαοσσ"
+(string-upcase "χαος") @result{} "ΧΑΟΣ"
+(string-upcase "χαοσ") @result{} "ΧΑΟΣ"
+
+(string-titlecase "kNock KNoCK") @result{} "Knock Knock"
+(string-titlecase "who's there?") @result{} "Who's There?"
+(string-titlecase "r6rs") @result{} "R6rs"
+(string-titlecase "R6RS") @result{} "R6rs"
address@hidden example
+
+Since these procedures are locale--independent, they may not be
+appropriate for some locales.
+
address@hidden Note:} The implementation of @func{string-titlecase}
+does not correctly handle the case where an initial character
+needs to be converted to multiple characters, such as
+``LATIN SMALL LIGATURE FL'' which should be converted to
+the two letters @code{"Fl"}.
+
address@hidden The result is an istring,
+except in compatibility mode, when it is an mstring.
address@hidden deffn
+
address@hidden Procedure string-normalize-nfd @var{string}
address@hidden Procedure string-normalize-nfkd @var{string}
address@hidden Procedure string-normalize-nfc @var{string}
address@hidden Procedure string-normalize-nfkc @var{string}
+These procedures take a string argument and return a string result,
+which is the input string normalized to Unicode normalization form D,
+KD, C, or KC, respectively. When the specified result is equal in the
+sense of @func{string=?} to the argument, these procedures may return
+the argument instead of a newly allocated string.
+
address@hidden
+(string-normalize-nfd "\xE9;") @result{} "\x65;\x301;"
+(string-normalize-nfc "\xE9;") @result{} "\xE9;"
+(string-normalize-nfd "\x65;\x301;") @result{} "\x65;\x301;"
+(string-normalize-nfc "\x65;\x301;") @result{} "\xE9;"
address@hidden example
address@hidden deffn
+
address@hidden Searching and matching
+
address@hidden Procedure string-prefix-length address@hidden address@hidden
address@hidden address@hidden address@hidden address@hidden
address@hidden Procedure string-suffix-length address@hidden address@hidden
address@hidden address@hidden address@hidden address@hidden
+Return the length of the longest common prefix/suffix of @address@hidden
+and @address@hidden
+For prefixes, this is equivalent to their ``mismatch index''
+(relative to the start indexes).
+
+The optional @var{start}/@var{end} indexes restrict the comparison
+to the indicated substrings of @address@hidden and @address@hidden
address@hidden deffn
+
address@hidden Procedure string-prefix? address@hidden address@hidden
address@hidden address@hidden address@hidden address@hidden
address@hidden Procedure string-suffix? address@hidden address@hidden
address@hidden address@hidden address@hidden address@hidden
+Is @address@hidden a prefix/suffix of @address@hidden
+
+The optional @var{start}/@var{end} indexes restrict the comparison
+to the indicated substrings of @address@hidden and @address@hidden
address@hidden deffn
+
address@hidden Procedure string-index string pred [start end]
address@hidden Procedure string-index-right string pred [start end]
address@hidden Procedure string-skip string pred [start end]
address@hidden Procedure string-skip-right string pred [start end]
+
address@hidden searches through the given substring from the
+left, returning the index of the leftmost character satisfying the
+predicate @var{pred}.
address@hidden searches from the right, returning
+the index of the rightmost character satisfying the predicate @var{pred}.
+If no match is found, these procedures return @code{#f}.
+
+The @var{start} and @var{end} arguments specify the beginning and end
+of the search; the valid indexes relevant to the search include @var{start}
+but exclude @var{end}. Beware of ``fencepost''" errors: when searching
+right-to-left, the first index considered is @code{(- @var{end} 1)},
+whereas when searching left-to-right, the first index considered is
@var{start}.
+That is, the start/end indexes describe the same half-open interval
address@hidden@var{start},@var{end})}
+in these procedures that they do in other string procedures.
+
+The @code{-skip} functions are similar, but use the complement of the
+criterion: they search for the first char that @emph{doesn't} satisfy
address@hidden To skip over initial whitespace, for example, say
+
address@hidden
+(substring string
+ (or (string-skip string char-whitespace?)
+ (string-length string))
+ (string-length string))
address@hidden example
+
+These functions can be trivially composed with @code{string-take} and
address@hidden to produce @code{take-while}, @code{drop-while},
address@hidden, and @code{break} procedures without loss of efficiency.
address@hidden deffn
+
address@hidden SRFI-13 and Guile generalizes pred to char_pred, which can be a
address@hidden predicate, a character, or a character set. That seems
address@hidden convenient.
+
address@hidden Procedure string-contains address@hidden address@hidden
address@hidden address@hidden address@hidden address@hidden
address@hidden Procedure string-contains-right address@hidden address@hidden
address@hidden address@hidden address@hidden address@hidden
+Does the substring of @address@hidden specified by @address@hidden and
@address@hidden contain the sequence of characters given by the substring of
@address@hidden specified by @address@hidden and @address@hidden
+
+Returns @code{#f} if there is no match.
+If @address@hidden = @address@hidden, @code{string-contains}
+returns @address@hidden but @code{string-contains-right}
+returns @address@hidden Otherwise returns the index in @address@hidden for the
first character of the first/last match; that index lies within the half-open
interval address@hidden@sub{1}},@address@hidden), and the match lies entirely
within the address@hidden@sub{1}},@address@hidden) range of @address@hidden
+
address@hidden
+(string-contains "eek -- what a geek." "ee" 12 18) ; Searches "a geek"
+ @result{} 15
address@hidden example
+Note: The names of these procedures do not end with a question mark. This
indicates a useful value is returned when there is a match.
+
+
address@hidden deffn
+
address@hidden Concatenation and replacing
+
address@hidden Procedure string-append @var{string} @dots{}
+Returns a string whose characters form the concatenation
+of the given strings.
+
address@hidden The result is an istring,
+except in compatibility mode, when it is an mstring.
address@hidden deffn
+
address@hidden Procedure string-concatenate string-list
+Concatenates the elements of @var{string-list} together into a single istring.
+
address@hidden:} Some implementations of Scheme limit the number of
+arguments that may be passed to an n-ary procedure, so the
address@hidden(apply string-append @var{string-list})} idiom,
+which is otherwise equivalent to using this procedure, is not as portable.
address@hidden deffn
+
address@hidden Procedure string-concatenate-reverse string-list [final-string
[end]])
+With no optional arguments, calling this procedure is equivalent to
address@hidden(string-concatenate (reverse @var{string-list}))}.
+If the optional argument @var{final-string} is specified,
+it is effectively consed onto the beginning of @var{string-list}
+before performing the list-reverse and string-concatenate operations.
+
+If the optional argument @var{end} is given, only the characters up to but not
including @var{end} in @var{final-string} are added to the result,
+thus producing
address@hidden
+(string-concatenate
+ (reverse (cons (substring final-string 0 end)
+ string-list)))
address@hidden example
+For example:
address@hidden
+(string-concatenate-reverse '(" must be" "Hello, I") " going.XXXX" 7)
+ @result{} "Hello, I must be going."
address@hidden example
+
address@hidden:} This procedure is useful when constructing
+procedures that accumulate character data into lists of string
+buffers, and wish to convert the accumulated data into a single string
+when done. The optional end argument accommodates that use case when
address@hidden is a bob-full mutable string,
+and is allowed (for uniformity) when
address@hidden is an immutable string.
address@hidden deffn
+
address@hidden Procedure string-join string-list [delimiter [grammar]]
+This procedure is a simple unparser; it pastes strings together
+using the @var{delimiter} string, returning an istring.
+
+The @var{string-list} is a list of strings.
+The @var{delimiter} is the string used to delimit elements; it defaults to a
single space @code{" "}.
+
+The @var{grammar} argument is a symbol that determines how the @var{delimiter}
+is used, and defaults to @code{'infix}.
+It is an error for @var{grammar} to be any symbol other than these four:
address@hidden @code
address@hidden 'infix
+An infix or separator grammar: insert the delimiter between list elements. An
empty list will produce an empty string.
address@hidden 'strict-infix
+Means the same as @code{'infix} if the string-list is non-empty,
+but will signal an error if given an empty list.
+(This avoids an ambiguity shown in the examples below.)
address@hidden 'suffix
+Means a suffix or terminator grammar: insert the @var{delimiter}
+after every list element.
address@hidden 'prefix
+Means a prefix grammar: insert the @var{delimiter} before every list element.
address@hidden table
+
address@hidden
+(string-join '("foo" "bar" "baz"))
+ @result{} "foo bar baz"
+(string-join '("foo" "bar" "baz") "")
+ @result{} "foobarbaz"
+(string-join '("foo" "bar" "baz") ":")
+ @result{} "foo:bar:baz"
+(string-join '("foo" "bar" "baz") ":" 'suffix)
+ @result{} "foo:bar:baz:"
+
+;; Infix grammar is ambiguous wrt empty list vs. empty string:
+(string-join '() ":") @result{} ""
+(string-join '("") ":") @result{} ""
+
+;; Suffix and prefix grammars are not:
+(string-join '() ":" 'suffix)) @result{} ""
+(string-join '("") ":" 'suffix)) @result{} ":"
address@hidden example
+
address@hidden deffn
+
address@hidden Procedure string-replace address@hidden address@hidden
address@hidden address@hidden address@hidden address@hidden
+Returns
address@hidden
+(string-append (substring @address@hidden 0 @address@hidden)
+ (substring @address@hidden @address@hidden @address@hidden)
+ (substring @address@hidden @address@hidden (string-length
@address@hidden)))
address@hidden example
+That is, the segment of characters in @address@hidden from @address@hidden
+to @address@hidden is replaced by the segment of characters in @address@hidden
from @address@hidden to @address@hidden
+If @address@hidden@address@hidden, this simply splices the characters
+drawn from @address@hidden into @address@hidden at that position.
+
+Examples:
address@hidden
+(string-replace "The TCL programmer endured daily ridicule."
+ "another miserable perl drone" 4 7 8 22)
+ @result{} "The miserable perl programmer endured daily ridicule."
+
+(string-replace "It's easy to code it up in Scheme." "lots of fun" 5 9)
+ @result{} "It's lots of fun to code it up in Scheme."
+
+(define (string-insert s i t) (string-replace s t i i))
+
+(string-insert "It's easy to code it up in Scheme." 5 "really ")
+ @result{} "It's really easy to code it up in Scheme."
+
+(define (string-set s i c) (string-replace s (string c) i (+ i 1)))
+
+(string-set "String-ref runs in O(n) time." 19 #\1)
+ @result{} "String-ref runs in O(1) time."
address@hidden example
address@hidden deffn
+
+Also see @code{string-append!} and @code{string-replace!}
+for destructive changes to a mutable string.
+
address@hidden Mapping and folding
+
address@hidden Procedure string-fold kons knil string [start end]
address@hidden Procedure string-fold-right kons knil string [start end]
+These are the fundamental iterators for strings.
+
+The @code{string-fold} procedure maps the @var{kons} procedure across
+the given @var{string} from left to right:
address@hidden
+(... (@var{kons} @address@hidden (@var{kons} @address@hidden (@var{kons}
@address@hidden @var{knil}))))
address@hidden example
+In other words, string-fold obeys the (tail) recursion
address@hidden
+ (string-fold @var{kons} @var{knil} @var{string} @var{start} @var{end})
+= (string-fold @var{kons} (@var{kons} @address@hidden @var{knil})
@var{start+1} @var{end})
address@hidden example
+The @code{string-fold-right} procedure maps @var{kons} across the given
+string @var{string} from right to left:
address@hidden
+(@var{kons} @address@hidden
+ (... (@var{kons} @address@hidden@var{end-3}}
+ (@var{kons} @address@hidden@var{end-2}}
+ (@var{kons} @address@hidden@var{end-1}}
+ @var{knil})))))
address@hidden example
+obeying the (tail) recursion
address@hidden
+ (string-fold-right @var{kons} @var{knil} @var{string} @var{start} @var{end})
+= (string-fold-right @var{kons} (@var{kons} @address@hidden@var{end-1}}
@var{knil}) @var{start} @var{end-1})
address@hidden example
+Examples:
address@hidden
+;;; Convert a string or string to a list of chars.
+(string-fold-right cons '() string)
+
+;;; Count the number of lower-case characters in a string or string.
+(string-fold (lambda (c count)
+ (if (char-lower-case? c)
+ (+ count 1)
+ count))
+ 0
+ string)
address@hidden example
+The string-fold-right combinator is sometimes called a "catamorphism."
address@hidden deffn
+
address@hidden Procedure string-for-each @var{proc} @vari{string}
@varii{string} @dots{}
address@hidden Procedure string-for-each @var{proc} @vari{string} [start [end]]
+The @var{string}s must all have the same length. @var{proc} should
+accept as many arguments as there are @var{string}s.
+
+The @address@hidden variant is provided for compatibility
+with the SRFI-13 version. (In that case @var{start} and @var{end}
+count code Unicode scalar values (@code{character} values),
+not Java 16-bit @code{char} values.)
+
+The @func{string-for-each} procedure applies @var{proc} element--wise to
+the characters of the @var{string}s for its side effects, in order from
+the first characters to the last. @var{proc} is always called in the
+same dynamic environment as @func{string-for-each} itself.
address@hidden The return values of @func{string-for-each} are unspecified.
+
+Analogous to @func{for-each}.
+
address@hidden
+(let ((v '()))
+ (string-for-each
+ (lambda (c) (set! v (cons (char->integer c) v)))
+ "abcde")
+ v)
+ @result{} (101 100 99 98 97)
address@hidden example
+
address@hidden The compiler generates efficient code
+for @code{string-for-each}.
+If @var{proc} is a lambda expression, it is inlined.
address@hidden deffn
+
address@hidden Procedure string-map @var{proc} @vari{string} @varii{string}
@dots{}
+The @code{string-map} procedure applies @var{proc} element-wise to
+the elements of the strings and returns a string of the results, in order.
+It is an error if @var{proc} does not accept as many arguments as there
+are strings, or return other than a single character or a string.
+If more than one string is given and not all strings have the same length,
address@hidden terminates when the shortest string runs out.
+The dynamic order in
+which @var{proc} is applied to the elements of the strings is unspecified.
address@hidden If multiple returns occur from string-map, the
address@hidden values returned by earlier returns are not mutated.
+
address@hidden
+(string-map char-foldcase "AbdEgH") @result{} "abdegh"
address@hidden example
address@hidden
+(string-map
+ (lambda (c) (integer->char (+ 1 (char->integer c))))
+ "HAL")
+ @result{} "IBM"
address@hidden example
address@hidden
+(string-map
+ (lambda (c k)
+ ((if (eqv? k #\u) char-upcase char-downcase) c))
+ "studlycaps xxx"
+ "ululululul")
+ @result{} "StUdLyCaPs"
address@hidden example
+
+Traditionally the result of @var{proc} had to be a character,
+but Kawa (and SRFI-140) allows the result to be a string.
+
address@hidden The @code{string-map} procedure has not been
+optimized (mainly because it is not very useful):
+The characters are boxed, and the @var{proc} is not inlined even if
+it is a lambda expression.
address@hidden deffn
+
address@hidden Procedure string-map-index proc string [start end]
+
+Calls @var{proc} on each valid index of the specified substring, converts
+the results of those calls into strings, and returns the concatenation
+of those strings. It is an error for @var{proc} to return anything other
+than a character or string. The dynamic order in which proc is called
+on the indexes is unspecified, as is the dynamic order in which the
+coercions are performed. If any strings returned by @var{proc} are mutated
+after they have been returned and before the call to @code{string-map-index}
+has returned, then @code{string-map-index} returns a string with unspecified
+contents; the @var{string-map-index} procedure itself does not mutate those
+strings.
address@hidden deffn
+
address@hidden Procedure string-for-each-index proc string [start end]
+
+Calls @var{proc} on each valid index of the specified substring, in
+increasing order, discarding the results of those calls. This is
+simply a safe and correct way to loop over a substring.
+
+Example:
address@hidden
+(let ((txt (string->string "abcde"))
+ (v '()))
+ (string-for-each-index
+ (lambda (cur) (set! v (cons (char->integer (string-ref txt cur)) v)))
+ txt)
+ v) @result{} (101 100 99 98 97)
address@hidden example
address@hidden deffn
+
address@hidden Procedure string-count string pred [start end]
+Returns a count of the number of characters in the specified substring
+of @var{string} that satisfy the predicate @var{pred}.
address@hidden deffn
+
address@hidden Procedure string-filter pred string [start end]
address@hidden Procedure string-remove pred string [start end]
+Return an immutable string consisting of only selected characters, in order:
address@hidden selects only the characters that satisfy @var{pred};
address@hidden selects only the characters that @emph{not}
+satisfy @var{pred}
address@hidden deffn
+
address@hidden Replication & splitting
+
address@hidden Procedure string-repeat string-or-character len
+Create an istring by repeating the first argument @var{len} times.
+If the first argument is a character, it is as if it were wrapped with
+the @code{string} constructor.
+We can define string-repeat in terms of the more general @code{xsubstring}
+procedure:
address@hidden
+(define (string-repeat S N)
+ (let ((T (if (char? S) (string S) S)))
+ (xsubstring T 0 (* N (string-length T))))
address@hidden example
address@hidden deffn
+
address@hidden Procedure xsubstring string [from to [start end]]
+This is an extended substring procedure that implements replicated copying of
a substring.
+The @var{string} is a string; @var{start} and @var{end} are optional arguments
that specify a substring of @var{string},
+defaulting to 0 and the length of @var{string}.
+This substring is conceptually replicated both up and down the index space,
+in both the positive and negative directions.
+For example, if @var{string} is @code{"abcdefg"}, @var{start} is 3,
+and @var{end} is 6, then we have the conceptual bidirectionally-infinite string
address@hidden
+ ... d e f d e f d e f d e f d e f d e f d ...
+ -9 -8 -7 -6 -5 -4 -3 -2 -1 0 +1 +2 +3 +4 +5 +6 +7 +8 +9
address@hidden example
address@hidden returns the substring of the @var{string} beginning
+at index @var{from}, and ending at @var{to}.
+It is an error if @var{from} is greater than @var{to}.
+
+If @var{from} and @var{to} are missing they default to 0 and
address@hidden(@address@hidden), respectively.
+This variant is a generalization of using @code{substring},
+but unlike @code{substring} never shares substructures that would
+retain characters or sequences of characters that are substructures of
+its first argument or previously allocated objects.
+
+You can use @code{xsubstring} to perform a variety of tasks:
address@hidden
address@hidden
+To rotate a string left: @code{(xsubstring "abcdef" 2 8) @result{} "cdefab"}
address@hidden
+To rotate a string right: @code{(xsubstring "abcdef" -2 4) @result{} "efabcd"}
address@hidden
+To replicate a string: @code{(xsubstring "abc" 0 7) @result{} "abcabca"}
address@hidden itemize
+
+Note that
address@hidden
address@hidden
+The @var{from}/@var{to} arguments give a half-open range containing the
+characters from index @var{from} up to, but not including, index @var{to}.
address@hidden
+The @var{from}/@var{to} indexes are not expressed in the index space of
address@hidden They refer instead to the replicated index space of the
+substring defined by @var{string}, @var{start}, and @var{end}.
address@hidden itemize
+
+It is an error if @address@hidden, unless @address@hidden,
+which is allowed as a special case.
address@hidden deffn
+
address@hidden Procedure string-split string delimiter [grammar limit start end]
+Returns a list of strings representing the words contained in the substring of
@var{string} from @var{start} (inclusive) to @var{end} (exclusive).
+The @var{delimiter} is a string to be used as the word separator.
+This will often be a single character, but multiple characters are
+allowed for use cases such as splitting on @code{"\r\n"}.
+The returned list will have one more item than the number of non-overlapping
+occurrences of the @var{delimiter} in the string.
+If @var{delimiter} is an empty string, then the returned list contains a
+list of strings, each of which contains a single character.
+
+The @var{grammar} is a symbol with the same meaning as in
+the @code{string-join} procedure.
+If it is @code{infix}, which is the default, processing is done as
+described above, except an empty string produces the empty list;
+if grammar is @code{strict-infix}, then an empty string signals an error.
+The values @code{prefix} and @code{suffix} cause a leading/trailing empty
string in the result to be suppressed.
+
+If @var{limit} is a non-negative exact integer, at most that many splits
occur, and the remainder of string is returned as the final element of the list
(so the result will have at most limit+1 elements). If limit is not specified
or is #f, then as many splits as possible are made. It is an error if limit is
any other value.
+
+To split on a regular expression, you can use SRFI 115's @code{regexp-split}
+procedure.
address@hidden deffn
+
address@hidden String mutation
+
+The following procedures create a mutable string,
+i.e. one that you can modify.
+
address@hidden Procedure make-string address@hidden address@hidden
+Return a newly allocated mstring of @var{k} characters,
+where @var{k} defaults to 0. If @var{char} is
+given, then all elements of the string are initialized to @var{char},
+otherwise the contents of the @var{string} are unspecified.
+
+The 1-argument version is deprecated as poor style, except when k is 0.
+
address@hidden:} In many languags the most common pattern for mutable strings
+is to allocate an empty string and incrementally append to it.
+It seems natural to initialize the string
+with @code{(make-string)}, rather than @code{(make-string 0)}.
+
+To return an immutable string that repeats @var{k} times a character
address@hidden use @code{string-repeat}.
+
+This is as R7RS, except the result is variable-size and we allow
+leaving out @var{k} when it is zero.
+
address@hidden deffn
+
address@hidden Procedure string-copy @var{string} address@hidden address@hidden
+Returns a newly allocated mutable (mstring) copy of the part of the given
address@hidden between @var{start} and @var{end}.
address@hidden deffn
+
+The following procedures modify a mutable string.
+
address@hidden Procedure string-set! string k char
+This procedure stores @var{char} in element @var{k} of @var{string}.
+
address@hidden
+(define s1 (make-string 3 #\*))
+(define s2 "***")
+(string-set! s1 0 #\?) @result{} @emph{void}
+s1 @result{} "?**"
+(string-set! s2 0 #\?) @result{} @emph{error}
+(string-set! (symbol->string 'immutable) 0 #\?) @result{} @emph{error}
address@hidden example
+
address@hidden Calling @code{string-set!} may take time proportional
+to the length of the string: First it must scan for the right position,
+like @code{string-ref} does. Then if the new character requires
+using a surrogate pair (and the old one doesn't) then we have to make room
+in the string, possibly re-allocating a new @code{char} array.
+Alternatively, if the old character requires using a surrogate pair
+(and the new one doesn't) then following characters need to be moved.
+
+The function @code{string-set!} is deprecated: It is inefficient,
+and it very seldom does the correct thing. Instead, you can
+construct a string with @code{string-append!}.
address@hidden deffn
+
address@hidden Procedure string-append! @var{string} @var{value} @dots{}
+The @var{string} must be a mutable string, such as one returned
+by @code{make-string} or @code{string-copy}.
+The @code{string-append!} procedure extends @var{string}
+by appending each @var{value} (in order) to the end of @var{string}.
+Each @code{value} should be a character or a string.
+
address@hidden The compiler converts a call with multiple @var{value}s
+to multiple @code{string-append!} calls.
+If a @var{value} is known to be a @code{character}, then
+no boxing (object-allocation) is needed.
+
+The following example shows how to efficiently process a string
+using @code{string-for-each} and incrementally ``build'' a result string
+using @code{string-append!}.
+
address@hidden
+(define (translate-space-to-newline str::string)::string
+ (let ((result (make-string 0)))
+ (string-for-each
+ (lambda (ch)
+ (string-append! result
+ (if (char=? ch #\Space) #\Newline ch)))
+ str)
+ result))
address@hidden example
address@hidden deffn
+
address@hidden Procedure string-copy! @var{to} @var{at} @var{from}
address@hidden address@hidden
+Copies the characters of the string @var{from} that are between
address@hidden end @var{end} into the string @var{to},
+starting at index @var{at}. The order in which characters are copied
+is unspecified, except that if the source and destination overlap,
+copying takes place as if the source is first copied into a
+temporary string and then into the destination.
+(This is achieved without allocating storage by making sure to copy in
+the correct direction in such circumstances.)
+
+This is equivalent to (and implemented as):
address@hidden
+(string-replace! to at (+ at (- end start)) from start end))
address@hidden example
+
address@hidden
+(define a "12345")
+(define b (string-copy "abcde"))
+(string-copy! b 1 a 0 2)
+b @result{} "a12de"
address@hidden example
address@hidden deffn
+
address@hidden Procedure string-replace! @var{dst} @var{dst-start}
@var{dst-end} @var{src} address@hidden address@hidden
+Replaces the characters of string @var{dst} (between @var{dst-start} and
@var{dst-end}) with the characters of @var{src} (between @var{src-start} and
@var{src-end}).
+The number of characters from @var{src} may be different than the
+number replaced in @var{dst}, so the string may grow or contract.
+The special case where @var{dst-start} is equal to @var{dst-end} corresponds to
+insertion; the case where @var{src-start} is equal to @var{src-end}
+corresponds to deletion.
+The order in which characters are copied
+is unspecified, except that if the source and destination overlap,
+copying takes place as if the source is first copied into a
+temporary string and then into the destination.
+(This is achieved without allocating storage by making sure to copy in
+the correct direction in such circumstances.)
address@hidden deffn
+
address@hidden Procedure string-fill! @var{string} @var{fill} address@hidden
address@hidden
+The @code{string-fill!} procedure stores @var{fill} in the elements
+of @var{string} between @var{start} and @var{end}.
+It is an error if @var{fill} is not a character or is forbidden in strings.
address@hidden deffn
+
address@hidden Strings as sequences
+
address@hidden Indexing a string
+
+Using function-call syntax with strings is convenient
+and efficient. However, it has some ``gotchas''.
+
+We will use the following example string:
address@hidden
+(! str1 "Smile \x1f603;!")
address@hidden example
+or if you're brave:
address@hidden
+(! str1 "Smile 😃!")
address@hidden example
+
+This is @code{"Smile "} followed by an emoticon (``smiling face with
+open mouth'') followed by @code{"!"}.
+The emoticon has scalar value @code{\x1f603} - it is not
+in the 16-bit Basic Multi-language Plane,
+and so it must be encoded by a surrogate pair
+(@code{#\xd83d} followed by @code{#\xde03}).
+
+The number of scalar values (@code{character}s) is 8,
+while the number of 16-bits code units (@code{char}s) is 9.
+The @code{java.lang.CharSequence:length} method
+counts @code{char}s. Both the @code{length} and the
address@hidden procedures count @code{character}s. Thus:
+
address@hidden
+(length str1) @result{} 8
+(string-length str1) @result{} 8
+(str1:length) @result{} 9
address@hidden example
+
+Counting @code{char}s is a constant-time operation (since it
+is stored in the data structure).
+Counting @code{character}s depends on the representation used:
+In geneeral it may take time proportional to the length of
+the string, since it has to subtract one for each surrogate pair;
+however the @var{istring} type (@code{gnu.lists.IString} class)
+uses a extra structure so it can count characters in constant-time.
+
+Similarly we can can index the string in 3 ways:
+
address@hidden
+(str1 1) @result{} #\m :: character
+(string-ref str1 1) @result{} #\m :: character
+(str1:charAt 1) @result{} #\m :: char
address@hidden example
+
+Using function-call syntax when the ``function'' is a string
+and a single integer argument is the same as using @code{string-ref}.
+
+Things become interesting when we reach the emoticon:
+
address@hidden
+(str1 6) @result{} #\😃 :: character
+(str1:charAt 6) @result{} #\d83d :: char
address@hidden example
+
+Both @code{string-ref} and the function-call syntax return the
+real character, while the @code{charAt} methods returns a partial character.
+
address@hidden
+(str1 7) @result{} #\! :: character
+(str1:charAt 7) @result{} #\de03 :: char
+(str1 8) @result{} @i{throws} StringIndexOutOfBoundsException
+(str1:charAt 8) @result{} #\! :: char
address@hidden example
+
address@hidden Indexing with a sequence
+
+You can index a string with a list of integer indexes,
+most commonly a range:
address@hidden
+(@var{str} address@hidden ...])
address@hidden example
+is basically the same as:
address@hidden
+(string (@var{str} @var{i}) ...)
address@hidden example
+
+Generally when working with strings it is best to
+work with substrings rather than individual characters:
address@hidden
+(@var{str} address@hidden <: @var{end}])
address@hidden example
+
+This is equivalent to invoking the @code{substring} procedure:
address@hidden
+(substring @var{str} @var{start} @var{end})
address@hidden example
+
address@hidden not implemented yet
address@hidden @subsubsection Assigning to a subsequence
+
address@hidden Cursor API}
address@hidden String Cursor API
+
+Indexing into a string (using for example @code{string-ref})
+is inefficient because of the possible presence of surrogate pairs.
+Hence given an index @var{i} access normally requires linearly
+scanning the string until we have seen @var{i} characters.
+
+The string-cursor API is defined in terms of abstract ``cursor values'',
+which point to a position in the string. This avoids the linear scan.
+
+Typical usage is:
address@hidden
+(let* ((str @var{whatever})
+ (end (string-cursor-end str)))
+ (do ((sc::string-cursor (string-cursor-start str)
+ (string-cursor-next str sc)))
+ ((string-cursor>=? sc end))
+ (let ((ch (string-cursor-ref str sc)))
+ (@var{do-something-with} ch))))
address@hidden example
+Alternatively, the following may be marginally faster:
address@hidden
+(let* ((str @var{whatever})
+ (end (string-cursor-end str)))
+ (do ((sc::string-cursor (string-cursor-start str)
+ (string-cursor-next-quick sc)))
+ ((string-cursor>=? sc end))
+ (let ((ch (string-cursor-ref str sc)))
+ (if (not (char=? ch #\ignorable-char))
+ (@var{do-something-with} ch)))))
address@hidden example
+
+The API is non-standard, but is based on that in Chibi Scheme.
+
address@hidden Type string-cursor
+An abstract position (index) in a string.
+Implemented as a primitive @code{int} which counts the
+number of preceding code units (16-bit @code{char} values).
address@hidden deffn
+
address@hidden Procedure string-cursor-start str
+Returns a cursor for the start of the string.
+The result is always 0, cast to a @code{string-cursor}.
address@hidden deffn
+
address@hidden Procedure string-cursor-end str
+Returns a cursor for the end of the string - one past the last valid character.
+Implemented as @code{(as string-cursor (invoke @var{str} 'length))}.
address@hidden deffn
+
address@hidden Procedure string-cursor-ref str cursor
+Return the @code{character} at the @var{cursor}.
+If the @var{cursor} points to the second @code{char} of a surrogate pair,
+returns @code{#\ignorable-char}.
address@hidden deffn
+
address@hidden Procedure string-cursor-next string cursor [count]
+Return the cursor position @var{count} (default 1) character
+positions forwards beyond @var{cursor}.
+For each @var{count} this may add either 1 or 2
+(if pointing at a surrogate pair) to the @var{cursor}.
address@hidden deffn
+
address@hidden Procedure string-cursor-next-quiet cursor
+Increment cursor by one raw @code{char} position,
+even if @var{cursor} points to the start of a surrogate pair.
+(In that case the next @code{string-cursor-ref} will
+return @code{#\ignorable-char}.)
+Same as @code{(+ @var{cursor} 1)} but with the @code{string-cursor} type.
address@hidden deffn
+
address@hidden Procedure string-cursor-prev string cursor [count]
+Return the cursor position @var{count} (default 1) character
+positions backwards before @var{cursor}.
address@hidden deffn
+
address@hidden Procedure substring-cursor string [start [end]]
+Create a substring of the section of @var{string}
+between the cursors @var{start} and @var{end}.
address@hidden deffn
+
address@hidden Procedure string-cursor<? cursor1 cursor2
address@hidden Procedure string-cursor<=? cursor1 cursor2
address@hidden Procedure string-cursor=? cursor1 cursor2
address@hidden Procedure string-cursor>=? cursor1 cursor2
address@hidden Procedure string-cursor>? cursor1 cursor2
+Is the position of @var{cursor1} respectively before,
+before or same, same, after, or after or same, as @var{cursor2}.
+
address@hidden Implemented as the corresponding @code{int} comparison.
address@hidden deffn
+
address@hidden non-chibi
address@hidden Procedure string-cursor-for-each proc string [start [end]]
+Apply the procedure @var{proc} to each character position in
address@hidden between the cursors @var{start} and @var{end}.
address@hidden deffn
+
address@hidden String literals
address@hidden String literals
+
+Kaw support two syntaxes of string literals:
+The traditional, portable, qdouble-quoted-delimited literals
+like @code{"this"};
+and extended SRFI-109 quasi-literals like @code{&@address@hidden
+
address@hidden Simple string literals
+
address@hidden
address@hidden @stxlit{"address@hidden@address@hidden"}
address@hidden @i{any character other than} @stxlit{"} @i{or} @address@hidden
+ | @stxref{mnemonic-escape} | @address@hidden"} |
@address@hidden@backslashchar{}}
+ | @address@hidden@address@hidden@stxref{line-ending} @address@hidden
+ | @stxref{inline-hex-escape}
address@hidden @address@hidden | @address@hidden | @address@hidden |
@address@hidden | @address@hidden | ... @i{(see below)}
address@hidden display
+
+A string is written as a sequence of characters enclosed
+within quotation marks (@stxlit{"}).
+Within a string literal, various escape sequence represent characters
+other than themselves.
+Escape sequences always start with a backslash (@address@hidden):
address@hidden @asis
address@hidden @address@hidden
+Alarm (bell), @code{#\x0007}.
address@hidden @address@hidden
+Backspace, @code{#\x0008}.
address@hidden @address@hidden
+Escape, @code{#\x001B}.
address@hidden @address@hidden
+Form feed, @code{#\x000C}.
address@hidden @address@hidden
+Linefeed (newline), @code{#\x000A}.
address@hidden @address@hidden
+Return, @code{#\x000D}.
address@hidden @address@hidden
+Character tabulation, @code{#\x0009}.
address@hidden @address@hidden
+Vertical tab, @code{#\x000B}.
address@hidden @address@hidden@meta{x}
address@hidden @address@hidden@meta{x}
+Returns the scalar value of @meta{x} masked (anded) with @code{#x9F}.
+An alternative way to write the Ascii control characters:
+For example @code{"\C-m"} or @code{"\^m"} is
+the same as @code{"#\x000D"} (which the same as @code{"\r"}).
+As a special case @code{\^?} is rubout (delete) (@code{\x7f;}).
address@hidden @address@hidden @address@hidden;}
address@hidden @address@hidden @address@hidden;}
+A hex encoding that gives the scalar value of a character.
address@hidden @address@hidden@backslashchar{}} @address@hidden
+At most three octal digits that give the scalar value of a character.
+(Historical, for C compatibility.)
address@hidden @address@hidden @address@hidden
+Exactly four hex digits that give the scalar value of a character.
+(Historical, for Java compatibility.)
address@hidden @address@hidden@meta{x}
+(Historical, for Emacs Lisp.)
+Set the meta-bit (high-bit of single byte) of the following character @var{x}.
address@hidden @address@hidden|}
+Vertical line, @code{#\x007c}.
+(Not useful for string literals, but useful for symbols.)
address@hidden @address@hidden"}
+Double quote, @code{#\x0022}.
address@hidden @address@hidden@backslashchar{}}
+Backslah, @code{#\005C}.
address@hidden @address@hidden@address@hidden@stxref{line-ending}
@address@hidden
+Nothing (ignored). Allows you to split up a long string over multiple
+lines; ignoring initial whitespace on the continuation lines allows
+you to indent them.
address@hidden table
+
+Except for a line ending, any character outside of an escape
+sequence stands for itself in the string literal. A line ending
+which is preceded by @address@hidden@address@hidden
+expands to nothing (along with any trailing @meta{intraline-whitespace}),
+and can be used to indent strings for improved legibility.
+Any other line ending has the same effect as inserting a @address@hidden
+character into the string.
+
+Examples:
address@hidden
+"The word \"recursion\" has many meanings."
+"Another example:\ntwo lines of text"
+"Here’s text \
+containing just one line"
+"\x03B1; is named GREEK SMALL LETTER ALPHA."
address@hidden example
+
address@hidden quasi-literals}
address@hidden String templates
+
+The following syntax is a @dfn{string template} (also called
+a string quasi-literal or
address@hidden://en.wikipedia.org/wiki/Here_document, here document}''):
address@hidden
+&@{Hello &address@hidden
address@hidden example
+Assuming the variable @code{name} evaluates to @code{"John"}
+then the example evaluates to @code{"Hello John!"}.
+
+The Kawa reader converts the above example to:
address@hidden
+($string$ "Hello " $<<$ name $>>$ "!")
address@hidden example
+See the @uref{http://srfi.schemers.org/srfi-109/srfi-109.html,SRFI-109}
+specification for details.
+
address@hidden
address@hidden @stxlit{&@lbracechar{}} address@hidden @address@hidden
@address@hidden
address@hidden @i{any character except} @stxlit{&}, @address@hidden @i{or}
@address@hidden
+ | @address@hidden @address@hidden @address@hidden
+ | @stxref{char-ref}
+ | @stxref{entity-ref}
+ | @stxref{special-escape}
+ | @stxref{enclosed-part}
address@hidden display
+
+You can use the plain @code{"@var{string}"} syntax for
+longer multiline strings, but @code{&@address@hidden@}} has
+various advantages.
+The syntax is less error-prone because the start-delimiter is
+different from the end-delimiter. Also note that nested braces
+are allowed: a right brace @address@hidden is only an end-delimiter
+if it is unbalanced, so you would seldom need to escape it:
address@hidden
+&@{This has a @address@hidden address@hidden
+ @result{} "This has a @address@hidden section."
address@hidden example
+
+The escape character used for special characters is
address@hidden&}. This is compatible with XML syntax and @ref{XML literals}.
+
address@hidden Special characters
+
address@hidden
address@hidden
+ @stxlit{&#} @address@hidden @stxlit{;}
+ | @stxlit{&#x} @address@hidden @stxlit{;}
address@hidden
+ @stxlit{&} @stxref{char-or-entity-name} @stxlit{;}
address@hidden @meta{tagname}
address@hidden display
+
+You can the standard XML syntax for character references, using
+either decimal or hexadecimal values. The following string has two
+instances of the Ascii escape character, as either decimal 27 or hex 1B:
address@hidden
+&@{@} @result{} "\e\e"
address@hidden example
+
+You can also use the pre-defined XML entity names:
address@hidden
+&@{& < > " '@} @result{} "& < > \" '"
address@hidden example
+In addition, @code{{} @code{}} can be used for left and
+right curly brace, though you don't need them for balanced parentheses:
address@hidden
+&@{ }_{ / @address@hidden @} @result{} " @address@hidden /
@address@hidden "
address@hidden example
+
+You can use the
@uref{http://www.w3.org/2003/entities/2007/w3centities-f.ent,standard XML
entity names}. For example:
address@hidden
+&@{Lærdalsøaddress@hidden
+ @result{} "Lærdalsøyri"
address@hidden example
+
+You can also use the standard R7RS character names @code{null},
address@hidden, @code{backspace}, @code{tab}, @code{newline}, @code{return},
address@hidden, @code{space}, and @code{delete}.
+For example:
address@hidden
+&@{&escape;&space;@}
address@hidden example
+
+The syntax @code{&@var{name};} is actually syntactic sugar
+(specifically reader syntax) to the variable reference
address@hidden:@var{name}}.
+Hence you can also define your own entity names:
address@hidden
+(define $entity$:crnl "\r\n")
+&@{&crnl;@} ⟹ "\r\n"
address@hidden example
+
address@hidden Multiline string literals
+
address@hidden
address@hidden
+ @address@hidden @stxref{line-ending} @address@hidden @stxlit{&|}
address@hidden
+ @address@hidden @stxlit{&|}
+ | @stxlit{&} @stxref{nested-comment}
+ | @stxlit{&-} @address@hidden @stxref{line-ending}
address@hidden example
+
+A line-ending directly in the text is becomes a newline,
+as in a simple string literal:
address@hidden
+(string-capitalize &@{one two three
+uno dos tres
address@hidden) @result{} "One Two Three\nUno Dos Tres\n"
address@hidden example
+However, you have extra control over layout.
+If the string is in a nested expression, it is confusing
+(and ugly) if the string cannot be indented to match
+the surrounding context. The indentation marker @stxlit{&|}
+is used to mark the end of insignificant initial whitespace.
+The @code{&|} characters and all the preceding whitespace are removed.
+In addition, it also suppresses an initial newline. Specifically,
+when the initial left-brace is followed by optional (invisible)
+intraline-whitespace, then a newline, then optional
+intraline-whitespace (the indentation), and finally the indentation
+marker @code{&|} - all of which is removed from the output.
+Otherwise the @code{&|} only removes initial intraline-whitespace
+on the same line (and itself).
+
address@hidden
+(write (string-capitalize &@{
+ &|one two three
+ &|uno dos tres
address@hidden) out)
+ @result{} @i{prints} "One Two Three\nUno Dos Tres\n"
address@hidden example
+
+As a matter of style, all of the indentation lines should line up.
+It is an error if there are any non-whitespace characters between
+the previous newline and the indentation marker.
+It is also an error to write an indentation marker before the
+first newline in the literal.
+
+The line-continuation marker @stxlit{&-} is used to suppress a newline:
address@hidden
+&@{abc&-
+ address@hidden @result{} "abc def"
address@hidden example
+
+You can write a @code{#|...|#}-style comment following a @code{&}.
+This could be useful for annotation, or line numbers:
address@hidden
+&@{&#|line 1|#one two
+ &#|line 2|# three
+ &#|line 3|#uno dos tres
address@hidden @result{} "one two\n three\nuno dos tres\n"
address@hidden example
+
address@hidden Embedded expressions
+
address@hidden
address@hidden
+ @stxlit{&} @address@hidden @stxlit{[} @address@hidden @stxlit{]}
+ | @stxlit{&} @address@hidden @stxlit{(} @address@hidden @stxlit{)}
address@hidden example
+
+An embedded expression has the form @code{&address@hidden
+It is evaluated, the result converted to a string (as by @code{display}),
+and the result added in the result string.
+(If there are multiple expressions, they are all evaluated and
+the corresponding strings inserted in the result.)
address@hidden
+&@{Hello &[(string-capitalize name)address@hidden
address@hidden example
+
+You can leave out the square brackets when the expression
+is a parenthesized expression:
address@hidden
+&@{Hello &(string-capitalize name)address@hidden
address@hidden example
+
address@hidden Formatting
+
address@hidden
address@hidden
+ @stxlit{~} @meta{format-specifier-after-tilde}
address@hidden example
+
+Using @ref{Format,@code{format}} allows finer-grained control over the
+output, but a problem is that the association between format
+specifiers and data expressions is positional, which is hard-to-read
+and error-prone. A better solution places the specifier adjacant to
+the data expression:
address@hidden
+&@{The response was &~,2f(* 100.0 (/ responses total))address@hidden
address@hidden example
+
+The following escape forms are equivalent to the corresponding
+forms withput the @address@hidden, except the
+expression(s) are formatted using @code{format}:
address@hidden
address@hidden&address@hidden@address@hidden@address@hidden
address@hidden display
+Again using parentheses like this:
address@hidden
address@hidden&address@hidden@stxlit{(address@hidden@address@hidden)}
address@hidden display
+is equivalent to:
address@hidden
address@hidden&address@hidden@stxlit{[(address@hidden@address@hidden)]}
address@hidden display
+
+The syntax of @code{format} specifications is arcane, but it allows you
+to do some pretty neat things in a compact space.
+For example to include @code{"_"} between each element of
+the array @code{arr} you can use the @address@hidden@}} format speciers:
address@hidden
+(define arr [5 6 7])
+&@{&address@hidden&[arr]&~^_&address@hidden@} @result{} "5_6_7"
address@hidden example
+
+If no format is specified for an enclosed expression,
+the that is equivalent to a @code{~a} format specifier,
+so this is equivalent to:
address@hidden
+&@{&address@hidden&~a[arr]&~^_&address@hidden@} @result{} "5_6_7"
address@hidden example
+which is in turn equivalent to:
address@hidden
+(format #f "address@hidden@}" arr)
address@hidden example
+
+The fine print that makes this work:
+If there are multiple expressions in a @code{&[...]} with
+no format specifier then there is an implicit @code{~a} for
+each expression.
+On the other hand, if there is an explicit format specifier,
+it is not repeated for each enclosed expression: it appears
+exactly once in the effective format string, whether
+there are zero, one, or many expressions.
+
address@hidden Unicode
address@hidden Unicode character classes and conversions
+
address@hidden
+The procedures exported by the @rsixlibrary{unicode} library provide
+access to some aspects of the Unicode semantics for characters and
+strings: category information, case--independent comparisons, case
+mappings, and normalization.
address@hidden ignore
+
+Some of the procedures that operate on characters or strings ignore the
+difference between upper case and lower case. These procedures have
address@hidden (for ``case insensitive'') embedded in their names.
+
+
address@hidden Characters
+
address@hidden Procedure char-upcase @var{char}
address@hidden Procedure char-downcase @var{char}
address@hidden Procedure char-titlecase @var{char}
address@hidden Procedure char-foldcase @var{char}
+These procedures take a character argument and return a character
+result.
+
+If the argument is an upper--case or title--case character, and if there
+is a single character that is its lower--case form, then
address@hidden returns that character.
+
+If the argument is a lower--case or title--case character, and there is
+a single character that is its upper--case form, then @func{char-upcase}
+returns that character.
+
+If the argument is a lower--case or upper--case character, and there is
+a single character that is its title--case form, then
address@hidden returns that character.
+
+If the argument is not a title--case character and there is no single
+character that is its title--case form, then @func{char-titlecase}
+returns the upper--case form of the argument.
+
+Finally, if the character has a case--folded character, then
address@hidden returns that character. Otherwise the character
+returned is the same as the argument.
+
+For Turkic characters @code{#\x130} and @code{#\x131},
address@hidden behaves as the identity function; otherwise
address@hidden is the same as @func{char-downcase} composed with
address@hidden
+
address@hidden
+(char-upcase #\i) @result{} #\I
+(char-downcase #\i) @result{} #\i
+(char-titlecase #\i) @result{} #\I
+(char-foldcase #\i) @result{} #\i
+
+(char-upcase #\ß) @result{} #\ß
+(char-downcase #\ß) @result{} #\ß
+(char-titlecase #\ß) @result{} #\ß
+(char-foldcase #\ß) @result{} #\ß
+
+(char-upcase #\Σ) @result{} #\Σ
+(char-downcase #\Σ) @result{} #\σ
+(char-titlecase #\Σ) @result{} #\Σ
+(char-foldcase #\Σ) @result{} #\σ
+
+(char-upcase #\ς) @result{} #\Σ
+(char-downcase #\ς) @result{} #\ς
+(char-titlecase #\ς) @result{} #\Σ
+(char-foldcase #\ς) @result{} #\σ
address@hidden example
+
address@hidden
address@hidden:} @func{char-titlecase} does not always return a title--case
+character.
address@hidden quotation
+
address@hidden
address@hidden:} These procedures are consistent with Unicode's
+locale--independent mappings from scalar values to scalar values for
+upcase, downcase, titlecase, and case--folding operations. These
+mappings can be extracted from @file{UnicodeData.txt} and
address@hidden from the Unicode Consortium, ignoring Turkic
+mappings in the latter.
+
+Note that these character--based procedures are an incomplete
+approximation to case conversion, even ignoring the user's locale. In
+general, case mappings require the context of a string, both in
+arguments and in result. The @func{string-upcase},
address@hidden, @func{string-titlecase}, and
address@hidden procedures perform more general case conversion.
address@hidden quotation
address@hidden deffn
+
address@hidden Procedure char-ci=? @vari{char} @varii{char} @variii{char}
@dots{}
address@hidden Procedure char-ci<? @vari{char} @varii{char} @variii{char}
@dots{}
address@hidden Procedure char-ci>? @vari{char} @varii{char} @variii{char}
@dots{}
address@hidden Procedure char-ci<=? @vari{char} @varii{char} @variii{char}
@dots{}
address@hidden Procedure char-ci>=? @vari{char} @varii{char} @variii{char}
@dots{}
+These procedures are similar to @func{char=?}, etc., but operate on the
+case--folded versions of the characters.
+
address@hidden
+(char-ci<? #\z #\Z) @result{} #f
+(char-ci=? #\z #\Z) @result{} #f
+(char-ci=? #\ς #\σ) @result{} #t
address@hidden example
address@hidden deffn
+
+
address@hidden Procedure char-alphabetic? @var{char}
address@hidden Procedure char-numeric? @var{char}
address@hidden Procedure char-whitespace? @var{char}
address@hidden Procedure char-upper-case? @var{char}
address@hidden Procedure char-lower-case? @var{char}
address@hidden Procedure char-title-case? @var{char}
+These procedures return @true{} if their arguments are alphabetic,
+numeric, whitespace, upper--case, lower--case, or title--case
+characters, respectively; otherwise they return @false{}.
+
+A character is alphabetic if it has the Unicode ``Alphabetic'' property.
+A character is numeric if it has the Unicode ``Numeric'' property. A
+character is whitespace if has the Unicode ``White_Space'' property. A
+character is upper case if it has the Unicode ``Uppercase'' property,
+lower case if it has the ``Lowercase'' property, and title case if it is
+in the Lt general category.
+
address@hidden
+(char-alphabetic? #\a) @result{} #t
+(char-numeric? #\1) @result{} #t
+(char-whitespace? #\space) @result{} #t
+(char-whitespace? #\x00A0) @result{} #t
+(char-upper-case? #\Σ) @result{} #t
+(char-lower-case? #\σ) @result{} #t
+(char-lower-case? #\x00AA) @result{} #t
+(char-title-case? #\I) @result{} #f
+(char-title-case? #\x01C5) @result{} #t
address@hidden example
address@hidden deffn
+
address@hidden Procedure char-general-category @var{char}
+Return a symbol representing the Unicode general category of
address@hidden, one of @code{Lu}, @code{Ll}, @code{Lt}, @code{Lm},
address@hidden, @code{Mn}, @code{Mc}, @code{Me}, @code{Nd}, @code{Nl},
address@hidden, @code{Ps}, @code{Pe}, @code{Pi}, @code{Pf}, @code{Pd},
address@hidden, @code{Po}, @code{Sc}, @code{Sm}, @code{Sk}, @code{So},
address@hidden, @code{Zp}, @code{Zl}, @code{Cc}, @code{Cf}, @code{Cs},
address@hidden, or @code{Cn}.
+
address@hidden
+(char-general-category #\a) @result{} Ll
+(char-general-category #\space) @result{} Zs
+(char-general-category #\x10FFFF) @result{} Cn
address@hidden example
address@hidden deffn
+
+
address@hidden Deprecated in-place case modification
+
+The following functions are deprecated; they really don't
+and cannot do the right thing, because in some languages
+upper and lower case can use different number of characters.
+
address@hidden Procedure string-upcase! str
address@hidden:} Destructively modify @var{str}, replacing the letters
+by their upper-case equivalents.
address@hidden deffn
+
address@hidden Procedure string-downcase! str
address@hidden:} Destructively modify @var{str}, replacing the letters
+by their upper-lower equivalents.
address@hidden deffn
+
address@hidden Procedure string-capitalize! str
address@hidden:} Destructively modify @var{str}, such that the letters that
start a new word
+are replaced by their title-case equivalents, while non-initial letters
+are replaced by their lower-case equivalents.
address@hidden deffn
+
address@hidden Regular expressions, , Unicode, Characters and text
address@hidden Regular expressions
+
+Kawa provides @dfn{regular expressions}, which is a convenient
+mechanism for matching a string against a @dfn{pattern}
+and maybe replacing matching parts.
+
+A regexp is a string that describes a pattern. A regexp matcher tries
+to match this pattern against (a portion of) another string, which we
+will call the text string. The text string is treated as raw text and
+not as a pattern.
+
+Most of the characters in a regexp pattern are meant to match
+occurrences of themselves in the text string. Thus, the pattern
address@hidden''
+matches a string that contains the characters address@hidden'',
address@hidden'',
address@hidden'' in succession.
+
+In the regexp pattern, some characters act as @dfn{metacharacters},
+and some character sequences act as @dfn{metasequences}. That is, they
+specify something other than their literal selves. For example, in the
+pattern address@hidden'', the characters address@hidden'' and address@hidden''
do stand
+for themselves but the metacharacter address@hidden'' can match any character
+(other than newline). Therefore, the pattern address@hidden'' matches an
address@hidden'', followed by any character, followed by a address@hidden''.
+
+If we needed to match the character address@hidden'' itself, we @dfn{escape}
+it, ie, precede it with a backslash address@hidden''. The character sequence
address@hidden'' is thus a metasequence, since it doesn’t match itself but
+rather just address@hidden''. So, to match address@hidden'' followed by a
literal
address@hidden'' followed by address@hidden'' we use the regexp pattern
address@hidden''. To write this as a Scheme string literal,
+you need to quote the backslash, so you need to write @code{"a\\.c"}.
+Kawa also allows the literal syntax @code{#/a\.c/},
+which avoids the need to double the backslashes.
+
+You can choose between two similar styles of regular expressions.
+The two differ slightly in terms of which characters act as metacharacters,
+and what those metacharacters mean:
address@hidden
address@hidden
+Functions starting with @code{regex-} are implemented using
+the @code{java.util.regex} package.
+This is likely to be more efficient, has better Unicode support and
+some other minor extra features, and literal syntax @code{#/a\.c/}
+mentioned above.
address@hidden
+Functions starting with @code{pregexp-} are implemented in pure Scheme
+using Dorai Sitaram's ``Portable Regular Expressions for Scheme'' library.
+These will be portable to more Scheme implementations, including BRL,
+and is available on older Java versions.
address@hidden itemize
+
+
address@hidden Java regular expressions
+
+The syntax for regular expressions is
address@hidden://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html,
documented here}.
+
address@hidden Type regex
+A compiled regular expression,
+implemented as @code{java.util.regex.Pattern}.
address@hidden deffn
+
address@hidden Constructor regex arg
+Given a regular expression pattern (as a string),
+compiles it to a @code{regex} object.
+
address@hidden
+(regex "a\\.c")
address@hidden example
+This compiles into a pattern that matches an
address@hidden'', followed by any character, followed by a address@hidden''.
address@hidden deffn
+
+The Scheme reader recognizes address@hidden/}'' as the start of a
+regular expression @dfn{pattern literal}, which ends with the next
+un-escaped address@hidden/}''.
+This has the big advantage that you don't need to double the backslashes:
address@hidden
+#/a\.c/
address@hidden example
+This is equivalent to @code{(regex "a\\.c")}, except it is
+compiled at read-time.
+If you need a literal address@hidden/}'' in a pattern, just escape it
+with a backslash: address@hidden/a\/c/}'' matches a address@hidden'',
+followed by a address@hidden/}'', followed by a address@hidden''.
+
+You can add single-letter @emph{modifiers} following the pattern literal.
+The following modifiers are allowed:
address@hidden @code
address@hidden i
+The modifier address@hidden'' cause the matching to ignore case.
+For example the following pattern matches address@hidden'' or address@hidden''.
address@hidden
+#/a/i
address@hidden example
address@hidden m
+Enables ``metaline'' mode.
+Normally metacharacters address@hidden'' and address@hidden'
+match at the start end end of the entire input string.
+In metaline mode address@hidden'' and address@hidden'' also
+match just before or after a line terminator.
+
+Multiline mode can also be enabled by the metasequence address@hidden(?m)}''.
address@hidden s
+Enable ``singleline'' (aka ``dot-all'') mode.
+In this mode the matacharacter address@hidden matches any character,
+including a line breaks.
+This mode be enabled by the metasequence address@hidden(?s)}''.
address@hidden table
+
+The following functions accept a regex either as
+a pattern string or a compiled @code{regex} pattern.
+I.e. the following are all equivalent:
address@hidden
+(regex-match "b\\.c" "ab.cd")
+(regex-match #/b\.c/ "ab.cd")
+(regex-match (regex "b\\.c") "ab.cd")
+(regex-match (java.util.regex.Pattern:compile "b\\.c") "ab.cd")
address@hidden example
+These all evaluate to the list @code{("b.c")}.
+
+The following functions must be imported by doing one of:
address@hidden
+(require 'regex) ;; or
+(import (kawa regex))
address@hidden example
+
address@hidden Procedure regex-match-positions regex string [start [end]]
+
+The procedure @code{regex‑match‑position} takes pattern and a
+text @var{string}, and returns a match if the regex matches (some part of)
+the text string.
+
+Returns @code{#f} if the regexp did not match the string;
+and a list of index pairs if it did match.
address@hidden
+(regex-match-positions "brain" "bird") @result{} #f
+(regex-match-positions "needle" "hay needle stack")
+ @result{} ((4 . 10))
address@hidden example
+
+In the second example, the integers 4 and 10 identify the substring
+that was matched. 4 is the starting (inclusive) index and 10 the
+ending (exclusive) index of the matching substring.
+
address@hidden
+(substring "hay needle stack" 4 10) @result{} "needle"
address@hidden example
+
+In this case the return list contains only one index
+pair, and that pair represents the entire substring matched by the
+regexp. When we discuss subpatterns later, we will see how a single
+match operation can yield a list of submatches.
+
address@hidden takes optional third and fourth arguments
+that specify the indices of the text string within which the matching
+should take place.
+
address@hidden
+(regex-match-positions "needle"
+ "his hay needle stack -- my hay needle stack -- her hay needle stack"
+ 24 43)
+ @result{} ((31 . 37))
address@hidden example
+
+Note that the returned indices are still reckoned relative to the full text
string.
address@hidden deffn
+
address@hidden Procedure regex-match regex string [start [end]]
+The procedure @code{regex‑match} is called like @code{regex‑match‑positions}
+but instead of returning index pairs it returns the matching substrings:
address@hidden
+(regex-match "brain" "bird") @result{} #f
+(regex-match "needle" "hay needle stack")
+ @result{} ("needle")
address@hidden example
+
address@hidden also takes optional third and fourth arguments,
+with the same meaning as does @code{regex‑match‑positions}.
address@hidden deffn
+
address@hidden Procedure regex-split regex string
+Takes two arguments, a @var{regex} pattern and a text @var{string},
+and returns a list of substrings of the text string,
+where the pattern identifies the delimiter separating the substrings.
address@hidden
+(regex-split ":" "/bin:/usr/bin:/usr/bin/X11:/usr/local/bin")
+ @result{} ("/bin" "/usr/bin" "/usr/bin/X11" "/usr/local/bin")
+
+(regex-split " " "pea soup")
+ @result{} ("pea" "soup")
address@hidden example
+
+If the first argument can match an empty string, then the list of all
+the single-character substrings is returned, plus we get
+a empty strings at each end.
+
address@hidden
+(regex-split "" "smithereens")
+ @result{} ("" "s" "m" "i" "t" "h" "e" "r" "e" "e" "n" "s" "")
address@hidden example
+
+(Note: This behavior is different from @code{pregexp-split}.)
+
+To identify one-or-more spaces as the delimiter, take care to use the regexp
address@hidden +}'', not address@hidden *}''.
address@hidden
+(regex-split " +" "split pea soup")
+ @result{} ("split" "pea" "soup")
+(regex-split " *" "split pea soup")
+ @result{} ("" "s" "p" "l" "i" "t" "" "p" "e" "a" "" "s" "o" "u" "p" "")
address@hidden example
address@hidden deffn
+
address@hidden Procedure regex‑replace regex string replacement
+Replaces the matched portion of the text @var{string} by another a
address@hidden string.
address@hidden
+(regex-replace "te" "liberte" "ty")
+ @result{} "liberty"
address@hidden example
+
+Submatches can be used in the replacement string argument.
+The replacement string can use address@hidden@var{n}}''
+as a @dfn{backreference} to refer back to the @var{n}th
+submatch, ie, the substring that matched the @var{n}th
+subpattern. address@hidden'' refers to the entire match.
address@hidden
+(regex-replace #/_(.+?)_/
+ "the _nina_, the _pinta_, and the _santa maria_"
+ "*$1*"))
+ @result{} "the *nina*, the _pinta_, and the _santa maria_"
address@hidden example
address@hidden deffn
+
address@hidden Procedure regex‑replace* regex string replacement
+Replaces all matches in the text @var{string} by the @var{replacement} string:
address@hidden
+(regex-replace* "te" "liberte egalite fraternite" "ty")
+ @result{} "liberty egality fratyrnity"
+(regex-replace* #/_(.+?)_/
+ "the _nina_, the _pinta_, and the _santa maria_"
+ "*$1*")
+ @result{} "the *nina*, the *pinta*, and the *santa maria*"
address@hidden example
address@hidden deffn
+
address@hidden Procedure regex-quote pattern
+Takes an arbitrary string and returns a pattern string that precisely
+matches it. In particular, characters in the input string that could
+serve as regex metacharacters are escaped as needed.
+
address@hidden
+(regex-quote "cons")
+ @result{} "\Qcons\E"
address@hidden example
address@hidden is useful when building a composite regex
+from a mix of regex strings and verbatim strings.
address@hidden deffn
+
address@hidden Portable Scheme regular expressions
+
+This provides the procedures @code{pregexp}, @code{pregexp‑match‑positions},
address@hidden, @code{pregexp‑split}, @code{pregexp‑replace},
address@hidden, and @code{pregexp‑quote}.
+
+Before using them, you must require them:
address@hidden
+(require 'pregexp)
address@hidden example
+
+These procedures have the same interface as the corresponding
address@hidden versions, but take slightly different pattern syntax.
+The replace commands use address@hidden'' instead of address@hidden''
+to indicate substitutions.
+Also, @code{pregexp‑split} behaves differently from
address@hidden if the pattern can match an empty string.
+
+See @uref{http://www.ccs.neu.edu/home/dorai/pregexp/index.html,here for
details}.
+
address@hidden Data structures
address@hidden Data structures
+
address@hidden
+* Sequences::
+* Lists::
+* Vectors::
+* Uniform vectors::
+* Bytevectors::
+* Ranges::
+* Streams:: Lazy lists.
+* Arrays:: Multi-dimensional Arrays
+* Hash tables::
address@hidden menu
+
address@hidden Sequences
address@hidden Sequences
+
+A @dfn{sequence} is a generalized list, consisting of zero or more values.
+You can choose between a number of different kinds of sequence implementations.
+Scheme traditionally has @ref{Lists,lists} and @ref{Vectors,vectors}.
+Any Java class that implements @code{java.util.List} is a sequence type.
+Raw Java arrays can also be viewerd as a sequence,
+and strings can be viewed a sequence (or vector) of characters.
+Kawa also provides @ref{Uniform vectors,uniform vectors}.
+
+Sequence types differ in their API, but given a sequence type @var{stype}
+you can construct instances of that type using the syntax:
address@hidden
+(@var{stype} @var{v0} @var{v1} .... @var{vn})
address@hidden example
+For example:
address@hidden
+(bytevector 9 8 7 6) @result{} #u8(9 8 7 6)
address@hidden example
+
+For a raw Java class name @var{jname} you may need to use
+the empty keyword @code{||:} to separate constructor parameters (if any)
+from sequence elements, as in:
address@hidden
+(gnu.lists.U8Vector ||: 9 8 7 6) @result{} #u8(9 8 7 6)
address@hidden example
+This syntax works with any type with a default constructor
+and a 1-argument @code{add} method;
+see @ref{Allocating objects} for details.
+You can use the same syntax for allocating arrays,
+though array creation supports @ref{Creating-new-Java-arrays,more options}.
+
+To extract an element from Scheme sequence of type @var{stype}
+there is usually a function @address@hidden For example:
address@hidden
+(define vec1 (vector 5 6 7 8))
+(vector-ref vec1 2) @result{} 7
address@hidden example
+
+More concisely, you can use (Kawa-specific) function call syntax:
address@hidden
+(vec1 3) @result{} 8
address@hidden example
+
+The index can be another sequence, which creates a new sequence
+of the selected indexes:
address@hidden
+(vec1 [3 0 2 1]) @result{} #(8 5 7 6)
address@hidden example
+It is convenient to use a @ref{Ranges,@dfn{range}} to select
+a sub-sequence:
address@hidden
+(vec1 [1 <=: 3]) @result{} #(6 7 8)
+(vec1 [2 <:]) @result{} #(7 8)
address@hidden example
+
+The same function call syntax also works for raw Java arrays
+(though the index is restricted to an integer, not a sequence or array):
address@hidden
+(define arr1 (long[] 4 5 6 7))
+(arr1 3) @result{} 7
address@hidden example
+
+To assign to (replace) an element from a sequence of Scheme type @var{stype}
+there is usually a function @address@hidden:
address@hidden
+(vector-set! vec1 1 9)
+vec1 @result{} #(5 9 7 8)
address@hidden example
+
+Again, you can use the function call syntax:
address@hidden
+(set! (vec1 2) 'x)
+vec1 @result{} #(5 9 x 8)
address@hidden example
+
address@hidden Procedure length seq
+Returns the number of elements of the @var{seq}.
+
address@hidden
+(length '(a b c)) @result{} 3
+(length '(a (b) (c d e))) @result{} 3
+(length '()) @result{} 0
+(length [3 4 [] 12]) @result{} 4
+(length (vector)) @result{} 0
+(length (int[] 7 6)) @result{} 2
address@hidden example
+
+The length of a string is the number of characters (Unicode code points).
+In contrast, the @code{length} @emph{method} (of the @code{CharSequence}
interface)
+returns the number of 16-bit code points:
address@hidden
+(length "Hello") @result{} 5
+(define str1 "Hello \x1f603;!")
+(invoke str1 'length) @result{} 9
+(length str1) @result{} 8 ; Used to return 9 in Kawa 2.x.
+(string-length str1) @result{} 8
address@hidden example
address@hidden deffn
+
address@hidden Lists
address@hidden Lists
+
+A pair (sometimes called a @dfn{dotted pair}) is a record structure
+with two fields called the car and cdr fields (for historical
+reasons). Pairs are created by the procedure @code{cons}. The
+car and cdr fields are accessed by the procedures @code{car} and
address@hidden The car and cdr fields are assigned by the procedures
address@hidden and @code{set-cdr!}.
+
+Pairs are used primarily to represent lists. A @dfn{list} can be
+defined recursively as either the empty list or a pair whose
+cdr is a list. More precisely, the set of lists is defined as
+the smallest set @var{X} such that:
address@hidden
address@hidden
+The empty list is in @var{X}.
address@hidden
+If @var{list} is in @var{X}, then any pair whose cdr field contains
address@hidden is also in @var{X}.
address@hidden itemize
+
+The objects in the car fields of successive pairs of a list are
+the elements of the list. For example, a two-element list
+is a pair whose car is the first element and whose cdr is a
+pair whose car is the second element and whose cdr is the
+empty list. The length of a list is the number of elements,
+which is the same as the number of pairs.
+
+The empty list is a special object of its own type. It is not
+a pair, it has no elements, and its length is zero.
+
address@hidden:} The above definitions imply that all lists have finite
+length and are terminated by the empty list.
+
+The most general notation (external representation) for
+Scheme pairs is the “dotted” notation @code{(@var{c1} . @var{c2} )}
+where @var{c1} is the value of the car field and
address@hidden is the value of the cdr field.
+For example @code{(4 . 5)} is a pair whose car is 4 and
+whose cdr is 5. Note that @code{(4 . 5)} is the external representation
+of a pair, not an expression that evaluates to a pair.
+
+A more streamlined notation can be used for lists: the
+elements of the list are simply enclosed in parentheses and
+separated by spaces. The empty list is written @code{()}.
+For example,
address@hidden
+(a b c d e)
address@hidden example
+and
address@hidden
+(a . (b . (c . (d . (e . ())))))
address@hidden example
+are equivalent notations for a list of symbols.
+
+A chain of pairs not ending in the empty list is called an
address@hidden list}. Note that an improper list is not a list.
+The list and dotted notations can be combined to represent
+improper lists:
address@hidden
+(a b c . d)
address@hidden example
+is equivalent to
address@hidden
+(a . (b . (c . d)))
address@hidden example
+
address@hidden to finish merging from R7RS!}
+
address@hidden Procedure make-list k [fill]
+Returns a newly allocated list of @var{k} elements. If a second argument
+is given, the each element is initialized to @var{fill}.
+Otherwise the initial contents of each element is unspecified.
address@hidden
+(make-list 2 3) @result{} (3 3)
address@hidden example
address@hidden deffn
+
address@hidden
address@hidden SRFI-1 list library
+
+The @uref{http://srfi.schemers.org/srfi-1/srfi-1.html, SRFI-1 List Library}
+is available, though not enabled by default. To use its functions you
+must @code{(require 'list-lib)} or @code{(require 'srfi-1)}.
address@hidden
+(require 'list-lib)
+(iota 5 0 -0.5) @result{} (0.0 -0.5 -1.0 -1.5 -2.0)
address@hidden example
+
address@hidden Procedure reverse! list
+The result is a list consisting of the elements of @var{list} in reverse order.
+No new pairs are allocated, instead the pairs of @var{list} are re-used,
+with @code{cdr} cells of @var{list} reversed in place. Note that if @var{list}
+was pair, it becomes the last pair of the reversed result.
address@hidden deffn
+
address@hidden
address@hidden SRFI-101 Purely Functional Random-Access Pairs and Lists
+
address@hidden://srfi.schemers.org/srfi-101/srfi-101.html, SRFI-101}
+specifies immutable (read-only) lists with fast (logarithmic) indexing
+and functional
+update (i.e. return a modified list).
+These are implemented by a @code{RAPair} class
+which extends the generic @code{pair} type, which means that most
+code that expects a standard list will work on these lists as well.
+
address@hidden Vectors
address@hidden Vectors
+
+Vectors are heterogeneous structures whose elements are indexed by
+integers. A vector typically occupies less space than a list of the
+same length, and the average time needed to access a randomly chosen
+element is typically less for the vector than for the list.
+
+The @emph{length} of a vector is the number of elements that it
+contains. This number is a non--negative integer that is fixed when the
+vector is created. The @emph{valid indices} of a vector are the exact
+non--negative integer objects less than the length of the vector. The
+first element in a vector is indexed by zero, and the last element is
+indexed by one less than the length of the vector.
+
+Vectors are written using the notation @code{#(@var{obj} ...)}.
+For example, a vector of length 3 3 containing the number zero
+in element 0, the list @code{(2 2 2 2)} in element 1, and the
+string @code{"Anna"} in element 2 can be written as following:
address@hidden
+#(0 (2 2 2 2) "Anna")
address@hidden example
+Note that this is the external representation of a vector.
+In Kawa, a vector datum is self-evaluating,
+but for style (and compatibility with R7RS) is is suggested
+you quote a vector constant:
address@hidden
+’#(0 (2 2 2 2) "Anna") @result{} #(0 (2 2 2 2) "Anna")
address@hidden example
+
+Compare these different ways of creating a vector:
address@hidden @code
address@hidden (vector a b c)
+In this case @code{a}, @code{b}, and @code{c} are expressions evaluated at
+run-time and the results used to initialize a newly-allocated 3-element vector.
address@hidden [a b c]
+Same as using vector, but more concise, and results in an immutable
+(non-modifiable) vector.
address@hidden #(a b c)
+This is reader syntax and creates a vector literal,
+at read-time, early in compile-time.
+The symbols @code{a}, @code{b}, and @code{c} are not evaluated
+but instead used literally.
address@hidden `#(,a ,b ,c)
+This is reader-syntax, using quasi-quotation,
+so @code{a}, @code{b}, and @code{c} are expressions evaluated at run-time.
+This is equivalent to @code{[a b c]} in that it results in an immutable vector.
address@hidden table
+
+
address@hidden Type vector
+The type of vector objects.
address@hidden deffn
+
address@hidden Constructor vector @var{obj} @dots{}
+Return a newly allocated vector whose elements contain the given
+arguments. Analogous to @code{list}.
+
address@hidden
+(vector 'a 'b 'c) @result{} #(a b c)
address@hidden example
+
+Alternatively, you can use square-bracket syntax,
+which results in an immutable vector:
address@hidden
+['a 'b 'c] @result{} #(a b c)
address@hidden example
address@hidden deffn
+
address@hidden Procedure make-vector @var{k}
address@hidden Procedure make-vector @var{k} @var{fill}
+Return a newly allocated vector of @var{k} elements. If a second
+argument is given, then each element is initialized to @var{fill}.
+Otherwise the initial contents of each element is @code{#!null}.
address@hidden deffn
+
address@hidden Procedure vector? @var{obj}
+Return @true{} if @var{obj} is a vector, @false{} otherwise.
address@hidden deffn
+
address@hidden Procedure vector-length @var{vector}
+Return the number of elements in @var{vector} as an exact integer.
+
address@hidden deffn
+
address@hidden Procedure vector-ref @var{vector} @var{k}
+It is an error if @var{k} is not a valid index of @var{vector}.
+The @func{vector-ref}
+procedure returns the contents of element @var{k} of @var{vector}.
+
address@hidden
+(vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
+(vector-ref '#(1 1 2 3 5 8 13 21)
+ (inexact->exact (round (* 2 (acos -1)))))
address@hidden 13
address@hidden example
address@hidden deffn
+
address@hidden Procedure vector-set! @var{vector} @var{k} @var{obj}
+It is an error if @var{k} is not a valid index of @var{vector}.
+The @func{vector-set!}
+procedure stores @var{obj} in element @var{k} of @var{vector}, and
+returns no values.
+
address@hidden
+(let ((vec (vector 0 '(2 2 2 2) "Anna")))
+ (vector-set! vec 1 '("Sue" "Sue"))
+ vec)
+ @result{} #(0 ("Sue" "Sue") "Anna")
+
+(vector-set! '#(0 1 2) 1 "doe")
+ @result{} @i{error} ;; constant vector
address@hidden example
address@hidden deffn
+
+A concise alternative to @code{vector-ref} and @code{vector-set!}
+is to use function call syntax. For example:
address@hidden
+(let ((vec (vector 0 '(2 2 2 2) "Anna")))
+ (set! (vec 1) '("Sue" "Sue"))
+ (list (vec 2) (vec 1)))
+ @result{} ("Anna" ("Sue" "Sue"))
address@hidden example
+
address@hidden Procedure vector->list @var{vector} address@hidden address@hidden
+The @func{vector->list} procedure returns a newly allocated list of the
+objects contained in the elements of @var{vector}
+between @var{start} and @var{end}.
+
address@hidden
+(vector->list '#(dah dah didah)) @result{} (dah dah didah)
+(vector->list '#(dah dah didah) 1 2) @result{} (dah)
address@hidden example
address@hidden deffn
+
address@hidden Procedure list->vector @var{list}
+The @func{list->vector} procedure returns a newly created vector
+initialized to the elements of the list @var{list}, in order.
address@hidden
+(list->vector '(dididit dah)) @result{} #(dididit dah)
address@hidden example
address@hidden deffn
+
address@hidden Procedure vector-copy vector [start [end]]
+Returns a newly allocated copy of the elements of the given
address@hidden between @var{start} and @var{end} . The elements of the new
+vector are the same (in the sense of @code{eqv?}) as the elements
+of the old.
+
address@hidden
+(define a #(1 8 2 8)) ; a may be immutable
+(define b (vector-copy a))
+(vector-set! b 0 3) ; b is mutable
+b @result{} #(3 8 2 8)
+(define c (vector-copy b 1 3))
+c @result{} #(8 2)
address@hidden example
address@hidden deffn
+
address@hidden Procedure vector-copy! to at from [start [end]]
+Copies the elements of vector from between start and end
+to vector to, starting at at. The order in which elements
+are copied is unspecified, except that if the source and
+destination overlap, copying takes place as if the source is first
+copied into a temporary vector and then into the destination.
+This can be achieved without allocating storage by making
+sure to copy in the correct direction in such circumstances.
+
+It is an error if @var{at} is less than zero or greater than the length
+of @var{to}.
+It is also an error if @code{(- (vector-length @var{to}) @var{at})} is less
+than @code{(- @var{end} @var{start})}.
+
address@hidden
+(define a (vector 1 2 3 4 5))
+(define b (vector 10 20 30 40 50))
+(vector-copy! b 1 a 0 2)
+b @result{} #(10 1 2 40 50)
address@hidden example
address@hidden deffn
+
address@hidden Procedure vector-append @var{arg}...
+Creates a newly allocated vector whose elements are the
+concatenation of the elements of the given arguments.
+Each @var{arg} may be a vector or a list.
address@hidden
+(vector-append #(a b c) #(d e f))
+ @result{} #(a b c d e f)
address@hidden example
address@hidden deffn
+
address@hidden Procedure {vector-fill!} @var{vector fill} address@hidden
address@hidden
+Stores @var{fill} in in the elements of @var{vector}
+between @var{start} and @var{end}.
address@hidden
+(define a (vector 1 2 3 4 5))
+(vector-fill! a 'smash 2 4)
+a @result{} #(1 2 smash smash 5)
address@hidden example
address@hidden deffn
+
+The procedures @code{vector-map} and @code{vector-for-each}
+are documented in @ref{Mapping functions}.
+
address@hidden Uniform vectors
address@hidden Uniform vectors
+
+Uniform vectors are vectors whose elements are of the same numeric type.
+The are defined by @uref{http://srfi.schemers.org/srfi-4/srfi-4.html,SRFI-4}.
+The type names (such as @code{s8vector}) are a Kawa extension.
+
address@hidden
address@hidden @stxlit{#} @stxref{uniform-tag} @stxref{list}
address@hidden @stxlit{f32} | @stxlit{f64}
+ | @stxlit{s8} | @stxlit{s16} | @stxlit{s32} | @stxlit{s64}
+ | @stxlit{u8} | @stxlit{u16} | @stxlit{u32} | @stxlit{u64}
address@hidden display
+
+This example is a literal for a 5-element vector of unsigned short
(@code{ushort}) values:
address@hidden
+(define uvec1 #u16(64000 3200 160 8 0))
address@hidden example
+
+Since a uniform vector is a sequence, you can use function-call
+notation to index one. For example:
address@hidden
+(uvec1 1) @result{} 3200
address@hidden example
+In this case the result is a primitive unsigned short (@code{ushort}),
+which is converted to a @code{gnu.math.UShort} if an object is needed.
+
address@hidden Type s8vector
+The type of uniform vectors where each element can contain
+a signed 8-bit integer. Represented using an array of @code{byte}.
address@hidden deffn
+
address@hidden Type u8vector
+The type of uniform vectors where each element can contain
+an unsigned 8-bit integer. Represented using an array of @code{<byte>},
+but each element is treated as if unsigned.
+
+This type is a synonym for @code{bytevector},
+which has @ref{Bytevectors, extra functions}.
address@hidden deffn
+
address@hidden Type s16vector
+The type of uniform vectors where each element can contain
+a signed 16-bit integer. Represented using an array of @code{short}.
address@hidden deffn
+
address@hidden Type u16vector
+The type of uniform vectors where each element can contain
+an unsigned 16-bit integer. Represented using an array of @code{short},
+but each element is treated as if unsigned.
address@hidden deffn
+
address@hidden Type s32vector
+The type of uniform vectors where each element can contain
+a signed 32-bit integer. Represented using an array of @code{int}.
address@hidden deffn
+
address@hidden Type u32vector
+The type of uniform vectors where each element can contain
+an unsigned 32-bit integer. Represented using an array of @code{int},
+but each element is treated as if unsigned.
address@hidden deffn
+
address@hidden Type s64vector
+The type of uniform vectors where each element can contain
+a signed 64-bit integer. Represented using an array of @code{long}.
address@hidden deffn
+
address@hidden Type u64vector
+The type of uniform vectors where each element can contain
+an unsigned 64-bit integer. Represented using an array of @code{long},
+but each element is treated as if unsigned.
address@hidden deffn
+
address@hidden Type f32vector
+The type of uniform vectors where each element can contain
+a 32-bit floating-point real. Represented using an array of @code{float}.
address@hidden deffn
+
address@hidden Type f64vector
+The type of uniform vectors where each element can contain
+a 64-bit floating-point real. Represented using an array of @code{double}.
address@hidden deffn
+
address@hidden Procedure s8vector? value
address@hidden Procedure u8vector? value
address@hidden Procedure s16vector? value
address@hidden Procedure u16vector? value
address@hidden Procedure s32vector? value
address@hidden Procedure u32vector? value
address@hidden Procedure s64vector? value
address@hidden Procedure u64vector? value
address@hidden Procedure f32vector? value
address@hidden Procedure f64vector? value
+Return true iff @var{value} is a uniform vector of the specified type.
address@hidden deffn
+
address@hidden Procedure make-s8vector n [value]
address@hidden Procedure make-u8vector n [value]
address@hidden Procedure make-s16vector n [value]
address@hidden Procedure make-u16vector n [value]
address@hidden Procedure make-s32vector n [value]
address@hidden Procedure make-u32vector n [value]
address@hidden Procedure make-s64vector n [value]
address@hidden Procedure make-u64vector n [value]
address@hidden Procedure make-f32vector n [value]
address@hidden Procedure make-f64vector n [value]
+Create a new uniform vector of the specified type,
+having room for @var{n} elements.
+Initialize each element to @var{value} if it is specified; zero otherwise.
address@hidden deffn
+
address@hidden Constructor s8vector value ...
address@hidden Constructor u8vector value ...
address@hidden Constructor s16vector value ..
address@hidden Constructor u16vector value ...
address@hidden Constructor s32vector value ...
address@hidden Constructor u32vector value ...
address@hidden Constructor s64vector value ...
address@hidden Constructor u64vector value ...
address@hidden Constructor f32vector value ...
address@hidden Constructor f64vector value ...
+Create a new uniform vector of the specified type,
+whose length is the number of @var{value}s specified,
+and initialize it using those @var{value}s.
address@hidden deffn
+
address@hidden Procedure s8vector-length v
address@hidden Procedure u8vector-length v
address@hidden Procedure s16vector-length v
address@hidden Procedure u16vector-length v
address@hidden Procedure s32vector-length v
address@hidden Procedure u32vector-length v
address@hidden Procedure s64vector-length v
address@hidden Procedure u64vector-length v
address@hidden Procedure f32vector-length v
address@hidden Procedure f64vector-length v
+Return the length (in number of elements) of the uniform vector @var{v}.
address@hidden deffn
+
address@hidden Procedure s8vector-ref v i
address@hidden Procedure u8vector-ref v i
address@hidden Procedure s16vector-ref v i
address@hidden Procedure u16vector-ref v i
address@hidden Procedure s32vector-ref v i
address@hidden Procedure u32vector-ref v i
address@hidden Procedure s64vector-ref v i
address@hidden Procedure u64vector-ref v i
address@hidden Procedure f32vector-ref v i
address@hidden Procedure f64vector-ref v i
+Return the element at index @var{i} of the uniform vector @var{v}.
address@hidden deffn
+
address@hidden Procedure s8vector-set! v i x
address@hidden Procedure u8vector-set! v i x
address@hidden Procedure s16vector-set! v i x
address@hidden Procedure u16vector-set! v i x
address@hidden Procedure s32vector-set! v i x
address@hidden Procedure u32vector-set! v i x
address@hidden Procedure s64vector-set! v i x
address@hidden Procedure u64vector-set! v i x
address@hidden Procedure f32vector-set! v i x
address@hidden Procedure f64vector-set! v i x
+Set the element at index @var{i} of uniform vector @var{v}
+to the value @var{x}, which must be a number coercible
+to the appropriate type.
address@hidden deffn
+
address@hidden Procedure s8vector->list v
address@hidden Procedure u8vector->list v
address@hidden Procedure s16vector->list v
address@hidden Procedure u16vector->list v
address@hidden Procedure s32vector->list v
address@hidden Procedure u32vector->list v
address@hidden Procedure s64vector->list v
address@hidden Procedure u64vector->list v
address@hidden Procedure f32vector->list v
address@hidden Procedure f64vector->list v
+Convert the uniform vetor @var{v} to a list containing the elments of @var{v}.
address@hidden deffn
+
address@hidden Procedure list->s8vector l
address@hidden Procedure list->u8vector l
address@hidden Procedure list->s16vector l
address@hidden Procedure list->u16vector l
address@hidden Procedure list->s32vector l
address@hidden Procedure list->u32vector l
address@hidden Procedure list->s64vector l
address@hidden Procedure list->u64vector l
address@hidden Procedure list->f32vector l
address@hidden Procedure list->f64vector l
+Create a uniform vector of the appropriate type, initializing it
+with the elements of the list @var{l}. The elements of @var{l}
+must be numbers coercible the new vector's element type.
address@hidden deffn
+
address@hidden Relationship with Java arrays
+
+Each uniform array type is implemented as an @dfn{underlying Java array},
+and a length field.
+The underlying type is
address@hidden for @code{u8vector} or @code{s8vector};
address@hidden for @code{u16vector} or @code{u16vector};
address@hidden for @code{u32vector} or @code{s32vector};
address@hidden for @code{u64vector} or @code{s64vector};
address@hidden for @code{f32vector}; and
address@hidden for @code{f32vector}.
+The length field allows a uniform array to only use the
+initial part of the underlying array. (This can be used
+to support Common Lisp's fill pointer feature.)
+This also allows resizing a uniform vector. There is no
+Scheme function for this, but you can use the @code{setSize} method:
address@hidden
+(invoke some-vector 'setSize 200)
address@hidden example
+
+If you have a Java array, you can create a uniform vector
+sharing with the Java array:
address@hidden
+(define arr :: byte[] ((primitive-array-new byte) 10))
+(define vec :: u8vector (make u8vector arr))
address@hidden example
+At this point @code{vec} uses @code{arr} for its underlying storage,
+so changes to one affect the other.
+It @code{vec} is re-sized so it needs a larger underlying array,
+then it will no longer use @code{arr}.
+
address@hidden Bytevectors
address@hidden Bytevectors
+
address@hidden represent blocks of binary data. They are
+fixed-length sequences of bytes, where a @var{byte} is an exact
+integer in the range [0, 255]. A bytevector is typically more
+space-efficient than a vector containing the same values.
+
+The length of a bytevector is the number of elements that
+it contains. This number is a non-negative integer that is
+fixed when the bytevector is created. The valid indexes of
+a bytevector are the exact non-negative integers less than
+the length of the bytevector, starting at index zero as with
+vectors.
+
+The @code{bytevector} type is equivalent to the @code{u8vector}
address@hidden vectors,uniform vector} type, but is specified
+by the R7RS standard.
+
+Bytevectors are written using the notation @code{#u8(byte . . . )}.
+For example, a bytevector of length 3 containing the byte
+0 in element 0, the byte 10 in element 1, and the byte 5 in
+element 2 can be written as following:
address@hidden
+#u8(0 10 5)
address@hidden example
+Bytevector constants are self-evaluating, so they do not
+need to be quoted in programs.
+
address@hidden Type bytevector
+The type of bytevector objects.
address@hidden deffn
+
address@hidden Constructor bytevector @var{byte} @dots{}
+Return a newly allocated bytevector whose elements contain the given
+arguments. Analogous to @code{vector}.
address@hidden
+(bytevector 1 3 5 1 3 5) @result{} #u8(1 3 5 1 3 5)
+(bytevector) @result{} #u8()
address@hidden example
address@hidden deffn
+
address@hidden Procedure bytevector? @var{obj}
+Return @true{} if @var{obj} is a bytevector, @false{} otherwise.
address@hidden deffn
+
address@hidden Procedure make-bytevector k
address@hidden Procedure make-bytevector k byte
+The @code{make-bytevector} procedure returns a newly allocated
+bytevector of length @var{k}. If @var{byte} is given, then all elements
+of the bytevector are initialized to @var{byte},
+otherwise the contents of each element are unspecified.
address@hidden
+(make-bytevector 2 12) @result{} #u8(12 12)
address@hidden example
address@hidden deffn
+
address@hidden Procedure bytevector-length bytevector
+Returns the length of @var{bytevector} in bytes
+as an exact integer.
address@hidden deffn
+
address@hidden Procedure bytevector-u8-ref bytevector k
+It is an error if @var{k} is not a valid index of @var{bytevector}.
+Returns the @var{k}th byte of @var{bytevector}.
address@hidden
+(bytevector-u8-ref ’#u8(1 1 2 3 5 8 13 21) 5)
+ @result{} 8
address@hidden example
address@hidden deffn
+
address@hidden Procedure bytevector-u8-set! bytevector k byte
+It is an error if @var{k} is not a valid index of @var{bytevector}.
+Stores @var{byte} as the @var{k}th byte of @var{bytevector}.
address@hidden
+(let ((bv (bytevector 1 2 3 4)
+ (bytevector-u8-set! bv 1 3)
+ bv)
+ @result{} #u8(1 3 3 4)
address@hidden example
address@hidden deffn
+
address@hidden Procedure bytevector-copy bytevector [start [end]]
+Returns a newly allocated bytevector containing the bytes
+in @var{bytevector} between @var{start} and @var{end}.
+
address@hidden
+(define a #u8(1 2 3 4 5))
+(bytevector-copy a 2 4))
+ @result{} #u8(3 4)
address@hidden example
address@hidden deffn
+
address@hidden Procedure bytevector-copy! to at from [start [end]]
+Copies the bytes of address@hidden between @var{start} and @var{end}
+to bytevector @var{to}, starting at @var{at}. The order in which bytes
+are copied is unspecified, except that if the source and destination overlap,
+copying takes place as if the source is first
+copied into a temporary bytevector and then into the destination.
+This is achieved without allocating storage
+by making sure to copy in the correct direction in such
+circumstances.
+
+It is an error if @var{at} is less than zero or greater than the length
+of @var{to}.
+It is also an error if @code{(- (bytevector-length @var{to}) @var{at})}
+is less than @code{(- @var{end} @var{start})}.
+
address@hidden
+(define a (bytevector 1 2 3 4 5))
+(define b (bytevector 10 20 30 40 50))
+(bytevector-copy! b 1 a 0 2)
+b @result{} #u8(10 1 2 40 50)
address@hidden example
address@hidden deffn
+
address@hidden Procedure bytevector-append bytevector...
+Returns a newly allocated bytevector whose elements are
+the concatenation of the elements in the given bytevectors.
+
address@hidden
+(bytevector-append #u8(0 1 2) #u8(3 4 5))
+ @result{} #u8(0 1 2 3 4 5)
address@hidden example
address@hidden deffn
+
address@hidden Converting to or from strings
+
address@hidden Procedure utf8->string bytevector [start [end]]
+This procedure decodes the bytes of a bytevector between @var{start}
+and @var{end}, interpreting as a UTF-8-encoded string,
+and returns the corresponding string.
+It is an error for @var{bytevector} to contain invalid UTF-8 byte sequences.
address@hidden
+(utf8->string #u8(#x41)) @result{} "A"
address@hidden example
address@hidden deffn
+
address@hidden Procedure utf16->string bytevector [start [end]]
address@hidden Procedure utf16be->string bytevector [start [end]]
address@hidden Procedure utf16le->string bytevector [start [end]]
+These procedures interpret their <var>bytevector</var> argument as
+a UTF-16 encoding of a sequence of characters,
+and return an istring containing that sequence.
+
+The bytevector subrange given to @code{utf16->string}
+may begin with a byte order mark (BOM); if so, that BOM
+determines whether the rest of the subrange is to be
+interpreted as big-endian or little-endian; in either case,
+the BOM will not become a character in the returned string.
+If the subrange does not begin with a BOM, it is decoded using
+the same implementation-dependent endianness used by
address@hidden>utf16}.
+
+The @code{utf16be->string} and @code{utf16le->string}
+procedures interpret their inputs as big-endian or little-endian,
+respectively. If a BOM is present, it is treated as a normal
+character and will become part of the result.
+
+It is an error if @code{(- @var{end} @var{start})} is odd,
+or if the bytevector subrange contains invalid UTF-16 byte sequences.
address@hidden deffn
+
address@hidden Procedure string->utf8 string [start [end]]
+This procedure encodes the characters of a string between
address@hidden and @var{end} and returns the corresponding bytevector,
+in UTF-8 encoding.
address@hidden
+(string->utf8 "λ") @result{} " #u8(#xCE #xBB)
address@hidden example
address@hidden deffn
+
address@hidden Procedure string->utf16 string [start [end]]
address@hidden Procedure string->utf16be string [start [end]]
address@hidden Procedure string->utf16le string [start [end]]
+These procedures return a newly allocated (unless empty)
+bytevector containing a UTF-16 encoding of the given substring.
+
+The bytevectors returned by @code{string->utf16be}
+and @code{string->utf16le}
+do not contain a byte-order mark (BOM);
address@hidden>utf16be}> returns a big-endian encoding,
+while @code{string->utf16le} returns a little-endian encoding.
+
+The bytevectors returned by @code{string->utf16}
+begin with a BOM that declares an implementation-dependent
+endianness, and the bytevector elements following that BOM
+encode the given substring using that endianness.
+
address@hidden:}
+These procedures are consistent with the Unicode standard.
+Unicode suggests UTF-16 should default to big-endian, but
+Microsoft prefers little-endian.
address@hidden deffn
+
address@hidden Ranges
address@hidden Ranges
+
+A @dfn{range} is an immutable sequence of values
+that increase ``linearly'' - i.e. by a fixed amount.
+Most commonly it's a sequence of consequtive integers.
+An example of the syntax is @code{[3 <: 7]} which evaluates
+to the sequence @code{[3 4 5 6]}.
+You can specify an explicit increment with a @code{by:} option.
+There are multiple ways to specify when the sequence stops.
+For example @code{[3 by 2 <=: 7]} is the even numbers from
+3 up to 7 (inclusive, because of the @code{<=}).
+
+Ranges are very useful for loop indexes, or selecting a sub-sequence.
+If you have a sequence @var{q} and a range @var{r}, and you
+use the syntax @code{(@var{q} @var{r})} to
+``apply''@var{q} with the argument @var{r},
+is result is to select elements of @var{q} with indexes in @var{r}.
address@hidden
+("ABCDEFG" [1 by: 2 <: 7]) @result{} "BDF"
address@hidden example
+
+A range can be @dfn{unbounded}, or non-finite, if you leave off
+the end value. For example @code{[3 by: 2]} is the odd integers starting at 3.
+
address@hidden
address@hidden
+ @stxlit{[} @var{start-expression} @stxlit{by:} @var{step-expression}
@stxlit{]}
+ | @stxlit{[} @var{start-expression} @stxlit{<:} @stxlit{]}
address@hidden display
+
+The expression @address@hidden by: @var{step}]} evaluates to an
+infinite sequence of values, starting with @var{start}, and followed by
address@hidden(+ @var{start} @var{step})},
address@hidden(+ @var{start} (* 2 @var{step}))}, and so on.
+
+The syntax @address@hidden <:]}
+is shorthand for @address@hidden by: 1]}.
+
address@hidden
address@hidden @stxlit{[} @var{start-expression} address@hidden:}
@var{step-expression}] @stxref{range-end} @stxlit{]}
address@hidden @stxlit{<:} @var{end-expression}
+ | @stxlit{<=:} @var{end-expression}
+ | @stxlit{>:} @var{end-expression}
+ | @stxlit{>=:} @var{end-expression}
+ | @stxlit{size:} @var{size-expression}
address@hidden display
+
+A bounded range takes an initial subsequence of the unbounded
+range specified by the @var{start-expression} and optional
@var{step-expression}.
+The different @var{end-expression} variants provide different
+ways to specify the initial subsequence.
+
+If @code{size: @var{size}} is specified, then the resulting range
+is the first @var{size} elements of unbounded sequence.
+
+In the @code{<: @var{end}} or @code{<=: @var{end}} cases then
+the sequence counts up: The @var{step} must be positive, and defaults to 1.
+The resulting values are those @var{x} such that @code{(< @var{x} @var{end})},
+or @code{(<= @var{x} @var{end})}, respectively.
+
+In the @code{>: @var{end}} or @code{>=: @var{end}} cases then
+the sequence counts down: The @var{step} must be negative, and defaults to -1.
+The resulting values are those @var{x} such that @code{(> @var{x} @var{end})},
+or @code{(>= @var{x} @var{end})}, respectively.
+
+The @var{start-expression}, @var{step-expression}, and @var{size-expression}
+must evaluate to real numbers, not necessarily integers.
+For example: @code{[1 by: 0.5 <=: 3.0]} is @code{[1.0 1.5 2.0 2.5 3.0]}.
+
+The two pseudo-ranges @code{[<:]} and @code{[>:]} are useful as
+array indexes. They mean ``all of the valid indexes'' of the array being
indexed.
+For increasing index values use @code{[<:]}; for decreasing
+index values (i.e. reversing) use @code{[>:]}.
+
address@hidden Streams
address@hidden Streams - lazy lists
+
+Streams, sometimes called lazy lists, are a sequential data structure
+containing elements computed only on demand. A stream is either null
+or is a pair with a stream in its cdr. Since elements of a stream are
+computed only when accessed, streams can be infinite. Once computed,
+the value of a stream element is cached in case it is needed again.
+
address@hidden:} These are not the same as Java 8 streams.
+
address@hidden
+(require 'srfi-41)
+(define fibs
+ (stream-cons 1
+ (stream-cons 1
+ (stream-map +
+ fibs
+ (stream-cdr fibs)))))
+(stream->list 8 fibs) @result{} (1 1 2 3 5 8 13 21)
address@hidden example
+
+See the @uref{http://srfi.schemers.org/srfi-41/srfi-41.html, SRFI 41
specification} for details.
+
+The Kawa implementations builds on @ref{Lazy evaluation,,promises}.
+The @code{stream-null} value is a promise that evaluates to the empty list.
+The result of @code{stream-cons} is an eager immutable pair whose
address@hidden and @code{cdr} properties return promises.
+
address@hidden Arrays
address@hidden Multi-dimensional Arrays
+
+Arrays are heterogeneous data structures that generaize vectors to multiple
+indexes or dimensions. Instead of a single integer index,
+there are multiple indexes: An index is a vector of integers;
+the length of a valid index sequence
+is the rank or the number of dimensions of an array.
+
address@hidden @example
address@hidden (define arr1 (
address@hidden @end example
+
+Kawa multi-dimensional arrays follows the
+by @uref{http://srfi.schemers.org/srfi-25/srfi-25.html,SRFI-25 specification},
+with additions from Racket's
address@hidden://docs.racket-lang.org/math/array.html, math.array} package
+and other sources.
+
+An array whose rank is 1, and where the (single) lower bound is 0
+is a sequence.
+Furthermore, if such an array is simple (not created by @code{share-array})
+it will be implemented using a @code{<vector>}.
+Uniform vectors and strings are also arrays in Kawa.
+
+A rank-0 array has a single value. It is essentially a box for that
+value. Functions that require arrays may treat non-arrays
+as a rank-0 array containing that value.
+
+An array of rank 2 is frequently called a @dfn{matrix}.
+
+Note that Kawa arrays are distinct from Java (native) arrays.
+The latter is a simpler one-dimensional vector-like data structure,
+which is used to implement Kawa arrays and vectors.
+
address@hidden Procedure array? obj
+Returns @code{#t} if @var{obj} is an array, otherwise returns @code{#f}.
address@hidden deffn
+
address@hidden Array shape
+
+The @dfn{shape} of an array consists of bounds for each index.
+
address@hidden a simple-array is either a SimpleVector or a GeneralArray
address@hidden a generic vector implements AVector
address@hidden a stored-array is a simple-array or a transform (view) of a
simple-array
+
+The lower bound @var{b} and the upper bound @var{e} of a dimension are
+exact integers with @code{(<= @var{b} @var{e})}. A valid index along the
+dimension is an exact integer @var{i} that satisfies both
address@hidden(<= @var{b} @var{i})} and @code{(< @var{i} @var{e})}.
+The length of the array along the dimension is the difference
address@hidden(- @var{e} @var{b})}.
+The size of an array is the product of the lengths of its dimensions.
+
+A procedure that requires a @var{shape} accepts any of the following:
address@hidden
address@hidden
+A vector of simple @ref{Ranges,ranges}, one for each
+dimension, all of who are
+bounded (finite), consist of integer values,
+and have a @var{step} of 1.
+Each range, which is usually written as @address@hidden <: @var{e}]},
+expresses the bounds of the corresponding dimension.
+For example @code{[[0 <: 5] [2 <=: 6]]} is the shape
+of a rank-2 array, where the first index can be from 0 to 5 (exclusive),
+while the second index can be from 2 to 6 (inclusive).
address@hidden
+A vector of simple integers.
+Each integer @var{e} is an upper bound,
+and is equivalent to the range @code{[0 <: @var{e}]}.
address@hidden
+A vector consisting of a mix of integers and ranges.
address@hidden
+A rank-2 array @var{S} whose own shape is @address@hidden 2]}.
+For each dimension @var{k}
+(where @code{(<= @var{k} 0)} and @code{(< @var{k} @var{r})}),
+the lower bound @address@hidden is @code{(S @var{k} 0)},
+and the upper bound @address@hidden is @code{(S @var{k} 1)}.
address@hidden itemize
+
address@hidden Procedure shape bound ...
+Returns a shape. The sequence @var{bound} ... must consist of an even number
+of exact integers that are pairwise not decreasing. Each pair gives the
+lower and upper bound of a dimension.
+If the shape is used to specify the dimensions of an array
+and @var{bound} ... is the sequence @var{b0} @var{e0} ... @var{bk} @var{ek}
+... of @var{n} pairs of bounds, then a valid index to the array is any
+sequence @var{j0} ... @var{jk} ... of @var{n} exact integers where
+each @var{jk} satisfies @code{(<= @var{bk} @var{jk})}
+and @code{(< @var{jk} @var{ek})}.
+
+The shape of a @var{d}-dimensional array is a @var{d} * 2 array
+where the element at @var{k 0} contains the lower bound for an index along
+dimension @var{k} and the element at @var{k 1} contains the
+corresponding upper bound, where @var{k} satisfies @code{(<= 0 @var{k})}
+and @code{(< @var{k} @var{d})}.
+
address@hidden(shape @@@var{bounds})}
+is equivalent to:
address@hidden(array [2 (/ (length @var{bounds}) 2)] @@@var{bounds})}
address@hidden deffn
+
address@hidden Procedure array-rank array
+Returns the number of dimensions of @var{array}.
address@hidden
+(array-rank
+ (make-array (shape 1 2 3 4)))
address@hidden example
+Returns 2.
address@hidden deffn
+
address@hidden Procedure array-start array k
+Returns the lower bound (inclusive) for the index along dimension @var{k}.
+This is most commonly 0.
address@hidden deffn
+
address@hidden Procedure array-end array k
+Returns the upper bound for the index along dimension @var{k}.
+The bound is exclusive - i.e. the first integer higher
+than the last legal index.
address@hidden deffn
+
address@hidden Procedure array-size array
+Return the total number of elements of @var{array}.
+This is the product of @code{(- (array-end @var{array} @var{k}) (array-start
@var{array} @var{k}))} for every valid @var{k}.
address@hidden deffn
+
address@hidden Array types
+
address@hidden Type array
address@hidden Type address@hidden
address@hidden Type address@hidden
address@hidden Type address@hidden@var{etype}]
+
+The type @code{array} matches all array values.
+The type @address@hidden, where @var{N} is an integer
+matches array of rank @var{N}.
+For example @code{array2} matches rank-2 array - i.e. matrixes.
+
+You can optionally specify the element type @var{etype}.
+This can be a primitive type.
+For example a @code{array2[double]} is a rank-2 array
+whose elements are @code{double} values.
address@hidden deffn
+
address@hidden
address@hidden Array literals and printing
+
+An array literal starts with @code{#} followed by its rank,
+followed by a tag that describes the underlying vector (by default @code{a}),
+optionally followed by information about its shape,
+and finally followed by the cells, organized into dimensions using parentheses.
+
+For example, @code{#2a((11 12 13) (21 22 23))} is a rank-2 array (a matrix)
+whose shape is @code{[2 3]} or equivalently @code{[[0 <: 2] [0 <: 3]]}.
+It is pretty-printed as:
address@hidden
+╔#2a:2:3═╗
+║11│12│13║
+╟──┼──┼──╢
+║21│22│23║
+╚══╧══╧══╝
address@hidden example
+
address@hidden
address@hidden @stxref{array-literal-header} @stxref{datum}
address@hidden @stxlit{#} @var{rank} @stxref{vectag} @address@hidden
address@hidden address@hidden@@address@hidden@stxlit{:address@hidden |
@stxlit{@@address@hidden
address@hidden @stxlit{a} | @stxref{uniform-tag}
address@hidden display
+
+The @var{vectag} specifies the type of the elements of the array.
+
+Following the @var{vectag} you can optionally include information
+about the shape: For each dimension you can optionally specify
+the lower bounds (after the character @code{"@@"}),
+followed by the length of the dimension (after the character @code{":"}).
+The shape information is required if a lower bound is non-zero,
+or any length is zero.
+
+The @stxref{datum} contains the elements in a nested-list format:
+a rank-1 array (i.e. vector) uses a single list,
+a rank-2 array uses a list-of-listrs, and so on.
+The elements are in lexicographic order.
+
+A uniform u32 array of rank 2 with index ranges 2..3 and 3..4:
address@hidden
+#2u32@@2@@3((1 2) (2 3))
address@hidden example
+
+This syntax follow Common Lisp with
address@hidden://www.gnu.org/software/guile/manual/html_node/Array-Syntax.html,Guile
+extensions}. (Note that Guile prints rank-0 arrays with an extra
+set of parentheses. Kawa follows Common Lisp in not doing so.)
+
+When an array is printed with the @code{write} function,
+the result is an @code{array-literal}.
+Printing with @code{display} formats the array in a rectangular grid
+using the @code{format-array} procedure.
+(Note that @code{format-array} is only used when the output is in column 0,
+because Kawa has very limited support for printing rectangles.)
+
address@hidden Procedure format-array value [element-format]
+Produce a nice ``pretty'' display for @var{value}, which is usually an array.
+
+The top line includes an @code{array-literal-header}.
+The lower bound are only printed if non-zero.
+The dimension lengths are printed if there is zoom, or if one of them is zero.
address@hidden
+#|kawa:34|# (! arr (array [[1 <=: 2] [1 <=: 3]]
+#|.....35|# #2a((1 2) (3 4)) 9 #2a((3 4) (5 6))
+#|.....36|# [42 43] #2a:1:3((8 7 6)) #2a((90 91) (100 101))))
+#|kawa:37|# arr
+╔#2a@@1:2@@1:3════╤═════════╗
+║#2a═╗ │ 9│#2a═╗ ║
+║║1│2║ │ │║3│4║ ║
+║╟─┼─╢ │ │╟─┼─╢ ║
+║║3│4║ │ │║5│6║ ║
+║╚═╧═╝ │ │╚═╧═╝ ║
+╟───────┼───────┼─────────╢
+║╔#1a:2╗│#2a:1:3│╔#2a:2:2╗║
+║║42│43║│║8│7│6║│║ 90│ 91║║
+║╚══╧══╝│╚═╧═╧═╝│╟───┼───╢║
+║ │ │║100│101║║
+║ │ │╚═══╧═══╝║
+╚═══════╧═══════╧═════════╝
address@hidden example
+If @var{element-format} is specified, it is a format string used
+for format each non-array:
address@hidden
+#|kawa:38|# (format-array arr "~4,2f")
+╔#2a@@1:2@@1:3══╤════════════════╤═══════════════╗
+║╔#2a:2:2══╗ │ 9.00│╔#2a:2:2══╗ ║
+║║1.00│2.00║ │ │║3.00│4.00║ ║
+║╟────┼────╢ │ │╟────┼────╢ ║
+║║3.00│4.00║ │ │║5.00│6.00║ ║
+║╚════╧════╝ │ │╚════╧════╝ ║
+╟─────────────┼────────────────┼───────────────╢
+║╔#1a:2╤═════╗│╔#2a:1:3══╤════╗│╔#2a:2:2══════╗║
+║║42.00│43.00║│║8.00│7.00│6.00║│║ 90.00│ 91.00║║
+║╚═════╧═════╝│╚════╧════╧════╝│╟──────┼──────╢║
+║ │ │║100.00│101.00║║
+║ │ │╚══════╧══════╝║
+╚═════════════╧════════════════╧═══════════════╝
address@hidden example
+If the rank is more than 2, then each ``layer''
+is printed separated by double lines.
address@hidden
+#|kawa:42|# (array-reshape [1 <=: 24] [3 2 4])
+╔#3a:3:2:4══╗
+║ 1│ 2│ 3│ 4║
+╟──┼──┼──┼──╢
+║ 5│ 6│ 7│ 8║
+╠══╪══╪══╪══╣
+║ 9│10│11│12║
+╟──┼──┼──┼──╢
+║13│14│15│16║
+╠══╪══╪══╪══╣
+║17│18│19│20║
+╟──┼──┼──┼──╢
+║21│22│23│24║
+╚══╧══╧══╧══╝
address@hidden example
address@hidden deffn
+
address@hidden Array construction
+
+See also @code{array-reshape}
+
address@hidden Procedure array shape obj ...
+Returns a new array whose shape is given by @var{shape} and the initial
+contents of the elements are @var{obj} ... in row major order. The array does
+not retain a reference to @var{shape}.
address@hidden deffn
+
address@hidden Procedure make-array shape
address@hidden Procedure make-array shape value...
+Returns a newly allocated array whose shape is given by @var{shape}.
+If @var{value} is provided, then each element is initialized to it.
+If there is more than one @var{value}, they are used in order, starting
+over then the @var{value}s are exhausted.
+If there is no @var{value}, the initial contents of each element is
+unspecified. (Actually, it is the @code{#!null}.)
+The array does not retain a reference to @var{shape}.
+
address@hidden
+#|kawa:16|# @kbd{(make-array [2 4] 1 2 3 4 5)}
+╔#2a:2:4╗
+║1│2│3│4║
+╟─┼─┼─┼─╢
+║5│1│2│3║
+╚═╧═╧═╧═╝
address@hidden example
+
address@hidden Guile has an incompatible @code{make-array} procedure.
address@hidden deffn
+
address@hidden Procedure build-array shape procedure
+Construct a ``virtual array'' of the given @var{shape},
+which uses no storage for the elements.
+Instead, elements are calculated on-demand by calling @var{procedure},
+which takes a single argument, an index vector.
+
+There is no caching or memoization.
+
address@hidden
+#|kawa:1|# @kbd{(build-array [[10 <: 12] 3]}
+#|....:2|# @kbd{ (lambda (ind)}
+#|....:3|# @kbd{ (let ((x (ind 0)) (y (ind 1)))}
+#|....:4|# @kbd{ (- x y))))}
+#2a@@10:2:3
+║10│ 9│8║
+╟──┼──┼─╢
+║11│10│9║
+╚══╧══╧═╝
address@hidden example
address@hidden deffn
+
address@hidden Procedure index-array shape
+Return a new immutable array of the specified @var{shape}
+where each element is the corresponding row-major index.
+Same as @code{(array-reshape [0 <: @var{size}] @var{shape})}
+where @var{size} is the @code{array-size} of the resulting array.
+
address@hidden
+#|kawa:1|# @kbd{(index-array [[1 <: 3] [2 <: 6]])}
+#2a@@1:2@@2:4
+║0│1│2│3║
+╟─┼─┼─┼─╢
+║4│5│6│7║
+╚═╧═╧═╧═╝
address@hidden example
+
address@hidden deffn
+
address@hidden Array indexing
+
+If you ``call'' an array as it it were a function,
+it is equivalent to using @code{array-index-ref},
+which is generalization of @code{array-ref}.
+For example, given a rank-2 array @var{arr} with integer indexes @var{i}
+and @var{j}, the following all get the element of @var{arr}
+at index @address@hidden @var{j}]}.
address@hidden
+(@var{arr} @var{i} @var{j})
+(array-index-ref @var{arr} @var{i} @var{j})
+(array-ref @var{arr} @var{i} @var{j})
+(array-ref @var{arr} address@hidden @var{j}])
address@hidden example
+
+Using function-call notation or @code{array-index-ref}
+(but not plain @code{array-ref}) you can do generalized APL-style
+slicing and indirect indexing.
+See under @code{array-index-ref} for examples.
+
address@hidden Procedure array-ref array k ...
address@hidden Procedure array-ref array index
+Returns the contents of the element of @var{array} at index @var{k} ....
+The sequence @var{k} ... must be a valid index to @var{array}.
+In the second form, @var{index} must be either a vector
+(a 0-based 1-dimensional array) containing @var{k} ....
address@hidden
+(array-ref (array [2 3]
+ 'uno 'dos 'tres
+ 'cuatro 'cinco 'seis)
+ 1 0)
address@hidden example
+Returns @code{cuatro}.
address@hidden
+(let ((a (array (shape 4 7 1 2) 3 1 4)))
+ (list (array-ref a 4 1)
+ (array-ref a (vector 5 1))
+ (array-ref a (array (shape 0 2)
+ 6 1))))
address@hidden example
+Returns @code{(3 1 4)}.
address@hidden deffn
+
address@hidden Procedure array-index-ref array index ...
+Generalized APL-style array indexing, where each @var{index}
+can be either an array or an integer.
+
+If each @var{index} is an integer, then the result is the same as
@code{array-ref}.
+
+Otherwise, the result is an immutable array whose rank is the sum of the ranks
of
+each @var{index}. An integer is treated as rank-0 array.
+
+If @var{marr} is the result of @code{(array-index-ref @var{arr}
@address@hidden @address@hidden ...)} then:
address@hidden
+(@var{marr} @address@hidden @address@hidden ... @address@hidden
@address@hidden ...)
address@hidden example
+is defined as:
address@hidden
+(@var{arr} (@address@hidden @address@hidden @address@hidden ...)
(@address@hidden @address@hidden @address@hidden ...) ...)
address@hidden example
+Each @address@hidden gets as many indexes as its rank.
+If @address@hidden is an integer, then it we use
+it directly without any indexing.
+
+Here are some examples, starting with simple indexing.
address@hidden
+#|kawa:1|# (define arr (array #2a((1 4) (0 4))
+#|.....2|# 10 11 12 13 20 21 22 23 30 31 32 33))
+#|kawa:3|# arr
+╔#2a@@1:3:4══╗
+║10│11│12│13║
+╟──┼──┼──┼──╢
+║20│21│22│23║
+╟──┼──┼──┼──╢
+║30│31│32│33║
+╚══╧══╧══╧══╝
+#|kawa:4|# (arr 2 3)
+23
address@hidden example
+If one index is a vector and the rest are scalar integers,
+then the result is a vector:
address@hidden
+#|kawa:5|# (arr 2 [3 1])
+#(23 21)
address@hidden example
+You can select a ``sub-matrix'' when all indexes are vectors:
address@hidden
+#|kawa:6|# (arr [2 1] [3 1 3])
+╔#2a:2:3═╗
+║23│21│23║
+╟──┼──┼──╢
+║13│11│13║
+╚══╧══╧══╝
address@hidden example
+Using ranges for index vectors selects a rectangular sub-matrix.
address@hidden
+#|kawa:7|# (arr [1 <: 3] [1 <: 4])
+╔#2a:2:3═╗
+║11│12│13║
+╟──┼──┼──╢
+║21│22│23║
+╚══╧══╧══╝
address@hidden example
+You can add new dimensions:
address@hidden
+#|kawa:8|# (arr [2 1] #2a((3 1) (3 2)))
+#3a╤══╗
+║23│21║
+╟──┼──╢
+║23│22║
+╠══╪══╣
+║13│11║
+╟──┼──╢
+║13│12║
+╚══╧══╝
address@hidden example
+The pseudo-range @code{[<:]} can be used to select all the indexes
+along a dimension. To select row 2 (1-origin):
address@hidden
+#|kawa:9|# (arr 2 [<:])
+#(20 21 22 23)
address@hidden example
+To reverse the order use @code{[>:]}:
address@hidden
+#|kawa:10|# (arr 2 [>:])
+#(23 22 21 20)
address@hidden example
+To select column 3:
address@hidden
+#|kawa:11|# (arr [<:] 3)
+#(13 23 33)
address@hidden example
+If you actually want a column matrix (i.e. with shape @code{[3 1]}
+you can write can place the index in a single-element vector:
address@hidden
+#|kawa:12|# (arr [<:] [3])
+#2a╗
+║13║
+╟──╢
+║23║
+╟──╢
+║33║
+╚══╝
address@hidden example
+To expand that column to 5 colums you can repeat the column index:
address@hidden
+#|kawa:13|# [3 by: 0 size: 5]
+#(3 3 3 3 3)
+#|kawa:14|# (arr [<:] [3 by: 0 size: 5])
+╔#2a:3:5═╤══╤══╗
+║13│13│13│13│13║
+╟──┼──┼──┼──┼──╢
+║23│23│23│23│23║
+╟──┼──┼──┼──┼──╢
+║33│33│33│33│33║
+╚══╧══╧══╧══╧══╝
address@hidden example
address@hidden deffn
+
address@hidden Modifying arrays
+
+You can use @code{set!} to modify one or multiple elements.
+To modify a single element:
address@hidden
+(set! (@var{arr} @var{index} ...) @var{new-value})
address@hidden example
+is equivalent to
address@hidden
+(array-set! @var{arr} @var{index} ... @var{new-value})
address@hidden example
+You can set a slice (or all of the elements).
+In that case:
address@hidden
+(set! (@var{arr} @var{index} ...) @var{new-array})
address@hidden example
+is equivalent to:
address@hidden
+(array-copy! (array-index-share @var{arr} @var{index} ...) @var{new-array})
address@hidden example
+
address@hidden Procedure array-set! array k ... obj
address@hidden Procedure array-set! array index obj
+Stores @var{obj} in the element of @var{array} at index @var{k} ....
+Returns the void value.
+The sequence @var{k} ... must be a valid index to @var{array}.
+In the second form, @var{index} must be either a vector or a
+0-based 1-dimensional array containing @var{k} ....
+
address@hidden
+(let ((a (make-array
+ (shape 4 5 4 5 4 5))))
+ (array-set! a 4 4 4 "huuhkaja")
+ (array-ref a 4 4 4))
address@hidden example
+Returns @code{"huuhkaja"}.
+
address@hidden SRFI-47, Guile and Scheme-48 have @code{array-set!} with a
+different argument order.
address@hidden deffn
+
address@hidden Procedure array-copy! dst src
address@hidden Guile has a @code{array-copy!} with the reversed
+argument order.
address@hidden deffn
+
address@hidden Procedure array-fill! array value
+Set all the values @var{array} to @var{value}.
address@hidden deffn
+
address@hidden Transformations and views
+
+A view or transform of an array is an array @address@hidden
+whose elements come from some other array @address@hidden,
+given some transform function @var{T} that maps @address@hidden indexes
+to @address@hidden indexes.
+Specifically @code{(array-ref @address@hidden @var{indexes})}
+is @code{(array-ref @address@hidden (@var{T} @var{indexes}))}.
+Modifying @address@hidden causes @address@hidden to be modified;
+modifying @address@hidden may modify @address@hidden
+(depending on the transform function).
+The shape of @address@hidden is in generally different than that of
@address@hidden
+
address@hidden Procedure array-transform array shape transform
+This is a general mechanism for creating a view.
+The result is a new array with the given @var{shape}.
+Accessing this new array is implemented by calling the @var{transform}
+function on the index vector, which must return a new index vector
+valid for indexing the original @var{array}.
+Here is an example (using the same @code{arr} as in
+the @code{array-index-ref} example):
address@hidden
+#|kawa:1|# (define arr (array #2a((1 4) (0 4))
+#|.....2|# 10 11 12 13 20 21 22 23 30 31 32 33))
+#|kawa:14|# (array-transform arr #2a((0 3) (1 3) (0 2))
+#|.....15|# (lambda (ix) (let ((i (ix 0)) (j (ix 1)) (k (ix 2)))
+#|.....16|# [(+ i 1)
+#|.....17|# (+ (* 2 (- j 1)) k)])))
+#3a:3@@1:2:2
+║10│11║
+╟──┼──╢
+║12│13║
+╠══╪══╣
+║20│21║
+╟──┼──╢
+║22│23║
+╠══╪══╣
+║30│31║
+╟──┼──╢
+║32│33║
+╚══╧══╝
address@hidden example
+
+The @code{array-transform} is generalization of @code{share-array},
+in that it does not require the @var{transform} to be affine.
+Also note the different calling conversions for the @var{tranform}:
address@hidden takes a single argument (a vector of indexes),
+and returns a single result (a vector of indexes);
address@hidden takes one argument for each index, and returns
+one value for each index. The difference is historical.
address@hidden deffn
+
address@hidden Procedure array-index-share array index ...
+This does the same generalized APL-style indexing
+as @code{array-index-ref}. However, the resulting array
+is a modifiable view into argument @var{array}.
address@hidden deffn
+
address@hidden Procedure array-reshape array shape
+Creates a new array @var{narray} of the given @var{shape},
+such that @code{(array->vector @var{array})} and
address@hidden(array->vector @var{narray})} are equivalent.
+I.e. the @var{i}'th element in row-major-order of @var{narray}
+is the @var{i}'th element in row-major-order of @var{array}.
+Hence @code{(array-size @var{narray})} (as specied from the @var{shape})
+must be equal to @code{(array-size @var{array})}.
+The resulting @var{narray} is a view such that modifying @var{array}
+also modifies @var{narray} and vice versa.
address@hidden deffn
+
address@hidden Procedure share-array array shape proc
+Returns a new array of @var{shape} shape that shares elements of @var{array}
+through @var{proc}. The procedure @var{proc} must implement an affine
+function that returns indices of @var{array} when given indices of the
+array returned by @code{share-array}.
+The array does not retain a reference to @var{shape}.
address@hidden
+(define i_4
+ (let* ((i (make-array
+ (shape 0 4 0 4)
+ 0))
+ (d (share-array i
+ (shape 0 4)
+ (lambda (k)
+ (values k k)))))
+ (do ((k 0 (+ k 1)))
+ ((= k 4))
+ (array-set! d k 1))
+ i))
address@hidden example
+
+Note: the affinity requirement for @var{proc} means that each value must
+be a sum of multiples of the arguments passed to @var{proc}, plus a constant.
+
+Implementation note: arrays have to maintain an internal index mapping
+from indices @var{k1} ... @var{kd} to a single index into a backing vector;
+the composition of this mapping and @var{proc} can be recognised
+as @code{(@var{+ n0} (* @var{n1} @var{k1}) ... (* @var{nd} @var{kd}))}
+by setting each index in turn to 1 and others to 0,
+and all to 0 for the constant term; the composition can then be compiled
+away, together with any complexity that the user introduced in their
+procedure.
+
+Here is an example where the @var{array} is a uniform vector:
address@hidden
+(share-array
+ (f64vector 1.0 2.0 3.0 4.0 5.0 6.0)
+ (shape 0 2 0 3)
+ (lambda (i j) (+ (* 2 i) j)))
+ @result{} #2f64((1.0 2.0 3.0) (4.0 5.0 6.0))
address@hidden example
address@hidden deffn
+
address@hidden Procedure array-flatten array
address@hidden Procedure array->vector array
+Return a vector consisting of the elements of the @var{array}
+in row-major-order.
+
+The result of @code{array-flatten} is fresh (mutable) copy, not a view.
+The result of @code{array->vector} is a view: If @var{array} is mutable,
+then modifying @var{array} changes the flattened result and vice versa.
+
+If @var{array} is ``simple'', @code{array->vector} returns the original
vector.
+Specifically, if @var{vec} is a vector then:
address@hidden
+(eq? @var{vec} (array->vector (array-reshape @var{vec} @var{shape})))
address@hidden example
address@hidden deffn
+
address@hidden Miscellaneous
+
address@hidden Procedure format-array value [element-format]
address@hidden deffn
+
address@hidden Hash tables
address@hidden Hash tables
+
+A @dfn{hashtable} is a data structure that
+associates keys with values.
+The hashtable has no intrinsic order for the (key, value) associations
+it contains, and
+supports in-place modification as the primary means of setting the contents
+of a hash table.
+Any object can be used as a key, provided a @dfn{hash function} and a suitable
address@hidden function} is available.
+A hash function is a procedure that
+maps keys to exact integer objects.
+
+The hashtable provides key lookup and destructive update in amortised
+constant time, provided that a good hash function is used.
+A hash function @var{h} is acceptable for an equivalence predicate @var{e} iff
address@hidden(@var{e} @var{obj1} @var{obj2})} implies
address@hidden(= (@var{h} @var{obj1}) (@var{h} @var{obj2}))}.
+A hash function @var{h} is good for a equivalence predicate @var{e} if
+it distributes the resulting hash values for non-equal objects
+(by @var{e}) as uniformly as possible over the range of hash
+values, especially in the case when some (non-equal) objects resemble
+each other by e.g. having common subsequences. This definition is
+vague but should be enough to assert that e.g. a constant function is
+not a good hash function.
+
+Kawa provides two complete sets of functions for hashtables:
address@hidden
address@hidden
+The functions specified by R6RS have names starting with @code{hashtable-}
address@hidden
+The functions specified by the older
address@hidden://srfi.schemers.org/srfi-69/srfi-69.html, SRFI-69} specifiation
+have names starting with @code{hash-table-}
address@hidden itemize
+
+Both interfaces use the same underlying datatype, so it is possible
+to mix and match from both sets.
+That datatype implements @code{java.util.Map}.
address@hidden The Kawa implementation has been optimized for performance and
better
address@hidden Java integration. Specifically, the default hash function uses
address@hidden the standard Java @code{hashCode} method.
+Freshly-written code should probably use the R6RS functions.
+
address@hidden R6RS hash tables
+
+To use these hash table functions in your Kawa program you must first:
+
address@hidden
+(import (rnrs hashtables))
address@hidden example
+
+This section uses the @var{hashtable} parameter name for arguments that
+must be hashtables, and the @var{key} parameter name for arguments that
+must be hashtable keys.
+
address@hidden Procedure make-eq-hashtable
address@hidden Procedure make-eq-hashtable @var{k}
+Return a newly allocated mutable hashtable that accepts arbitrary
+objects as keys, and compares those keys with @func{eq?}. If an
+argument is given, the initial capacity of the hashtable is set to
+approximately @var{k} elements.
address@hidden deffn
+
+
address@hidden Procedure make-eqv-hashtable
address@hidden Procedure make-eqv-hashtable @var{k}
+Return a newly allocated mutable hashtable that accepts arbitrary
+objects as keys, and compares those keys with @func{eqv?}. If an
+argument is given, the initial capacity of the hashtable is set to
+approximately @var{k} elements.
address@hidden deffn
+
address@hidden Procedure make-hashtable @var{hash-function} @var{equiv}
address@hidden Procedure make-hashtable @var{hash-function} @var{equiv} @var{k}
address@hidden and @var{equiv} must be procedures.
address@hidden should accept a key as an argument and should return
+a non--negative exact integer object. @var{equiv} should accept two
+keys as arguments and return a single value. Neither procedure should
+mutate the hashtable returned by @func{make-hashtable}.
+
+The @func{make-hashtable} procedure returns a newly allocated mutable
+hashtable using @var{hash-function} as the hash function and @var{equiv}
+as the equivalence function used to compare keys. If a third argument
+is given, the initial capacity of the hashtable is set to approximately
address@hidden elements.
+
+Both @var{hash-function} and @var{equiv} should behave like pure
+functions on the domain of keys. For example, the @func{string-hash}
+and @func{string=?} procedures are permissible only if all keys are
+strings and the contents of those strings are never changed so long as
+any of them continues to serve as a key in the hashtable. Furthermore,
+any pair of keys for which @var{equiv} returns true should be hashed to
+the same exact integer objects by @var{hash-function}.
+
address@hidden
address@hidden:} Hashtables are allowed to cache the results of calling the
+hash function and equivalence function, so programs cannot rely on the
+hash function being called for every lookup or update. Furthermore any
+hashtable operation may call the hash function more than once.
address@hidden quotation
address@hidden deffn
+
address@hidden Procedures
+
address@hidden Procedure {hashtable?} @var{obj}
+Return @true{} if @var{obj} is a hashtable, @false{} otherwise.
address@hidden deffn
+
address@hidden Procedure hashtable-size @var{hashtable}
+Return the number of keys contained in @var{hashtable} as an exact
+integer object.
address@hidden deffn
+
address@hidden Procedure hashtable-ref @var{hashtable} @var{key} @var{default}
+Return the value in @var{hashtable} associated with @var{key}. If
address@hidden does not contain an association for @var{key},
address@hidden is returned.
address@hidden deffn
+
address@hidden Procedure {hashtable-set!} @var{hashtable} @var{key} @var{obj}
+Change @var{hashtable} to associate @var{key} with @var{obj}, adding a
+new association or replacing any existing association for @var{key}, and
+returns unspecified values.
address@hidden deffn
+
address@hidden Procedure {hashtable-delete!} @var{hashtable} @var{key}
+Remove any association for @var{key} within @var{hashtable} and returns
+unspecified values.
address@hidden deffn
+
address@hidden Procedure {hashtable-contains?} @var{hashtable} @var{key}
+Return @true{} if @var{hashtable} contains an association for @var{key},
address@hidden otherwise.
address@hidden deffn
+
address@hidden Procedure {hashtable-update!} @var{hashtable} @var{key}
@var{proc} @var{default}
address@hidden should accept one argument, should return a single value, and
+should not mutate @var{hashtable}.
+
+The @func{hashtable-update!} procedure applies @var{proc} to the value
+in @var{hashtable} associated with @var{key}, or to @var{default} if
address@hidden does not contain an association for @var{key}. The
address@hidden is then changed to associate @var{key} with the value
+returned by @var{proc}.
+
+The behavior of @func{hashtable-update!} is equivalent to the following
+code, but is may be (and is in Kawa) implemented more efficiently in cases
+where the implementation can avoid multiple lookups of the same key:
+
address@hidden
+(hashtable-set!
+ hashtable key
+ (proc (hashtable-ref
+ hashtable key default)))
address@hidden example
address@hidden deffn
+
+
address@hidden Procedure hashtable-copy @var{hashtable}
address@hidden Procedure hashtable-copy @var{hashtable} @var{mutable}
+Return a copy of @var{hashtable}. If the @var{mutable} argument is
+provided and is true, the returned hashtable is mutable; otherwise it is
+immutable.
address@hidden deffn
+
address@hidden Procedure {hashtable-clear!} @var{hashtable}
address@hidden Procedure {hashtable-clear!} @var{hashtable} @var{k}
+Remove all associations from @var{hashtable} and returns unspecified
+values.
+
+If a second argument is given, the current capacity of the hashtable is
+reset to approximately @var{k} elements.
address@hidden deffn
+
address@hidden Procedure hashtable-keys @var{hashtable}
+Return a vector of all keys in @var{hashtable}. The order of the vector
+is unspecified.
address@hidden deffn
+
address@hidden Procedure hashtable-entries @var{hashtable}
+Return two values, a vector of the keys in @var{hashtable}, and a vector
+of the corresponding values.
+
+Example:
+
address@hidden
+(let ((h (make-eqv-hashtable)))
+ (hashtable-set! h 1 'one)
+ (hashtable-set! h 2 'two)
+ (hashtable-set! h 3 'three)
+ (hashtable-entries h))
address@hidden #(1 2 3) #(one two three) ; two return values
address@hidden example
+
address@hidden
+the order of the entries in the result vectors is not known.
address@hidden deffn
+
address@hidden Inspection
+
address@hidden Procedure hashtable-equivalence-function @var{hashtable}
+Return the equivalence function used by @var{hashtable} to compare keys.
+For hashtables created with @func{make-eq-hashtable} and
address@hidden, returns @func{eq?} and @func{eqv?}
+respectively.
address@hidden deffn
+
address@hidden Procedure hashtable-hash-function @var{hashtable}
+Return the hash function used by @var{hashtable}. For hashtables
+created by @func{make-eq-hashtable} or @func{make-eqv-hashtable},
address@hidden is returned.
address@hidden deffn
+
address@hidden Procedure {hashtable-mutable?} @var{hashtable}
+Return @true{} if @var{hashtable} is mutable, otherwise @false{}.
address@hidden deffn
+
address@hidden Hash functions
+
+The @func{equal-hash}, @func{string-hash}, and @func{string-ci-hash}
+procedures of this section are acceptable as the hash functions of a
+hashtable only if the keys on which they are called are not mutated
+while they remain in use as keys in the hashtable.
+
address@hidden Procedure equal-hash @var{obj}
+Return an integer hash value for @var{obj}, based on its structure and
+current contents. This hash function is suitable for use with
address@hidden as an equivalence function.
address@hidden
address@hidden:} Like @func{equal?}, the @func{equal-hash} procedure must
+always terminate, even if its arguments contain cycles.
address@hidden quotation
address@hidden deffn
+
address@hidden Procedure string-hash @var{string}
+Return an integer hash value for @var{string}, based on its current
+contents. This hash function is suitable for use with @func{string=?}
+as an equivalence function.
address@hidden deffn
+
address@hidden Procedure string-ci-hash @var{string}
+Return an integer hash value for @var{string} based on its current
+contents, ignoring case. This hash function is suitable for use with
address@hidden as an equivalence function.
address@hidden deffn
+
address@hidden Procedure symbol-hash @var{symbol}
+Return an integer hash value for @var{symbol}.
address@hidden deffn
+
+
address@hidden SRFI-69 hash tables
+
+To use these hash table functions in your Kawa program you must first:
address@hidden
+(require 'srfi-69)
address@hidden example
+or
address@hidden
+(require 'hash-table)
address@hidden example
+or
address@hidden
+(import (srfi 69 basic-hash-tables))
address@hidden example
+
address@hidden Type constructors and predicate
address@hidden Procedure make-hash-table [ equal? [ hash [ size-hint]]] →
hash-table
+
+Create a new hash table with no associations.
+The @var{equal?} parameter is a predicate
+that should accept two keys and return a boolean telling whether they
+denote the same key value; it defaults to the @code{equal?} function.
+
+The @var{hash} parameter is a hash function, and defaults to an
+appropriate hash function
+for the given @var{equal?} predicate (see the Hashing section).
+However, an
+acceptable default is not guaranteed to be given for any equivalence
+predicate coarser than @code{equal?}, except for @code{string-ci=?}.
+(The function @code{hash} is acceptable for @code{equal?}, so if you
+use coarser equivalence than @code{equal?} other than @code{string-ci=?},
+you must always provide the function hash yourself.)
+(An equivalence predicate @var{c1} is coarser than a equivalence
+predicate @var{c2} iff there exist values @var{x} and @var{y} such
+that @code{(and (@var{c1} @var{x} @var{y}) (not (@var{c2} @var{x} @var{y})))}.)
+
+The @var{size-hint} parameter can be used to suggested an approriate
+initial size. This option is not part of the SRFI-69 specification
+(though it is handled by the reference implementation), so specifying
+that option might be unportable.
address@hidden deffn
+
address@hidden Procedure hash-table? obj → boolean
+A predicate to test whether a given object @var{obj} is a hash table.
address@hidden deffn
+
address@hidden Procedure alist->hash-table alist [ equal? [ hash [ size-hint]]]
→ hash-table
+
+Takes an association list @var{alist} and creates a hash table
address@hidden which maps the @code{car} of every element in
address@hidden to the @code{cdr} of corresponding elements in
address@hidden The @var{equal?}, @var{hash}, and @var{size-hint}
+parameters are interpreted as in @code{make-hash-table}. If some key
+occurs multiple times in @var{alist}, the value in the first
+association will take precedence over later ones. (Note: the choice of
+using @code{cdr} (instead of @code{cadr}) for values tries to strike
+balance between the two approaches: using @var{cadr} would render this
+procedure unusable for @code{cdr} alists, but not vice versa.)
address@hidden deffn
+
address@hidden Reflective queries
address@hidden Procedure hash-table-equivalence-function hash-table
+Returns the equivalence predicate used for keys of @var{hash-table}.
address@hidden deffn
+
address@hidden Procedure hash-table-hash-function hash-table
+Returns the hash function used for keys of @var{hash-table}.
address@hidden deffn
+
address@hidden Dealing with single elements
address@hidden Procedure hash-table-ref hash-table key [ thunk ] → value
+This procedure returns the value associated to @var{key} in
address@hidden If no value is associated to @var{key} and
address@hidden is given, it is called with no arguments and its value is
+returned; if @var{thunk} is not given, an error is signalled. Given a
+good hash function, this operation should have an (amortised) complexity
+of O(1) with respect to the number of associations in @var{hash-table}.
address@hidden deffn
+
address@hidden Procedure hash-table-ref/default hash-table key default → value
+Evaluates to the same value as @code{(hash-table-ref @var{hash-table}
address@hidden (lambda () @var{default}))}. Given a good hash function, this
+operation should have an (amortised) complexity of O(1) with respect
+to the number of associations in hash-table.
address@hidden deffn
+
address@hidden Procedure hash-table-set! hash-table key value → void
+This procedure sets the value associated to @var{key} in
address@hidden The previous association (if any) is removed. Given
+a good hash function, this operation should have an (amortised)
+complexity of O(1) with respect to the number of associations in
+hash-table.
address@hidden deffn
+
address@hidden Procedure hash-table-delete! hash-table key → void
+This procedure removes any association to @var{key} in
address@hidden It is not an error if no association for the
address@hidden exists; in this case, nothing is done. Given a good hash
+function, this operation should have an (amortised) complexity of O(1)
+with respect to the number of associations in hash-table.
address@hidden deffn
+
address@hidden Procedure hash-table-exists? hash-table key → boolean
+This predicate tells whether there is any association to @var{key} in
address@hidden Given a good hash function, this operation should
+have an (amortised) complexity of O(1) with respect to the number of
+associations in hash-table.
address@hidden deffn
+
address@hidden Procedure hash-table-update! hash-table key function [ thunk ] →
void
+Semantically equivalent to, but may be implemented more efficiently than,
+the following code:
address@hidden
+(hash-table-set! @var{hash-table key}
+ (function (hash-table-ref @var{hash-table} @var{key}
@var{thunk})))
address@hidden example
address@hidden deffn
+
address@hidden Procedure hash-table-update!/default hash-table key function
default → void
+Behaves as if it evaluates to
address@hidden(hash-table-update! @var{hash-table} @var{key} @var{function}
(lambda () @var{default}))}.
address@hidden deffn
+
address@hidden Dealing with the whole contents
+
address@hidden Procedure hash-table-size hash-table → integer
+Returns the number of associations in @var{hash-table}. This operation takes
+constant time.
address@hidden deffn
+
address@hidden Procedure hash-table-keys hash-table → list
+Returns a list of keys in @var{hash-table}.
+The order of the keys is unspecified.
address@hidden deffn
+
address@hidden Procedure hash-table-values hash-table → list
+Returns a list of values in @var{hash-table}. The order of the values is
+unspecified, and is not guaranteed to match the order of keys in the
+result of @code{hash-table-keys}.
address@hidden deffn
+
address@hidden Procedure hash-table-walk hash-table proc → void
address@hidden should be a function taking two arguments, a key and a
+value. This procedure calls @var{proc} for each association in
address@hidden, giving the key of the association as key and the
+value of the association as value. The results of @var{proc} are
+discarded. The order in which @var{proc} is called for the different
+associations is unspecified.
address@hidden deffn
+
address@hidden Procedure hash-table-fold hash-table f init-value → final-value
+This procedure calls @var{f} for every association in @var{hash-table}
+with three arguments: the key of the association key, the value of the
+association value, and an accumulated value, @var{val}. The @var{val}
+is @var{init-value} for the first invocation of @var{f}, and for
+subsequent invocations of @var{f}, the return value of the previous
+invocation of @var{f}. The value @var{final-value} returned by
address@hidden is the return value of the last invocation of
address@hidden The order in which @var{f} is called for different
+associations is unspecified.
address@hidden deffn
+
address@hidden Procedure hash-table->alist hash-table → alist
+Returns an association list such that the @code{car} of each element
+in @var{alist} is a key in @var{hash-table} and the corresponding
address@hidden of each element in @var{alist} is the value associated to
+the key in @var{hash-table}. The order of the elements is unspecified.
+
+The following should always produce a hash table with the same mappings
+as a hash table @var{h}:
address@hidden
+(alist->hash-table (hash-table->alist @var{h})
+ (hash-table-equivalence-function @var{h})
+ (hash-table-hash-function @var{h}))
address@hidden example
address@hidden deffn
+
address@hidden Procedure hash-table-copy hash-table → hash-table
+Returns a new hash table with the same equivalence predicate, hash
+function and mappings as in @var{hash-table}.
address@hidden deffn
+
address@hidden Procedure hash-table-merge! hash-table1 hash-table2 → hash-table
+Adds all mappings in @var{hash-table2} into @var{hash-table1} and
+returns the resulting hash table. This function may modify
address@hidden destructively.
address@hidden deffn
+
address@hidden Hash functions
+
+The Kawa implementation always calls these hash functions with a single
+parameter, and expects the result to be within the entire
+(32-bit signed) @code{int} range, for compatibility with
+standard @code{hashCode} methods.
+
address@hidden Procedure hash object [ bound ] → integer
+Produces a hash value for object in the range from 0 (inclusive) tp to
address@hidden (exclusive).
+
+If @var{bound} is not given, the Kawa implementation returns a value within
+the range @address@hidden(- (expt 2 32))}} (inclusive)
+to @address@hidden(- (expt 2 32) 1)}} (inclusive).
+It does this by calling the standard @code{hashCode} method,
+and returning the result as is.
+(If the @var{object} is the Java @code{null} value, 0 is returned.)
+This hash function is acceptable for @code{equal?}.
address@hidden deffn
+
address@hidden Procedure string-hash string [ bound ] → integer
+The same as @code{hash}, except that the argument string must be a string.
+(The Kawa implementation returns the same as the @code{hash} function.)
address@hidden deffn
+
address@hidden Procedure string-ci-hash string [ bound ] → integer
+The same as @code{string-hash}, except that the case of characters in
+string does not affect the hash value produced.
+(The Kawa implementation returns the same the @code{hash} function
+applied to the lower-cased @var{string}.)
address@hidden deffn
+
address@hidden Procedure hash-by-identity object [ bound ] → integer
+The same as @code{hash}, except that this function is only guaranteed
+to be acceptable for @code{eq?}.
+Kawa uses the @code{identityHashCode} method of @code{java.lang.System}.
address@hidden deffn
+
+
address@hidden Eval and Environments
address@hidden Eval and Environments
+
address@hidden Procedure environment @arbno{list}
+This procedure returns a specifier for the environment that
+results by starting with an empty environment and then
+importing each @var{list}, considered as an @stxref{import-set}, into it.
+The bindings of the environment represented by the specifier
+are immutable, as is the environment itself.
+See the @code{eval} function for examples.
address@hidden deffn
+
address@hidden Procedure null-environment version
+This procedure returns an environment that contains no variable bindings,
+but contains (syntactic) bindings for all the syntactic keywords.
+
+The effect of assigning to a variable in this environment (such
+as @code{let}) is undefined.
address@hidden deffn
+
address@hidden Procedure scheme-report-environment version
+The @var{version} must be an exact non-negative inetger corresponding to
+a version of one of the address@hidden Reports on Scheme.
+The procedure returns an environment that contains exactly the set of
+bindings specified in the corresponding report.
+
+This implementation supports @var{version} that is 4 or 5.
+
+The effect of assigning to a variable in this environment (such
+as @code{car}) is undefined.
address@hidden deffn
+
address@hidden Procedure interaction-environment
+This procedure return an environment that contains implementation-defined
+bindings, as well as top-level user bindings.
address@hidden deffn
+
address@hidden Procedure environment-bound? environment symbol
+Return true @code{#t} if there is a binding for @var{symbol}
+in @var{environment}; otherwise returns @code{#f}.
address@hidden deffn
+
address@hidden Syntax fluid-let ((variable init) ...) body ...
+Evaluate the @var{init} expressions.
+Then modify the dynamic bindings for the @var{variables} to the
+values of the @var{init} expressions, and evaluate the @var{body} expressions.
+Return the result of the last expression in @var{body}.
+Before returning, restore the original bindings.
+The temporary bindings are only visible in the current thread, and its
+descendent threads.
address@hidden deffn
+
address@hidden Procedure base-uri [node]
+If @var{node} is specified, returns the base-URI property
+of the @var{node}. If the @var{node} does not have the base-URI
+property, returns @code{#f}.
+(The XQuery version returns the empty sequence in that case.)
+
+In the zero-argument case, returns the "base URI" of the current context.
+By default the base URI is the current working directory (as a URL).
+While a source file is @code{load}ed, the base URI is temporarily
+set to the URL of the document.
address@hidden deffn
+
address@hidden Procedure eval expression [environment]
+This procedure evaluates @var{expression} in the environment indicated
+by @var{environment}.
+The default for @var{environment} is the result
+of @code{(interaction-environment)}.
+
address@hidden
+(eval ’(* 7 3) (environment '(scheme base)))
+ @result{} 21
+
+(let ((f (eval '(lambda (f x) (f x x))
+ (null-environment 5))))
+ (f + 10))
+ @result{} 20
+
+(eval '(define foo 32) (environment '(scheme base)))
+ @result{} @i{error is signaled}
address@hidden example
address@hidden deffn
+
address@hidden Procedure load path [environment]
address@hidden Procedure load-relative path [environment]
+The @var{path} can be an (absolute) URL or a filename
+of a source file, which is read and evaluated line-by-line.
+The @var{path} can also be a fully-qualified class name.
+(Mostly acts like the @code{-f} command-line option,
+but with different error handling.)
+Since @code{load} is a run-time function it doesn't know
+about the enclosing lexical environment, and the latter
+can't know about definitions introduced by @code{load}.
+For those reasons it is highly recommended that you use instead use
address@hidden@ref{require, require}} or @address@hidden, include}}.
+
+Evaluation is done in the specified @var{environment},
+which defauls to result of @code{(interaction-environment)}.
+
+The @code{load-relative} procedure is like @code{load},
+except that @var{path} is a
+URI that is relative to the context's current base URI.
address@hidden deffn
+
address@hidden
+* Locations::
+* Parameter objects::
address@hidden menu
+
address@hidden Locations, Parameter objects, , Eval and Environments
address@hidden Locations
+
+A @dfn{location} is a place where a value can be stored.
+An @dfn{lvalue} is an expression that refers to a location.
+(The name "lvalue" refers to the fact that the left operand
+of @code{set!} is an lvalue.)
+The only kind of lvalue in standard Scheme is a @dfn{variable}.
+Kawa also allows @dfn{computed lvalues}. These are procedure
+calls used in "lvalue context", such as the left operand of @code{set!}.
+
+You can only use procedures that have an associated @dfn{setter}.
+In that case, @code{(set! (f arg ...) value)}
+is equivalent to @code{((setter f) arg ... value)}
+Currently, only a few procedures have associated @code{setter}s,
+and only builtin procedures written in Java can have @code{setter}s.
+
+For example:
address@hidden
+(set! (car x) 10)
address@hidden example
+is equivalent to:
address@hidden
+((setter car) x 10)
address@hidden example
+which is equivalent to:
address@hidden
+(set-car! x 10)
address@hidden example
+
address@hidden Procedure setter procedure
+Gets the "setter procedure" associated with a "getter procedure".
+Equivalent to @code{(procedure-property @var{procedure} 'setter)}.
+By convention, a setter procedure takes the same parameters as
+the "getter" procedure, plus an extra parameter that is the
+new value to be stored in the location specified by the parameters.
+The expectation is that following
address@hidden((setter @var{proc}) @var{args} ... @var{value})} then
+the value of @code{(@var{proc} @var{args} ...)} will be @var{value}.
+
+The @code{setter} of @code{setter} can be used to set the
address@hidden property.
+For example the Scheme prologue effectively does the following:
address@hidden
+(set! (setter vector-set) vector-set!)
address@hidden example
address@hidden deffn
+
+Kawa also gives you access to locations as first-class values:
+
address@hidden Syntax location lvalue
+Returns a location object for the given @var{lvalue}.
+You can get its value (by applying it, as if it were a procedure),
+and you can set its value (by using @code{set!} on the application).
+The @var{lvalue} can be a local or global variable, or a procedure
+call using a procedure that has a @code{setter}.
address@hidden
+(define x 100)
+(define lx (location x))
+(set! (lx) (cons 1 2)) ;; set x to (1 . 2)
+(lx) ;; returns (1 . 2)
+(define lc (location (car x)))
+(set! (lc) (+ 10 (lc)))
+;; x is now (11 . 2)
address@hidden example
address@hidden deffn
+
address@hidden Syntax define-alias variable lvalue
+Define @var{variable} as an alias for @var{lvalue}.
+In other words, makes it so that @code{(location @var{variable})}
+is equivalent to @code{(location @var{lvalue})}.
+This works both top-level and inside a function.
address@hidden deffn
+
address@hidden Syntax define-private-alias variable lvalue
+Same as @code{define-alias}, but the @var{variable}
+is local to the current module.
address@hidden deffn
+
+Some people might find it helpful to think of a location
+as a settable @dfn{thunk}. Others may find it useful to
+think of the @code{location} syntax as similar to the C @samp{&} operator;
+for the @samp{*} indirection operator, Kawa uses procedure application.
+
+You can use @code{define-alias} to define a shorter type synonym,
+similar to Java's @code{import TypeName} (single-type-import) declaration:
address@hidden
+(define-alias StrBuf java.lang.StringBuffer)
address@hidden example
+
address@hidden Parameter objects, , Locations, Eval and Environments
address@hidden Parameter objects
+
+A parameter object is a procedure that is bound to a location,
+and may optionally have a conversion procedure.
+The procedure accepts zero or one argument.
+When the procedure is called with zero arguments,
+the content of the location is returned.
+On a call with one argument the content of the location
+is updated with the result of applying the parameter object's conversion
+procedure to the argument.
+
+Parameter objects are created with the @code{make-parameter} procedure
+which takes one or two arguments. The second argument is a one
+argument conversion procedure. If only one argument is passed to
+make-parameter the identity function is used as a conversion
+procedure.
+A new location is created and asociated with the
+parameter object. The initial content of the location is the
+result of applying the conversion procedure to the first argument of
+make-parameter.
+
+Note that the conversion procedure can be used for guaranteeing the
+type of the parameter object's binding and/or to perform some
+conversion of the value.
+
+The @code{parameterize} special form, when given a parameter object
+and a value, binds the parameter
+object to a new location for the dynamic extent of its body.
+The initial content of the location is the result of
+applying the parameter object's conversion procedure to the value. The
address@hidden special form behaves analogously to @code{let}
+when binding more than one parameter object (that is the order of
+evaluation is unspecified and the new bindings are only visible in the
+body of the parameterize special form).
+
+When a new thread is created using @code{future} or @code{runnable}
+then the child thread inherits initial values from its parent.
+Once the child is running, changing the value in the child does not
+affect the value in the parent or vice versa.
+(In the past this was not the case: The child would share a location
+with the parent except within a @code{parameterize}.
+This was changed to avoid unsafe and inefficient coupling between threads.)
+
+Note that @code{parameterize} and @code{fluid-let} have similar
+binding and sharing behavior.
+The difference is that @code{fluid-let} modifies locations
+accessed by name, while @code{make-parameter} and @code{parameterize}
+create anonymous locations accessed by calling a parameter procedure.
+
+The R5RS procedures @code{current-input-port} and @code{current-output-port}
+are parameter objects.
+
address@hidden Procedure make-parameter init [converter]
+
+Returns a new parameter object which is bound in the global dynamic
+environment to a location containing the value returned by the call
address@hidden(@var{converter} @var{init})}. If the conversion procedure
+converter is not specified the identity function is used instead.
+
+The parameter object is a procedure which accepts zero or one
+argument. When it is called with no argument, the content of the
+location bound to this parameter object in the current dynamic
+environment is returned. When it is called with one argument, the
+content of the location is set to the result of the call
address@hidden(@var{converter} @var{arg})}, where @var{arg} is the argument
+passed to the parameter object, and an unspecified value is returned.
+
address@hidden
+(define radix
+ (make-parameter 10))
+
+(define write-shared
+ (make-parameter
+ #f
+ (lambda (x)
+ (if (boolean? x)
+ x
+ (error "only booleans are accepted by write-shared")))))
+
+(radix) @result{} 10
+(radix 2)
+(radix) @result{} 2
+(write-shared 0) gives an error
+
+(define prompt
+ (make-parameter
+ 123
+ (lambda (x)
+ (if (string? x)
+ x
+ (with-output-to-string (lambda () (write x)))))))
+
+(prompt) @result{} "123"
+(prompt ">")
+(prompt) @result{} ">"
address@hidden example
address@hidden deffn
+
address@hidden
address@hidden Syntax parameterize ((expr1 expr2) ...) @stxref{body}
+The expressions @var{expr1} and @var{expr2} are evaluated in an
+unspecified order. The value of the @var{expr1} expressions must be
+parameter objects. For each @var{expr1} expression and in an
+unspecified order, the local dynamic environment is extended with a
+binding of the parameter object @var{expr1} to a new location whose
+content is the result of the call @code{(@var{converter} @var{val})},
+where @var{val} is the value of @var{expr2} and @var{converter} is the
+conversion procedure of the parameter object. The resulting dynamic
+environment is then used for the evaluation of @var{body} (which
+refers to the R5RS grammar nonterminal of that name). The result(s) of
+the parameterize form are the result(s) of the @var{body}.
+
address@hidden
+(radix) @result{} 2
+(parameterize ((radix 16)) (radix)) @result{} 16
+(radix) @result{} 2
+
+(define (f n) (number->string n (radix)))
+
+(f 10) @result{} "1010"
+(parameterize ((radix 8)) (f 10)) @result{} "12"
+(parameterize ((radix 8) (prompt (f 10))) (prompt)) @result{} "1010"
address@hidden example
address@hidden deffn
+
address@hidden Debugging
address@hidden Debugging
+
address@hidden Syntax trace procedure
+Cause @var{procedure} to be "traced", that is debugging output will
+be written to the standard error port every time @var{procedure}
+is called, with the parameters and return value.
+
+Note that Kawa will normally assume that a procedure defined with
+the procedure-defining variant of @code{define} is constant,
+and so it might be inlined:
address@hidden
+(define (ff x) (list x x))
+(trace ff) ;; probably won't work
+(ff 3) ;; not traced
address@hidden example
+It works if you specify the @code{--no-inline} flag to Kawa.
+Alternatively, you can use the variable-defining variant of @code{define}:
address@hidden
+#|kawa:1|# (define ff (lambda (x) name: 'ff (list x x)))
+#|kawa:2|# (trace ff) ;; works
+#|kawa:3|# (ff 3)
+call to ff (3)
+return from ff => (3 3)
+(3 3)
address@hidden example
+Note the use of the @code{name:} procedure property to give the
+anonymous @code{lambda} a name.
address@hidden deffn
+
address@hidden Syntax untrace procedure
+Turn off tracing (debugging output) of @var{procedure}.
address@hidden deffn
+
address@hidden Procedure disassemble procedure
+Returns a string representation of the disassembled bytecode
+for @var{procedure}, when known.
address@hidden deffn
+
address@hidden Input-Output
address@hidden Input, output, and file handling
+
+Kawa has a number of useful tools for controlling input and output:
+
+A programmable reader.
+
+A powerful pretty-printer.
+
address@hidden
+* Named output formats::
+* Paths:: Paths - file name, URLs, and URIs
+* Files:: File System Interface
+* Reading and writing whole files::
+* Ports::
+* Format:: Formatted Output (Common-Lisp-style)
+* Pretty-printing::
+* Resources::
address@hidden menu
+
address@hidden Named output formats, Paths, , Input-Output
address@hidden Named output formats
+
+The @code{--output-format} (or @code{--format}) command-line switch
+can be used to override the default format for how values are
+printed on the standard output. This format is used for values printed
+by the read-eval-print interactive interface. It is also used to
+control how values are printed when Kawa evaluates a file named on the
+command line (using the @code{-f} flag or just a script name).
+(It also affects applications compiled with the @code{--main} flag.)
+It currently affects how values are printed by a @code{load},
+though that may change.
+
+The default format depends on the current programming language.
+For Scheme, the default is @code{scheme} for read-eval-print
+interaction, and @code{ignore} for files that are loaded.
+
+The formats currently supported include the following:
address@hidden @code
address@hidden scheme
+Values are printed in a format matching the Scheme programming language,
+as if using @code{display}. "Groups" or "elements" are written as lists.
address@hidden readable-scheme
+Like @code{scheme}, as if using @code{write}:
+Values are generally printed in a way that they can
+be read back by a Scheme reader. For example, strings have quotation marks,
+and character values are written like @samp{#\A}.
address@hidden elisp
+Values are printed in a format matching the Emacs Lisp programming language.
+Mostly the same as @code{scheme}.
address@hidden readable-elisp
+Like @code{elisp}, but values are generally printed in a way that they can
+be read back by an Emacs Lisp reader. For example, strings have quotation
+marks, and character values are written like @samp{?A}.
address@hidden clisp
address@hidden commonlisp
+Values are printed in a format matching the Common Lisp programming language,
+as if written by @code{princ}.
+Mostly the same as @code{scheme}.
address@hidden readable-clisp
address@hidden readable-commonlisp
+Like @code{clisp}, but as if written by @code{prin1}: values are generally
+printed in a way that they can be read back by a Common Lisp reader.
+For example, strings have quotation marks, and character values are
+written like @samp{#\A}.
address@hidden xml
address@hidden xhtml
address@hidden html
+Values are printed in XML, XHTML, or HTML format.
+This is discussed in more detail in @ref{Formatting XML}.
address@hidden cgi
+The output should follow the CGI standards. I.e. assume that this
+script is invoked by a web server as a CGI script/program, and that the
+output should start with some response header,
+followed by the actual response data.
+To generate the response headers, use the @code{response-header} function.
+If the @code{Content-type} response header has not been specified, and
+it is required by the CGI standard, Kawa will attempt
+to infer an appropriate @code{Content-type} depending on the following value.
address@hidden ignore
+Top-level values are ignored, instead of printed.
address@hidden table
+
address@hidden Paths
address@hidden Paths - file name, URLs, and URIs
+
+A @dfn{Path} is the name of a file or some other @dfn{resource}.
+The path mechanism provides a layer of abstraction, so you can
+use the same functions on either a filename or a URL/URI.
+Functions that in standard Scheme take a filename
+have been generalized to take a path or a path string,
+as if using the @code{path} function below. For example:
address@hidden
+(open-input-file "http://www.gnu.org/index.html";)
+(open-input-file (URI "ftp://ftp.gnu.org/README";))
address@hidden example
+
address@hidden Type path
+A general path, which can be a @code{filename} or a @code{URI}.
+It can be either a @code{filename} or a @code{URI}.
+Represented using the abstract Java class @code{gnu.kawa.io.Path}.
+
+Coercing a value to a @code{Path} is equivalent to
+calling the @code{path} constructor documented below.
address@hidden deffn
+
address@hidden Constructor path arg
+Coerces the @var{arg} to a @code{path}.
+If @var{arg} is already a @code{path}, it is returned unchanged.
+If @var{arg} is a @code{java.net.URI}, or a @code{java.net.URL}
+then a @code{URI} value is returned.
+If @var{arg} is a @code{java.io.File}, a @code{filepath} value is returned.
+Otherwise, @var{arg} can be a string.
+A @code{URI} value is returned if the string starts with a URI scheme
+(such as @code{"http:"}),
+and a @code{filepath} value is returned otherwise.
address@hidden deffn
+
address@hidden Predicate path? arg
+True if @var{arg} is a @code{path} - i.e. an instance of a
@code{gnu.kawa.io.Path}.
address@hidden deffn
+
address@hidden Procedure current-path [new-value]
+With no arguments, returns the default directory of the current thread
+as a @code{path}.
+This is used as the base directory for relative pathnames.
+The initial value is that of the @code{user.dir} property
+as returned by @code{(java.lang.System:getProperty "user.dir")}.
+
+If a @var{new-value} argument is given, sets the default directory:
address@hidden
+(current-path "/opt/myApp/")
address@hidden example
+A string value is automatically converted to a @code{path},
+normally a @code{filepath}.
+
+Alternatively, you can change the default using a setter:
address@hidden
+(set! (current-path) "/opt/myApp/")
address@hidden example
+
+Since @code{current-path} is a @ref{Parameter objects,parameter object}, you
can
+locally change the value using @ref{parameterize-syntax,@code{parameterize}}.
address@hidden deffn
+
address@hidden Type filepath
+The name of a local file.
+Represented using the Java class @code{gnu.kawa.io.FilePath},
+which is a wrapper around @code{java.io.File}.
address@hidden deffn
+
address@hidden Predicate filepath? arg
+True if @var{arg} is a @code{filepath} - i.e. an instance of
+a @code{gnu.kawa.io.FilePath}.
address@hidden deffn
+
address@hidden
address@hidden Type URI
+A Uniform Resource Indicator, which is a generalization of
+the more familiar URL. The general format is specified by
address@hidden://www.ietf.org/rfc/rfc2396.txt,
+RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax}.
+Represented using the Java class @code{gnu.kawa.io.URIPath},
+which is a wrapper around @code{java.net.URI}.
+A URI can be a URL, or it be a relative URI.
address@hidden deffn
+
address@hidden Predicate URI? arg
+True if @var{arg} is a @code{URI} - i.e. an instance of
+a @code{gnu.kawa.io.URIPath}.
address@hidden deffn
+
address@hidden Type URL
+A Uniform Resource Locator - a subtype of @code{URI}.
+Represented using the Java class @code{gnu.kawa.io.URLPath},
+which is a wrapper around a @code{java.net.URL}, in
+addition to extending @code{gnu.kawa.io.URIPath}.
address@hidden deffn
+
address@hidden Extracting Path components
+
address@hidden Procedure path-scheme arg
+Returns the ``URI scheme'' of @var{arg} (coerced to a @code{path}) if it is
+defined, or @code{#f} otherwise. The URI scheme of a @code{filepath}
+is @code{"file"} if the @code{filepath} is absolute, and @code{#f} otherwise.
address@hidden
+(path-scheme "http://gnu.org/";) @result{} "http"
address@hidden example
address@hidden deffn
+
address@hidden Procedure path-authority arg
+Returns the authority part of @var{arg} (coerced to a @code{path}) if it is
+defined, or @code{#f} otherwise.
+The ``authority'' is usually the hostname, but may also include user-info
+or a port-number.
+
address@hidden
+(path-authority "http://me@@localhost:8000/home";) @result{}
"me@@localhost:8000"
address@hidden example
address@hidden deffn
+
address@hidden Procedure path-host arg
+Returns the name name part of @var{arg} (coerced to a @code{path}) if it is
+defined, or @code{#f} otherwise.
+
address@hidden
+(path-host "http://me@@localhost:8000/home";) @result{} "localhost"
address@hidden example
address@hidden deffn
+
address@hidden Procedure path-user-info arg
+Returns the ``user info'' of @var{arg} (coerced to a @code{path}) if it is
+specified, or @code{#f} otherwise.
+
address@hidden
+(path-host "http://me@@localhost:8000/home";) @result{} "me"
address@hidden example
address@hidden deffn
+
address@hidden Procedure path-port arg
+Returns the port number of @var{arg} (coerced to a @code{path}) if it is
+specified, or @code{-1} otherwise. Even if there is a default port
+associated with a URI scheme (such as 80 for @code{http}), the value
+-1 is returned unless the port number is @emph{explictly} specified.
+
address@hidden
+(path-host "http://me@@localhost:8000/home";) @result{} 8000
+(path-host "http://me@@localhost/home";) @result{} -1
address@hidden example
address@hidden deffn
+
address@hidden Procedure path-file arg
+Returns the ``path component'' of the @var{arg}
+(coerced to a @code{path}).
+(The name @code{path-path} might be more logical,
+but it is obviously a bit awkward.)
+The path component of a file name is the file name itself.
+For a URI, it is the main hierarchical part of the URI,
+without schema, authority, query, or fragment.
address@hidden
+(path-file "http://gnu.org/home/me.html?add-bug#body";) @result{}
"/home/me.html"
address@hidden example
address@hidden deffn
+
address@hidden Procedure path-directory arg
+If @var{arg} (coerced to a @code{path}) is directory,
+return @var{arg}; otherwise return the ``parent'' path, without the
+final component.
address@hidden
+(path-directory "http://gnu.org/home/me/index.html#body";)
+ @result{} (path "http://gnu.org/home/me/";)
+(path-directory "http://gnu.org/home/me/";)
+ @result{} (path "http://gnu.org/home/me/";)
address@hidden example
address@hidden(path-directory "./dir")} @address@hidden @code{(path "./dir")}
if @code{dir} is a directory, and @code{(path ".")} otherwise.
address@hidden deffn
+
address@hidden Procedure path-parent arg
+Returns the ``parent directory'' of @var{arg} (coerced to a @code{path}).
+If @var{arg} is not a directory, same as @code{path-directory @var{arg}}.
address@hidden
+(path-parent "a/b/c") @result{} (path "a/b")
+(path-parent "file:/a/b/c") @result{} (path "file:/a/b/c")
+(path-parent "file:/a/b/c/") @result{} (path "file:/a/b/")
address@hidden example
address@hidden deffn
+
address@hidden Procedure path-last arg
+The last component of path component
+of @var{arg} (coerced to a @code{path}).
+Returns a substring of @code{(path-file @var{arg})}.
+If that string ends with @samp{/} or the path separator,
+that last character is ignored.
+Returns the tail of the path-string, following
+the last (non-final) @samp{/} or path separator.
address@hidden
+(path-last "http:/a/b/c") @result{} "c"
+(path-last "http:/a/b/c/") @result{} "c"
+(path-last "a/b/c") @result{} "c"
address@hidden example
address@hidden deffn
+
address@hidden Procedure path-extension arg
+Returns the ``extension'' of the @var{arg}
+(coerced to a @code{path}).
address@hidden
+(path-extension "http://gnu.org/home/me.html?add-bug#body";) @result{} "html"
+(path-extension "/home/.init") @result{} #f
address@hidden example
address@hidden deffn
+
address@hidden Procedure path-query arg
+Returns the query part of @var{arg} (coerced to a @code{path}) if it is
+defined, or @code{#f} otherwise. The query part of a URI is the
+part after @samp{?}.
address@hidden
+(path-query "http://gnu.org/home?add-bug";) @result{} "add-bug"
address@hidden example
address@hidden deffn
+
address@hidden Procedure path-fragment arg
+Returns the fragment part of @var{arg} (coerced to a @code{path}) if it is
+defined, or @code{#f} otherwise. The fragment of a URI is the
+part of after @samp{#}.
address@hidden
+(path-query "http://gnu.org/home#top";) @result{} "top"
address@hidden example
address@hidden deffn
+
address@hidden Procedure resolve-uri uri base
+Returns a @var{uri} unchanged if it is an absolute URI.
+Otherwise resolves it against a base URI @var{base},
+which is normally (though not always) absolute.
+
+This uses the algorithm specifyed by RFC-3986 (assuming @var{base}
+is absolute), unlike the obsolete RFC-2396 algorithm used
+by @code{java.net.URI.resolve}.
address@hidden deffn
+
address@hidden Files
address@hidden File System Interface
+
address@hidden Procedure file-exists? filename
+Returns true iff the file named @var{filename} actually exists.
+This function is defined on arbitrary @code{path} values:
+for URI values we open a @code{URLConnection}
+and invoke @code{getLastModified()}.
address@hidden deffn
+
address@hidden Procedure file-directory? filename
+Returns true iff the file named @var{filename} actually exists
+and is a directory.
+This function is defined on arbitrary @code{path} values;
+the default implementation for non-file objects is to
+return @code{#t} iff the path string ends with the character @samp{/}.
address@hidden deffn
+
address@hidden Procedure file-readable? filename
+Returns true iff the file named @var{filename} actually exists
+and can be read from.
address@hidden deffn
+
address@hidden Procedure file-writable? filename
+Returns true iff the file named @var{filename} actually exists
+and can be writen to.
+(Undefined if the @var{filename} does not exist,
+but the file can be created in the directory.)
address@hidden deffn
+
address@hidden Procedure delete-file filename
+Delete the file named @var{filename}.
+On failure, throws an exception.
address@hidden deffn
+
address@hidden Procedure rename-file oldname newname
+Renames the file named @var{oldname} to @var{newname}.
address@hidden deffn
+
address@hidden Procedure copy-file oldname newname-from path-to
+Copy the file named @var{oldname} to @var{newname}.
+The return value is unspecified.
address@hidden deffn
+
address@hidden Procedure create-directory dirname
+Create a new directory named @var{dirname}.
+Unspecified what happens on error (such as exiting file with the same name).
+(Currently returns @code{#f} on error, but may change to be more compatible
+with scsh.)
address@hidden deffn
+
address@hidden Procedure system-tmpdir
+Return the name of the default directory for temporary files.
address@hidden deffn
+
address@hidden Procedure make-temporary-file [format]
+Return a file with a name that does not match any existing file.
+Use @var{format} (which defaults to @code{"kawa~d.tmp"}) to generate
+a unique filename in @code{(system-tmpdir)}.
+The current implementation is @emph{not} safe from race conditions;
+this will be fixed in a future release (using Java2 features).
address@hidden deffn
+
address@hidden Reading and writing whole files
address@hidden Reading and writing whole files
+
+The following procedures and syntax allow you to read and write
+the entire contents of a file, without iterating using a port.
+
address@hidden Reading a file
+
+For reading the contents of a file in a single operation,
+you can use the following syntax:
+
address@hidden
address@hidden&<@address@hidden@address@hidden
address@hidden display
+
+This is equivalent to using the @code{path-data} function (defined below):
address@hidden
address@hidden(path-data} @stxlit{&@address@hidden@address@hidden)}
address@hidden display
+
+For example:
address@hidden
+(define dir "/home/me/")
+(define help-message &<@lbracechar{}&address@hidden)
address@hidden example
+This binds @code{help-message} to the contents of the file
+named @code{HELP} in the @code{dir} directory.
+
address@hidden
address@hidden Blobs
+
+The content of a file is, in general, a sequence of uninterpreted bytes.
+Often these bytes represent text in a locale-dependent encoding,
+but we don't always know this. Sometimes they're images, or videos,
+or word-processor documents. A filename extension or a ``magic number''
+in the file can give you hints, but not certainty as to the type of the data.
+
+A @address@hidden://en.wikipedia.org/wiki/Binary_large_object,blob}}
+is a raw uninterpreted sequence of bytes. It is a @code{bytevector}
+that can be automatically converted to other types as needed,
+specifically to a string or a bytevector.
+
+The @code{&<@address@hidden returns a blob. For example,
+assume the file @code{README} contains (bytes representing)
+the text @code{"Check doc directory.\n"}. Then:
address@hidden
+#|kawa:1|# (define readme &<@address@hidden))
+|kawa:2|# readme:class
+class gnu.lists.Blob
+#|kawa:3|# (write (->string readme))
+"Check doc directory.\n"
+#|kawa:4|# (write (->bytevector readme))
+#u8(67 104 101 99 107 32 100 111 99 32 100 105 114 101 99 116 111 114 121 46
10)
+#|kawa:5|# (->bytevector readme):class
+class gnu.lists.U8Vector
address@hidden example
+
address@hidden Writing to a file
+
+The @code{&<@address@hidden syntax can be used with @code{set!}
+to replace the contents of a file:
address@hidden
+(set! &<@address@hidden "Check example.com\n")
address@hidden example
+
+The new contents must be blob-compatible - i.e. a bytevector or a string.
+
+If you dislike using @code{<} as an output operator, you can instead using the
@code{&>@address@hidden operation, which evaluates to a function whose single
argument is the new value:
address@hidden
+(&>@address@hidden "Check example.com\n")
address@hidden example
+In general:
address@hidden
address@hidden&>@address@hidden@address@hidden
address@hidden example
+is equivalent to:
address@hidden
+(lambda (new-contents)
+ (set! @stxlit{&<@address@hidden@address@hidden new-contents))
address@hidden example
+
+You can use @code{&>>} to append more data to a file:
+
address@hidden
+(&>>@address@hidden "or check example2.com\n")
address@hidden example
+
address@hidden Functions
+
address@hidden Procedure path-data path
+Reads the contents of the file specified by @var{path},
+where @var{path} can be a @ref{Paths,path} object, or anything that can
+be converted to a @code{Path}, including a filename string or a URL.
+returning the result as a blob.
+The result is a @emph{blob}, which is a kind of bytevector than can be
+auto-converted to a string or bytevecor as required.
+
+The function @code{path-data} has a setter, which replaces the contents
+with new contents:
address@hidden
+(set! &<@address@hidden new-contents)
address@hidden example
address@hidden deffn
+
address@hidden Procedure path-bytes path
+Reads the contents of the file specified by @var{path}, as
+with the @code{path-data} function, but the result is a plain bytevector,
+rather than a blob. This functtion also has a setter, which you
+can use to replace the file-contents by new bytevector-valued data.
address@hidden deffn
+
address@hidden Ports
address@hidden Ports
+
+Ports represent input and output devices.
+An input port is a Scheme object that can deliver data upon
+command, while an output port is a Scheme object that can
+accept data.
+
+Different @dfn{port types} operate on different data:
address@hidden @bullet
address@hidden
+A @dfn{textual port} supports reading or writing of individual
+characters from or to a backing store containing characters
+using @code{read-char} and @code{write-char} below, and it supports
+operations defined in terms of characters, such as @code{read} and
address@hidden
address@hidden
+A @dfn{binary port} supports reading or writing of individual
+bytes from or to a backing store containing bytes using
address@hidden and @code{write-u8} below, as well as operations defined
+in terms of bytes (integers in the range 0 to 255).
+
+All Kawa binary ports created by procedures documented here
+are also textual ports. Thus you can either read/write
+bytes as described above, or read/write
+characters whose scalar value is in the range 0 to 255
+(i.e. the Latin-1 character set), using @code{read-char} and @code{write-char}.
+
+A native binary port is a @code{java.io.InputStream}
+or @code{java.io.OutputStream} instance. These are not textual ports.
+You can use methods @code{read-u8} and @code{write-u8},
address@hidden not true?
+but not @code{read-char} and @code{write-char} on native binary ports.
+(The functions @code{input-port?}, @code{output-port?}, @code{binary-port?},
+and @code{port?} all currently return false on native binary ports,
+but that may change.)
address@hidden itemize
+
address@hidden Procedure call-with-port port proc
+The @code{call-with-port} procedure calls @var{proc} with port as an
+argument. If @var{proc} returns, then the port is closed automatically
+and the values yielded by the proc are returned.
+
+If @var{proc} does not return, then the port must not be closed
+automatically unless it is possible to prove that the port
+will never again be used for a read or write operation.
+
+As a Kawa extension, @var{port} may be any object
+that implements @code{java.io.Closeable}.
+It is an error if @var{proc} does not accept one argument.
+
address@hidden @emph{Rationale}: Because Scheme’s escape procedures have
unlimited
address@hidden extent, it is possible to escape from the current continuation
address@hidden but later to resume it. If implementations were permitted to
address@hidden close the port on any escape from the current continuation,
address@hidden then it would be impossible to write portable code using both
address@hidden call-with-current-continuation and call-with-port.
address@hidden deffn
+
address@hidden Procedure call-with-input-file path proc
address@hidden Procedure call-with-output-file path proc
+These procedures obtain a textual port obtained by
+opening the named file for input or output as if by
address@hidden or @code{open-output-file}. The port and
address@hidden are then passed to a procedure equivalent to
address@hidden
+
+It is an error if @var{proc} does not accept one argument.
address@hidden deffn
+
address@hidden Procedure input-port? obj
address@hidden Procedure output-port? obj
address@hidden Procedure textual-port? obj
address@hidden Procedure binary-port? obj
address@hidden Procedure port? obj
+These procedures return @code{#t} if obj is an input port, output port,
+textual port, binary port, or any kind of port,
+respectively. Otherwise they return @code{#f}.
+
+These procedures currently return @code{#f} on a native Java streams
+(@code{java.io.InputStream} or @code{java.io.OutputStream}),
+a native reader (a @code{java.io.Reader} that is not an
address@hidden), or a native writer (a @code{java.io.Writer}
+that is not an @code{gnu.mapping.Outport}). This may change if
+conversions between native ports and Scheme ports becomes more seamless.
+
address@hidden deffn
+
address@hidden Procedure input-port-open? port
address@hidden Procedure output-port-open? port
+Returns @code{#t} if @var{port} is still open and capable of performing
+input or output, respectively, and @code{#f} otherwise.
+(Not supported for native binary ports - i.e. @code{java.io.InputStteam}
+or @code{java.io.OutputStream}.)
address@hidden deffn
+
address@hidden Procedure current-input-port
address@hidden Procedure current-output-port
address@hidden Procedure current-error-port
+Returns the current default input port, output port, or
+error port (an output port), respectively.
+(The error port is the port to which errors and warnings should be sent
+- the @dfn{standard error} in Unix and C terminology.)
+These procedures are @ref{Parameter objects,parameter objects},
+which can be overridden with @ref{parameterize-syntax,@code{parameterize}}.
+
+The initial bindings for @code{(current-output-port)} and
address@hidden(current-error-port)} are hybrid textual/binary
+ports that wrap the values of the corresponding @code{java.lang.System} fields
address@hidden, and @code{err}. The latter, in turn are bound
+to the standard output and error streams of the JVM process.
+This means you can write binary data to standard output
+using @code{write-bytevector} and @code{write-u8}.
+
+The initial value @code{(current-input-port)} similarly is a textual port
+that wraps the @code{java.lang.System} field @code{in}, which is bound
+to the standard input stream of the JVM process.
+It is a @emph{hybrid} textual/binary port only if there
+is no console (as determined by @code{(java.lang.System:console)}
+returning @code{#!null}) - i.e. if standard input is not a tty.
+
+Here is an example that copies standard input to standard output:
address@hidden
+(let* ((in (current-input-port))
+ (out (current-output-port))
+ (blen ::int 2048)
+ (buf (make-bytevector blen)))
+ (let loop ()
+ (define n (read-bytevector! buf in))
+ (cond ((not (eof-object? n))
+ (write-bytevector buf out 0 n)
+ (loop)))))
address@hidden example
+
address@hidden deffn
+
address@hidden Procedure with-input-from-file path thunk
address@hidden Procedure with-output-to-file path thunk
+The file is opened for input or output as if by
address@hidden or @code{open-output-file}, and the new port
+is made to be the value returned by @code{current-input-port}
+or @code{current-output-port} (as used by @code{(read)},
address@hidden(write @var{obj})}, and so forth). The thunk is then called with
no
+arguments. When the @var{thunk} returns, the port is closed
+and the previous default is restored. It is an error if @var{thunk}
+does not accept zero arguments. Both procedures return
+the values yielded by @var{thunk}. If an escape procedure is used
+to escape from the continuation of these procedures, they
+behave exactly as if the current input or output port had
+been bound dynamically with @code{parameterize}.
address@hidden deffn
+
address@hidden Procedure open-input-file path
address@hidden Procedure open-binary-input-file path
+Takes a @var{path} naming an existing file and returns a textual
+input port or binary input port that is capable of delivering
+data from the file.
address@hidden If the file does not exist or cannot be
address@hidden opened, an error that satisfies file-error? is signaled.
+
+The procedure @code{open-input-file} checks the fluid variable
address@hidden,@code{port-char-encoding}} to determine how bytes are decoded
+into characters. The procedure @code{open-binary-input-file}
+is equivalent to calling @code{open-input-file} with
address@hidden set to @code{#f}.
address@hidden deffn
+
address@hidden Procedure open-output-file path
address@hidden Procedure open-binary-output-file path
+Takes a @var{path} naming an output file to be created and returns
+respectively a textual output port or binary output port that is
+capable of writing data to a new file by that name. If a
+file with the given name already exists, the effect is unspecified.
address@hidden If the file cannot be opened, an error that satisfies
address@hidden file-error? is signaled.
+
+The procedure @code{open-output-file} checks the fluid variable
address@hidden,@code{port-char-encoding}} to determine how characters are
+encoded as bytes. The procedure @code{open-binary-output-file}
+is equivalent to calling @code{open-output-file} with
address@hidden set to @code{#f}.
address@hidden deffn
+
address@hidden Procedure close-port port
address@hidden Procedure close-input-port port
address@hidden Procedure close-output-port port
+Closes the resource associated with @var{port}, rendering the port
+incapable of delivering or accepting data. It is an error to
+apply the last two procedures to a port which is not an
+input or output port, respectively.
+(Specifically, @code{close-input-port} requires a @code{java.io.Reader},
+while @code{close-output-port} requires a @code{java.io.Writer}.
+In contrast @code{close-port} accepts any object whose class
+implements @code{java.io.Closeable}.)
address@hidden Scheme implementations may provide ports which are
simultaneously input
address@hidden and output ports, such as sockets; the close-input-port
address@hidden and close-output-port procedures can then be used to
address@hidden close the input and output sides of the port independently.
+
+These routines have no effect if the port has already been
+closed.
address@hidden deffn
+
address@hidden String and bytevector ports
+
address@hidden Procedure open-input-string string
+Takes a string and returns a text input port that delivers characters
+from the string. The port can be closed by @code{close-input-port},
+though its storage will be reclaimed by the
+garbage collector if it becomes inaccessible.
+
address@hidden
+(define p
+ (open-input-string "(a . (b c . ())) 34"))
+
+(input-port? p) @result{} #t
+(read p) @result{} (a b c)
+(read p) @result{} 34
+(eof-object? (peek-char p)) @result{} #t
address@hidden example
address@hidden deffn
+
address@hidden Procedure open-output-string
+Returns an textual output port that will accumulate characters
+for retrieval by @code{get-output-string}.
+The port can be closed by the procedure @code{close-output-port},
+though its storage will be reclaimed by the garbage collector
+if it becomes inaccessible.
address@hidden
+(let ((q (open-output-string))
+ (x '(a b c)))
+ (write (car x) q)
+ (write (cdr x) q)
+ (get-output-string q)) @result{} "a(b c)"
address@hidden example
address@hidden deffn
+
address@hidden Procedure get-output-string output-port
+Given an output port created by @code{open-output-string},
+returns a string consisting of the characters that have been
+output to the port so far in the order they were output.
+If the result string is modified, the effect is unspecified.
+
address@hidden
+(parameterize
+ ((current-output-port (open-output-string)))
+ (display "piece")
+ (display " by piece ")
+ (display "by piece.")
+ (newline)
+ (get-output-string (current-output-port)))
+ @result{} "piece by piece by piece.\n"
address@hidden example
address@hidden deffn
+
address@hidden Procedure call-with-input-string string proc
+Create an input port that gets its data from @var{string},
+call @var{proc} with that port as its one argument, and return
+the result from the call of @var{proc}
address@hidden deffn
+
address@hidden Procedure call-with-output-string proc
+Create an output port that writes its data to a @var{string},
+and call @var{proc} with that port as its one argument.
+Return a string consisting of the data written to the port.
address@hidden deffn
+
address@hidden Procedure open-input-bytevector bytevector
+Takes a bytevector and returns a binary input port that
+delivers bytes from the bytevector.
address@hidden deffn
+
address@hidden Procedure open-output-bytevector
+Returns a binary output port that will accumulate bytes
+for retrieval by @code{get-output-bytevector}.
address@hidden deffn
+
address@hidden Procedure get-output-bytevector port
+Returns a bytevector consisting of the bytes that have been
+output to the port so far in the order they were output.
+It is an error if @var{port} was not created with
@code{open-output-bytevector}.
address@hidden deffn
+
address@hidden Input
+
+If @var{port} is omitted from any input procedure, it defaults
+to the value returned by @code{(current-input-port)}. It is an
+error to attempt an input operation on a closed port.
+
address@hidden Procedure read [port]
+The @code{read} procedure converts external representations of
+Scheme objects into the objects themselves. That is, it is
+a parser for the non-terminal @stxref{datum}.
+It returns the next object parsable from the
+given textual input port, updating port to point to the
+first character past the end of the external representation
+of the object.
+
+If an end of file is encountered in the input before any
+characters are found that can begin an object, then an
+end-of-file object is returned. The port remains open, and
+further attempts to read will also return an end-of-file object.
+If an end of file is encountered after the beginning of
+an object’s external representation, but the external representation
+is incomplete and therefore not parsable, an error
+that satisfies @code{read-error?} is signaled.
address@hidden deffn
+
address@hidden Procedure read-char [port]
+Returns the next character available from the textual input
address@hidden, updating the port to point to the following character.
+If no more characters are available, an end-of-file value is
+returned.
+
+The result type is @code{character-or-eof}.
address@hidden deffn
+
address@hidden Procedure peek-char [port]
+Returns the next character available from the textual input @var{port},
+but @emph{without} updating the port to point to the
+following character. If no more characters are available, an
+end-of-file value is returned.
+
+The result type is @code{character-or-eof}.
+
address@hidden:} The value returned by a call to @code{peek-char} is the same as
+the value that would have been returned by a call to @code{read-char}
+with the same @var{port}. The only difference is that the very next call
+to @code{read-char} or @code{peek-char} on that @var{port} will return the
+value returned by the preceding call to @code{peek-char}. In particular, a
+call to @code{peek-char} on an interactive port will hang waiting for
+input whenever a call to @code{read-char} would have hung.
address@hidden deffn
+
address@hidden Procedure read-line [port [handle-newline]]
+Reads a line of input from the textual input @var{port}.
+The @var{handle-newline} parameter determines what is done with
+terminating end-of-line delimiter.
+The default, @code{'trim}, ignores the delimiter;
address@hidden'peek} leaves the delimiter in the input stream;
address@hidden'concat} appends the delimiter to the returned value;
+and @code{'split} returns the delimiter as a second value.
+You can use the last three options to tell if the string was
+terminated by end-or-line or by end-of-file.
+If an end of file is encountered before any end of
+line is read, but some characters have been read, a string
+containing those characters is returned.
+(In this case, @code{'trim}, @code{'peek}, and @code{'concat}
+have the same result and effect. The @code{'split} case returns two
+values: The characters read, and the delimiter is an empty string.)
+If an end of file is encountered before any characters are read,
+an end-of-file object is returned.
+For the purpose of this procedure, an
+end of line consists of either a linefeed character, a carriage
+return character, or a sequence of a carriage return character
+followed by a linefeed character.
address@hidden deffn
+
address@hidden Procedure eof-object? obj
+Returns @code{#t} if @var{obj} is an end-of-file object,
+otherwise returns @code{#f}.
+
address@hidden note}: If @var{obj} has type @code{character-or-eof},
+this is compiled as an @code{int} comparison with -1.
address@hidden deffn
+
address@hidden Procedure eof-object
+Returns an end-of-file object.
address@hidden deffn
+
address@hidden Procedure char-ready? [port]
+Returns @code{#t} if a character is ready on the textual input
address@hidden and returns @code{#f} otherwise. If char-ready returns @code{#t}
+then the next @code{read-char} operation on the given @var{port} is
+guaranteed not to hang. If the port is at end of file then
address@hidden returns @code{#t}.
+
address@hidden:} The @code{char-ready?} procedure exists to make it
+possible for a program to accept characters from interactive ports
+without getting stuck waiting for input. Any input editors as-
+sociated with such ports must ensure that characters whose
+existence has been asserted by @code{char-ready?} cannot be removed
+from the input. If @code{char-ready?} were to return @code{#f} at end of
+file, a port at end-of-file would be indistinguishable from an
+interactive port that has no ready characters.
address@hidden deffn
+
address@hidden Procedure read-string k [port]
+Reads the next @var{k} characters, or as many as are available
+before the end of file, from the textual input @var{port} into a
+newly allocated string in left-to-right order and returns the
+string. If no characters are available before the end of file,
+an end-of-file object is returned.
address@hidden deffn
+
address@hidden Procedure read-u8 [port]
+Returns the next byte available from the binary input @var{port},
+updating the @var{port} to point to the following byte. If no more
+bytes are available, an end-of-file object is returned.
address@hidden deffn
+
address@hidden Procedure peek-u8 [port]
+Returns the next byte available from the binary input @var{port},
+but @emph{without} updating the @var{port} to point to the following byte.
+If no more bytes are available, an end-of-file object is returned.
address@hidden deffn
+
address@hidden Procedure u8-ready? [port]
+Returns @code{#t} if a byte is ready on the binary input @var{port} and
+returns @code{#f} otherwise. If @code{u8-ready?} returns @code{#t} then the
+next @code{read-u8} operation on the given port is guaranteed
+not to hang. If the port is at end of file then @code{u8-ready?}
+returns @code{#t}.
address@hidden deffn
+
address@hidden Procedure read-bytevector k [port]
+Reads the next @var{k} bytes, or as many as are available before
+the end of file, from the binary input @var{port} into a newly
+allocated bytevector in left-to-right order and returns the
+bytevector. If no bytes are available before the end of file,
+an end-of-file object is returned.
address@hidden deffn
+
address@hidden Procedure read-bytevector! bytevector [port [start [end]]]
+Reads the next @var{end} − @var{start} bytes, or as many as are
+available before the end of file, from the binary input @var{port}
+into @var{bytevector} in left-to-right order beginning at the @var{start}
+position. If @var{end} is not supplied, reads until the end of
address@hidden has been reached. If @var{start} is not supplied, reads
+beginning at position 0. Returns the number of bytes read.
+If no bytes are available, an end-of-file object is returned.
address@hidden deffn
+
address@hidden Output
+
+If @var{port} is omitted from any output procedure, it defaults
+to the value returned by @code{(current-output-port)}. It is an
+error to attempt an output operation on a closed port.
+
+The return type of these methods is @code{void}.
+
address@hidden Procedure write obj [port]
+Writes a representation of @var{obj} to the given textual output
address@hidden Strings that appear in the written representation
+are enclosed in quotation marks, and within those strings
+backslash and quotation mark characters are escaped by
+backslashes.
+Symbols that contain non-ASCII characters
+are escaped with vertical lines.
+Character objects are written using the @code{#\} notation.
+
+If @var{obj} contains cycles which would cause an infinite loop
+using the normal written representation, then at least the
+objects that form part of the cycle must be represented
+using @ref{datum labels}. Datum
+labels must not be used if there are no cycles.
address@hidden deffn
+
address@hidden Procedure write-shared obj [port]
+The @code{write-shared} procedure is the same as @code{write}, except
+that shared structure must be represented using datum
+labels for all pairs and vectors that appear more than once
+in the output.
address@hidden deffn
+
address@hidden Procedure write-simple obj [port]
+The @code{write-simple} procedure is the same as @code{write}, except
+that shared structure is never represented using datum labels.
+This can cause write-simple not to terminate if @var{obj}
+contains circular structure.
address@hidden deffn
+
address@hidden Procedure display obj [port]
+Writes a representation of @var{obj} to the given textual output
+port. Strings that appear in the written representation
+are output as if by @code{write-string} instead of by @code{write}.
+Symbols are not escaped. Character objects appear in the
+representation as if written by @code{write-char} instead of by
address@hidden
+The @code{display} representation of other objects is unspecified.
address@hidden However, display must always terminate. Thus if the normal write
address@hidden representation is used, datum labels are needed
address@hidden to represent cycles as in write.
address@hidden deffn
+
address@hidden Procedure newline [port]
+Writes an end of line to textual output @var{port}.
+This is done using the @code{println} method
+of the Java class @code{java.io.PrintWriter}.
address@hidden deffn
+
address@hidden Procedure write-char char [port]
+Writes the character @var{char} (not an external representation
+of the character) to the given textual output @var{port}.
address@hidden deffn
+
address@hidden Procedure write-string string [port [start [end]]]
+Writes the characters of @var{string} from @var{start} to @var{end}
+in left-to-right order to the textual output @var{port}.
address@hidden deffn
+
address@hidden Procedure write-u8 byte [port]
+Writes the @var{byte} to the given binary output port.
address@hidden deffn
+
address@hidden Procedure write-bytevector bytevector [port [start [end]]]
+Writes the bytes of @var{bytevector} from @var{start} to @var{end}
+in left-to-right order to the binary output @var{port}.
address@hidden deffn
+
address@hidden Procedure flush-output-port [port]
address@hidden Procedure force-output [port]
+Forces any pending output on @var{port} to be delivered to the output file or
+device and returns an unspecified value. If the @var{port} argument is
+omitted it defaults to the value returned by @code{(current-output-port)}.
+(The name @code{force-output} is older,
+while R6RS added @code{flush-output-port}. They have the same effect.)
address@hidden deffn
+
address@hidden
address@hidden prompts
address@hidden Prompts for interactive consoles (REPLs)
+
+When an interactive input port is used for a read-eval-print-loop (REPL
+or console) it is traditional for the REPL to print a short
address@hidden string to signal that the user is expected to type
+an expression. These prompt strings can be customized.
+
address@hidden
address@hidden input-prompt1
address@hidden input-prompt2
+These are fluid variable whose values are string templates
+with placeholders similar to @code{printf}-style format.
+The placeholders are expanded (depending on the current state),
+and the resulting string printed in front of the input line.
+
+The @code{input-prompt1} is used normally. For multi-line input commands
+(for example if the first line is incomplete), @code{input-prompt1}
+is used for the first line of each command, while @code{input-prompt2} is
+used for subsequent ``continuation'' lines.
+
+The following placeholders are handled:
address@hidden @asis
address@hidden @stxlit{%%}
+A literal @samp{%}.
address@hidden @stxlit{%N}
+The current line number. This is @code{(+ 1 (port-line @var{port}))}.
address@hidden @address@hidden@address@hidden
+Insert padding at this possion, repeating the following
+ character @address@hidden as needed to bring the total number of columns
+of the prompt to that specified by the digits @address@hidden
address@hidden @address@hidden
+Same as @address@hidden@var{c}}, but @address@hidden defaults to the number
+of columns in the initial prompt from the expansion of @code{input-prompt1}.
+This is only meaningful when expanding @code{input-prompt2} for
+continuation lines.
address@hidden @address@hidden@address@hidden@}}
+Same as @var{hidden}, but the characters of @var{hidden}
+are assumed to have zero visible width. Can be used for
address@hidden://en.wikipedia.org/wiki/ANSI_escape_code,ANSI escape sequences}
+to change color or style:
address@hidden
+(set! input-prompt1 "address@hidden;5;address@hidden@{Kawa:address@hidden
address@hidden@}")
address@hidden example
+The above changes both the text and the background color
+(to a pale blue).
address@hidden @stxlit{%M}
+Insert a ``message'' string.
+Not normally used by Kawa, but supported by JLine.
address@hidden table
+
+These variables can be initialized by the command-line
+arguments @code{console:address@hidden and
address@hidden:address@hidden, respectively. If these are
+not specified, languages-specific defaults are used.
+For example for Scheme the default value of @code{input-prompt1}
+is @code{"#|kawa:%N|# "} and @code{input-prompt2} is @code{"#|$P.%N| "}.
+These have the form of Scheme comments, to make it easier to cut-and-paste.
+
+If @code{input-prompt1} (respectively @code{input-prompt2}) does not contain
+an escape sequence (either @code{"address@hidden or the escape character
@code{"\e"})
+then ANSI escape sequences are added to to highlight the prompt.
+(Under DomTerm this sets the @code{prompt} style, which can be customised
+with CSS but defaults to a light green background;
+if using JLine the background is set to light green.)
address@hidden defvar
+
+For greater flexibility, you can also set a prompter procedure.
+
address@hidden Procedure set-input-port-prompter! port prompter
+Set the prompt procedure associated with @var{port} to @var{prompter},
+which must be a one-argument procedure taking an input port,
+and returning a string.
+The procedure is called before reading the first line of a command;
+its return value is used as the first-line prompt.
+
+The prompt procedure can have side effects.
+In Bash shell terms: It combines the features of @code{PROMPT_COMMAND}
+and @code{PS1}.
+
+The initial @var{prompter} is @code{default-prompter},
+which returns the expansion of @code{input-prompt1}.
address@hidden deffn
+
address@hidden Procedure input-port-prompter port
+Get the prompt procedure associated with @var{port}.
address@hidden deffn
+
address@hidden Procedure default-prompter port
+The default prompt procedure.
+Normally (i.e. when @code{input-port-read-state} is a space)
+returns @code{input-prompt1} after expanding the @code{%}-placeholders.
+Can also expand @code{input-prompt2} when @code{input-port-read-state}
+is not whitespace.
address@hidden deffn
+
address@hidden Line numbers and other input port properties
+
address@hidden Function port-column input-port
address@hidden Function port-line input-port
+Return the current column number or line number of @var{input-port},
+using the current input port if none is specified.
+If the number is unknown, the result is @code{#f}. Otherwise,
+the result is a 0-origin integer - i.e. the first character
+of the first line is line 0, column 0. (However, when you
+display a file position, for example in an error message,
+we recommend you add 1 to get 1-origin integers. This is
+because lines and column numbers traditionally start with
+1, and that is what non-programmers will find most natural.)
address@hidden deffn
+
address@hidden Procedure set-port-line! port line
+Set (0-origin) line number of the current line of @var{port} to @var{num}.
address@hidden deffn
+
address@hidden Procedure input-port-line-number port
+Get the line number of the current line of @var{port},
+which must be a (non-binary) input port.
+The initial line is line 1.
+Deprecated; replaced by @code{(+ 1 (port-line @var{port}))}.
address@hidden deffn
+
address@hidden Procedure set-input-port-line-number! port num
+Set line number of the current line of @var{port} to @var{num}.
+Deprecated; replaced by @code{(set-port-line! @var{port} (- @var{num} 1))}.
address@hidden deffn
+
address@hidden Procedure input-port-column-number port
+Get the column number of the current line of @var{port},
+which must be a (non-binary) input port.
+The initial column is column 1.
+Deprecated; replaced by @code{(+ 1 (port-column @var{port}))}.
address@hidden deffn
+
address@hidden Procedure input-port-read-state port
+Returns a character indicating the current @code{read} state of the @var{port}.
+Returns @code{#\Return} if not current doing a @var{read},
address@hidden"} if reading a string; @code{#\|} if reading a comment;
@code{#\(}
+if inside a list; and @code{#\Space} when otherwise in a @code{read}.
+The result is intended for use by prompt prcedures, and is not necessarily
+correct except when reading a new-line.
address@hidden deffn
+
address@hidden symbol-read-case
+A symbol that controls how @code{read} handles letters when reading a symbol.
+If the first letter is @samp{U}, then letters in symbols are upper-cased.
+If the first letter is @samp{D} or @samp{L}, then letters
+in symbols are down-cased.
+If the first letter is @samp{I}, then the case of letters in symbols
+is inverted.
+Otherwise (the default), the letter is not changed.
+(Letters following a @samp{\} are always unchanged.)
+The value of @code{symbol-read-case} only checked
+when a reader is created, not each time a symbol is read.
address@hidden defvar
+
address@hidden Miscellaneous
+
address@hidden
address@hidden port-char-encoding
+Controls how bytes in external files are converted to/from internal
+Unicode characters. Can be either a symbol or a boolean.
+If @code{port-char-encoding} is @code{#f}, the file is assumed
+to be a binary file and no conversion is done.
+Otherwise, the file is a text file. The default is @code{#t}, which
+uses a locale-dependent conversion. If @code{port-char-encoding}
+is a symbol, it must be the name of a character encoding known to Java.
+For all text files (that is if @code{port-char-encoding} is not @code{#f}),
+on input a @code{#\Return} character or
+a @code{#\Return} followed by @code{#\Newline}
+are converted into plain @code{#\Newline}.
+
+This variable is checked when the file is opened; not when actually
+reading or writing. Here is an example of how you can safely
+change the encoding temporarily:
address@hidden
+(define (open-binary-input-file name)
+ (fluid-let ((port-char-encoding #f)) (open-input-file name)))
address@hidden example
address@hidden defvar
+
address@hidden *print-base*
+The number base (radix) to use by default when printing rational numbers.
+Must be an integer between 2 and 36, and the default is of course 10.
+For example setting @code{*print-base*} to 16 produces hexadecimal output.
address@hidden defvar
+
address@hidden *print-radix*
+If true, prints an indicator of the radix used when printing rational numbers.
+If @code{*print-base*} is respectively 2, 8, or 16, then
address@hidden, @code{#o} or @code{#x} is written before the number;
+otherwise @address@hidden is written, where @address@hidden is the base.
+An exception is when @code{*print-base*} is 10, in which case a period
+is written @emph{after} the number, to match Common Lisp; this may
+be inappropriate for Scheme, so is likely to change.
address@hidden defvar
+
address@hidden *print-right-margin*
+The right margin (or line width) to use when pretty-printing.
address@hidden defvar
+
address@hidden *print-miser-width*
+If this an integer, and the available width is less or equal to this value,
+then the pretty printer switch to the more @dfn{miser} compact style.
address@hidden defvar
+
address@hidden *print-xml-indent*
+When writing to XML, controls pretty-printing and indentation.
+If the value is @code{'always} or @code{'yes} force each element to
+start on a new suitably-indented line.
+If the value is @code{'pretty} only force new lines for elements that
+won't fit completely on a line.
+The the value is @code{'no} or unset, don't add extra whitespace.
address@hidden defvar
+
address@hidden Format, , Ports, Input-Output
address@hidden Formatted Output (Common-Lisp-style)
+
address@hidden Procedure format destination fmt . arguments
+An almost complete implementation of Common LISP format description
+according to the CL reference book @cite{Common LISP} from Guy L.
+Steele, Digital Press. Backward compatible to most of the available
+Scheme format implementations.
+
+Returns @code{#t}, @code{#f} or a string; has side effect of printing
+according to @var{fmt}. If @var{destination} is @code{#t},
+the output is to the current output port and @code{#!void} is returned. If
address@hidden is @code{#f}, a formatted string is returned as the
+result of the call. If @var{destination} is a string,
address@hidden is regarded as the format string; @var{fmt} is
+then the first argument and the output is returned as a string. If
address@hidden is a number, the output is to the current error port
+if available by the implementation. Otherwise @var{destination} must be
+an output port and @code{#!void} is address@hidden
+
address@hidden must be a string or an instance of @code{gnu.text.MessageFormat}
+or @code{java.text.MessageFormat}. If @var{fmt} is a string,
+it is parsed as if by @code{parse-format}.
address@hidden deffn
+
address@hidden Procedure parse-format format-string
+Parses @code{format-string}, which is a string of the form of a Common LISP
+format description. Returns an instance of @code{gnu.text.ReportFormat},
+which can be passed to the @code{format} function.
address@hidden deffn
+
+A format string passed to @code{format} or @code{parse-format}
+consists of format directives (that start with @samp{~}),
+and regular characters (that are written directly to the destination).
+Most of the Common Lisp (and Slib) format directives are implemented.
+Neither justification, nor pretty-printing are supported yet.
+
+Plus of course, we need documentation for @code{format}!
+
address@hidden Implemented CL Format Control Directives
+
+Documentation syntax: Uppercase characters represent the corresponding
+control directive characters. Lowercase characters represent control
+directive parameter descriptions.
+
address@hidden @asis
address@hidden ~a
address@hidden @code{~A}
+Any (print as @code{display} does).
address@hidden @asis
address@hidden @code{~@@A}
+left pad.
address@hidden @address@hidden,@var{colinc},@var{minpad},@var{padchar}A}
+full padding.
address@hidden table
address@hidden ~s
address@hidden @code{~S}
+S-expression (print as @code{write} does).
address@hidden @asis
address@hidden @code{~@@S}
+left pad.
address@hidden @address@hidden,@var{colinc},@var{minpad},@var{padchar}S}
+full padding.
address@hidden table
+
address@hidden ~c
address@hidden @code{~C}
+Character.
address@hidden @asis
address@hidden @code{~@@C}
+prints a character as the reader can understand it (i.e. @code{#\} prefixing).
address@hidden @code{~:C}
+prints a character as emacs does (eg. @code{^C} for ASCII 03).
address@hidden table
address@hidden table
+
address@hidden Formatting Integers
+
address@hidden @asis
address@hidden ~d
address@hidden @code{~D}
+Decimal.
address@hidden @asis
address@hidden @code{~@@D}
+print number sign always.
address@hidden @code{~:D}
+print comma separated.
address@hidden @address@hidden,@var{padchar},@var{commachar},@var{commawidth}D}
+padding.
address@hidden table
address@hidden ~x
address@hidden @code{~X}
+Hexadecimal.
address@hidden @asis
address@hidden @code{~@@X}
+print number sign always.
address@hidden @code{~:X}
+print comma separated.
address@hidden @address@hidden,@var{padchar},@var{commachar},@var{commawidth}X}
+padding.
address@hidden table
address@hidden ~o
address@hidden @code{~O}
+Octal.
address@hidden @asis
address@hidden @code{~@@O}
+print number sign always.
address@hidden @code{~:O}
+print comma separated.
address@hidden @address@hidden,@var{padchar},@var{commachar},@var{commawidth}O}
+padding.
address@hidden table
address@hidden ~b
address@hidden @code{~B}
+Binary.
address@hidden @asis
address@hidden @code{~@@B}
+print number sign always.
address@hidden @code{~:B}
+print comma separated.
address@hidden @address@hidden,@var{padchar},@var{commachar},@var{commawidth}B}
+padding.
address@hidden table
address@hidden ~r
address@hidden @address@hidden
+Radix @var{n}.
address@hidden @asis
address@hidden
@address@hidden,@var{mincol},@var{padchar},@var{commachar},@var{commawidth}R}
+padding.
address@hidden table
address@hidden @code{~@@R}
+print a number as a Roman numeral.
address@hidden @code{~:@@R}
+print a number as an ``old fashioned'' Roman numeral.
address@hidden @code{~:R}
+print a number as an ordinal English number.
address@hidden @code{~R}
+print a number as a cardinal English number.
address@hidden ~p
address@hidden @code{~P}
+Plural.
address@hidden @asis
address@hidden @code{~@@P}
+prints @code{y} and @code{ies}.
address@hidden @code{~:P}
+as @code{~P but jumps 1 argument backward.}
address@hidden @code{~:@@P}
+as @code{~@@P but jumps 1 argument backward.}
address@hidden table
address@hidden table
+
address@hidden is the number of characters between two comma characters.
+
+
address@hidden Formatting real numbers
+
address@hidden @asis
address@hidden ~f
address@hidden @code{~F}
+Fixed-format floating-point (prints a flonum like @var{mmm.nnn}).
address@hidden @asis
address@hidden
@address@hidden,@var{digits},@var{scale},@var{overflowchar},@var{padchar}F}
address@hidden @code{~@@F}
+If the number is positive a plus sign is printed.
address@hidden table
address@hidden table
+
address@hidden @asis
address@hidden ~e
address@hidden @code{~E}
+Exponential floating-point (prints a flonum like @address@hidden@var{ee})
address@hidden @asis
address@hidden
@address@hidden,@var{digits},@var{exponentdigits},@var{scale},@var{overflowchar},@var{padchar},@var{exponentchar}E}
address@hidden @code{~@@E}
+If the number is positive a plus sign is printed.
address@hidden table
address@hidden table
+
address@hidden @asis
address@hidden ~g
address@hidden @code{~G}
+General floating-point (prints a flonum either fixed or exponential).
address@hidden @asis
address@hidden
@address@hidden,@var{digits},@var{exponentdigits},@var{scale},@var{overflowchar},@var{padchar},@var{exponentchar}G}
address@hidden @code{~@@G}
+If the number is positive a plus sign is printed.
address@hidden table
+A slight difference from Common Lisp: If the number is printed
+in fixed form and the fraction is zero,
+then a zero digit is printed for the fraction, if allowed by the @var{width}
+and @var{digits} is unspecified.
address@hidden table
+
address@hidden @asis
address@hidden ~$
address@hidden @code{~$}
+Dollars floating-point (prints a flonum in fixed with signs separated).
address@hidden @asis
address@hidden @address@hidden,@var{scale},@var{width},@var{padchar}$}
address@hidden @code{~@@$}
+If the number is positive a plus sign is printed.
address@hidden @code{~:@@$}
+A sign is always printed and appears before the padding.
address@hidden @code{~:$}
+The sign appears before the padding.
address@hidden table
address@hidden table
+
address@hidden Miscellaneous formatting operators
+
address@hidden @asis
address@hidden ~%
address@hidden @code{~%}
+Newline.
address@hidden @asis
address@hidden @address@hidden
+print @var{n} newlines.
address@hidden table
address@hidden ~&
address@hidden @code{~&}
+print newline if not at the beginning of the output line.
address@hidden @asis
address@hidden @address@hidden&}
+prints @code{~&} and then @var{n-1} newlines.
address@hidden table
address@hidden ~|
address@hidden @code{~|}
+Page Separator.
address@hidden @asis
address@hidden @address@hidden|}
+print @var{n} page separators.
address@hidden table
address@hidden ~~
address@hidden @code{~~}
+Tilde.
address@hidden @asis
address@hidden @address@hidden
+print @var{n} tildes.
address@hidden table
address@hidden address@hidden
address@hidden @code{~}<newline>
+Continuation Line.
address@hidden @asis
address@hidden @code{~:}<newline>
+newline is ignored, white space left.
address@hidden @code{~@@}<newline>
+newline is left, white space ignored.
address@hidden table
address@hidden ~t
address@hidden @code{~T}
+Tabulation.
address@hidden @asis
address@hidden @code{~@@T}
+relative tabulation.
address@hidden @address@hidden,@var{colinc}T}
+full tabulation.
address@hidden table
address@hidden ~?
address@hidden @code{~?}
+Indirection (expects indirect arguments as a list).
address@hidden @asis
address@hidden @code{~@@?}
+extracts indirect arguments from format arguments.
address@hidden table
address@hidden ~(
address@hidden @code{~(@var{str}~)}
+Case conversion (converts by @code{string-downcase}).
address@hidden @asis
address@hidden @code{~:(@var{str}~)}
+converts by @code{string-capitalize}.
address@hidden @code{~@@(@var{str}~)}
+converts by @code{string-capitalize-first}.
address@hidden @code{~:@@(@var{str}~)}
+converts by @code{string-upcase}.
address@hidden table
address@hidden ~*
address@hidden @code{~*}
+Argument Jumping (jumps 1 argument forward).
address@hidden @asis
address@hidden @address@hidden
+jumps @var{n} arguments forward.
address@hidden @code{~:*}
+jumps 1 argument backward.
address@hidden @address@hidden:*}
+jumps @var{n} arguments backward.
address@hidden @code{~@@*}
+jumps to the 0th argument.
address@hidden @address@hidden@@*}
+jumps to the @var{n}th argument (beginning from 0)
address@hidden table
address@hidden @address@hidden;@var{str1}~;...~;@var{strn}~]}
+Conditional Expression (numerical clause conditional).
address@hidden @asis
address@hidden ~[
address@hidden @address@hidden
+take argument from @var{n}.
address@hidden @code{~@@[}
+true test conditional.
address@hidden @code{~:[}
+if-else-then conditional.
address@hidden ~;
address@hidden @code{~;}
+clause separator.
address@hidden @code{~:;}
+default clause follows.
address@hidden table
address@hidden @address@hidden@address@hidden
+Iteration (args come from the next argument (a list)).
address@hidden @asis
address@hidden @address@hidden@{}
+at most @var{n} iterations.
address@hidden address@hidden
address@hidden @code{~:@{}
+args from next arg (a list of lists).
address@hidden @code{~@@@{}
+args from the rest of arguments.
address@hidden @code{~:@@@{}
+args from the rest args (lists).
address@hidden table
address@hidden ~^
address@hidden @code{~^}
+Up and out.
address@hidden @asis
address@hidden @address@hidden
+aborts if @var{n} = 0
address@hidden @address@hidden,@var{m}^}
+aborts if @var{n} = @var{m}
address@hidden @address@hidden,@var{m},@var{k}^}
+aborts if @var{n} <= @var{m} <= @var{k}
address@hidden table
address@hidden table
+
address@hidden Unimplemented CL Format Control Directives
+
address@hidden @asis
address@hidden @code{~:A}
+print @code{#f} as an empty list (see below).
address@hidden @code{~:S}
+print @code{#f} as an empty list (see below).
address@hidden @code{~<~>}
+Justification.
address@hidden @code{~:^}
address@hidden table
+
address@hidden Extended, Replaced and Additional Control Directives
+
+These are not necesasrily implemented in Kawa!
+
address@hidden @asis
address@hidden @code{~I}
+print a R4RS complex number as @code{~F~@@Fi} with passed parameters for
address@hidden
address@hidden @code{~Y}
+Pretty print formatting of an argument for scheme code lists.
address@hidden @code{~K}
+Same as @code{~?.}
address@hidden @code{~!}
+Flushes the output if format @var{destination} is a port.
address@hidden @code{~_}
+Print a @code{#\space} character
address@hidden @asis
address@hidden @address@hidden
+print @var{n} @code{#\space} characters.
address@hidden table
+
address@hidden @address@hidden
+Takes @var{n} as an integer representation for a character. No arguments
+are consumed. @var{n} is converted to a character by
address@hidden>char}. @var{n} must be a positive decimal address@hidden
address@hidden @code{~:S}
+Print out readproof. Prints out internal objects represented as
address@hidden<...>} as strings @code{"#<...>"} so that the format output can
always
+be processed by @code{read}.
address@hidden
address@hidden @code{~:A}
+Print out readproof. Prints out internal objects represented as
address@hidden<...>} as strings @code{"#<...>"} so that the format output can
always
+be processed by @code{read}.
address@hidden
address@hidden @code{~F, ~E, ~G, ~$}
+may also print number strings, i.e. passing a number as a string and
+format it accordingly.
address@hidden table
+
address@hidden Pretty-printing
address@hidden Pretty-printing
+
+Pretty-printing is displaying a data structure as text,
+by adding line-breaks and indenttaion so that the visual
+structure of the output corresponds to the logical structure of
+data structure. This makes it easier to read and understand.
+Pretty-printing takes into account the column width of the output
+so as to avoid using more lines than needed.
+
+Pretty-printing of standard sequences types such as lists and
+vectors is done by default. For example:
address@hidden
+#|kawa:11|# @kbd{(set! *print-right-margin* 50)}
+#|kawa:12|# @kbd{'(ABCDEF (aa bb cc dd) (x123456789}
+#|.....13|# @kbd{y123456789 z123456789) ABCDEFG HIJKL)}
+(ABCDEF (aa bb cc dd)
+ (x123456789 y123456789 z123456789) ABCDEFG HIJK)
address@hidden example
+Setting @code{*print-right-margin*} to 50
+causes output to be limited to 50 columns.
+Notice the top-level list has to be split,
+but sub-lists @code{(aa bb cc dd)}
+and @code{(x123456789 y123456789 z123456789)}
+don't need to be split.
+
+When outputting to a DomTerm REPL,
+then @code{*print-right-margin*} is ignored,
+and the line-breaking is actually handled by DomTerm.
+If you change the window width, DomTerm will dynamically
+re-calculate the line-breaks of previous pretten output.
+This works even in the case of a session saved to an HTML
+file, as long as JavaScript is enabled.
+
+The concepts and terminology are
+based on those of
@uref{https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node253.html,Common Lisp}.
+
address@hidden Pretty-printing Scheme forms
+
+Scheme and Lisp code is traditionally pretty-printed
+slightly differently than plain lists.
+The @code{pprint} procedure assumes the argument
+is a Scheme form, and prints its accordingly.
+For example the special form @code{(let ...)} is printed
+differently from a regular function call @code{(list ...)}.
+
address@hidden Procedure pprint obj [out]
+Assume @var{obj} is a Scheme form, and pretty-print it
+in traditional Scheme format. For example:
address@hidden
+#|kawa:1|# @kbd{(import (kawa pprint))}
+#|kawa:2|# @kbd{(define fib-form}
+#|.....3|# @kbd{ '(define (fibonacci n)}
+#|.....4|# @kbd{ (let loop ((i0 0) (i1 1) (n n))}
+#|.....5|# @kbd{ (if (<= n 0) i0}
+#|.....6|# @kbd{ (loop i1 (+ i0 i1) (- n 1))))))}
+#|kawa:7|# @kbd{(set! *print-right-margin* 80)}
+#|kawa:8|# @kbd{(pprint fib-form)}
+(define (fibonacci n)
+ (let loop ((i0 0) (i1 1) (n n)) (if (<= n 0) i0 (loop i1 (+ i0 i1) (- n
1)))))
+#|kawa:9|# @kbd{(set! *print-right-margin* 40)}
+#|kawa:10|# @kbd{(pprint fib-form)}
+(define (fibonacci n)
+ (let loop ((i0 0) (i1 1) (n n))
+ (if (<= n 0)
+ i0
+ (loop i1 (+ i0 i1) (- n 1)))))
address@hidden example
+
+The @code{pprint} special-cases forms that start with
address@hidden, @code{if}, @code{lambda}, @code{let},
+and a few more, and formats them with ``traditional'' indentation.
+However, it is not as complete or polished as it should be.
+(It should also use a programmable dispatch table,
+rather than having these special cases hard-wired.
+That is an improvemet for another day.)
address@hidden deffn
+
address@hidden Generic pretty-printing functions
+
+The following procedures are used to indicate logical blocks,
+and optional newlines.
+
+To access them do:
address@hidden
+(import (kawa pprint))
address@hidden example
+
+In the following, @var{out} is the output port, which
+defaults to @code{(current-output-port)}.
+
address@hidden Syntax pprint-logical-block @var{options} @address@hidden
+
+Evaluate the @var{statement}s within the context of a new ``logical block''.
+
+
+The @var{options} are one or more of the following:
address@hidden @asis
address@hidden @stxlit{prefix:} @var{prefix}
address@hidden @stxlit{per-line:} @var{per-line-prefix}
+Emit @var{prefix} or @var{per-line-prefix} (only one of them can be specified)
before the start of the logical block.
+If @var{per-line-prefix} is provided, it is also print for each
+line within the logical block, indented the same.
+These are strings and default to @code{""}.
address@hidden @stxlit{suffix:} @var{suffix}
+Emit @var{suffix} after the end of the logical block.
address@hidden @stxlit{out:} @var{out}
+The output file.
address@hidden table
+
+For example to print a list you might do:
address@hidden
+(pprint-logical-block prefix: "(" suffix: ")"
+ @i{print contents of list})
address@hidden example
+
+This macro is equivalent to:
address@hidden
+(pprint-start-logical-block @var{prefix} @var{is-per-line} @var{suffix}
@var{out})
+(try-finally
+ (begin @address@hidden)
+ (pprint-end-logical-block @var{suffix} @var{out}))
address@hidden example
address@hidden deffn
+
address@hidden Procedure pprint-start-logical-block prefix is-per-line suffix
out
+Start a logical block.
+The @var{is-per-line} argument is a boolean to specifiy
+of @var{prefix} is a per-line-prefix or a plain prefix.
address@hidden deffn
address@hidden Procedure pprint-end-logical-block suffix out
+End a logical block.
address@hidden deffn
+
address@hidden Procedure pprint-newline kind [out]
+Print a conditional newline, where @var{kind} is one of the
+symbols @code{'fill}, @code{'linear}, @code{'mandatory},
+or @code{'miser}.
+Usually follows printing of a space, as nothing is printed
+if the line is not broken here.
address@hidden deffn
+
address@hidden Procedure pprint-ident mode amount [out]
+Change how much following lines are indented
+(with the current logical block).
+The @var{amount} is the size of the indentation, in characters.
+The @var{mode} is either @code{'current} (if the
address@hidden is relative to the current position),
+or @code{'block} (if the @var{amount} is relative to the
+start (after any @var{prefix}) of the current logical block).
address@hidden deffn
+
address@hidden Resources
address@hidden Resources
+
+A resource is a file or other fixed data that an application may access.
+Resources are part of the application and are shipped with it, but are
+stored in external files. Examples are images, sounds,
+and translation (localization) of messages.
+In the Java world a resource is commonly bundled in the same jar file
+as the application itself.
+
address@hidden Syntax resource-url resource-name
+Returns a @code{URLPath} you can use as a @code{URL}, or
+you can pass to it @code{open-input-file} to read the resource data.
+The @var{resource-name} is a string which is passed to the
address@hidden of the containing module.
+If the module class is in a jar file, things will magically
+work if the resource is in the same jar file, and @var{resource-name}
+is a filename relative to the module class in the jar.
+If the module is immediately evaluated, the @var{resource-name} is resolved
+against the location of the module source file.
address@hidden deffn
+
address@hidden Syntax module-uri
+Evaluates to a special URI that can be used to access resources
+relative to the class of the containing module.
+The URI has the form @code{"class-resource://@var{CurrentClass}/"}
+in compiled code, to allow moving the classes/jars.
+The current @code{ClassLoader} is associated with the URI, so accessing
+resources using the URI will use that @code{ClassLoader}.
+Therefore you should not create a @code{"class-resource:"} URI
+except by using this function or @code{resolve-uri},
+since that might try to use the wrong @code{ClassLoader}.
+
+The macro @code{resource-url} works by using @code{module-uri}
+and resolving that to a normal @code{URL}.
address@hidden deffn
+
address@hidden Syntax module-class
+Evaluates to the containing module class, as a @code{java.lang.Class} instance.
address@hidden deffn
+
address@hidden Types, Objects Classes and Modules, Input-Output, Top
address@hidden Types
+
+A @dfn{type} is a set of values, plus an associated set of operations
+valid on those values.
+Types are useful for catching errors ("type-checking"), documenting
+the programmer's intent, and to help the compiler generate better code.
+Types in some languages (such as C) appear in programs,
+but do not exist at run-time. In such languages, all type-checking
+is done at compile-time. Other languages (such as standard Scheme)
+do not have types as such, but they have @dfn{predicates}, which
+allow you to check if a value is a member of certain sets; also,
+the primitive functions will check at run-time if the arguments
+are members of the allowed sets. Other languages, including Java
+and Common Lisp, provide a combination: Types may be used as specifiers
+to guide the compiler, but also exist as actual run-time values.
+In Java, for each class, there is a corresponding @code{java.lang.Class}
+run-time object, as well as an associated type (the set of values
+of that class, plus its sub-classes, plus @code{null}).
+
+Kawa, like Java, has first-class types, that is types exist as
+objects you can pass around at run-time. For each Java type,
+there is a corresponding Kawa type (but not necessarily vice
+versa). It would be nice if we could represent run-time
+type values using @code{java.lang.Class} objects, but unfortunately
+that does not work very well. One reason is that we need
+to be able to refer to types and classes that do not exist yet,
+because we are in the processing of compiling them. Another
+reason is that we want to be able to distinguish between different
+types that are implemented using the same Java class.
+
+Various Kawa constructs require or allow a type to be specified.
+Those specifications consist of @dfn{type expressions}, and a type expression
+is evaluated to yield a type value. The current Kawa compiler
+is rather simple-minded, and in many places only allows simple
+types that the compiler can evaluate at compile-time.
+More specifically, it only allows simple @dfn{type names}
+that map to primitive Java types or Java classes.
+
address@hidden
address@hidden @stxref{expression}
address@hidden address@hidden::} @stxref{type}]
address@hidden display
+
address@hidden
+* Standard Types::
+* Parameterized Types::
+* Type tests and conversions::
address@hidden menu
+
address@hidden Standard Types
address@hidden Standard Types
+
+These types are predefined with the following names.
+
+Instead of plain @address@hidden you can also use
+the syntax @code{<@var{typename}>} with angle brackets,
+but that syntax is no longer recommended, because it doesn't
+``fit'' as well with some ways type names are used.
+
+To find which Java classes these types map into, look in
address@hidden/standard/Scheme.java}.
+
+Note that the value of these variables are instances
+of @code{gnu.bytecode.Type},
+not (as you might at first expect) @code{java.lang.Class}.
+
+The numeric types (@code{number}, @code{quantity},
address@hidden, @code{real}, @code{rational}, @code{integer},
address@hidden, @code{int}, @code{short}, @code{byte}
address@hidden, @code{uint}, @code{ushort}, @code{ubyte},
address@hidden, @code{float})
+are discussed in @ref{Numerical types}.
+
+The types @code{character} and @code{char}
+are discussed in @ref{Characters}.
+
address@hidden Object
+An arbitrary Scheme value - and hence an arbitrary Java object.
address@hidden defvar
+
address@hidden symbol
+The type of Scheme symbols.
+(Implemented using the Java class @code{gnu.mapping.Symbol}.)
+(@CompatibilityNote{} Previous versions of Kawa implemented
+a simple Scheme symbol using an interned @code{java.lang.String}.)
address@hidden defvar
+
address@hidden keyword
+The type of keyword values. @xref{Keywords}.
address@hidden defvar
+
address@hidden list
+The type of Scheme lists (pure and impure, including the empty list).
address@hidden defvar
+
address@hidden pair
+The type of Scheme pairs. This is a sub-type of @code{list}.
address@hidden defvar
+
address@hidden string
+The type of Scheme strings.
+(Implemented using @code{java.lang.String} for immutable strings,
+and @code{gnu.lists.FString} for mutable strings.
+Both of these implement the interface @code{java.lang.CharSequence}.
+In the future, we may change the representation for strings
+containing ``surrogate characters'', for efficient indexing.)
+(@CompatibilityNote{} Previous versions of Kawa
+always used @code{gnu.lists.FString}.)
address@hidden defvar
+
address@hidden character
+The type of Scheme character values. This is a sub-type of
address@hidden, in contrast to type @code{char}, which is the
+primitive Java @code{char} type.
address@hidden defvar
+
address@hidden vector
+The type of Scheme vectors.
address@hidden defvar
+
address@hidden procedure
+The type of Scheme procedures.
address@hidden defvar
+
address@hidden input-port
+The type of Scheme input ports.
address@hidden defvar
+
address@hidden output-port
+The type of Scheme output ports.
address@hidden defvar
+
address@hidden String
+This type name is a special case. It specifies the class
address@hidden
+However, coercing a value to @code{String} is done by
+invoking the @code{toString} method on the value to be coerced.
+Thus it "works" for all objects.
+It also works for @code{#!null}.
+
+When Scheme code invokes a Java method, any parameter
+whose type is @code{java.lang.String} is converted
+as if it was declared as a @code{String}.
address@hidden defvar
+
address@hidden parameter
+A parameter object, as created by @code{make-parameter}.
+This type can take a type parameter (sic):
address@hidden
+(define-constant client ::parameter[Client] (make-parameter #!null))
address@hidden example
+This lets Kawa know that reading the parameter (as in @code{(client)})
+returns a value of the specified type (in this case @code{Client}).
address@hidden defvar
+
+More will be added later.
+
+A type specifier can also be one of the primitive Java types.
+The numeric types @code{long}, @code{int}, @code{short},
address@hidden, @code{float}, and @code{double} are converted from the
+corresponding Scheme number classes. Similarly, @code{char}
+can be converted to and from Scheme characters. The type
address@hidden matches any object, and the result is @code{false}
+if and only if the actual argument is @code{#f}.
+(The value @code{#f} is identical to @code{Boolean.FALSE},
+and @code{#t} is identical to @code{Boolean.TRUE}.)
+The return type @code{void} indicates that no value is returned.
+
+A type specifier can also be a fully-qualified Java class name
+(for example @code{java.lang.StringBuffer}). In that case,
+the actual argument is cast at run time to the named class.
+Also, @code{java.lang.StringBuffer[]} represents
+an array of references to @code{java.lang.StringBuffer} objects.
+
address@hidden
address@hidden dynamic
+Used to specify that the type is unknown, and is likely to change
+at run-time.
+Warnings about unknown member names are supressed
+(a run-time name lookup is formed).
+An expression of type @code{dynamic} is (statically) compatible with
+any type.
address@hidden defvar
+
address@hidden Parameterized Types
address@hidden Parameterized Types
+Kawa has some basic support for parameterized (generic) types.
+The syntax:
address@hidden
+Type[Arg1 Arg2 ... ArgN]
address@hidden example
+is more-or-less equivalent to Java's:
address@hidden
+Type<Arg1, Arg2, ..., ArgN>
address@hidden example
+
+This is a work-in-progress. You can use this syntax with
+fully-qualified class names, and also type aliases:
address@hidden
+(define v1 ::gnu.lists.FVector[gnu.math.IntNum] [4 5 6])
+(define-alias fv gnu.lists.FVector)
+(define v2 ::fv[integer] [5 6 7])
+(define-alias fvi fv[integer])
+(define v3 ::fvi [6 7 8])
address@hidden example
+
address@hidden Type tests and conversions
address@hidden Type tests and conversions
+
+Scheme defines a number of standard type testing predicates.
+For example @code{(vector? x)} is @code{#t} if and only if
address@hidden is a vector.
+
+Kawa generalizes this to arbitrary type names:
+If @var{T} is a type-name (that is in scope at compile-time),
+then @address@hidden is a one-argument function that returns
address@hidden if the argument is an instance of the type @address@hidden,
+and @code{#f} otherwise:
address@hidden
+(gnu.lists.FVector? #(123)) @result{} #t
+(let ((iarr (int[] 10))) (int[]? iarr)) @result{} #t
address@hidden example
+
+To convert (coerce) the result of an expression @var{value} to a
+type @var{T} use the syntax: @code{(->@var{T} @var{value})}.
address@hidden
+(->float 12) @result{} 12.0f0
address@hidden example
+
+In general:
address@hidden
+(@var{T}? @var{x}) @result{} (instance? @var{x} @var{T})
+(->@var{T} @var{x}) @result{} (as @var{T} @var{x})
address@hidden example
+
address@hidden Procedure instance? value type
+Returns @code{#t} iff @var{value} is an instance of type @var{type}.
+(Undefined if @var{type} is a primitive type, such as @code{int}.)
address@hidden deffn
+
address@hidden Procedure as type value
+Converts or coerces @var{value} to a value of type @var{type}.
+Throws an exception if that cannot be done.
+Not supported for @var{type} to be a primitive type such as @code{int}.
address@hidden deffn
+
address@hidden Objects Classes and Modules, XML tools, Types, Top
address@hidden Object, Classes and Modules
+
+Kawa provides various ways to define, create, and access Java objects.
+Here are the currently supported features.
+
+The Kawa module system is based on the features of the Java class system.
+
address@hidden
+* Defining new classes::
+* Anonymous classes::
+* Enumerations:: Enumeration types
+* Annotations::
+* Module classes:: Modules and how they are compiled to classes
+* Importing:: Importing from a library
+* Record types:: Defining Record Types
+* Dynamic records:: Creating New Record Types On-the-fly
+* Method operations:: Calling Java methods from Scheme
+* Allocating objects::
+* Field operations:: Accessing fields of Java objects
+* Mangling:: Mapping Scheme names to Java names
+* Scheme types in Java::
+* Array operations:: Using Java arrays
+* Loading Java functions into Scheme::
+* Evaluating Scheme expressions from Java::
address@hidden menu
+
address@hidden Syntax this
+Returns the "this object" - the current instance of the current class.
+The current implementation is incomplete, not robust, and not
+well defined. However, it will have to do for now.
+Note: "@code{this}" is a macro, not a variable, so you have to write
+it using parentheses: @samp{(this)}. A planned extension will
+allow an optional class specifier (needed for nested clases).
address@hidden deffn
+
address@hidden Defining new classes
address@hidden Defining new classes
+
+Kawa provides various mechanisms for defining new classes.
+The @code{define-class} and @code{define-simple-class} forms
+will usually be the preferred mechanisms. They have basically
+the same syntax, but have a couple of differences.
address@hidden allows multiple inheritance as well as true nested
+(first-class) class objects. However, the implementation
+is more complex: code using it is slightly slower, and the mapping to
+Java classes is a little less obvious. (Each Scheme class is implemented
+as a pair of an interface and an implementation class.)
+A class defined by @code{define-simple-class} is slightly more
+efficient, and it is easier to access it from Java code.
+
+The syntax of @code{define-class} are mostly compatible with that
+in the Guile and Stk dialects of Scheme.
+
address@hidden Syntax define-class @stxref{class-name} @stxlit{(}supers
address@hidden)} @arbno{(@stxref{annotation}|@stxref{option-pair})}
@stxref{field-or-method-decl} ...
address@hidden Syntax define-simple-class @stxref{class-name} @stxlit{(}supers
address@hidden)} @arbno{(@stxref{annotation}|@stxref{option-pair})}
@stxref{field-or-method-decl} ...
+
+Defines a new class named @var{class-name}. If @code{define-simple-class} is
+used, creates a normal Java class named @var{class-name} in the current
package.
+(If @var{class-name} has the form @code{<xyz>} the Java implementation
+type is named @code{xyz}.) For @code{define-class} the implementation is
+unspecified. In most cases, the compiler creates a class pair,
+consisting of a Java interface and a Java implementation class.
address@hidden deffn
address@hidden
address@hidden @stxref{identifier}
address@hidden @var{option-keyword} @var{option-value}
address@hidden @stxref{field-decl} | @stxref{method-decl}
address@hidden display
+
address@hidden General class properties
+
+The class inherits from the classes and interfaces listed in @var{supers}.
+This is a list of names of classes that are in scope (perhaps imported
+using @code{require}), or names for existing classes or interfaces
+optionally surrounded by @code{<>}, such as @code{<gnu.lists.Sequence>}.
+If @code{define-simple-class} is used, at most one of these may be
+the name of a normal Java class or classes defined using
address@hidden; the rest must be interfaces or classes
+defined using @code{define-class}.
+If @code{define-class} is used, @emph{all} of the classes listed
+in @var{supers} should be interfaces or classes defined using
address@hidden
+
address@hidden @asis
address@hidden @stxlit{interface:} @var{make-interface}
+Specifies whether Kawa generates a Java class, interface, or both.
+If @var{make-interface} is @code{#t}, then a Java interface is generated.
+In that case all the supertypes must be interfaces, and
+all the declared methods must be abstract.
+If @var{make-interface} is @code{#f}, then a Java class is generated.
+If @code{interface:} is unspecified, the default is @code{#f}
+for @code{define-simple-class}. For @code{define-class} the default
+is to generate an interface, and in addition (if needed) a helper
+class that implements the interface. (In that case any non-abstract methods
+are compiled to static methods. The methods that implement the interface
+are just wrapper methods that call the real static methods. This
+allows Kawa to implement true multiple inheritance.)
+
address@hidden @stxlit{access:} @var{kind}
+Specifies the Java access permission on the class.
+Can be one of @code{'public} (which is the default in Kawa),
address@hidden'package} (which the default "unnamed" permission in Java code),
address@hidden'protected}, @code{'private},
address@hidden'volatile}, or @code{'transient}.
+Can also be used to specify @code{final}, @code{abstract}, or @code{enum}, as
in Java.
+(You don't need to explicitly specify the class is @code{abstract}
+if any @var{method-body} is @code{#!abstract},
+or you specify @code{interface: #t}.)
+The @var{kind} can also be a list, as for example:
address@hidden
+access: '(protected volatile)
address@hidden example
+
address@hidden @stxlit{class-name:} @code{"address@hidden@code{"}
+Specifies the Java name of the created class.
+The @var{name} specified after @code{define-class}
+or @code{define-simple-class} is the @emph{Scheme name},
+i.e. the name of a Scheme variable that is bound to the class.
+The Java name is by default derived from the Scheme name,
+but you can override the default with a @code{class-name:} specifier.
+If the @var{cname} has no periods, then it is a name in
+the package of the main (module) class.
+If the @var{cname} starts with a period,
+then you get a class nested within the module class.
+In this case the actual class name is @address@hidden@var{rname},
+where @var{rname} is @var{cname} without the initial period.
+To force a class in the top-level (unnamed) package (something
+not recommended) write a period at the end of the @var{cname}.
address@hidden table
+
address@hidden Declaring fields
+
address@hidden
address@hidden @stxlit{(address@hidden (@stxref{annotation} |
@stxref{opt-type-specifier} | @stxref{field-option})address@hidden)}
address@hidden @stxref{identifier}
address@hidden @stxref{keyword} @stxref{expression}
address@hidden display
+
+As a matter of style the following order is suggested, though this not
enforced:
address@hidden
address@hidden(address@hidden @stxref{annotation}* @stxref{opt-type-specifier}
@address@hidden)}
address@hidden display
+
+Each @var{field-decl} declares a instance "slot" (field)
+with the given @var{field-name}.
+By default it is publicly visible, but you can specify
+a different visiblity with the @code{access:} specifier.
+The following @var{field-option} @var{keyword}s are implemented:
address@hidden @asis
address@hidden @stxlit{type:} @stxref{type}
+Specifies that @var{type} is the type of (the values of) the field.
+Equivalent to @samp{:: @var{type}}.
address@hidden @stxlit{allocation:} @var{kind}
+If @var{kind} is @code{'class} or @code{'static} a single slot is shared
+between all instances of the class (and its sub-classes).
+Not yet implemented for @code{define-class},
+only for @code{define-simple-class}.
+In Java terms this is a @code{static} field.
+
+If @var{kind} is @code{'instance} then
+each instance has a separate value "slot", and they
+are not shared. In Java terms, this is a address@hidden field.
+This is the default.
+
address@hidden You can use a keyword like @code{class:} or a string like
@code{"class"}
address@hidden if you prefer instead of a quoted symbol like @code{'class};
address@hidden the latter is recommended.
address@hidden @stxlit{access:} @var{kind}
+Specifies the Java access permission on the field.
+Can be one of @code{'private}, @code{'protected},
address@hidden'public} (which is the default in Kawa),
+or @code{'package} (which the default "unnamed" permission
+in Java code).
+Can also be used to specify @code{volatile}, @code{transient},
address@hidden, or @code{final}, as in Java,
+or a quoted list with these symbols.
address@hidden @stxlit{init:} @var{expr}
+An expression used to initialize the slot.
+The expression is evaluated in a scope that includes the field and
+method names of the current class.
address@hidden @stxlit{init-form:} @var{expr}
+An expression used to initialize the slot.
+The lexical environment of the @var{expr} is that of the @code{define-class};
+it does @emph{not} include the field and method names of the current class.
+or @code{define-simple-class}.
address@hidden @stxlit{init-value:} @var{value}
+A value expression used to initialize the slot.
+For now this is synonymous with @var{init-form:}, but that may change
+(depending on what other implementation do), so to be safe only use
address@hidden:} with a literal.
address@hidden @stxlit{init-keyword:} @address@hidden:}
+A keyword that that can be used to initialize instance in @code{make} calls.
+For now, this is ignored, and @var{name} should be the same as the
+field's @var{field-name}.
address@hidden table
+
+The @var{field-name} can be left out. That indicates a "dummy slot",
+which is useful for initialization not tied to a specific field.
+In Java terms this is an instance or static initializer, i.e., a
+block of code executed when a new instance is created or the class is loaded.
+
+In this example, @code{x} is the only actual field. It is first
+initialized to 10, but if @code{(some-condition)} is true
+then its value is doubled.
address@hidden
+(define-simple-class <my-class> ()
+ (allocation: 'class
+ init: (perform-actions-when-the-class-is-initizalized))
+ (x init: 10)
+ (init: (if (some-condition) (set! x (* x 2)))))
address@hidden example
+
address@hidden Declaring methods
+
address@hidden
address@hidden @stxlit{((address@hidden @address@hidden)}
+ @address@hidden address@hidden @address@hidden)}
address@hidden @stxref{identifier}
address@hidden @stxref{annotation} | @stxref{opt-return-type} |
@stxref{option-pair}
address@hidden @stxref{body} | @stxlit{#!abstract} | @stxlit{#!native}
address@hidden @stxref{identifier}
address@hidden display
+
+Each @var{method-decl} declares a method,
+which is by default public and non-static, and whose name is @var{method-name}.
+(If @var{method-name} is not a valid
+Java method name, it is mapped to something reasonable.
+For example @code{foo-bar?} is mapped to @code{isFooBar}.)
+The types of the method arguments can be specified in the
address@hidden The return type can be specified by
+a @var{opt-return-type}, @var{deprecated-return-specifier},
+or is otherwise the type of the @var{body}.
+Currently, the @var{formal-arguments} cannot contain optional, rest,
+or keyword parameters. (The plan is to allow optional parameters,
+implemented using multiple overloaded methods.)
+
+A @var{method-decl} in a @code{define-simple-class}
+can have the following @var{option-keyword}s:
address@hidden @asis
address@hidden @stxlit{access:} @var{kind}
+Specifies the Java access permission on the method.
+Can be one of @code{'private}, @code{'protected},
address@hidden'public}, or @code{'package}.
+Can also be @code{'synchronized}, @code{'final}, @code{'strictfp},
+or a quoted list.
address@hidden @stxlit{allocation:} @var{kind}
+If @var{kind} is @code{'class} or @code{'static} creates a static method.
address@hidden @stxlit{throws:} ( @var{exception-class-name} ... )
+Specifies a list of checked exception that the method may throw.
+Equivalent to a @code{throws} specification in Java code.
+For example:
address@hidden
+(define-simple-class T
+ (prefix)
+ ((lookup name) throws: (java.io.FileNotFoundException)
+ (make java.io.FileReader (string-append prefix name))))
address@hidden example
address@hidden table
+
+The scope of the @var{body} of a method includes the @var{field-decl}s
+and @var{method-decl}s of the class, including those inherited from
+superclasses and implemented interfaces.
+
+If the @var{method-body} is the special form @code{#!abstract},
+then the method is abstract. This means the method must
+be overridden in a subclass, and you're not allowed to
+create an instance of the enclosing class.
+
address@hidden
+(define-simple-class Searchable () interface: #t
+ ((search value) :: boolean #!abstract))
address@hidden example
+
+If the @var{method-body} is the special form @code{#!native},
+then the method is native, implemented using
@uref{http://en.wikipedia.org/wiki/Java_Native_Interface,JNI}.
+
+The special @var{method-name} @samp{*init*} can be used to name
+a non-default constructor (only if @var{make-interface} discussed above
+is @code{#f}).
+It can be used to initialize a freshly-allocated instance
+using passed-in parameters.
+You can call a superclass or a sibling constructor using
+the @code{invoke-special} special function.
+(This is general but admittedly a bit verbose; a more compact
+form may be added in the future.)
+See the example below.
+
address@hidden Example
+
+In the following example we define a simple class @code{2d-vector}
+and a class @code{3d-vector} that extends it. (This is for illustration
+only - defining 3-dimensional points as an extension
+of 2-dimensional points does not really make sense.)
+
address@hidden
+(define-simple-class 2d-vector ()
+ (x ::double init-keyword: x:)
+ ;; Alternative type-specification syntax.
+ (y type: double init-keyword: y:)
+ (zero-2d :: 2d-vector allocation: 'static
+ init-value: (2d-vector 0))
+ ;; An object initializer (constructor) method.
+ ((*init* (x0 ::double) (y0 ::double))
+ (set! x x0)
+ (set! y y0))
+ ((*init* (xy0 ::double))
+ ;; Call above 2-argument constructor.
+ (invoke-special 2d-vector (this) '*init* xy0 xy0))
+ ;; Need a default constructor as well.
+ ((*init*) #!void)
+ ((add (other ::2d-vector)) ::2d-vector
+ ;; Kawa compiles this using primitive Java types!
+ (2d-vector
+ x: (+ x other:x)
+ y: (+ y other:y)))
+ ((scale (factor ::double)) ::2d-vector
+ (2d-vector x: (* factor x) y: (* factor y))))
+
+(define-simple-class 3d-vector (2d-vector)
+ (z type: double init-value: 0.0 init-keyword: z:)
+ ;; A constructor which calls the superclass constructor.
+ ((*init* (x0 ::double) (y0 ::double) (z0 ::double))
+ (invoke-special 2d-vector (this) '*init* x0 y0)
+ (set! z z0))
+ ;; Need a default constructor.
+ ((*init*) #!void)
+ ((scale (factor ::double)) ::2d-vector
+ ;; Note we cannot override the return type to 3d-vector
+ ;; because Kawa doesn't yet support covariant return types.
+ (3d-vector
+ x: (* factor x)
+ y: (* factor (this):y) ;; Alternative syntax.
+ z: (* factor z))))
address@hidden example
+
+Note we define both explicit non-default constructor methods,
+and we associate fields with keywords, so they can be named
+when allocating an object. Using keywords requires a default constructor,
+and since having non-default constructors suppresses
+the implicit default constructor we have to explicitly define it.
+Using both styles of constructors is rather redundant, though.
+
address@hidden Anonymous classes
address@hidden Anonymous classes
+
address@hidden Syntax object @stxlit{(}supers address@hidden)}
field-or-method-decl ...
+Returns a new instance of an anonymous (inner) class.
+The syntax is similar to @code{define-class}.
address@hidden
address@hidden @stxref{object-field-decl} | @stxref{method-decl}
address@hidden @stxlit{(address@hidden (@stxref{annotation} |
@stxref{opt-type-specifier} | @stxref{field-option})* address@hidden @stxlit{)}
address@hidden @stxref{expression}
address@hidden display
+
+Returns a new instance of a unique (anonymous) class.
+The class inherits from the list of @var{supers}, where at most one of the
+elements should be the base class being extended from, and the rest
+are interfaces.
+
+This is roughly equivalent to:
address@hidden
+(begin
+ (define-simple-class @var{hname} (@var{supers} ...)
@var{field-or-method-decl} ...)
+ (make @var{hname}))
address@hidden example
+
+A @var{field-decl} is as for @code{define-class}, except
+that we also allow an abbreviated syntax.
+Each @var{field-decl} declares a public instance field.
+If @var{object-finit} is given, it is an expression whose value
+becomes the initial value of the field.
+The @var{object-init} is evaluated at the same time as the @code{object}
+expression is evaluated,
+in a scope where all the @var{field-name}s are visible.
+
+A @var{method-decl} is as for @code{define-class}.
address@hidden deffn
+
address@hidden
address@hidden Lambda as shorthand for anonymous class
+An anonymous class is commonly used in the Java platform where a
+function language would use a lambda expression.
+Examples are call-back handlers, events handlers, and @code{run} methods.
+In these cases Kawa lets you use a lambda expression as a short-hand
+for an anonymous class. For example:
address@hidden
+(button:addActionListener
+ (lambda (e) (do-something)))
address@hidden example
+is equivalent to:
address@hidden
+(button:addActionListener
+ (object (java.awt.event.ActionListener)
+ ((actionPerformed (e ::java.awt.event.ActionEvent))::void
+ (do-something))))
address@hidden example
+This is possible when the required type is an interface or
+abstract class with a Single (exactly one) Abstract Methods.
+Such a class is sometypes called a @dfn{SAM-type}, and the
+conversion from a lambda expression to an anonymous class
+is sometimes called @dfn{SAM-conversion}.
+
+Note that Kawa can also infer the parameter and return types
+of a method that overrides a method in a super-class.
+
address@hidden Enumerations
address@hidden Enumeration types
+
+An enumeration type is a set of named atomic enumeration values
+that are distinct from other values. You define the type
+using @code{define-enum}, and you reference enumeration values
+using colon notation:
address@hidden
+(define-enum colors (red blue green))
+(define favorite-color colors:green)
address@hidden example
+Displaying an enum just prints the enum name,
+but readable output using @code{write} (or the @code{~s} @code{format}
+specifier) prepends the type name:
address@hidden
+(format "~a" favorite-color) @result{} "green"
+(format "~s" favorite-color) @result{} "colors:green"
address@hidden example
+The static @code{values} method returns a Java array of the enumeration
+values, in declaration order, while @code{ordinal} yields the index
+of an enumeration value:
address@hidden
+(colors:values) @result{} [red blue green]
+((colors:values) 1) @result{} blue
+(favorite-color:ordinal) @result{} 2
address@hidden example
+If you invoke the enumeration type as a function,
+it will map the name (as a string) to the corresponding value.
+(This uses the @code{valueOf} method.)
address@hidden
+(colors "red") @result{} red
+(colors "RED") @result{} throws IllegalArgumentException
+(eq? favorite-color (colors:valueOf "green")) @result{} #t
address@hidden example
+
+Kawa enumerations are based on Java enumerations.
+Thus the above is similar to a Java5 @code{enum} declaration,
+and the type @code{colors} above extends @code{java.lang.Enum}.
+
address@hidden Syntax define-enum enum-type-name @var{option-pair}...
@stxlit{(}enum-value-name address@hidden)} @var{field-or-method-decl}...
+This declares a new enumeration type @var{enum-type-name},
+whose enumerations values are the @var{enum-value-name} list.
+You can specify extra options and members using
address@hidden and @var{field-or-method-decl},
+which are as in @code{define-simple-class}.
+(The @var{define-enum} syntax is similar to a
address@hidden that extends @code{java.lang.Enum}.)
address@hidden deffn
+
+(Note that R6RS has a separate Enumerations library @code{(rnrs enum)}.
+Unfortunately, this is not compatible with standard Java enums.
+R6RS enums are simple symbols, which means you cannot distinguish
+two enum values from different enumeration types if they have the
+same value, nor from a vanilla symbol. That makes them less useful.)
+
address@hidden Annotations
address@hidden Annotations of declarations
+
+The Java platform lets you associate with each declaration zero or more
address@hidden://download.oracle.com/javase/1.5.0/docs/guide/language/annotations.html,
annotations}.
+They provide an extensible mechanism to associate properties
+with declarations.
+Kawa support for annotations is not complete (the most important
+functionality missing is being able to declare annotation types),
+but is fairly functional.
+Here is a simple example illustrating use of
address@hidden://jcp.org/en/jsr/detail?id=222,JAXB annotations}:
+an @code{XmlRootElement} annotation on a class,
+and an @code{XmlElement} annotation on a field:
address@hidden
+(import (class javax.xml.bind.annotation XmlRootElement XmlElement))
+(define-simple-class Bib ( ) (@@XmlRootElement name: "bib")
+ (books (@@XmlElement name: "book" type: Book) ::java.util.ArrayList))
+(define-simple-class Book () ...)
address@hidden example
+
address@hidden://per.bothner.com/blog/2011/Using-JAXB-annotations, This
tutorial}
+explains the JAXB example in depth.
+
+Here is the syntax:
address@hidden
address@hidden @stxlit{(@@address@hidden @address@hidden)}
address@hidden @stxref{annotation-element-value}
+ | @stxref{annotation-element-pair} ...
address@hidden @stxref{keyword} @stxref{annotation-element-value}
address@hidden @stxref{expression}
address@hidden @stxref{expression}
address@hidden display
+
+An @var{annotations-element-values} consisting of just
+a single @var{annotation-element-value} is equivalent to an
address@hidden with a @code{value:} keyword.
+
+Each @var{keyword} must correspond to the name of
+an element (a zero-argument method) in the annotation type.
+The corresponding @var{annotation-element-value} must be compatible with the
+element type (return type of the method) of the annotation type.
+
+Allowed element types are of the following kinds:
address@hidden @bullet
address@hidden
+Primitive types, where the @var{annotation-element-value} must
+be number or boolean coercible to the element type.
address@hidden
+Strings, where the @var{annotation-element-value} is normally a string literal.
address@hidden
+Classes, where the @var{annotation-element-value} is normally
+a classname.
address@hidden
+Enumeration types. The value usually has the form
@address@hidden:@var{enumFieldname}}.
address@hidden
+Nested annotation types, where the @var{annotation-element-value} must
+be a compatible @var{annotation} value.
address@hidden
+An array of one of the allowable types.
+An array constructor expression works, but using the
+square bracket syntax is recommended.
address@hidden itemize
+
+Annotations are usually used in declarations,
+where they are required to be ``constant-folded'' to compile-time
+constant annotation values.
+This is so they can be written to class files.
+However, in other contexts an annotation can be used as an expression
+with general sub-expressions evaluated at run-time:
address@hidden
+(define bk-name "book")
+(define be (@@XmlElement name: bk-name type: Book))
+(be:name) @result{} "book"
address@hidden example
+(This may have limited usefulness: There are some bugs, including
+lack of support for default values for annotation elements.
+These bugs can be fixed if someone reports a need for
+runtime construction of annotation values.)
+
address@hidden Module classes
address@hidden Modules and how they are compiled to classes
+
+Modules provide a way to organize Scheme into
+reusable parts with explicitly defined interfaces to the rest
+of the program.
+A @dfn{module} is a set of definitions that the module @dfn{exports},
+as well as some @dfn{actions} (expressions evaluated for their side effect).
+The top-level forms in a Scheme source file compile a module;
+the source file is the @dfn{module source}.
+When Kawa compiles the module source, the result is the
address@hidden class}. Each exported definition is translated to
+a public field in the module class.
+
address@hidden Name visibility
+
+The definitions that a module exports are accessible to other modules.
+These are the "public" definitions, to use Java terminology.
+By default, all the identifiers declared at the top-level of a module
+are exported, except those defined using @code{define-private}.
+(If compiling with the @code{--main} flag,
+then by default no identifiers are exported.)
+However, a major purpose of using modules is to control the set of
+names exported. One reason is to reduce the chance of accidental
+name conflicts between separately developed modules. An even more
+important reason is to enforce an interface: Client modules should
+only use the names that are part of a documented interface, and should
+not use internal implementation procedures (since those may change).
+
+If there is a @code{module-export} (or @code{export})
+declaration in the module, then only those names listed are exported.
+There can be more than one @code{module-export}, and they can be
+anywhere in the Scheme file. The recommended style has
+a single @code{module-export} near the beginning of the file.
+
address@hidden
address@hidden Syntax module-export @address@hidden
address@hidden Syntax export @address@hidden
+The forms @code{export} and @code{module-export} are equivalent.
+(The older Kawa name is @code{module-export};
address@hidden comes from R7RS.)
+Either form specifies a list of identifiers which
+can be made visible to other libraries or programs.
address@hidden
address@hidden @var{identifier}
+ | @stxlit{(rename} @address@hidden @address@hidden@stxlit{)}
address@hidden display
+In the former variant, an @var{identifier} names a single binding
+defined within or imported into the library, where the
+external name for the export is the same as the name of
+the binding within the library.
+A @code{rename} spec exports the
+binding defined within or imported into the library and
+named by @address@hidden,
+using @address@hidden as the external name.
+
+Note that it is an error if there is no definition for @var{identifier}
+(or @address@hidden)
+in the current module, or if it is defined using @code{define-private}.
+
+As a matter of style, @code{export} or @code{module-export} should
+appear after @code{module-name} but @emph{before} other commands
+(including @code{import} or @code{require}).
+(This is a requirement if there are any cycles.)
+
address@hidden deffn
+
+In this module, @code{fact} is public and @code{worker} is private:
address@hidden
+(module-export fact)
+(define (worker x) ...)
+(define (fact x) ...)
address@hidden example
+
+Alternatively, you can write:
address@hidden
+(define-private (worker x) ...)
+(define (fact x) ...)
address@hidden example
+
address@hidden R7RS explicit library modules
+
+A R7RS @code{define-library} form is another way to create a module.
+The R7RS term @dfn{library} is roughly the same as a Kawa module.
+In Kawa, each source file is a @ref{implicit library,@dfn{implicit module}},
+which may contain zero or more explicit sub-modules (in
+the form of @code{define-library}) optionally followed by
+the definitions and expressions of the implicit (file-level) module.
+
address@hidden
address@hidden @i{library-definition}
address@hidden Syntax define-library @stxref{library-name} @address@hidden
address@hidden deffn
address@hidden
address@hidden @stxlit{(} @stxref{library-name-parts} @stxlit{)}
address@hidden @address@hidden
address@hidden display
+
+A @meta{library-name} is a list whose members are identifiers and
+exact non-negative integers. It is used to identify the library
+uniquely when importing from other programs or
+libraries. Libraries whose first identifier is @code{scheme} are
+reserved for use by the R7RS report and future versions of that
+report. Libraries whose first identifier is @code{srfi} are reserved
+for libraries implementing @uref{http://srfi.schemer.org/,Scheme Requests for
Implementation}.
+It is inadvisable, but not an error, for identifiers
+in library names to contain any of the characters @code{|} @code{\} @code{?}
address@hidden @code{<} @code{"} @code{:} @code{>} @code{+} @code{[} @code{]}
address@hidden/} @code {.} or control characters after escapes are
+expanded.
+
+See @ref{module-name} for how a @meta{library-name} is
+mapped to a class name.
+
address@hidden
address@hidden
+ @stxref{export-declaration}
+ | @stxref{import-declaration}
+ | @stxlit{(begin} @address@hidden @stxlit{)}
+ | @stxlit{(include} @address@hidden@stxlit{)}
+ | @stxlit{(include-ci} @address@hidden@stxlit{)}
+ | @stxlit{(include-library-declarations} @address@hidden@stxlit{)}
+ | @stxlit{(cond-expand} @address@hidden address@hidden(else}
address@hidden)address@hidden)}
+ | @stxref{statement}
address@hidden display
+
+The @code{begin}, @code{include}, and @code{include-ci} declarations are
+used to specify the body of the library. They have the
+same syntax and semantics as the corresponding expression types.
+This form of @code{begin} is analogous to, but not the
+same as regular @code{begin}.
+A plain @meta{statement} (which is allowed as a Kawa extension)
+is also part of the body of the library,
+as if it were wrapped in a @code{begin}).
+
+The @code{include-library-declarations} declaration is similar
+to @code{include} except that the contents of the file are
+spliced directly into the current library definition. This
+can be used, for example, to share the same @code{export} declaration
+among multiple libraries as a simple form of library interface.
+
+The @code{cond-expand} declaration has the same syntax and semantics
+as the @code{cond-expand} expression type, except that
+it expands to spliced-in library declarations rather than
+expressions enclosed in @code{begin}.
+
+When a library is loaded, its expressions are executed in
+textual order. If a library’s definitions are referenced in
+the expanded form of a program or library body, then that
+library must be loaded before the expanded program or
+library body is evaluated. This rule applies transitively. If
+a library is imported by more than one program or library,
+it may possibly be loaded additional times.
+
+Similarly, during the expansion of a library @code{(foo)}, if any
+syntax keywords imported from another library @code{(bar)} are
+needed to expand the library, then the library @code{(bar)} must
+be expanded and its syntax definitions evaluated before the
+expansion of @code{(foo)}.
+
+Regardless of the number of times that a library is loaded,
+each program or library that imports bindings from a library must
+do so from a single loading of that library, regardless
+of the number of import declarations in which it
+appears. That is, @code{(import (only (foo) a})) followed by
address@hidden(import (only (foo) b))} has the same effect as
address@hidden(import (only (foo) a b))}.
+
address@hidden How a module becomes a class
+
+If you want to just use a Scheme module as a module (i.e. @code{load}
+or @code{require} it), you don't care how it gets translated
+into a module class. However, Kawa gives you some control over how this
+is done, and you can use a Scheme module to define a class which
+you can use with other Java classes. This style of class definition
+is an alternative to @code{define-class},
+which lets you define classes and instances fairly conveniently.
+
+The default name of the module class is the main part of the
+filename of the Scheme source file (with directories and extensions
+stripped off). That can be overridden by the @code{-T} Kawa
+command-line flag. The package-prefix specified by the @code{-P}
+flag is prepended to give the fully-qualified class name.
+
address@hidden
address@hidden Syntax module-name name
address@hidden Syntax module-name <name>
address@hidden Syntax module-name @stxref{library-name}
+Sets the name of the generated class, overriding the default.
+If there is no @samp{.} in the @var{name}, the package-prefix
+(specified by the @code{-P} Kawa command-line flag) is prepended.
+
+If the form @meta{library-name} is used,
+then the class name is the result of taking
+each @meta{identifier} in the @meta{library-name-parts},
address@hidden,mangling} if needed, and concatenating them
+separated by periods.
+For example @code{(org example doc-utils)} becomes
address@hidden (You can't reference the class name
address@hidden directly in Java, but the JVM has no problems with it.
+In Java you can use reflection to access classes with such names.)
+
+As a matter of style, @code{module-name} should be the first
+command in a file (after possible comments). It must appear
+before a @code{require} or @code{import}, in case of cycles.
address@hidden deffn
+
+By default, the base class of the generated module class is unspecified;
+you cannot count on it being more specific than @code{Object}.
+However, you can override it with @code{module-extends}.
+
address@hidden Syntax module-extends class
+Specifies that the class generated from the immediately surrounding
+module should extend (be a sub-class of) the class @address@hidden
address@hidden deffn
+
address@hidden Syntax module-implements interface ...
+Specifies that the class generated from the immediately surrounding
+module should implement the interfaces listed.
address@hidden deffn
+
+Note that the compiler does @emph{not} currently check that all the
+abstract methods requires by the base class or implemented interfaces
+are actually provided, and have the correct signatures. This will
+hopefully be fixed, but for now, if you are forgot a method, you will
+probably get a verifier error
+
+For each top-level exported definition the compiler creates a
+corresponding public field with a similar (mangled) name.
+By default, there is some indirection: The value of the Scheme variable
+is not that of the field itself. Instead, the field is a
address@hidden object, and the value Scheme variable is
+defined to be the value stored in the @code{Location}.
+Howewer, if you specify an explicit type, then the field will
+have the specified type, instead of being a @code{Location}.
+The indirection using @code{Location} is also avoided if you use
address@hidden
+
+If the Scheme definition defines a procedure (which is not re-assigned
+in the module), then the compiler assumes the variable as bound as a
+constant procedure. The compiler generates one or more methods
+corresponding to the body of the Scheme procedure. It also generates
+a public field with the same name; the value of the field is an
+instance of a subclass of @code{<gnu.mapping.Procedure>} which when
+applied will execute the correct method (depending on the actual arguments).
+The field is used when the procedure used as a value (such as being passed
+as an argument to @code{map}), but when the compiler is able to do so,
+it will generate code to call the correct method directly.
+
+You can control the signature of the generated method by declaring
+the parameter types and the return type of the method. See the
+applet (@pxref{Applet compilation}) example for how this can be done.
+If the procedures has optional parameters, then the compiler will
+generate multiple methods, one for each argument list length.
+(In rare cases the default expression may be such that this is
+not possible, in which case an "variable argument list" method
+is generated instead. This only happens when there is a nested
+scope @emph{inside} the default expression, which is very contrived.)
+If there are @code{#!keyword} or @code{#!rest} arguments, the compiler
+generate a "variable argument list" method. This is a method whose
+last parameter is either an array or a @code{<list>}, and whose
+name has @code{$V} appended to indicate the last parameter is a list.
+
+Top-leval macros (defined using either @code{define-syntax}
+or @code{defmacro}) create a field whose type is currently a sub-class of
address@hidden; this allows importing modules to detect
+that the field is a macro and apply the macro at compile time.
+
+Unfortunately, the Java class verifier does not allow fields to have
+arbitrary names. Therefore, the name of a field that represents a
+Scheme variable is "mangled" (@pxref{Mangling}) into an acceptable Java name.
+The implementation can recover the original name of a field @code{X}
+as @code{((gnu.mapping.Named) X).getName()} because all the standard
+compiler-generated field types implement the @code{Named} interface.
+
address@hidden
address@hidden Same class for module and defined class
+
+You can declare a class using @code{define-simple-class}
+with the same name as the module class, for example the
+following in a file named @code{foo.scm}:
address@hidden
+(define-simple-class foo ...)
address@hidden example
+In this case the defined class will serve dual-purpose as the module class.
+
+To avoid confusion, in this case you must not specify
address@hidden, @code{module-implements}, or @code{(module-static #t)}.
+Also, the defined class should not have public static members.
+In that case it works out pretty well: public static members
+represent bindings exported by the module; other non-private members
+``belong'' to the defined class.
+
+In this case @code{(module-static 'init-run)} is implied.
+
address@hidden
address@hidden Static vs non-static modules
+
+There are two kinds of module class:
+A @dfn{static module} is a class (or gets compiled to a class)
+all of whose public fields are static, and that does not have a
+public constructor. A JVM can only have a single global instance of
+a static module.
+An @dfn{instance module} has a public default constructor,
+and usually has at least one non-static public field.
+There can be multiple instances
+of an instance module; each instance is called a @dfn{module instance}.
+However, only a single instance of a module can be @dfn{registered}
+in an environment, so in most cases there is only a single
+instance of instance modules. Registering an instance in an environment
+means creating a binding mapping a magic name (derived from the class name)
+to the instance.
+
+In fact, any Java class class that has the properties of either
+an instance module or a static module, is a module, and can be
+loaded or imported as such; the class need not have written
+using Scheme.
+
+You can control whether a module is compiled to a static or
+a non-static class using either a command-line flag to the compiler,
+or using the @code{module-static} special form.
+
address@hidden @code
address@hidden --module-static
+Generate a static module
+(as if @code{(module-static #t)} were specified).
+This is (now) the default.
address@hidden --module-nonstatic
address@hidden --no-module-static
+Generate a non-static module
+(as if @code{(module-static #f)} were specified).
+This used to be the default.
address@hidden --module-static-run
+Generate a static module
+(as if @code{(module-static 'init-run)} were specified).
address@hidden table
+
address@hidden Syntax module-static name ...
address@hidden Syntax module-static @code{#t}
address@hidden Syntax module-static @code{#f}
address@hidden Syntax module-static @code{'init-run}
+Control whether the generated fields and methods are static.
+If @code{#t} or @code{'init-run} is specified, then the module will be a
+static module, @emph{all} definitions will be static.
+If @code{'init-run} is specified, in addition the module body
+is evaluated in the class's static initializer.
+(Otherwise, it is run the first time it is @code{require}'d.)
+Otherwise, the module is an instance module. If there is a non-empty
+list of @var{name}s then the module is an instance module, but the @var{name}s
+that are explicitly listed will be compiled to static fields and methods.
+If @code{#f} is specified, then all exported names will
+be compiled to non-static (instance) fields and methods.
+
+By default, if no @code{module-static} is specified:
address@hidden
address@hidden
+If there is a @code{module-extends} or @code{module-implements}
+declaration, or one of the @code{--applet} or @code{--servlet}
+command-line flags was specified, then @code{(module-static #f)} is implied.
address@hidden
+If one of the command-line flags
address@hidden, @code{--module-nonstatic},
address@hidden, or @code{--module-static-run} was specified,
+then the default is @code{#f}, @code{#f}, @code{#t}, or @code{'init-run},
+respectively.
address@hidden
+If the module class is @ref{dual-purpose-class,dual-purpose}
+then @code{(module-static 'init-run)} is implied.
address@hidden
+Otherwise the default is @code{(module-static #t)}.
+(It used to be @code{(module-static #f)} in older Kawa versions.)
address@hidden enumerate
+
+The default is @code{(module-static #t)}. It usually produces more efficient
+code, and is recommended if a module contains only procedure or macro
+definitions. However, a static module means that all environments in a JVM
+share the same bindings, which you may not want if you use
+multiple top-level environments.
address@hidden deffn
+
+The top-level actions of a module will get compiled to a @code{run}
+method. If there is an explicit @code{method-extends}, then the
+module class will also automatically implement @code{java.lang.Runnable}.
+(Otherwise, the class does not implement @code{Runnable}, since in that
+case the @code{run} method return an @code{Object} rather than @code{void}.
+This will likely change.)
+
address@hidden Module options
+
+Certain compilation options can be be specified @emph{either}
+on the command-line when compiling, or in the module itself.
+
address@hidden Syntax module-compile-options address@hidden:} value] ...
+This sets the value of the @code{key} option to @code{value}
+for the current module (source file). It takes effect as
+soon it is seen during the first macro-expansion pass,
+and is active thereafter (unless overridden by @code{with-compile-options}).
+
+The @var{key:} is one of the supported option names
+(The ending colon makes it a Kawa keyword). Valid
+option keys are:
+
address@hidden @bullet
address@hidden
address@hidden:} - Generate an application, with a main method.
address@hidden itemize
+
address@hidden @bullet
address@hidden
address@hidden:} - Use a calling convention that supports proper tail recursion.
address@hidden itemize
+
address@hidden @bullet
address@hidden
address@hidden:} - Warn if no compiler-visible binding for a variable.
+
address@hidden
address@hidden:} - Warn if referencing an unknown method or field.
+
address@hidden
address@hidden:} - Warn if invoke calls an unknown method (subsumed by
warn-unknown-member).
+
address@hidden
address@hidden:} - Warn if a variable is usused or code never executed.
+
address@hidden
address@hidden:} - Warn if this code can never be executed.
address@hidden
address@hidden:} - Warn if an expression depends on the value of a void
sub-expression (one that never returns a value).
address@hidden
address@hidden:} - Treat a compilation warning as if it were an error.
address@hidden itemize
+
+The @var{value} must be a literal value: either a boolean
+(@code{#t} or @code{#f}), a number, or a string,
+depending on the @var{key}.
+(All the options so far are boolean options.)
+
address@hidden
+(module-compile-options warn-undefined-variable: #t)
+;; This causes a warning message that y is unknown.
+(define (func x) (list x y))
address@hidden example
address@hidden deffn
+
address@hidden Syntax with-compile-options [key: value] ... body
+Similar to @code{module-compile-options}, but the option
+is only active within @var{body}.
+
+The module option key @code{main:} has no effect when applied
+to a particular body via the @code{with-compile-options} syntax.
+
address@hidden
+(define (func x)
+ (with-compile-options warn-invoke-unknown-method: #f
+ (invoke x 'size)))
address@hidden example
address@hidden deffn
+
address@hidden Importing
address@hidden Importing from a library
+
address@hidden
+You can import a module into the current namespace with @code{import} or
@code{require}. This adds the exported bindings (or a subset of them) to the
+current lexical scope. It follows that these bindings (which are said
+to be imported) are determined at compile-time.
+
address@hidden
address@hidden Syntax import @address@hidden
+An @code{import} declaration provides a way to import identifiers
+exported by a library (module). Each @meta{import-set} names a set of
+bindings from a library and possibly specifies local names
+for the imported bindings.
address@hidden
address@hidden
+ @meta{classname}
+ | @stxref{library-reference}
+ | @stxlit{(library} @stxref{library-reference} @stxlit{)}
+ | @stxlit{(class} @var{class-prefix} @address@hidden@stxlit{)}
+ | @stxlit{(only} @stxref{import-set} @address@hidden@stxlit{)}
+ | @stxlit{(except} @stxref{import-set} @address@hidden@stxlit{)}
+ | @stxlit{(prefix} @stxref{import-set} @var{identifier} @stxlit{)}
+ | @stxlit{(rename} @stxref{import-set} @address@hidden@stxlit{)}
address@hidden @stxlit{(} @stxref{library-name-parts} address@hidden@stxlit{)}
address@hidden @var{identifier}|@stxref{rename-pair}
address@hidden @stxref{string}
address@hidden @stxlit{(} @address@hidden @address@hidden@stxlit{)}
address@hidden display
+
+A @var{library-reference} is mapped to a class name by concatenating
+all the identifiers, separated by dots.
+For example:
address@hidden
+(import (gnu kawa slib srfi37))
address@hidden example
+is equivalent to:
address@hidden
+(import gnu.kawa.slib.srfi37)
address@hidden example
+as well as to:
address@hidden
+(require gnu.kawa.slib.srfi37)
address@hidden example
+
+By default, all of an imported library's exported bindings are made
+visible within an importing library using the names given to the
+bindings by the imported library. The precise set of bindings to be
+imported and the names of those bindings can be adjusted with the
address@hidden, @code{except}, @code{prefix}, and @code{ rename} forms as
+described below.
+
address@hidden
address@hidden
+An @code{only} form produces a subset of the bindings from another
address@hidden, including only the listed @meta{identifier}s. The
+included @meta{identifier}s must be in the original @meta{import-set}.
+If a @var{rename-pair} is used, then the @address@hidden@sub{1}}
+must be in the original @meta{import-set},
+and is renamed to @address@hidden@sub{2}}. For example:
address@hidden
+(import (only (kawa example) A (B1 B2) C (D1 D2)))
address@hidden example
+is equivalent to:
address@hidden
+(import (rename (only (kawa example) A B1 C D1)
+ (B1 B2) (D1 D2)))
address@hidden example
+The names @code{A}, @code{B1}, @code{C}, and @code{D1} must
+exist in the library @code{(kawa example)}. The bindings are
+accessible using the names @code{A}, @code{B2}, @code{C}, and @code{D2}.
+
address@hidden
+An @code{except} form produces a subset of the bindings from another
address@hidden, including all but the listed @meta{identifier}s. All
+of the excluded @meta{identifier}s must be in the original @meta{import-set}.
+
address@hidden
+A @code{prefix} form adds the @meta{identifier} prefix to each name from
+another @meta{import-set}.
+
address@hidden
+A @code{rename} form:
address@hidden
+(rename (@address@hidden @address@hidden) @dots{})
address@hidden example
address@hidden
+removes the bindings for @address@hidden@sub{1} @dots{}} to form an
+intermediate @meta{import-set}, then adds the bindings back for the
+corresponding @address@hidden@sub{2} @dots{}} to form the final
address@hidden Each @address@hidden@sub{1}} must be in the original
address@hidden, each @address@hidden must not be in the
+intermediate @meta{import-set}, and the @address@hidden must be
+distinct.
address@hidden itemize
+
+A @code{class} form is a convenient way to define abbreviations
+for class names; it may be more convenient than @code{define-alias}.
+The @var{class-prefix} is concatenated with each @meta{identifier}
+(with a period in between) to produce a classname.
+Each @meta{identifier} becomes an alias for the class.
+For example:
address@hidden
+(import (class java.util Map (HashMap HMap)))
address@hidden example
+This defines @code{Map} as an alias for @code{java.util.Map},
+and @code{HMap} as an alias for @code{java.util.HashMap}.
+(You can think of the @code{class} form as similar to a @code{only} form,
+where the @var{class-prefix} names a special kind of
+library represented of a Java package, and whose exported
+bindings are the classes in the package.)
+
+You can combine the @code{class} form with
address@hidden, @code{except}, @code{rename}, and @code{prefix},
+though only @code{prefix} is likely to be useful. For example:
address@hidden
+(import (prefix (class java.lang Long Short) jl-))
address@hidden example
+is equivalent to
address@hidden
+(import (class java.lang (Long jl-Long) (Short jl-Short)))
address@hidden example
+which is equivalent to:
address@hidden
+(define-private-alias jl-Short java.lang.Short)
+(define-private-alias jl-Long java.lang.Long)
address@hidden example
address@hidden deffn
+
address@hidden Syntax require @stxlit{'}featureName
address@hidden Syntax require classname address@hidden
address@hidden Syntax require @stxref{explicit-source-name}]
+Search for a matching module (class), and add the names
+exported by that module to the current set of visible names.
+Normally, the module is specified using @var{classname}.
+
+The form @code{require} has similar functionality as @code{import},
+but with a different syntax, and without options like @code{rename}.
+
+If a @address@hidden"address@hidden@stxlit{"}} is specified then
+that is used to locate the source file for the module, and if necessary,
+compile it.
+
+If a @code{'@var{featurename}} is specified then the
address@hidden is looked up (at compile time) in the "feature table"
+which yields the implementing @var{classname}.
address@hidden deffn
+
address@hidden Syntax provide @stxlit{'}featurename
+Declare that @code{'@var{featurename}} is available.
+A following @code{cond-expand} in this scope will match @var{featurename}.
address@hidden deffn
+
+Using @code{require} and @code{provide} with @var{featurename}s is
+similar to the same-named macros in SLib, Emacs, and Common Lisp.
+However, in Kawa these are not functions, but instead they
+are syntax forms that are processed at compile time. That is
+why only quoted @var{featurename}s are supported.
+This is consistent with Kawa emphasis on compilation and
+static binding.
+
+For some examples, you may want to look in the @code{gnu/kawa/slib}
+directory.
+
address@hidden Searching for modules
+
+When Kawa sees a @code{import} or @code{require} it searches for
+either a matching source file or a previously-compiled class with a
+matching name.
+
+For @code{import} we generate a classname by converting it in the same
+way @code{module-name} does: taking each identifier in the
address@hidden, mangling if needed, and concatenating the parts
+separated by periods.
+
+If there is a matching module in any @meta{program-unit} that is
+in the process of being compiled, we use that. This may be
+a file requested to be compiled with the @code{-C} command-line switch,
+or an extra @meta{library-definition} in a file already parsed.
+Kawa will attempt to finish compiling the module and load the class,
+but if there are circular dependencies it will use the uncompiled definitions.
+
+Next Kawa looks for a matching class in the context classpath.
+(There is special handling if the library-name starts with @code{srfi},
+and certain builtin classes will have @code{kawa.lib.} prepended.)
+
+Kawa also searches for a matching source file, described below.
+It uses the implicit source name (formed by concatenating the
+library-name parts, separated by @code{"/"}), as well as
+any @meta{explicit-source-name}. The source file is parsed as
+a @stxref{program-unit}. It is an error if the @meta{program-unit}
+does not declare a library (explicit or implicit) with the
+matching name.
+
+If Kawa finds both a matching source file and a class, it will pick one
+based on which is newer.
+
address@hidden Searching for source files
+
+The Java property @code{kawa.import.path} controls how @code{import}
+and @code{require} search for a suitable source file. Example usage:
address@hidden
+$ kawa -Dkawa.import.path=".:<foo fo>/opt/fo-libs/*.scm:/usr/local/kawa"
address@hidden example
+
+The value of the @code{kawa.import.path} property is a list of
+path elements, separated by @code{":"}.
+Each path element is combined with either the explicit source name
+or the implicit source name to produce a filename.
+If a matching file exists, then we have found a source file.
+
+If a path element contains a @code{"*"} then the @code{"*"}
+is replaced by the implicit source name (without an extension).
+(Any explicit source name is ignored in this case.)
+For example, for @code{(import (foo bar))} or @code{(require foo.bar)}
+the implicit source name is @code{"foo/bar"}. If the path element is
address@hidden"/opt/kawa/*.sc"} then the resulting filename is
@code{"/opt/kawa/foo/bar.sc"}.
+
+If there is no @code{"*"} in the path element, and there is an
+explicit source, then it is appended to the path element
+(or replaces the path element if the explicit source is absolute).
+Otherwise we use the implicit source, followed by the default file extension.
+(The default file extension is that of the current source if that is a
+named file; otherwise the default for the current language, which
+is @code{".scm"} for Scheme.)
+
+A path element that starts with a selector of the
+form @code{"<@stxref{library-name-parts}>"} is only applicable if a prefix
+of the requested module name matches the @meta{library-name-parts}. If there
+is @code{"*"} in the path element, that is replaced by the corresponding rest
+of the implicit source name. For example if importing @code{(fee fo foo fum})
+and the path element is @code{"<fee fo>/opt/fo-libs/*.scm"} then the
+resulting filename is @code{"/opt/fo-libs/foo/fum.scm"}.
+If there is a selector but no @code{"*"}, then the rest of the path element
+following the selector is combined with the explicit or implicit source
+as if there were no selector (assuming of course that the selector matches).
+
+If the resulting filename is relative, then it is resolved
+relative to the @dfn{current root}. For example the source to
+a library with the name @code{(x y)} that compiles to
+a class @code{x.y} might be a file named @code{/a/b/x/y.scm}.
+Then the current root would be @code{/a/b/}
+- that is the directory that results from removing the library name
+suffix from the file name.
+
+More generally: assume the current module has @math{N} name components.
+For example the name @code{(x y)}
+(with the class name @code{x.y}) has 2 components.
+The current root is what you get when you take the current file name
+(say @code{"/a/b/c/d.scm"}), and remove everything after
+the @math{N}'th slash (@code{"/"}) from the end (say @code{"c/d.scm"};
+what remains (e.g. @code{"/a/b/"} is the current root.
+(If the current input source is not a named file,
+use the value of @code{(current-path)} with a @code{"/"} appended.)
+
+The default search path is @code{"."} - i.e. just search relative
+to the current root.
+
address@hidden Builtin libraries
+
+The following libraries are bundled with Kawa:
+
address@hidden @code
address@hidden (scheme base)
address@hidden (scheme case-lambda)
address@hidden (scheme char)
address@hidden (scheme complex)
address@hidden (scheme cxr)
address@hidden (scheme cxr)
address@hidden (scheme eval)
address@hidden (scheme inexact)
address@hidden (scheme lazy)
address@hidden (scheme load)
address@hidden (scheme process-context)
address@hidden (scheme read)
address@hidden (scheme repl)
address@hidden (scheme time)
address@hidden (scheme write)
address@hidden (scheme r5rs)
+The above are standard libraries as defined by R7RS.
address@hidden (rnrs arithmetic bitwise)
address@hidden (rnrs hashtables)
address@hidden (rnrs lists)
address@hidden (rnrs programs)
address@hidden (rnrs sorting)
address@hidden (rnrs unicode)
+The above are standard libraries as defined by R6RS.
address@hidden (kawa reflect)
+Defines procedures and syntax for acessing Java objects and members:
+ @code{as}
+ @code{field}
+ @code{instance?}
+ @code{invoke}
+ @code{invoke-static}
+ @code{invoke-special}
+ @code{make}
+ @code{primitive-throw}
+ @code{set-field!}
+ @code{set-static-field!}
+ @code{static-field}
address@hidden (kawa expressions)
address@hidden (kawa hashtable)
address@hidden (kawa quaternions)
address@hidden (kawa rotations)
address@hidden (kawa regex)
address@hidden (kawa string-cursors)
+Various Kawa libraries @i{add details}.
address@hidden (kawa base)
+All the bindings by default available to the kawa top-level.
address@hidden table
+
address@hidden Importing a SRFI library
+
+Importing a supported SRFI numbered @var{N} is conventionally
+doing using a @code{(import (srfi @var{N}))}
+or the older R6RS syntax @code{(import (srfi :@var{N}))} (with a colon, for
historical reasons). You can also give it
+a name, as specified by
@uref{http://srfi.schemers.org/srfi-95/srfi-95.html,SRFI 95}. For example, any
of these work:
address@hidden
+(import (srfi 95))
+(import (srfi 95 sorting-and-merging))
+(import (srfi :95))
+(import (srfi :95 sorting-and-merging))
address@hidden example
+You can also use @code{(require 'address@hidden)}:
address@hidden
+(require 'srfi-95)
address@hidden example
+
address@hidden Importing from a plain class
+
+Note you can import from many classes, even if they weren't
+compiled from a library-definition. The set of @code{public} fields
+in a class are considered as the set of exported definitions,
+with the names demangled as needed.
+
+The module can be static module (all public fields must be static),
+or an instance module (it has a public default constructor).
+
+If an imported definition is a non-static field and if no module
+instance for that class
+has been registered in the current environment, then a new instance
+is created and registered (using a "magic" identifier).
+If the module class either inherits from @code{gnu.expr.ModuleBody}
+or implements @code{java.lang.Runnable} then the corresponding @code{run}
+method is executed. (This is done @emph{after} the instance is
+registered so that cycles can be handled.) These actions (creating,
+registering, and running the module instance) are done both at compile
+time and at run time, if necessary.
+
+All the imported fields of the module class are then incorporated
+in the current set of local visible names in the current module.
+(This is for both instance and static modules.)
+This is done at compile time - no new bindings are created at run-time
+(except for the magic binding used to register the module instance),
+and the imported bindings are private to the current module.
+References to the imported bindings will be compiled as field
+references, using the module instance (except for static fields).
+
address@hidden Record types
address@hidden Record types
+
+The @code{define-record-type} form can be used for creating new data
+types, called record types. A predicate, constructor, and field
+accessors and modifiers are defined for each record type.
+The @code{define-record-type} feature is specified
+by @uref{http://srfi.schemers.org/srfi-9/srfi-9.html,SRFI-9},
+which is implemented by many modern Scheme implementations.
+
address@hidden Syntax define-record-type @var{type-name}
(@var{constructor-name} @var{field-tag} ...) @var{predicate-name}
(@var{field-tag} @var{accessor-name} address@hidden) ...
+
+The form @code{define-record-type} is generative: each use creates a new
+record type that is distinct from all existing types, including other
+record types and Scheme's predefined types. Record-type definitions may
+only occur at top-level (there are two possible semantics for `internal'
+record-type definitions, generative and nongenerative, and no consensus
+as to which is better).
+
+An instance of @code{define-record-type} is equivalent to the following
definitions:
address@hidden
address@hidden
+The @var{type-name} is bound to a representation of the record type
+itself.
address@hidden
+The @var{constructor-name} is bound to a procedure that takes
+as many arguments as there are @var{field-tag}s in the
address@hidden(@var{constructor-name} ...)} subform and returns
+a new @var{type-name} record. Fields whose tags are listed with
address@hidden have the corresponding argument as their initial
+value. The initial values of all other fields are unspecified.
address@hidden
+The @var{predicate-name} is a predicate that returns @code{#t}
+when given a value returned by @var{constructor-name}
+and @code{#f} for everything else.
address@hidden
+Each @var{accessor-name} is a procedure that takes a record of
+type @var{type-name} and returns the current value of the corresponding field.
+It is an error to pass an accessor a value which is not a record of the
+appropriate type.
address@hidden
+Each @var{modifier-name} is a procedure that takes a record of
+type @var{type-name} and a value which becomes the new value of
+the corresponding field.
+The result (in Kawa) is the empty value @code{#!void}.
+It is an error to pass a
+modifier a first argument which is not a record of the appropriate type.
address@hidden itemize
+
+Set!ing the value of any of these identifiers has no effect on the
+behavior of any of their original values.
address@hidden deffn
+
+Here is an example of how you can define a record type named @code{pare}
+with two fields @code{x} and @code{y}:
address@hidden
+(define-record-type pare
+ (kons x y)
+ pare?
+ (x kar set-kar!)
+ (y kdr))
address@hidden example
+
+The above defines @code{kons} to be a constructor,
address@hidden and @code{kdr} to be accessors,
address@hidden to be a modifier,
+and @code{pare?} to be a predicate for @code{pare}s.
address@hidden
+(pare? (kons 1 2)) @result{} #t
+(pare? (cons 1 2)) @result{} #f
+(kar (kons 1 2)) @result{} 1
+(kdr (kons 1 2)) @result{} 2
+(let ((k (kons 1 2)))
+ (set-kar! k 3)
+ (kar k)) @result{} 3
address@hidden example
+
+Kawa compiles the record type into a nested class.
+If the @code{define-record-type} appears at module level,
+the result is a class that is a member of the module class.
+For example if the above @code{pare} class is define in a
+module @code{parelib}, then the result is a class
+named @code{pare} with the internal JVM name @code{parelib$pare}.
+The @code{define-record-type} can appear inside a procedure,
+in which case the result is an inner class.
+
+The nested class has a name derived from
+the @var{type-name}. If the @var{type-name} is valid Java class name,
+that becomes the name of the Java class. If the @var{type-name} has
+the form @code{<@var{name}>} (for example @code{<pare>}), then @var{name}
+is used, if possible, for the Java class name. Otherwise, the name
+of the Java class is derived by "mangling" the @var{type-name}.
+In any case, the package is the same as that of the surrounding module.
+
+Kawa generates efficient code for the resulting functions,
+without needing to use run-time reflection.
+
address@hidden Dynamic records, Method operations, Record types, Objects
Classes and Modules
address@hidden Creating New Record Types On-the-fly
+
+Calling the @code{make-record-type} procedure creates a new record data
+type at run-time, without any compile-time support.
+It is primarily provided for compatibility; in most cases it is better
+to use the @code{define-record-type} form (@pxref{Record types}).
+
address@hidden Procedure make-record-type type-name field-names
+Returns a @dfn{record-type descriptor}, a value representing a new data
+type disjoint from all others. The @var{type-name} argument must be a
+string, but is only used for debugging purposes (such as the printed
+representation of a record of the new type). The @var{field-names}
+argument is a list of symbols naming the @dfn{fields} of a record of the
+new type. It is an error if the list contains any duplicates.
address@hidden deffn
+
address@hidden @deffn Procedure make-record-sub-type type-name field-names rtd
address@hidden Returns a @dfn{record-type descriptor}, a value representing a
new data
address@hidden type, disjoint from all others. The @var{type-name} argument
must be a
address@hidden string. The @var{field-names} argument is a list of symbols
naming the
address@hidden additional @dfn{fields} to be appended to @var{field-names} of
address@hidden @var{rtd}. It is an error if the combinded list contains any
address@hidden address@hidden
address@hidden
address@hidden Record-modifiers and record-accessors for @var{rtd} work for the
new
address@hidden record-sub-type as well. But record-modifiers and
record-accessors for
address@hidden the new record-sub-type will not neccessarily work for
@address@hidden
address@hidden @end deffn
+
address@hidden Procedure record-constructor rtd [field-names]
+Returns a procedure for constructing new members of the type represented
+by @var{rtd}. The returned procedure accepts exactly as many arguments
+as there are symbols in the given list, @var{field-names}; these are
+used, in order, as the initial values of those fields in a new record,
+which is returned by the constructor procedure. The values of any
+fields not named in that list are unspecified. The @var{field-names}
+argument defaults to the list of field names in the call to
address@hidden that created the type represented by @var{rtd};
+if the @var{field-names} argument is provided, it is an error if it
+contains any duplicates or any symbols not in the default list.
+
address@hidden In Kawa, @var{rtd} may be any @code{Class} that has a public
default
address@hidden constructor, as long as the @var{field-names} are public instance
address@hidden fields. (The fields should have type @code{Object} -- unless you
address@hidden know what you are doing!)
address@hidden deffn
+
address@hidden Procedure record-predicate rtd
+Returns a procedure for testing membership in the type represented by
address@hidden The returned procedure accepts exactly one argument and
+returns a true value if the argument is a member of the indicated record
+type; it returns a false value otherwise.
+
address@hidden In Kawa, the returned procedure checks if the argument is an
instance
address@hidden of @var{rtd} or one of its sub-classes.
address@hidden deffn
+
address@hidden @deffn Procedure record-sub-predicate rtd
address@hidden Returns a procedure for testing membership in the type
represented by
address@hidden @var{rtd} or its parents. The returned procedure accepts
exactly one
address@hidden argument and returns a true value if the argument is a member of
the
address@hidden indicated record type or its parents; it returns a false value
address@hidden address@hidden
address@hidden @end deffn
+
address@hidden Procedure record-accessor rtd field-name
+Returns a procedure for reading the value of a particular field of a
+member of the type represented by @var{rtd}. The returned procedure
+accepts exactly one argument which must be a record of the appropriate
+type; it returns the current value of the field named by the symbol
address@hidden in that record. The symbol @var{field-name} must be a
+member of the list of field-names in the call to @code{make-record-type}
+that created the type represented by @var{rtd}.
address@hidden deffn
+
address@hidden Procedure record-modifier rtd field-name
+Returns a procedure for writing the value of a particular field of a
+member of the type represented by @var{rtd}. The returned procedure
+accepts exactly two arguments: first, a record of the appropriate type,
+and second, an arbitrary Scheme value; it modifies the field named by
+the symbol @var{field-name} in that record to contain the given value.
+The returned value of the modifier procedure is unspecified. The symbol
address@hidden must be a member of the list of field-names in the call
+to @code{make-record-type} that created the type represented by @var{rtd}.
address@hidden deffn
+
address@hidden Procedure record? obj
+Returns a true value if @var{obj} is a record of any type and a false
+value otherwise.
address@hidden deffn
+
address@hidden Procedure record-type-descriptor record
+Returns a record-type descriptor representing the type of the given
+record. That is, for example, if the returned descriptor were passed to
address@hidden, the resulting predicate would return a true
+value when passed the given record.
address@hidden deffn
+
address@hidden Procedure record-type-name rtd
+Returns the type-name associated with the type represented by rtd. The
+returned value is @code{eqv?} to the @var{type-name} argument given in
+the call to @code{make-record-type} that created the type represented by
address@hidden@refill
address@hidden deffn
+
address@hidden Procedure record-type-field-names rtd
+Returns a list of the symbols naming the fields in members of the type
+represented by @var{rtd}. The returned value is @code{equal?} to the
+field-names argument given in the call to @code{make-record-type} that
+created the type represented by @address@hidden
address@hidden deffn
+
+Records are extensions of the class @code{Record}.
+These procedures use the Java 1.1 reflection facility.
+
address@hidden Method operations, Allocating objects, Dynamic records, Objects
Classes and Modules
address@hidden Calling Java methods from Scheme
+
+You can call a Java method as if it were a Scheme procedure
+using various mechanisms.
+
address@hidden Calling static methods using colon notation
+
+The easiest way to invoke a static method is to use
address@hidden notation, colon notation}, specifically:
address@hidden
address@hidden(address@hidden@stxlit{:address@hidden @var{argument}
address@hidden)}
address@hidden display
+
+The @var{class-expression} can be a class in the current lexical
+scope, such as a class defined using @code{define-simple-class}:
address@hidden
+(define-simple-class MyClass ()
+ ((add2 x y) allocation: 'static (+ x y)))
+(MyClass:add2 3 4) @result{} 7
address@hidden example
+
+Often @var{class-expression} is a fully-qualified class name:
address@hidden
+(java.lang.Math:sqrt 9.0) @result{} 3.0
address@hidden example
+
+This is only allowed when the name is of a class that exists
+and is accessible both at compile-time and run-time,
+and the name is not otherwise lexically bound.
+
+You can also use a defined alias:
address@hidden
+(define-alias jlMath java.lang.Math)
+(jlMath:sqrt 16.0) @result{} 4.0
address@hidden example
+
+You can even evaluate @var{class-expression} at run-time
+(in which case Kawa may have to use slower reflection):
address@hidden
+(let ((math java.lang.Math)) math:sqrt 9.0) @result{} 3.0
address@hidden example
+
+Here @code{java.lang.Math} evaluates to a @code{java.lang.Class}
+instance for the named class (like Java's @code{java.lang.Class.class},
+again assuming the class exists and is accessible both at compile-time and
+run-time, and the name is not otherwise lexically bound.
+
address@hidden Calling instance methods using colon notation
+
+The syntax is:
address@hidden
address@hidden(address@hidden@stxlit{:address@hidden @var{argument}
address@hidden)}
address@hidden display
+This invokes the method named @var{method-name}
+with the evaluated @var{instance} as the target object
+and the evaluated @var{argument}s as the method arguments.
+
+For example:
address@hidden
+((list 9 8 7):toString) @result{} "(9 8 7)"
+([5 6 7]:get 2) @result{} 7
address@hidden example
+
+This older syntax is also available:
address@hidden
address@hidden(*:address@hidden @var{instance} @var{argument} address@hidden)}
address@hidden display
+
+For example:
address@hidden
+(*:toString (list 9 8 7))
address@hidden example
+
+You can also name the class explicitly:
address@hidden
address@hidden(address@hidden@stxlit{:address@hidden @var{instance}
@var{argument} address@hidden)}
address@hidden display
+For example:
address@hidden
+(java.util.List:get [5 6 7] 2) @result{} 7
address@hidden example
+Using an explicit class is like coercing the @var{instance}:
address@hidden
address@hidden(*:address@hidden @stxlit{(as address@hidden @var{instance}
@stxlit{)address@hidden address@hidden)}
address@hidden display
+
+Note that for some special values,
+including @code{java.lang.Class} instances, you can't
+use the compact form of @ref{Colon notation, colon notation}
+where the @var{instance} is before the comma:
address@hidden
+(java.lang.Integer:getDeclaredField "MAX_VALUE") @result{} @i{error}
address@hidden example
+This is because in this case we look for a static member
+of @code{java.lang.Integer}
+(at least as currently defined and implemented),
+while we want an instance member of @code{java.lang.Class}.
+In those cases you can use one of
+these alternative forms, which all return the same
address@hidden result:
address@hidden
+(*:getDeclaredField java.lang.Integer "MAX_VALUE")
+(java.lang.Class:getDeclaredField java.lang.Integer "MAX_VALUE")
+(invoke java.lang.Integer 'getDeclaredField "MAX_VALUE")
address@hidden example
+
address@hidden Method names
+
+The method to invoke is selected using the specified
+method name and argments. If specified name is not a Java name,
+it is "mangled" (@pxref{Mangling}) into a valid Java name.
+All accessible methods whose names match are considered.
+Methods that match after appending @code{$V} or @code{$X} or @code{$V$X}
+are also considered. A @code{$V} suffix matches a variable
+number of arguments: any excess arguments are collect into an
address@hidden or a Java array (depending on the final parameter type).
+A @code{$X} specifies that the method expects an extra implicit
address@hidden parameter. In that case the method's result is written
+to the @code{CallContext}, so the method result type must be @code{void}.
+
+(Kawa may compile a procedure with a @code{#!rest} or keyword args
+whose name is @address@hidden to a method named @address@hidden
+It adds an implicit parameter for the extra arguments.
+By default this extra extra parameter is a Scheme list.
+You can specify a Java array type instead, in which case the method is
+named @address@hidden without the @code{$V},
+and instead it is marked as a Java-5 varargs method.
+The array element type must be compatible with all the extra arguments.)
+
address@hidden Invoking a method with the @code{invoke} function
+
+If you prefer, you can instead use the following functions.
+(There is also an older deprecated lower-level interface
+(@pxref{Low-level Method invocation}.)
+
address@hidden Procedure invoke-static class name args ...
+The @var{class} can be a @code{java.lang.Class}, a
address@hidden, or a @code{symbol} or @code{string}
+that names a Java class. The @var{name} can be @code{symbol} or
address@hidden that names one or more methods in the Java class.
+
+Any accessible methods (static or instance) in the specified @var{class}
+(or its super-classes) that match "@var{name}" or "@var{name}$V" collectively
+form a generic procedure. When the procedure is applied to the argument list,
+the most specific applicable method is chosen depending on the
+argument list; that method is then
+called with the given arguments. Iff the method is an instance method,
+the first actual argument is used as the @code{this} argument. If there are
+no applicable methods (or no methods at all!), or there is no "best"
+method, @code{WrongType} is thrown.
+
+An example:
address@hidden
+(invoke-static java.lang.Thread 'sleep 100)
address@hidden example
+
+The behavior of interpreted code and compiled code is not
+identical, though you should get the same result either way
+unless you have designed the classes rather strangely. The
+details will be nailed down later, but the basic idea is that
+the compiler will "inline" the @code{invoke-static} call
+if it can pick a single "best" matching method.
address@hidden deffn
+
address@hidden Procedure invoke object name args ...
+The @var{name} can be @code{<symbol>} or
address@hidden<string>} that names one or more methods in the Java class.
+
+Any accessible methods (static or instance) in the specified @var{class}
+(or its super-classes) that match "@var{name}" or "@var{name}$V" collectively
+form a generic procedure. When the procedure is applied to the argument list,
+the most specific applicable method is chosen depending on the
+argument list; that method is then
+called with the given arguments. Iff the method is an instance method,
+the @var{object} is used as the @code{this} argument;
+otherwise @var{object} is prepended to the @var{args} list. If there are
+no applicable methods (or no methods at all!), or there is no "best"
+method, @code{WrongType} is thrown.
+
+The behavior of interpreted code and compiled code is not
+indentical, though you should get the same result either way
+unless you have designed the classes rather strangely. The
+details will be nailed down later, but the basic idea is that
+the compiler will "inline" the @code{invoke-static} call
+if it can pick a single "best" matching method.
+
+If the compiler cannot determine the method to call (assuming
+the method name is constant), the compiler has to generate code
+at run-time to find the correct method. This is much slower,
+so the compiler will print a warning. To avoid a waning, you can
+use a type declaration, or insert a cast:
address@hidden
+(invoke (as java.util.Date my-date) 'setDate cur-date)
address@hidden example
+or
address@hidden
+(let ((my-date ::java.util.Date (calculate-date))
+ (cur-date ::int (get-cur-date)))
+ (invoke my-date 'setDate cur-date))
address@hidden example
address@hidden deffn
+
address@hidden Procedure invoke-special class receiver-object name arg ...
+The @var{class} can be a @code{java.lang.Class}, a
address@hidden, or a @code{symbol} or @code{string}
+that names a Java class.
+The @var{name} can be @code{symbol} or
address@hidden that names one or more methods in the Java class.
+
+This procedure is very similar to @code{invoke} and @code{invoke-static}
+and invokes the specified method, ignoring any methods in subclasses
+that might overide it. One interesting use is to invoke a method in
+your super-class like the Java language @code{super} keyword.
+
+Any methods in the specified @var{class} that match "@var{name}" or
+"@var{name}$V" collectively form a generic procedure. That generic
+procedure is then applied as in @code{invoke} using the
address@hidden and the arguments (if any).
+
+The compiler must be able to inline this procedure (because you cannot
+force a specific method to be called using reflection). Therefore the
address@hidden and @var{name} must resolve at compile-time to a specific
+method.
+
address@hidden
+(define-simple-class <MyClass> (<java.util.Date>)
+ ((get-year) :: <int>
+ (+ (invoke-special <java.util.Date> (this) 'get-year)) 1900)
+ ((set-year (year :: <int>)) :: <void>
+ (invoke-special <java.util.Date> (this) 'set-year (- year 1900))))
address@hidden example
address@hidden deffn
+
address@hidden Procedure class-methods class name
+Return a generic function containing those methods of @var{class}
+that match the name @var{name}, in the sense of @code{invoke-static}.
+Same as:
address@hidden
+(lambda args (apply invoke-static (cons class (cons name args))))
address@hidden example
address@hidden deffn
+
+Some examples using these functions are @samp{vectors.scm}
+and @samp{characters.scm} the directory @samp{kawa/lib} in
+the Kawa sources.
+
address@hidden Using a namespace prefix
+
address@hidden way of invoking a method is deprecated.}
+
+You can use @code{define-namespace} to define an alias for a Java class:
address@hidden
+(define-namespace Int32 "class:java.lang.Integer")
address@hidden example
+In this example the name @code{Int32} is a @dfn{namespace alias}
+for the namespace whose full name is @code{"class:java.lang.Integer"}.
+The full name should be the 6 characters @code{"class:"} followed
+by the fully-qualified name of a Java class.
+
+Instead of a @var{vamespace-uri} you can use a variable that names
+a class, usually of the form @code{<@var{classname}>}.
+The following is equivalent to the above:
address@hidden
+(define-namespace Int32 <java.lang.Integer>)
address@hidden example
+However, there is one important difference: The @code{<@var{classname}>}
+is first searched in the lexical scope.
+It may resolve to a class defined in the current compilation unit
+(perhaps defined using @code{define-simple-class}),
+or imported from another module,
+or an alias (such as from @code{define-alias}).
+Only if @code{<@var{classname}>} is @emph{not} found in the current
+scope is it tried as the class name @var{classname}.
+
+You can name a method using a @dfn{qualified name} containing a colon.
+The part of the name before the colon is a namespace alias (in
+this case @code{Int32}), and the part of the name after the colon is the
+method name. For example:
address@hidden
+(Int32:toHexString 255) @result{} "ff"
address@hidden example
+This invokes the static method @code{toHexString} in the
+Java class @code{java.lang.Integer}, passing it the argument @code{255},
+and returning the String @code{"ff"}.
+
+The general syntax is
address@hidden
+(@var{prefix}:@var{method-name} @var{arg} ...)
address@hidden example
+This invokes the method named @var{method-name} in the class corresponding
+to @var{prefix}, and the @var{arg}s are the method arguments.
+
+You can use the method name @code{new} to construct new objects:
address@hidden
+(Int32:new '|255|)
address@hidden example
+This is equivalent to the Java expression @code{new Integer("255")}.
+You can also write:
address@hidden
+(Int32:new "255")
address@hidden example
+
+You can also call instance methods using a namespace prefix:
address@hidden
+(Int32:doubleValue (Int32:new "00255"))
address@hidden example
+This returns the @code{double} value @code{255.0}.
+
+As a shorthand, you can use the name of a Java class instead of a
+namespace alias:
address@hidden
+(java.lang.Integer:toHexString 255)
+(java.lang.Object:toString some-value)
address@hidden example
+If Kawa sees a qualified name with a prefix that is not defined @emph{and}
+that matches the name of a known class, then Kawa will automatically
+treat the prefix
+as a nickname for namespace uri like @code{class:java.lang.Integer}.
+Both conditions should be true at both compile-time and run-time.
+However, using an explicit @code{define-namespace} is recommended.
+
+As a final shorthand you can use an identifier in handle brackets,
+such as an existing type alias like @code{<list>}.
+The following are all equivalent:
address@hidden
+(<list>:list3 'a 'b 'c)
address@hidden example
+This is equivalent to:
address@hidden
+(define-namespace @var{prefix} <list>
+(@var{prefix}:list3 'a 'b 'c)
address@hidden example
+for some otherwise-unused @var{prefix}.
+
address@hidden Allocating objects, Field operations, Method operations, Objects
Classes and Modules
address@hidden Allocating objects
+
+The recommended way to create an instance of a type @var{T}
+is to ``call'' @var{T} as if it were a function, with the
+arguments used to initialize the object.
+If @code{T} is a class and @code{T} has a matching constructor,
+then the arguments will used for constructor arguments:
address@hidden
+(java.util.StringTokenizer "this/is/a/test" "/")
address@hidden example
+(You can think of the type @var{T} as being
+coerced to an instance-constructor function.)
+
+If @code{T} is a container or collection type,
+then typically the arguments will be used to specify
+the child or component values.
+Many standard Scheme procedures fit this convention.
+For example in Kawa @code{list} and @code{vector} evaluate to
+types, rather than procedures as in standard Scheme,
+but because types can be used as constructor functions it just works:
address@hidden
+(list 'a (+ 3 4) 'c) @result{} (a 7 c)
+(vector 'a 'b 'c) @result{} #(a b c)
address@hidden example
+Any class @code{T} that has a default constructor
+and an @code{add} method can be initialized this way.
+Examples are @code{java.util} collection classes,
+and @code{jawa.awt} and @code{javax.swing} containers.
address@hidden
+(java.util.ArrayList 11 22 33) @result{} [11, 22, 333]
address@hidden example
+The above expression is equivalent to:
address@hidden
+(let ((tmp (java.util.ArrayList)))
+ (tmp:add 11)
+ (tmp:add 22)
+ (tmp:add 33)
+ tmp)
address@hidden example
+
+Allocating Java arrays (@pxref{Creating-new-Java-arrays}) uses a
+similar pattern:
address@hidden
+(int[] 2 3 5 7 11)
address@hidden example
+
+Sometimes you want to set some named property to an initial value.
+You can do that using a keyword argument. For example:
address@hidden
+(javax.swing.JButton text: "Do it!" tool-tip-text: "do it")
address@hidden example
+
+This is equivalent to using @dfn{setter methods}:
address@hidden
+(let ((tmp (javax.swing.JButton)))
+ (tmp:setText "Do it!")
+ (tmp:setToolTipText "do it")
+ tmp)
address@hidden example
+
+A keyword argument @address@hidden@stxlit{:} can
+can translated to either a @address@hidden@address@hidden:}}
+or a @address@hidden@address@hidden:}} method.
+The latter makes it convenient to add listeners:
+
address@hidden
+(javax.swing.JButton
+ text: "Do it!"
+ action-listener:
+ (object (java.awt.event.ActionListener)
+ ((actionPerformed e) (do-the-action))))
address@hidden example
+This is equivalent to:
address@hidden
+(let ((tmp (javax.swing.JButton)))
+ (tmp:setText "Do it!")
+ (tmp:addActionListener
+ (object (java.awt.event.ActionListener)
+ ((actionPerformed e) (do-the-action))))
+ tmp)
address@hidden example
+
+Making use of so-called ``SAM-conversion'' (@pxref{SAM-conversion})
+ makes it even more convenient:
address@hidden
+(javax.swing.JButton
+ text: "Do it!"
+ action-listener:
+ (lambda (e) (do-the-action)))
address@hidden example
+
+The general case allows for a mix of
+constructor arguments, property keywords, and child values:
address@hidden
address@hidden @stxref{constructor-value}... @stxref{property-initializer}...
@stxref{child-value}...
address@hidden @stxref{expression}
address@hidden @stxref{keyword} @stxref{expression}
address@hidden @stxref{expression}
address@hidden display
+
+First an object is constructed with the @var{constructor-value} arguments
+(if any) passed to the object constructor;
+then named properties (if any) are used to initialize named properties;
+and then remaining arguments are used to add child values.
+
+There is an ambiguity if there is no @var{property-initializer} -
+we can't distinguish between a @var{constructor-value}
+and a @var{child-value}.
+In that case, if there is a matching constructor method, then all of the
+arguments are constructor arguments;
+otherwise, there must a default constructor, and all
+of the arguments are @var{child-value} arguments.
+
+There is a trick you can you if you need both
address@hidden and @var{child-value} arguments:
+separate them with an ``empty keyword'' @code{||:}.
+This matches a method named @code{add}, which means that
+the next argument effectively a @var{child-value} - as do
+all the remaining arguments. Example:
address@hidden
+(let ((vec #(1 2 3)))
+ (java.util.ArrayList vec ||: 4 5 6))
+ @result{} [1, 2, 3, 4, 5, 6]
address@hidden example
+
+The compiler rewrites these allocations expression
+to generated efficient bytecode, assuming that the ``function''
+being applied is a type known by the compiler.
+Most of the above expressions also work if the type is applied
+at run-time, in which case Kawa has to use slower reflection:
address@hidden
+(define iarr int[])
+(apply iarr (list 3 4 5)) @result{} [3 4 5]
address@hidden example
+However @address@hidden methods and SAM-conversion
+are currently only recognized in the case of a class known at compile-time,
+not at run-time.
+
+Here is a working Swing demo illustrating many of these techniques:
+
address@hidden
+(import (class javax.swing
+ JButton Box JFrame))
+(define-simple-class HBox (Box)
+ ((*init*) (invoke-special Box (this) '*init* 0)))
+
+(define value 0)
+
+(define txt
+ (javax.swing.JLabel
+ text: "0"))
+
+(define (set-value i)
+ (set! value i)
+ (set! txt:text (number->string i)))
+
+(define fr
+ (JFrame
+ title: "Hello!"
+ (Box 1#|VERTICAL|# ||:
+ (javax.swing.Box:createGlue)
+ txt
+ (javax.swing.Box:createGlue)
+ (HBox
+ (JButton ;; uses 1-argument constructor
+ "Decrement" ;; constructor argument
+ tool-tip-text: "decrement"
+ action-listener: (lambda (e) (set-value (- value 1))))
+ (javax.swing.Box:createGlue)
+ (JButton ;; uses 0-argument constructor
+ text: "Increment"
+ tool-tip-text: "increment"
+ action-listener: (lambda (e) (set-value (+ value 1))))))))
+(fr:setSize 200 100)
+(set! fr:visible #t)
address@hidden example
+
+If you prefer, you can use the older @code{make} special function:
+
address@hidden Procedure make type args ...
+Constructs a new object instance of the specified @var{type},
+which must be either a @code{java.lang.Class} or a
address@hidden<gnu.bytecode.ClassType>}.
+Equivalent to:
address@hidden
address@hidden @var{args} ...
address@hidden example
address@hidden deffn
+
+Another (semi-deprecated) function is to use the colon notation
+with the @code{new} pseudo-function.
+The following three are all equivalent:
address@hidden
+(java.awt.Point:new x: 4 y: 3)
+(make java.awt.Point: x: 4 y: 3)
+(java.awt.Point x: 4 y: 3)
address@hidden example
+
address@hidden Field operations, Mangling, Allocating objects, Objects Classes
and Modules
address@hidden Accessing object fields
+
address@hidden Accessing static fields and properties
+
+The recommmended way to access fields
+uses the @ref{Colon notation, colon notation}.
+For static fields and properties the following is recommended:
address@hidden
address@hidden@stxlit{:address@hidden
address@hidden display
+For example:
address@hidden
+java.lang.Integer:MAX_VALUE
address@hidden example
+
+A property with a @code{get} method is equivalent to a field.
+The following are all equivalent:
address@hidden
+java.util.Currency:available-currencies
+java.util.Currency:availableCurrencies
+(java.util.Currency:getAvailableCurrencies)
address@hidden example
+
+Just like for a method call, the @var{class-expression}
+can be a class in the current lexical scope,
+a fully-qualified class name, or more generally an
+expression that evaluates to a class.
+
address@hidden Accessing instance fields and properties
+
+The syntax is:
address@hidden
address@hidden@stxlit{:address@hidden
address@hidden display
+
+The @var{field-name} can of course be the name of an actual
+object field, but it can also be the name of a property with
+a zero-argument @code{get} method.
+For example, if @code{cal} is a @code{java.util-Calendar} instance,
+then the following are all equivalent:
address@hidden
+cal:time-zone
+cal:timeZone
+(cal:getTimeZone)
+(cal:get-time-zone)
address@hidden example
+
+You can use colon notation to assign to a field:
address@hidden
+(set! cal:time-zone TimeZone:default)
address@hidden example
+which is equivalent to:
address@hidden
+(cal:setTimeZone (TimeZone:getDefault))
address@hidden example
+
+A Java array only has the @code{length} field, plus the @code{class} property:
address@hidden
+(int[] 4 5 6):length @result{} 3
+(int[] 4 5 6):class:name @result{} "int[]"
address@hidden example
+
address@hidden Using field and static-field methods
+
+The following methods are useful in cases where colon notation
+is ambiguous, for example where there are both fields and methods
+with the same name.
+You might also prefer as a matter of style, to
+emphasise that a field is being accessed.
+
address@hidden Procedure field object fieldname
+Get the instance field with the given @var{fieldname} from the given
address@hidden Returns the value of the field, which must be accessible.
+This procedure has a @code{setter}, and so can be used as the first
+operand to @code{set!}.
+
+The field name is "mangled" (@pxref{Mangling}) into a valid Java name.
+If there is no accessible field whose name is @code{"@var{fieldname}"},
+we look for a no-argument method whose name is
address@hidden"address@hidden"} (or @code{"address@hidden"} for a
+boolean property).
+
+If @var{object} is a primitive Java array, then @var{fieldname} can only
+be @code{'length}, and the result is the number of elements of the array.
address@hidden deffn
+
address@hidden Procedure static-field class fieldname
+Get the static field with the given @var{fieldname} from the given
address@hidden Returns the value of the field, which must be accessible.
+This procedure has a @code{setter}, and so can be used as the first
+operand to @code{set!}.
+
+If the @var{fieldname} is the special name @code{class},
+then it returns the @code{java.lang.Class} object corresponding to
address@hidden (which is usually a @code{gnu.bytecode.ClassType} object).
address@hidden deffn
+
+Examples:
address@hidden
+(static-field java.lang.System 'err)
+;; Copy the car field of b into a.
+(set! (field a 'car) (field b 'car))
address@hidden example
+
address@hidden Procedure slot-ref object fieldname
+A synonym for @code{(field @var{object} @var{fieldname})}.
address@hidden deffn
+
address@hidden Procedure slot-set! object fieldname value
+A synonym for @code{(set! (field @var{object} @var{fieldname}) @var{value})}.
address@hidden deffn
+
address@hidden Older colon-dot notation
+
+There is older syntax where following the colon
+there is field name a following the colon @emph{and} a period.
+
+To access an static field named @var{field-name} use this syntax
address@hidden
+(@var{prefix}:address@hidden @var{instance})
address@hidden example
+The @var{prefix} can be as discussed in @xref{Method operations}.
+Here are 5 equivalent ways:
address@hidden
+(java.lang.Integer:.MAX_VALUE)
+(<java.lang.Integer>:.MAX_VALUE)
+(define-namespace Int32 <java.lang.Integer>)
+(Int32:.MAX_VALUE)
+(define-namespace Integer "class:java.lang.Integer")
+(Integer:.MAX_VALUE)
+(define-alias j.l.Integer java.lang.Integer)
+(j.l.Integer:.MAX_VALUE)
address@hidden example
+You can set a static field using this syntax:
address@hidden
+(set! (@var{prefix}:address@hidden) @var{new-value})
address@hidden example
+
+The special field name @code{class} can be used to extract the
address@hidden object for a class-type. For example:
address@hidden
+(java.util.Vector:.class) @result{} class java.util.Vector
address@hidden example
+
+To access a instance field named @var{field-name} use the following syntax.
+Note the period before the @var{field-name}.
address@hidden
+(*:address@hidden @var{instance})
address@hidden example
+This syntax works with @code{set!} - to set the field use this syntax:
address@hidden
+(set! (*:address@hidden @var{instance}) @var{new-value})
address@hidden example
+Here is an example:
address@hidden
+(define p (list 3 4 5))
+(*:.cdr p) @result{} (4 5)
+(set! (*:.cdr p) (list 6 7))
+p @result{} (3 6 7)
address@hidden example
+
+You can specify an explicit class:
address@hidden
+(@var{prefix}:address@hidden @var{instance})
address@hidden example
+If @var{prefix} is bound to @code{<@var{class}>}, then the above
+is equivalent to:
address@hidden
+(*:address@hidden (as <@var{class}> @var{instance}))
address@hidden example
+
address@hidden Mangling, Scheme types in Java, Field operations, Objects
Classes and Modules
address@hidden Mapping Scheme names to Java names
+
+Programs use "names" to refer to various values and procedures.
+The definition of what is a "name" is different in different
+programming languages. A name in Scheme (and other Lisp-like
+languages) can in principle contain any character (if using a
+suitable quoting convention), but typically names consist of
+"words" (one or more letters) separated by hyphens, such
+as @samp{make-temporary-file}. Digits
+and some special symbols are also used. Traditionally, Scheme is
+case-insensitive; this means that the names @samp{loop},
address@hidden, and @samp{LOOP} are all the same name. Kawa
+is by default case-sensitive, but we recommend that you
+avoid using upper-case letters as a general rule.
+
+The Java language and the Java virtual machine uses names for
+classes, variables, fields and methods.
+Names in the Java language can contain upper- and lower-case letters,
+digits, and the special symbols @samp{_} and @samp{$}.
+The Java virtual machine (JVM) allows most characters, but still
+has some limitations.
+
+Kawa translates class names, package names, field names, and local variable
+names using the
address@hidden://blogs.oracle.com/jrose/entry/symbolic_freedom_in_the_vm,''symbolic''
convention}, so most characters are unchanged.
+For example the Scheme function @samp{file-exists?}
+becomes the field @samp{file-exists?}, but @code{dotted.name}
+becomes @samp{dotted\,name}.
+Such names may not be valid Java name, so to access them from a
+Java program you might have to use reflection.
+
+When translating procedure names to method names,
+Kawa uses a different translation, in order to achieve
+more ``Java-like'' names. This means translating a
+Scheme-style name like @samp{make-temporary-file} to
+"mixed-case" words, such as @samp{makeTemporaryFile}.
+The basic rule is simple: Hyphens are dropped, and
+a letter that follows a hyphen is translated to its
+upper-case (actually "title-case") equivalent. Otherwise,
+letters are translated as is.
+
+Some special characters are handled specially. A final @samp{?}
+is replaced by an @emph{initial} @samp{is}, with the following
+letter converted to titlecase. Thus @samp{number?} is
+converted to @samp{isNumber} (which fits with Java conventions),
+and @samp{file-exists?} is converted to @samp{isFileExists}
+(which doesn't really).
+The pair @samp{->} is translated to @samp{$To$}.
+For example @samp{list->string} is translated to @samp{list$To$string}.
+
+Some symbols are mapped to a mnemonic sequence, starting with a dollar-sign,
+followed by a two-character abbreviation. For example, the less-than
+symbol @samp{<} is mangled as @samp{$Ls}.
+See the source code to the @code{mangleName} method in the
address@hidden class for the full list.
+Characters that do not have a mnemonic abbreviation are
+mangled as @samp{$} followed by a four-hex-digit unicode value.
+For example @samp{Tamil vowel sign ai} is mangled as @samp{$0bc8}.
+
+Note that this mapping may map different Scheme names to the
+same Java name. For example @samp{string?}, @samp{String?},
address@hidden, @samp{is-String},
+and @samp{isString} are all mapped to the same Java identifier
address@hidden Code that uses such "Java-clashing" names
+is @emph{not} supported. There is very partial support for
+renaming names in the case of a clash, and there may be better
+support in the future. However, some of the nice features of
+Kawa depend on being able to map Scheme name to Java names
+naturally, so we urge you to @emph{not} write code that
+"mixes" naming conventions by using (say) the names @samp{open-file}
+and @samp{openFile} to name two different objects.
+
address@hidden Scheme types in Java, Array operations, Mangling, Objects
Classes and Modules
address@hidden Scheme types in Java
+
+All Scheme values are implemented by sub-classes of @samp{java.lang.Object}.
+
+Scheme symbols are implemented using @code{java.lang.String}.
+(Don't be confused by the fact the Scheme sybols are represented
+using Java Strings, while Scheme strings are represented by
address@hidden It is just that the semantics of Java strings
+match Scheme symbols, but do not match mutable Scheme strings.)
+Interned symbols are presented as interned Strings.
+(Note that with JDK 1.1 string literals are automatically interned.)
+
+Scheme integers are implemented by @code{gnu.math.IntNum}.
+Use the make static function to create a new IntNum from an int or a long.
+Use the intValue or longValue methods to get the int or long value of
+an IntNum.
+
+A Scheme "flonum" is implemented by @code{gnu.math.DFloNum}.
+
+A Scheme pair is implemented by @code{gnu.lists.Pair}.
+
+A Scheme vector is implemented by @code{gnu.lists.FVectror}.
+
+Scheme characters are implemented using @code{gnu.text.Char}.
+
+Scheme strings are implemented using @code{gnu.lists.FString}.
+
+Scheme procedures are all sub-classes of @code{gnu.mapping.Procedure}.
+The "action" of a @samp{Procedure} is invoked by using one of
+the @samp{apply*} methods: @samp{apply0}, @samp{apply1},
address@hidden, @samp{apply3}, @samp{apply4}, or @samp{applyN}.
+Various sub-class of @samp{Procedure} provide defaults
+for the various @samp{apply*} methods. For example,
+a @samp{Procedure2} is used by 2-argument procedures.
+The @samp{Procedure2} class provides implementations of all
+the @samp{apply*} methods @emph{except} @samp{apply2},
+which must be provided by any class that extends @code{Procedure2}.
+
address@hidden Array operations, Loading Java functions into Scheme, Scheme
types in Java, Objects Classes and Modules
address@hidden Using Java Arrays
+
address@hidden
address@hidden Creating new Java arrays
+To allocate a Java array you can use the array type specifier
+as a constructor function. For example, to allocate an array with room for 10
elements
+each of each is a primitive @code{int}:
address@hidden
+(int[] length: 10)
address@hidden example
+
+You can specify the initial elements instead of the length:
address@hidden
+(object[] 31 32 33 34)
address@hidden example
+This creates a 4-length array, initialized to the given values.
+
+Note this is a variation of the generation object-allocation
+(@pxref{Allocating objects}) pattern. You can explicitly
+use the @code{make} function, if you prefer:
address@hidden
+(make object[] 31 32 33 34)
address@hidden example
+
+If you specify a length, you can also specify initial values for selected
+elements.
+If you specify an index, in the form of a literal integer-valued keyword,
+then following elements are placed starting at that position.
address@hidden
+(int[] length: 100 10 12 80: 15 16 50: 13 14)
address@hidden example
+This creates an array with 100 elements. Most of them are initialized
+to the default value of zero,
+but elements with indexes 0, 1, 50, 51, 80, 81 are initialized
+to the values 10, 12, 13, 14, 15, 16, respectively.
+
address@hidden Accessing Java array elements
+
+You can access the elements of a Java array by treating it as
+a one-argument function, where the argument is the index:
address@hidden
+(define primes (integer[] 2 3 5 7 11 13))
+(primes 0) @result{} 2
+(primes 5) @result{} 13
address@hidden example
+
+You can set an element by treating the array as a function
+with a @code{setter}:
address@hidden
+(set! (primes 0) -2)
+(set! (primes 3) -7)
+primes @result{} [-2 3 5 -7 11 13]
address@hidden example
+
+To get the number of elements of an array, you can treat
+it as having a @code{length} field:
address@hidden
+primes:length @result{} 6
address@hidden example
+
+Here is a longer example. This is the actual definition of the
+standard @code{gcd} function. Note the @code{args} variable
+receives all the arguments on the form of an @code{integer} array.
+(This uses the Java5 varargs feature.)
address@hidden
+(define (gcd #!rest (args ::integer[])) ::integer
+ (let ((n ::int args:length))
+ (if (= n 0)
+ 0
+ (let ((result ::integer (args 0)))
+ (do ((i ::int 1 (+ i 1)))
+ ((>= i n) result)
+ (set! result (gnu.math.IntNum:gcd result (args i))))))))
address@hidden example
+
+The above example generates good code,
+thanks to judicious use of casts and type specifications.
+In general, if Kawa knows that
+a ``function'' is an array then it will generate efficient
+bytecode instructions for array operations.
+
address@hidden Old low-level array macros
+
+The deprecated @ref{Low-level array macros} are also supported.
+
address@hidden Loading Java functions into Scheme, Evaluating Scheme
expressions from Java, Array operations, Objects Classes and Modules
address@hidden Loading Java functions into Scheme
+
+When @code{kawa -C} compiles (@pxref{Files compilation}) a Scheme module
+it creates a class that implements the @code{java.lang.Runnable} interface.
+(Usually it is a class that extends the @code{gnu.expr.ModuleBody}.)
+It is actually fairly easy to write similar "modules" by hand in Java,
+which is useful when you want to extend Kawa with new "primitive functions"
+written in Java. For each function you need to create an object that
+extends @code{gnu.mapping.Procedure}, and then bind it in the global
+environment. We will look at these two operations.
+
+There are multiple ways you can create a @code{Procedure} object. Below
+is a simple example, using the @code{Procedure1} class, which is class
+extending @code{Procedure} that can be useful for one-argument
+procedure. You can use other classes to write procedures. For example
+a @code{ProcedureN} takes a variable number of arguments, and you must
+define @code{applyN(Object[] args)} method instead of @code{apply1}.
+(You may notice that some builtin classes extend @code{CpsProcedure}.
+Doing so allows has certain advantages, including support for
+full tail-recursion, but it has some costs, and is a bit trickier.)
+
address@hidden
+import gnu.mapping.*;
+import gnu.math.*;
+public class MyFunc extends Procedure1
address@hidden
+ // An "argument" that is part of each procedure instance.
+ private Object arg0;
+
+ public MyFunc(String name, Object arg0)
+ @{
+ super(name);
+ this.arg0 = arg0;
+ @}
+
+ public Object apply1 (Object arg1)
+ @{
+ // Here you can so whatever you want. In this example,
+ // we return a pair of the argument and arg0.
+ return gnu.lists.Pair.make(arg0, arg1);
+ @}
address@hidden
address@hidden example
+
+You can create a @code{MyFunc} instance and call it from Java:
address@hidden
+ Procedure myfunc1 = new MyFunc("my-func-1", Boolean.FALSE);
+ Object aresult = myfunc1.apply1(some_object);
address@hidden example
+The name @code{my-func-1} is used when @code{myfunc1} is printed
+or when @code{myfunc1.toString()} is called. However,
+the Scheme variable @code{my-func-1} is still not bound.
+To define the function to Scheme, we can create
+a "module", which is a class intended to be loaded
+into the top-level environment. The provides the definitions to be
+loaded, as well as any actions to be performed on loading
+
address@hidden
+public class MyModule
address@hidden
+ // Define a function instance.
+ public static final MyFunc myfunc1
+ = new MyFunc("my-func-1", IntNum.make(1));
address@hidden
address@hidden example
+
+If you use Scheme you can use @code{require}:
address@hidden
+#|kawa:1|# (require <MyModule>)
+#|kawa:2|# (my-func-1 0)
+(1 0)
address@hidden example
+
+Note that @code{require} magically defines @code{my-func-1} without
+you telling it to. For each public final
+field, the name and value of the field are entered in the
+top-level environment when the class is loaded. (If there are
+non-static fields, or the class implements @code{Runnable}, then
+an instance of the object is created, if one isn't available.)
+If the field value is a @code{Procedure} (or implements @code{Named}),
+then the name bound to the procedure is used instead of the field name.
+That is why the variable that gets bound in the Scheme environment is
address@hidden, not @code{myfunc1}.
+
+Instead of @code{(require <MyModule>)}, you can do @code{(load "MyModule")}
+or @code{(load "MyModule.class")}.
+If you're not using Scheme, you can use Kawa's @code{-f} option:
address@hidden
+$ kawa -f MyModule --xquery --
+#|kawa:1|# my-func-1(3+4)
+<list>1 7</list>
address@hidden example
+
+If you need to do some more complex calculations when a module is loaded,
+you can put them in a @code{run} method, and have the module
+implement @code{Runnable}:
+
address@hidden
+public class MyModule implements Runnable
address@hidden
+ public void run ()
+ @{
+ Interpreter interp = Interpreter.getInterpreter();
+ Object arg = Boolean.TRUE;
+ interp.defineFunction (new MyFunc ("my-func-t", arg));
+ System.err.println("MyModule loaded");
+ @}
address@hidden
address@hidden example
+
+Loading @code{MyModule} causes @code{"MyModule loaded"} to be printed,
+and @code{my-func-t} to be defined. Using @code{Interpreter}'s
address@hidden method is recommended because it does the righ
+things even for languages like Common Lisp that use separate
+"namespaces" for variables and functions.
+
+A final trick is that you can have a @code{Procedure} be its own module:
+
address@hidden
+import gnu.mapping.*;
+import gnu.math.*;
+public class MyFunc2 extends Procedure2
address@hidden
+ public MyFunc(String name)
+ @{
+ super(name);
+ @}
+
+ public Object apply2 (Object arg1, arg2)
+ @{
+ return gnu.lists.Pair.make(arg1, arg2);
+ @}
+
+ public static final MyFunc myfunc1 = new MyFunc("my-func-2);
address@hidden
address@hidden example
+
address@hidden Evaluating Scheme expressions from Java, , Loading Java
functions into Scheme, Objects Classes and Modules
address@hidden Evaluating Scheme expressions from Java
+
+The following methods are recommended if you need to evaluate a
+Scheme expression from a Java method.
+(Some details (such as the @samp{throws} lists) may change.)
+
address@hidden {Static method} void Scheme.registerEnvironment ()
+Initializes the Scheme environment. Maybe needed if you
+try to load a module compiled from a Scheme source file.
address@hidden deftypefn
+
address@hidden {Static method} Object Scheme.eval (InPort @var{port},
Environment @var{env})
+Read expressions from @var{port}, and evaluate them in the
address@hidden environment, until end-of-file is reached.
+Return the value of the last expression,
+or @code{Interpreter.voidObject} if there is no expression.
address@hidden deftypefn
+
address@hidden {Static method} Object Scheme.eval (String @var{string},
Environment @var{env})
+Read expressions from @var{string}, and evaluate them in the
address@hidden environment, until the end of the string is reached.
+Return the value of the last expression,
+or @code{Interpreter.voidObject} if there is no expression.
address@hidden deftypefn
+
address@hidden {Static method} Object Scheme.eval (Object @var{sexpr},
Environment @var{env})
+The @var{sexpr} is an S-expression (as may be returned by @code{read}).
+Evaluate it in the @var{env} environment, and return the result.
address@hidden deftypefn
+
+For the @code{Environment} in most cases you could use
address@hidden()}. Before you start, you
+need to initialize the global environment,
+which you can do with
address@hidden
+Environment.setCurrent(new Scheme().getEnvironment());
address@hidden example
+
+Alternatively, rather than setting the global environment,
+you can use this style:
address@hidden
+Scheme scm = new Scheme();
+Object x = scm.eval("(+ 3 2)");
+System.out.println(x);
address@hidden example
+
address@hidden Using @code{javax.script} portable Java scripting
+
+Kawa also supports the standard
address@hidden://docs.oracle.com/javase/8/docs/api/javax/script/package-summary.html,@code{javax.script}}
API.
+The main advantage of this API is if you want your users to be able to choose
+between multiple scripting languages. That way you can support Kawa
+without Kawa-specific programming.
+
+For example the standard JDK tool
@uref{http://docs.oracle.com/javase/8/docs/technotes/tools/unix/jrunscript.html,jrunscript}
provides a
+read-eval-print-loop for any language that implements the @code{javax.script}
+API. It knows nothing about Kawa but can still use it:
address@hidden
+$ jrunscript -cp kawa.jar -l scheme
+scheme> (cadr '(3 4 5))
+4
address@hidden example
+
+(Of course the @code{jrunscript} REPL isn't as nice as the one that
+Kawa provides. For example the latter can handle multi-line inputs.)
+
address@hidden XML tools
address@hidden Working with XML and HTML
+
+Kawa has a number of features for working with XML, HTML,
+and generated web pages.
+
+In Kawa you don't write XML or HTML directly.
+Instead you write expressions that evaluate to ``node objects''
+corresponding to elements, attributes, and text.
+You then write these node objects using either an XML or HTML format.
+
+Many web-page-generating tools require you to work directly
+with raw HTML, as for example:
address@hidden
+(display "<p>Don't use the <code><blink></code> tag.</p>")
address@hidden example
+
+In Kawa you would instead do:
address@hidden
+(display (html:p "Don't use the " (html:code "<blink>") " tag."))
address@hidden example
+
+The conversion from node objects to XML or HTML is handled by
+the formatter (or serializer).
+Some advantages of doing it this way are:
address@hidden
address@hidden
+You don't have to worry about quoting special characters.
+Missing or incorrect quoting is a common source of bugs
+and security problems on systems that work directly with text, such as PHP.
address@hidden
+Some errors, such as mismatched element tags, are automatically avoided.
address@hidden
+The generated XML can be validated as it is generated,
+or even using compile-time type-checking. (Kawa doesn't yet do either.)
address@hidden
+In an application that also reads XML,
+you can treat XML that is read in and XML that is generated using
+the same functions.
address@hidden itemize
+
address@hidden
+* Formatting XML::
+* Creating HTML nodes::
+* Creating XML nodes::
+* XML literals::
+* Server-side scripts:: Writing web-server-side Kawa scripts
+* Self-configuring page scripts::
+* Servlets:: Installing Kawa programs as Servlets
+* CGI scripts:: Installing Kawa programs as CGI scripts
+* HTTP requests:: Functions for accessing HTTP requests
+* HTTP response:: Functions for generating HTTP response
+* XML beyond Scheme:: Using non-Scheme languages for XML/HTML
address@hidden menu
+
address@hidden Formatting XML, Creating HTML nodes, , XML tools
address@hidden Formatting XML
+
+The easiest way to generate HTML or XML output is to run Kawa
+with the appropriate @ref{Named output formats, , @code{--output-format}
option}.
+
+The intentation is that these output modes should be compatible with
address@hidden://www.w3.org/TR/2006/PR-xslt-xquery-serialization-20061121/,
+XSLT 2.0 and XQuery 1.0 Serialization}.
+(However, that specifies many options, most
+of which have not yet been implemented.
+
address@hidden @code
address@hidden xml
+Values are printed in XML format.
+"Groups" or "elements" are written as using xml element syntax.
+Plain characters (such as @samp{<}) are escaped (such as @samp{<}).
address@hidden xhtml
+Same as @code{xml}, but follows the xhtml compatibility guidelines.
address@hidden html
+Values are printed in HTML format.
+Mostly same as @code{xml} format, but certain elements without body,
+are written without a closing tag. For example @code{<img>} is written
+without @code{</img>}, which would be illegal for html, but required for xml.
+Plain characters (such as @samp{<}) are not escaped inside @code{<script>}
+or @code{<style>} elements.
address@hidden table
+
+To illustrate:
address@hidden
+$ kawa --output-format html
+#|kawa:1|# (html:img src:"img.jpg")
+<img src="img.jpg">
address@hidden example
address@hidden
+$ kawa --output-format xhtml
+#|kawa:1|# (html:img src:"img.jpg")
+<img xmlns="http://www.w3.org/1999/xhtml"; src="img.jpg" />
address@hidden example
address@hidden
+$ kawa --output-format xml
+#|kawa:1|# (html:img src:"img.jpg")
+<img xmlns="http://www.w3.org/1999/xhtml"; src="img.jpg"></img>
address@hidden example
+And here is the default @code{scheme} formatting:
address@hidden
+$ kawa
+#|kawa:1|# (html:img src:"img.jpg")
+(@{http://www.w3.org/1999/address@hidden src: img.jpg )
address@hidden example
+
address@hidden Procedure as-xml value
+Return a value (or multiple values) that when printed will
+print @var{value} in XML syntax.
address@hidden
+(require 'xml)
+(as-xml (make-element 'p "Some " (make-element 'em "text") "."))
address@hidden example
+prints @code{<p>Some <em>text</em>.</p>}.
address@hidden deffn
+
address@hidden Procedure unescaped-data data
+Creates a special value which causes @code{data} to be printed,
+as is, without normal escaping. For example, when the output format
+is XML, then printing @code{"<?xml?>"} prints as @samp{<?xml?>},
+but @code{(unescaped-data "<?xml?>")} prints as @samp{<?xml?>}.
address@hidden deffn
+
address@hidden Creating HTML nodes, Creating XML nodes, Formatting XML, XML
tools
address@hidden Creating HTML nodes
+
+The @code{html} prefix names a special namespace
+(@pxref{Namespaces}) of functions to create HTML element nodes.
+For example, @code{html:em} is a constructor that
+when called creates a element node whose tag is @code{em}.
+If this element node is formatted as HTML, the
+result has an @code{<em>} tag.
+
address@hidden Syntax html:@var{tag} attributes ... content ...
+Creates an element node whose tag is @var{tag}.
+The parameters are first zero or more attributes, followed
+by zero of more child values.
+An attribute is either an attribute value (possibly
+created using @code{make-attribute}), or a pair of arguments:
+A keyword followed by the attribute value.
+Child values are usually either strings (text content),
+or nested element nodes, but can also be comment or processing-instruction
+nodes.
address@hidden
+(html:a href: "http://gnu.org/"; "the "(html:i "GNU")" homepage")
address@hidden example
address@hidden deffn
+
+The compound identifier @code{html:@var{tag}} is actually
+a type: When you call it as a function you're using Kawa's
+standard coercion of a type to its constructor function.
+This means you can do type tests:
address@hidden
+(define some-node ...)
+(if (instance? some-node html:blink)
+ (error "blinking not allowed!"))
address@hidden example
+
+Object identity is currently not fully specified. Specifically,
+it is undefined if a nested (child) element node is copied
+``by value'' or ``by reference''. This is related to whether
+nodes have a parent reference. In the XPath/XQuery data model
+nodes do have a parent reference, and child nodes are conceptually
+copied. (In the actual implemention copying is commonly avoided.)
+Kawa/Scheme currently followed the XQuery copying semantics,
+which may not be the most appropriate for Scheme.
+
address@hidden Creating XML nodes, XML literals, Creating HTML nodes, XML tools
address@hidden Creating XML nodes
+
+The XML data model is similar to HTML, with one important addition:
+XML tags may be @dfn{qualified names}, which are similar
+to @ref{Namespaces, , compound symbols}.
+
+You must do this to use the following types and functions:
address@hidden
+(require 'xml)
address@hidden example
+
+The following types and functions assume:
address@hidden
+(require 'xml)
address@hidden example
+
address@hidden Procedure make-element tag [attribute ...] child ...
+Create a representation of a XML element, corresponding to
address@hidden
+<@var{tag} @var{attribute}...>@var{child}...</@var{tag}>
address@hidden example
+The result is a @code{TreeList}, though if the result context is a consumer
+the result is instead "written" to the consumer.
+Thus nested calls to @code{make-element} only result in a
+single @code{TreeList}.
+More generally, whether an @var{attribute} or @var{child} is includded
+by copying or by reference is (for now) undefined.
+The @var{tag} should currently be a symbol, though in the future it should
+be a qualified name.
+An @var{attribute} is typically a call to @code{make-attribute},
+but it can be any attribute-valued expression.
address@hidden
+(make-element 'p
+ "The time is now: "
+ (make-element 'code (make <java.util.Date>)))
address@hidden example
address@hidden deffn
+
address@hidden Procedure element-name element
+Returns the name (tag) of the element node, as a symbol (QName).
address@hidden deffn
+
address@hidden Procedure make-attribute name value...
+Create an "attribute", which is a name-value pair.
+For now, @var{name} should be a symbol.
address@hidden deffn
+
address@hidden Procedure attribute-name element
+Returns the name of the attribute node, as a symbol (QName).
address@hidden deffn
+
address@hidden Type comment
+Instances of this type represent comment values,
+specifically including comments in XML files.
+Comment nodes are currently ignored when printing using Scheme formatting,
+though that may change.
address@hidden deffn
address@hidden Constructor comment comment-text
+Create a comment object with the specified @var{comment-text}.
address@hidden deffn
+
address@hidden Type processing-instruction
+Instances of this type represent ``processing instructions'',
+such as may appear in XML files.
+Processing-instruction nodes are currently ignored when printing using
+Scheme formatting, though that may change.
address@hidden deffn
address@hidden Constructor processing-instruction target contents
+Crreate a processing-instruction object with the specified @var{target}
+(a simple symbol) and @var{contents} (a string).
address@hidden deffn
+
address@hidden XML literals, Server-side scripts, Creating XML nodes, XML tools
address@hidden XML literals
+
+You can write XML literals directly in Scheme code,
+following a @code{#}.
+Notice that the outermost element needs to be prefixed
+by @code{#}, but nested elements do not (and must not).
address@hidden
+#<p>The result is <b>final</b>!</p>
address@hidden example
+
+Actually, these are not really literals since they can contain
+enclosed expressions:
address@hidden
+#<em>The result is &@address@hidden</em>
address@hidden example
+The value of @var{result} is substituted into the output,
+in a similar way to quasi-quotation.
+(If you try to quote one of these ``XML literals'',
+what you get is unspecified and is subject to change.)
+
+An @var{xml-literal} is usually an element constructor,
+but there some rarely used forms (processing-instructions,
+comments, and CDATA section) we'll cover later.
+
address@hidden
address@hidden @address@hidden
address@hidden @stxref{xml-element-constructor}
+ | @stxref{xml-PI-constructor}
+ | @stxref{xml-comment-constructor}
+ | @stxref{xml-CDATA-constructor}
address@hidden display
+
address@hidden Element constructors
+
address@hidden
address@hidden
+ @stxlit{<address@hidden
@address@hidden>address@hidden@stxlit{</address@hidden @stxlit{>}
+ | @stxlit{<address@hidden @address@hidden>address@hidden@stxlit{</>}
+ | @stxlit{<address@hidden @address@hidden/>}
address@hidden @stxref{QName}
+ | @stxref{xml-enclosed-expression}
address@hidden
+ @address@hidden@address@hidden@rbracechar{}}
+ | @stxlit{(address@hidden@stxlit{)}
address@hidden display
+
+The first @var{xml-element-constructor} variant uses a literal @var{QName},
+and looks like standard non-empty XML element, where the starting @var{QName}
+and the ending @var{QName} must match exactly:
+
address@hidden
+#<a href="next.html">Next</a>
address@hidden example
+
+As a convenience, you can leave out the ending tag(s):
address@hidden
+This is a paragraph in <emphasis>DocBook</> syntax.</>
address@hidden example
+
+You can use an expression to compute the element tag at runtime -
+in that case you @emph{must} leave out the ending tag:
address@hidden
+#<p>This is <(if be-bold 'strong 'em)>important</>!</p>
address@hidden example
+
+You can use arbitrary @var{expression} inside curly braces,
+as long as it evaluates to a symbol.
+You can leave out the curly braces
+if the @var{expression} is a simple parenthesised compound expression.
+The previous example is equivalent to:
address@hidden
+#<p>This is <@{(if be-bold 'strong 'em)@}>important</>!</p>
address@hidden example
+
+The third @var{xml-element-constructor} variant above is an XML
+``empty element''; it is equivalent to the second variant
+when there are no @var{xml-element-datum} items.
+
+(Note that every well-formed XML element, as defined in the XML specifications,
+is a valid @var{xml-element-constructor}, but not vice versa.)
+
address@hidden Elements contents (children)
+
+The ``contents'' (children) of an element
+are a sequence of character (text) data, and nested nodes.
+The characters @code{&}, @code{<}, and @code{>} are special,
+and need to be escaped.
+
address@hidden
address@hidden
+ any character except @code{&}, or @code{<}.
+ | @stxref{xml-constructor}
+ | @stxref{xml-escaped}
address@hidden
+ @stxlit{&address@hidden
+ | @stxlit{&address@hidden@stxlit{;}
+ | @stxref{xml-character-reference}
address@hidden
+ @stxlit{&address@hidden@stxlit{;}
+ | @stxlit{&address@hidden@stxlit{;}
address@hidden display
+
+Here is an example shows both hex and decimal character references:
address@hidden
+#<p>ABCDE</p> @result{} <p>ABCDE</p>
address@hidden example
+
address@hidden
address@hidden @stxref{identifier}
address@hidden display
+Currently, the only supported values for @var{xml-entity-name}
+are the builtin XML names @code{lt}, @code{gt}, @code{amp},
address@hidden, and @code{apos}, which stand for the characters
address@hidden<}, @code{>}, @code{&}, @code{"}, and @code{'}, respectively.
+The following two expressions are equivalent:
address@hidden
+#<p>< > & " '</p>
+#<p>&@{"< > & \" '"@}</p>
address@hidden example
+
address@hidden Attributes
+
address@hidden
address@hidden
+ @address@hidden@stxref{xml-attribute-value}
address@hidden
+ @stxlit{"address@hidden@stxlit{"}
+ | @stxlit{'address@hidden@stxlit{'}
address@hidden
+ any character except @code{"}, @code{&}, or @code{<}.
+ | @stxref{xml-escaped}
address@hidden
+ any character except @code{'}, @code{&}, or @code{<}.
+ | @stxref{xml-escaped}
address@hidden display
+
+If the @var{xml-name-form} is either @code{xmlns} or
+a compound named with the prefix @code{xmlns}, then
+technically we have a namespace declaration, rather than
+an attribute.
+
address@hidden QNames and namespaces
+
+The names of elements and attributes are @dfn{qualified names}
+(QNames), which are represented using compound symbols (@pxref{Namespaces}).
+The lexical syntax for a QName is either a simple identifier,
+or a (prefix,local-name) pair:
+
address@hidden
address@hidden @stxref{xml-local-part}
+ | @address@hidden:address@hidden
address@hidden @stxref{identifier}
address@hidden @stxref{identifier}
address@hidden display
+
+An @var{xml-prefix} is an alias for a namespace-uri,
+and the mapping between them is defined by a namespace-declaration.
+You can either use a @code{define-namespace} form, or you
+can use a @dfn{namespace declaration attribute}:
+
address@hidden
address@hidden
+ @stxlit{xmlns:address@hidden@address@hidden
+ | @address@hidden
address@hidden display
+
+The former declares @var{xml-prefix} as a namespace alias for
+the namespace-uri specified by @var{xml-attribute-value}
+(which must be a compile-time constant).
+The second declares that @var{xml-attribute-value} is the default
+namespace for simple (unprefixed) element tags.
+(A default namespace declaration is ignored for attribute names.)
+
address@hidden
+(let ((qn (element-name #<gnu:b xmlns:gnu="http://gnu.org/"/>)))
+ (list (symbol-local-name qn)
+ (symbol-prefix qn)
+ (symbol-namespace-uri qn)))
address@hidden ("b" "gnu" "http://gnu.org/";)
+
address@hidden example
+
address@hidden Other XML types
+
address@hidden Processing instructions
+
+An @var{xml-PI-constructor} can be used to create an XML
address@hidden instruction}, which can be used to pass
+instructions or annotations to an XML processor (or tool).
+(Alternatively, you can use the @code{processing-instruction}
+type constructor.)
+
address@hidden
address@hidden @stxlit{<address@hidden @address@hidden>}
address@hidden @var{NCname} (i.e. a simple (non-compound) identifier)
address@hidden any characters, not containing @code{?>}.
address@hidden display
+
+For example, the DocBook XSLT stylesheets can use the @code{dbhtml}
+instructions to specify that a specific chapter should be
+written to a named HTML file:
address@hidden
+#<chapter><?dbhtml filename="intro.html" ?>
+<title>Introduction</title>
+...
+</chapter>
address@hidden example
+
address@hidden XML comments
+
+You can cause XML comments to be emitted in the XML output document.
+Such comments can be useful for humans reading the XML document,
+but are usually ignored by programs.
+(Alternatively, you can use the @code{comment} type constructor.)
+
address@hidden
address@hidden @stxlit{<address@hidden@stxlit{-->}
address@hidden any characters, not containing @code{--}.
address@hidden display
+
address@hidden CDATA sections
+
+A @code{CDATA} section can be used to avoid excessive use of
address@hidden such as @code{&} in element content.
+
address@hidden
address@hidden @stxlit{<address@hidden@stxlit{]]>}
address@hidden any characters, not containing @code{]]>}.
address@hidden display
+
+The following are equivalent:
address@hidden
+#<p>Specal characters <![CDATA[< > & ' "]]> here.</p>
+#<p>Specal characters < > & " ' here.</p>
address@hidden example
+
+Kawa remembers that you used a @code{CDATA} section in
+the @var{xml-element-constructor} and will write it out
+using a @code{CDATA} constructor.
+
address@hidden Server-side scripts, Self-configuring page scripts, XML
literals, XML tools
address@hidden Web page scripts
+
+A Kawa @dfn{web page script} is a Kawa program that is invoked
+by a web server because the server received an HTTP request.
+The result of evaluating the top-level expressions becomes
+the HTTP response that the servlet sends back to the client, usually a browser.
+
+A web page script may be as simple as:
address@hidden
+(format "The time is <~s>." (java.util.Date))
address@hidden example
+This returns a response of consisting of a formatted string
+giving the current time.
+The string would interpreted as @code{text/plain} content:
+The angle brackets are regular characters, and not
+HTML tag markers.
+
+The script can alternatively evaluate to XML/HTML node
+values, for example those created by @ref{XML literals}:
address@hidden
+#<p>Hello, <b>&(request-remote-host)</b>!</p>
address@hidden example
+In this case the response would be @code{text/html} or similar content:
+The angle brackets should be interpreted by the browser as HTML tag markers.
+The function @code{request-remote-host} is available (automatically)
+to web page scripts; it returns the host that made the HTTP request,
+which is then interpolated into the response.
+
+Following sections will go into more details about how
+to write web page scripts. You can do so in any supported
+Kawa language, including Scheme, BRL, KRL, or XQuery.
+
+A web server will use a URL mapping to map a request URL
+to a specific web page script. This can be done in a
+number of different ways:
address@hidden
address@hidden
+The easiest to manage is to use Kawa's mechanism for
address@hidden page scripts}. Ths is especially
+easy if you the web server built in to JDK 6, since no
+configuration files are needed.
+You can also use a ``servlet engine'' like Tomcat or Glassfish.
+
address@hidden
+You can explicitly compile the web page script to a servlet,
+in the same way Java servlets are compiled.
+This can then be installed ("deployed") in a servlet-supporting
+web server, such a Tomcat or Glassfish. @xref{Servlets}.
address@hidden
+You can run the servlet as a @ref{CGI scripts,CGI script}.
address@hidden itemize
+
+For details on how to extract information from the request
+see @ref{HTTP requests}.
+For details on how the response is created see @ref{HTTP response,Generating
HTTP responses}.
+If the response is HTML or XML, you may want to
+read @ref{Creating HTML nodes}, or @ref{Creating XML nodes},
+or @ref{XML literals}.
+
+Here are some examples, starting with a simple @code{hello.scm}:
address@hidden
+(response-content-type 'text/html) ; Optional
+(html:p
+ "The request URL was: " (request-url))
+(make-element 'p
+ (let ((query (request-query-string)))
+ (if query
+ (values-append "The query string was: " query)
+ "There was no query string.")))
address@hidden example
+This returns two @code{<p>} (paragraph) elements: One using
address@hidden and one using the @code{html:p} constructor.
+Or you may prefer to use @ref{XML literals}.
+
+The same program using KRL:
address@hidden
+<p>The request URL was: [(request-url)]</p>,
+<p>[(let ((query (request-query-string)))
+ (if query
+ (begin ]The query string was: [query)
+
+ ]There was no query string.[))]</p>
address@hidden example
+
+You can also use XQuery:
address@hidden
+<p>The request URL was: @{request-url()@}</p>
+<p>@{let $query := request-query-string() return
+ if ($query)
+ then ("The query string was: ",$query)
+ else "There was no query string."@}</p>
address@hidden example
+
+The @code{+default+} script in the @code{doc} directory is
+useful for reading the Kawa documentation using a browser.
+The script uses the @code{jar:} URL scheme to automatically extract
+and uncompress the pages from @code{doc/kawa-manual.epub},
+which is in EPUB3 format. Read the script for usage instructions.
+
address@hidden Self-configuring page scripts, Servlets, Server-side scripts,
XML tools
address@hidden Self-configuring web page scripts
+
+Kawa makes it easy to set up a web site without configuration
+files. Instead, the mapping from request URL to web page script
+matches the layout of files in the application directory.
+
+Many web servers make it easy to execute a script using a script
+processor which is selected depending on the extension of the
+requested URL. That is why you see lots of URLs that end in
address@hidden, @code{.php}, or @code{.jsp}. This is bad, because it
+exposes the server-side implementation to the user: Not only are such
+URLs ugly, but they make it difficult to change the server without
+breaking people's bookmarks and search engines. A server will usually
+provide a mechanism to use prettier URLs, but doing so requires extra
+effort, so many web-masters don't.
+
+If you want a script to be executed in response to a URL
address@hidden://host/app/foo/bar} you give the script the name
address@hidden/foo/bar}, in the appropriate server ``application''
+directory (as explained below). You get to pick the name @code{bar}.
+Or you can use the name @code{bar.html}, even though the file named
address@hidden isn't actually
+an html file - rather it produces html when evaluated. Or better: just use
+a name without an extension at all.
+Kawa figures
+out what kind of script it is based on the content of the file,
+rather than the file name. Once Kawa has
+found a script, it looks at the first line to see if it can recognize
+the kind (language) of the script. Normally this would be a comment
+that contains the name of a programming language that Kawa
+knows about. For example:
address@hidden
+;; Hello world page script written in -*- scheme -*-
+#<p>Hello, <b>&(request-remote-host)</b>!</p>
address@hidden example
+(Using the funny-looking string @code{-*- scheme -*-} has the
+bonus is that it recognized by the Emacs text editor.)
+
+A script named @code{+default+} is run if there isn't a matching script.
+For example assume the following is a file named @code{+default}.
address@hidden
+;; This is -*- scheme -*-
+(make-element 'p "servlet-path: " (request-servlet-path))
address@hidden example
+This becomes the default script for HTTP requests that aren't handled
+by a more specific script.
+The @code{request-servlet-path} function
+returns the "servlet path", which is the part of the requested URL
+that is relative to the current web application. Thus a request for
address@hidden://host:port/app/this/is/a/test} will return:
address@hidden
+servlet-path: /this/is/a/test
address@hidden example
+
address@hidden Using the OpenJDK built-in web server
+
+The easiest way to run a Kawa web server is to
+use the web server built in to JDK 6 or later.
+
address@hidden
+kawa --http-auto-handler @var{context-path} @var{appdir} --http-start
@var{port}
address@hidden example
+
+This starts a web server that listens on the given @var{port},
+using the files in directory @var{appdir} to handle
+requests that start with the given @var{context-path}.
+The @var{context-path} must start with a @code{"/"} (one is added if
+needed), and it is recommended that it also end with a @code{"/"}
+(otherwise you might get some surprising behavior).
+
+You can specify multiple @code{--http-auto-handler} options.
+
+For example use the files in the current directory to handle
+all requests on the standard port 80 do:
address@hidden
+kawa --http-auto-handler / . --http-start 80
address@hidden example
+
+There are some examples in the @code{testsuite/webtest} directory
+the Kawa source distribution. You can start the server thus:
address@hidden
+bin/kawa --http-auto-handler / testsuite/webtest/ --http-start 8888
address@hidden example
+and then for example browse to @code{http://localhost:8888/adder.scm}.
+
+For lots of information about the HTTP request, browse to
address@hidden://localhost:8888/info/@var{anything}}.
+
address@hidden Using a servlet container
+
+You can also can use a ``servlet container''
+such as Tomcat or Glassfish with self-configuring script.
+See @ref{Servlets} for information on how to install
+these servers, and the concept of web applications.
+Once you have these server installed, you create a
+web application with the following in the
address@hidden@var{appdir}/WEB-INF/web.xml} configuration file:
address@hidden
+<web-app>
+ <display-name>Kawa auto-servlet</display-name>
+ <servlet>
+ <servlet-name>KawaPageServlet</servlet-name>
+ <servlet-class>gnu.kawa.servlet.KawaPageServlet</servlet-class>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>KawaPageServlet</servlet-name>
+ <url-pattern>/*</url-pattern>
+ </servlet-mapping>
+</web-app>
address@hidden example
+This creates a web application where all URLs
+are handled by the @code{gnu.kawa.servlet.KawaPageServlet} servlet class,
+which is included in the Kawa jar file.
+The @code{KawaPageServlet} class handles the searching
+and compiling described in this page.
+
address@hidden Finding a matching script
+
+When Kawa receives a request for:
address@hidden
+http://host:port/appname/a/b/anything
address@hidden example
+it will look for a file:
address@hidden
address@hidden/a/b/anything
address@hidden example
+
+If such a file exists, the script will be executed, as described
+below. If not, it will look for a file name @code{+default+} in the same
+directory. If that desn't exist either, it will look for @code{+default+}
+in the parent
+directory, then the grand-parent directory, and so on until it gets to
+the appname web application root directory. So the default script is
+this: @address@hidden/+default}.
+
+If that doesn't exist then Kawa returns a 404 "page not found" error.
+
address@hidden Determining script language
+
+Once Kawa has found a script file corresponding to a request URL,
+it needs to determine if this is a data file or a web page script,
+and in the latter case, what language it is written in.
+
+Kawa recognizes the following "magic strings" in the first line of a script:
+
address@hidden @code
address@hidden kawa:scheme
+The Scheme language.
+
address@hidden kawa:xquery
+The XQuery language.
+
address@hidden kawa:@var{language}
+Some other language known to Kawa.
address@hidden table
+
+Kawa also recognizes Emacs-style "mode specifiers":
+
address@hidden @code
address@hidden -*- scheme -*-
+The Scheme language.
address@hidden -*- xquery -*-
+The XQuery language (though Emacs doesn't know about XQuery).
address@hidden -*- emacs-lisp -*-
address@hidden -*- elisp -*-
+The Emacs Lisp extension language.
address@hidden -*- common-lisp -*-
address@hidden -*- lisp -*-
+ The Common Lisp language.
address@hidden table
+
+Also, it also recognizes comments in the first two columns of the line:
address@hidden @code
address@hidden ;;
+A Scheme or Lisp comment - assumed to be in the Scheme language.
address@hidden (:
+Start of an XQuery comment, so assumed to be in the XQuery language.
address@hidden table
+
+If Kawa doesn't recognize the language of a script (and it
+isn't named +default+) then it assumes the file is a data file. It
+asks the servlet engine to figure out the content type (using the
+getMimeType method of ServletContext), and just copies the file into
+the response.
+
address@hidden Compilation and caching
+
+Kawa automatically compiles a script into a class. The
+class is internal to the server, and is not written out to
+disk. (There is an unsupported option to write the compiled file to a
+class file, but there is no support to use previously-compiled
+classes.) The server then creates a module instance to handle the
+actual request, and runs the body (the @code{run} method)
+of the script class. On subsequence
+requests for the same script, the same class and instance are reused;
+only the @code{run} is re-executed.
+
+If the script is changed, then it is re-compiled and a new module
+instance created. This makes it very easy to develop and modify a
+script. (Kawa for performance reasons doesn't check more
+than once a second whether a script has been modified.)
+
address@hidden Servlets, CGI scripts, Self-configuring page scripts, XML tools
address@hidden Installing web page scripts as Servlets
+
+You can compile a Kawa program to a
@uref{http://en.wikipedia.org/wiki/Java_Servlet,Servlet}, and run it
+in a servlet engine (a Servlet-aware web server).
+One or more servlets are installed together as a web application.
+This section includes specific information for
+the Tomcat and Glassfish web servers.
+
address@hidden Creating a web application
+
+A @dfn{web application} is a group of data, servlets, and
+configuration files to handle a related set of URLs.
+The @uref{http://jcp.org/aboutJava/communityprocess/final/jsr315/index.html,
+servlet specification}
+specifies the directory structure of a web application.
+
+Assume the web application is called @code{myapp}, and lives in a
+directory with the same name. The application normally handles
+requests for URLs that start with @code{http://example.com/myapp}.
+Most files in the application directory are used to handle
+requests with corresponding URL. For example,
+a file @code{myapp/list/help.html} would be the response
+to the request @code{http://example.com/myapp/list/help.html}.
+
+The directory @code{WEB-INF} is special. It contains configuration
+files, library code, and other server data.
+
+So to create the @code{myapp} application, start with:
address@hidden
+mkdir myapp
+cd myapp
+mkdir WEB-INF WEB-INF/lib WEB-INF/classes
address@hidden example
+
+Copy the Kawa jar from the @code{lib} direcory.
+(You can also use a ``hard'' link, but symbolic links may not
+work, for security systems.)
address@hidden
+cp @var{kawa-home}/address@hidden WEB-INF/lib/kawa.jar
address@hidden example
+
+If you build Kawa from source, you must specify the
address@hidden @ref{configure options,configure option}.
+
+You should also create the file @code{WEB-INF/web.xml}.
+For now, this is is just a place-holder:
address@hidden
+<web-app>
+ <display-name>My Application</display-name>
+</web-app>
address@hidden example
+
address@hidden Compiling a web page script to a servlet
+
+Assume for simplicity that the source files
+are in the @code{WEB-INF/classes} directory, and make that the
+current directory:
address@hidden
+cd .../myapp/WEB-INF/classes
address@hidden example
+
+Depending on the source language, you compile your script
+sing the @code{--servlet} switch:
address@hidden
+kawa --servlet -C hello.scm
address@hidden example
+or:
address@hidden
+kawa --servlet --krl -C hello.krl
address@hidden example
+or:
address@hidden
+kawa --servlet --xquery -C hello.xql
address@hidden example
+
+This lets the web-application find the compiled servlets.
+Finally, you just need to add the new servlet to
+the @code{WEB-INF/web.xml} file:
address@hidden
+<web-app>
+ <display-name>My Application</display-name>
+
+ <servlet>
+ <servlet-name>MyHello</servlet-name>
+ <servlet-class>hello</servlet-class>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>MyHello</servlet-name>
+ <url-pattern>/hello</url-pattern>
+ </servlet-mapping>
+</web-app>
address@hidden example
+
+The @code{<servlet>} clause says that the servlet named
address@hidden is implemented by the Java class @code{hello}.
+The @code{<servlet-mapping>} clause says that a request
+URL @code{/hello} should be handled by the servlet named @code{MyHello}.
+The URL is relative to the application context path,
+so the actual URL would be @code{http://example.com/myapp/hello}.
+
address@hidden Installing a servlet under Tomcat
address@hidden Tomcat
+
+Apache's @uref{http://tomcat.apache.org/,Tomcat} is an open-source
+implementation of the servlet specifications.
+After you @uref{http://tomcat.apache.org/download-60.cgi, download it},
+uncompress it in some convenient location,
+which is commonly referred to as @code{$CATALINA_HOME}.
+
+To install your web application, copy/move its directory
+to be in the @code{$CATALINA_HOME/webapps} directory.
+Thus for the example above you would have
+a @code{$CATALINA_HOME/webapps/myapp} directory.
+
+To start or stop Tomcat use the scripts in @code{$CATALINA_HOME/bin}.
+For example to start Tomcat on a GNU/Linux system run
address@hidden/bin/startup.sh}. This will start a web server
+that listens on the default port of 8080,
+so you can browse the above example at
@code{http://localhost:8080/myapp/hello}.
+
+If you're running Fedora GNU/Linux, you can use the @code{tomcat6} package:
address@hidden
+# yum install tomcat6
+# export CATALINA_HOME=/usr/share/tomcat6
address@hidden example
+You can the manage Tomcat like other system services.
+You can install webapps under @code{$CATALINA_HOME/webapps}.
+
address@hidden Installing a servlet under Glassfish
address@hidden Glassfish
+
address@hidden://glassfish.dev.java.net/,Glassfish} from Oracle/Sun
+is a open-source ``application server'' that implements
+Java EE 6, including the 3.0 servlet specification.
+After you @uref{https://glassfish.dev.java.net/downloads/3.0.1-final.html,
download it}, uncompress it in some convenient location.
+This location is called @var{as-install-parent} in the
address@hidden://docs.sun.com/app/docs/doc/820-7689/aboaa?a=view,Quick Start
Guide}.
+The commands you will use is most in @address@hidden/bin},
+where @var{as-install} is @address@hidden/glassfish}.
+
+To start the server, do:
address@hidden
address@hidden/bin/startserv
address@hidden example
+or under under Windows:
address@hidden
address@hidden
address@hidden example
+The default post to listen to is @code{8080};
+you can the port (and lots of other properties)
+using the adminstration console at port @code{4848}.
+
+A web application does not need to be any particular
+location, instead you just install it with this command:
address@hidden
address@hidden/bin/adadmin deploy @var{appdir}
address@hidden example
+where @var{appdir} is the application directory - @code{myapp} in the example.
+(Use @code{asadmin.bat} under Windows.)
+
address@hidden Servlet-specific script functions
+
+The following functions only work within a servlet container.
+To use these functions, first do:
address@hidden
+(require 'servlets)
address@hidden example
+
+You can conditionalize your code to check at compile-time for servlets,
+like this:
+
address@hidden
+(cond-expand
+ (in-servlet
+ (require 'servlets)
+ (format "[servlet-context: ~s]" (current-servlet-context)))
+ (else
+ "[Not in a servlet]"))
address@hidden example
+
+For a run-time check you can test if @code{(current-servlet)} is
address@hidden
+
address@hidden Procedure current-servlet
+When called from a Kawa servlet handler, returns the
+actual @code{javax.servlet.http.HttpServlet} instance.
+Returns @code{#!null} if the current context is not that of
address@hidden
+(Hence this function also returns @code{#!null} if you compile a servlet
+``by hand'' rather that using the @code{--servet} option.)
address@hidden deffn
+
address@hidden Procedure current-servlet-context
+Returns the context of the currently executing servlet,
+as an instance of @code{javax.servlet.ServletContext}.
address@hidden deffn
+
address@hidden Procedure current-servlet-config
+Returns the @code{ServletConfig} of the currently executing servlet.
address@hidden deffn
+
address@hidden Procedure get-request
+Return the current servlet request, as an instance of
address@hidden
address@hidden deffn
+
address@hidden Procedure get-response
+Return the current servlet response, as an instance of
address@hidden
address@hidden deffn
+
address@hidden Procedure request-servlet-path
+Get the servlet path of the current request.
+Similar to @code{request-script-path}, but not always the same,
+depending on configuration, and does @emph{not} end with a @code{"/"}.
address@hidden deffn
+
address@hidden Procedure request-path-info
+Get the path info of the current request.
+Corresponds to the CGI variable @code{PATH_INFO}.
address@hidden deffn
+
address@hidden Procedure servlet-context-realpath [path]
+Returns the file path of the current servlet's "Web application".
address@hidden deffn
+
address@hidden CGI scripts, HTTP requests, Servlets, XML tools
address@hidden Installing Kawa programs as CGI scripts
+
+The recommended way to have a web-server run a Kawa program
+as a CGI script is to compile the Kawa program to a servlet
+(as explained in @ref{Server-side scripts}, and then use
+Kawa's supplied CGI-to-servlet bridge.
+
+First, compile your program to one or more class files
+as explained in @ref{Server-side scripts}. For example:
address@hidden
+kawa --servlet --xquery -C hello.xql
address@hidden example
+
+Then copy the resulting @code{.class} files to your server's
+CGI directory. On Red Hat GNU/Linux, you can do the following (as root):
address@hidden
+cp hello*.class /var/www/cgi-bin/
address@hidden example
+
+Next find the @code{cgi-servlet} program that Kawa builds and installs.
+If you installed Kawa in the default place, it will be in
address@hidden/usr/local/bin/cgi-servlet}.
+(You'll have this if you installed Kawa from source, but not
+if you're just using Kawa @code{.jar} file.)
+Copy this program into the same CGI directory:
address@hidden
+cp /usr/local/bin/cgi-servlet /var/www/cgi-bin/
address@hidden example
+
+You can link instead of copying:
address@hidden
+ln -s /usr/local/bin/cgi-servlet /var/www/cgi-bin/
address@hidden example
+However, because of security issues this may not work, so it is
+safer to copy the file. However, if you already have a copy
+of @code{cgi-servlet} in the CGI-directory, it is safe to make
+a hard link instead of making an extra copy.
+
+Make sure the files have the correct permissions:
address@hidden
+chmod a+r /var/www/cgi-bin/hello*.class /var/www/cgi-bin/hello
+chmod a+x /var/www/cgi-bin/hello
address@hidden example
+
+Now you should be able to run the Kawa program,
+using the URL @url{http://localhost/cgi-bin/hello}.
+It may take a few seconds to get the reply, mainly because of the
+start-up time of the Java VM. That is why servlets are
+preferred. Using the CGI interface can still be useful
+for testing or when you can't run servlets.
+
address@hidden HTTP requests, HTTP response, CGI scripts, XML tools
address@hidden Functions for accessing HTTP requests
+
+The following functions are useful for accessing
+properties of a HTTP request, in a Kawa program that is
+run either as a servlet or a CGI script. These functions
+can be used from plain Scheme, from KRL (whether
+in BRL-compatible mode or not), and from XQuery.
+
+The examples below assume the request
@code{http://example.com:8080/myapp/foo/bar?val1=xyz&val2=abc}, where
@code{myapp} is the application context.
+We also assume that this is handled by a script @code{foo/+default+}.
+
+The file @code{testsuite/webtest/info/+default+} in the Kawa source
distribution
+calls most of these functions.
+You can try it as described in @ref{Self-configuring page scripts}.
+
address@hidden Request URL components
+
address@hidden Procedure request-URI
+Returns the URI of the request, as a value of type @code{URI}.
+This excludes the server specification,
+but includes the query string.
+(It is the combination of CGI variables @code{SCRIPT_NAME},
address@hidden, and @code{QUERY_STRING}.
+Using servlets terminology, it is the combination of
+Context Path, Servlet Path, PathInfo, and Query String.)
address@hidden
+(request-URI) @result{} "/myapp/foo/bar?val1=xyz&val2=abc"
address@hidden example
address@hidden deffn
+
address@hidden Procedure request-path
+Returns the URI of the request, as a value of type @code{URI}.
+This excludes the server specification and the query string.
+Equivalent to @code{(path-file (request-URI))}.
+(It is the combination of CGI variables @code{SCRIPT_NAME}, and
address@hidden
+Same as the concatenation of @code{(request-context-path)},
address@hidden(request-script-path)}, and @code{(request-local-path)}.
+Using servlets terminology, it is the combination of
+Context Path, Servlet Path, and PathInfo.)
address@hidden
+(request-path) @result{} "/myapp/foo/bar"
address@hidden example
address@hidden deffn
+
address@hidden Procedure request-uri
+This function is deprecated, because of possible confusion
+with @code{request-URI}. Use @code{request-path} instead.
address@hidden deffn
+
address@hidden Procedure request-url
+Returns the complete URL of the request, except the query string.
+The result is a @code{java.lang.StringBuffer}.
address@hidden
+(request-url) @result{} "http://example.com:8080/myapp/foo/bar";
address@hidden example
address@hidden deffn
+
address@hidden Procedure request-context-path
+Returns the context path, relative to the server root.
+This is an initial substring of the @code{(request-path)}.
+Similar to the Context Path of a servlet request,
+except that it ends with a @code{"/"}.
address@hidden
+(request-context-path) @result{} "/myapp/"
address@hidden example
address@hidden deffn
+
address@hidden Procedure request-script-path
+Returns the path of the script, relative to the context.
+This is either an empty string, or a string that ends with @code{"/"},
+but does not start with one. (The reason for this is to produce URIs
+that work better with operations like @code{resolve-uri}.)
+This is conceptually similar to @code{request-servlet-path},
+though not always the same, and the @code{"/"} conventions differ.
address@hidden
+(request-script-path) @result{} "foo/"
address@hidden example
address@hidden deffn
+
address@hidden Procedure request-local-path
+Returns the remainder of the @code{request-path},
+relative to the @code{request-script-path}.
address@hidden
+(request-local-path) @result{} "bar"
address@hidden example
address@hidden deffn
+
address@hidden Procedure request-query-string
+Returns the query string from an HTTP request. The query string is
+the part of the request URL after a question mark.
+Returns false if there was no query string.
+Corresponds to the CGI variable @code{QUERY_STRING}.
address@hidden
+(request-query-string) @result{} "val1=xyz&val2=abc"
address@hidden example
address@hidden deffn
+
address@hidden Request parameters
+
+Request parameters are used for data returned from forms,
+and for other uses.
+They may be encoded in the query string or in the request body.
+
address@hidden Procedure request-parameter name [default]
+If there is a parameter with the given name (a string),
+return the (first) corresponding value, as a string.
+Otherwise, return the @var{default} value,
+or @code{#!null} if there is no @var{default}.
address@hidden
+(request-parameter "val1") @result{} "xyz"
+(request-parameter "val9" "(missing)") @result{} "(missing)"
address@hidden example
address@hidden deffn
+
address@hidden Procedure request-parameters name
+If there is are one or more parameter with the given name (a string),
+return them all (as multiple values).
+Otherwise, return no values (i.e. @code{(values)}).
address@hidden
+(request-parameters "val1") @result{} "xyz"
+(request-parameters "val9") @result{} #!void
address@hidden example
address@hidden deffn
+
address@hidden Procedure request-parameter-map
+Request a map of all the parameters.
+This is a map from strings to a sequence of strings.
+(Specifically, a @code{java.util.Map<String,java.util.List<String>>}.)
address@hidden deffn
+
address@hidden Request headers
+
+The request headers are a set of (keyword, string)-pairs
+transmitted as part of the HTTP request, before the request body.
+
address@hidden Procedure request-header name
+If there is a header with the given @var{name} (a string),
+return the corresponding value string.
+Otherwise, return @code{#!null}.
address@hidden
+(request-header "accept-language") @result{} "en-us,en;q=0.5"
address@hidden example
address@hidden deffn
+
address@hidden Procedure request-header-map
+Request a map of all the headers.
+This is a map from strings to a sequence of strings.
+(Specifically, a @code{java.util.Map<String,java.util.List<String>>}.)
address@hidden deffn
+
address@hidden Request body
+
address@hidden Procedure request-input-port
+Return a textual input port for reading the request body,
+as a sequence of characters.
address@hidden deffn
+
address@hidden Procedure request-input-stream
+Return a binary input stream for reading the request body,
+as a sequence of bytes.
address@hidden deffn
+
address@hidden Procedure request-body-string
+Return the entire request body as a string
address@hidden deffn
+
address@hidden Request IP addresses and ports
+
+Information about the interface and port on which the request was received.
+
address@hidden Procedure request-local-socket-address
+The local address on which the request was received.
+This is the combination of @code{(request-local-host)}
+and @code{(request-local-port)}, as an instance of
address@hidden
address@hidden deffn
address@hidden Procedure request-local-host
+Get the IP address of the interface on which request was received,
+as an @code{java.net.InetAddress}.
address@hidden deffn
address@hidden Procedure request-local-IP-address
+Get the IP address of the interface on which request was received,
+a string in numeric form:
address@hidden
+(request-local-host) @result{} "127.0.0.1"
address@hidden example
address@hidden deffn
address@hidden Procedure request-local-port
+Get the port this request was received on.
address@hidden
+(request-local-port) @result{} 8080
address@hidden example
address@hidden deffn
+
+Information about the interface and port of the remote client that invoked the
request.
+
address@hidden Procedure request-remote-socket-address
+The address of the remote client (usually a web browser)
+which invoked the request.
+This is the combination of @code{(request-remove-host)}
+and @code{(request-remote-port)}, as an instance of
address@hidden
address@hidden deffn
address@hidden Procedure request-remote-host
+Get the IP address of the remote client which invoked the request,
+as an @code{java.net.InetAddress}.
address@hidden deffn
address@hidden Procedure request-remote-IP-address
+Get the IP address of the remote client which invoked the request,
+as a string in numeric form.
address@hidden
+(request-remote-host) @result{} "123.45.6.7"
address@hidden example
address@hidden deffn
address@hidden Procedure request-remote-port
+The port used by the remote client.
address@hidden deffn
+
address@hidden Miscellaneous request properties
+
address@hidden Procedure request-path-translated
+Map the request-path to a file name (a string)
+in the server application directory.
+Corresponds to the CGI variable @code{PATH_TRANSLATED}.
address@hidden deffn
+
address@hidden Procedure request-method
+Returns the method of the HTTP request, usually @code{"GET"}
+or @code{"POST"}. Corresponds to the CGI variable @code{REQUEST_METHOD}.
address@hidden deffn
+
address@hidden Procedure request-scheme
+Returns the scheme (protocol) of the request.
+Usually @code{"http"}, or @code{"https"}.
address@hidden deffn
+
address@hidden HTTP response, XML beyond Scheme, HTTP requests, XML tools
address@hidden Generating HTTP responses
+
+The result of evaluating the top-level expressions of a web page script
+becomes the HTTP response that the servlet sends back to the browser.
+The result is typically an HTML/XML element code object
+Kawa will automatically format the result as appropriate for the type.
+Before the main part of the response there may be
+special "response header values",
+as created by the @code{response-header} function.
+Kawa will use the response header values to set various
+required and optional fields of the HTTP response.
+Note that @code{response-header} does not actually do anything
+until it is "printed" to the standard output.
+Note also that a @code{"Content-Type"} response value is
+special since it controls the formatting of the following
+non-response-header values.
+
address@hidden Procedure response-header key value
+Create the response header @address@hidden: @var{value}} in the HTTP
+response. The result is a "response header value" (of some unspecified
+type). It does not directly set or print a response header, but only
+does so when you actually "print" its value to the response output stream.
address@hidden deffn
+
address@hidden Procedure response-content-type type
+Species the content-type of the result - for example @code{"text/plain"}.
+Convenience function for @code{(response-header "Content-Type" @var{type})}.
address@hidden deffn
+
address@hidden Procedure error-response code [message]
+Creates a response-header with an error code of @var{code} and a
+response message of @var{message}.
+(For now this is the same as @code{response-status}.)
+
+Note this also returns a response-header value, which does not actually
+do anything unless it is returned as the result of executing a servlet body.
address@hidden deffn
+
address@hidden Procedure response-status code [message]
+Creates a response-header with an status code of @var{code} and a
+response message of @var{message}.
+(For now this is the same as @code{error-response}.)
address@hidden deffn
+
address@hidden XML beyond Scheme, , HTTP response, XML tools
address@hidden Using non-Scheme languages for XML/HTML
+
address@hidden XQuery language
+
+Bundled with Kawa is a fairly complete implementation of W3C's
+new @uref{http://www.w3c.org/XML/Query,XML Query language}.
+If you start Kawa with the @code{--xquery} it selects the "XQuery"
+source language; this also prints output using XML syntax.
+See the @uref{http://www.gnu.org/software/qexo/,Qexo (Kawa-XQuery) home page}
+for examples and more information.
+
address@hidden XSL transformations
+
+There is an experimental implementation of the XSLT (XML Stylesheet
+Language Transformations) language. Selecting @code{--xslt} at the
+Kawa command line will parse a source file according to the syntax
+on an XSLT stylesheet.
+See the @uref{http://www.gnu.org/software/qexo/xslt.html,Kawa-XSLT page}
+for more information.
+
address@hidden
+* KRL:: KRL - The Kawa Report Language for generating XML/HTML
address@hidden menu
+
address@hidden KRL, , , XML beyond Scheme
address@hidden KRL - The Kawa Report Language for generating XML/HTML
+
+KRL (the "Kawa Report Language") is powerful Kawa dialect for embedding
+Scheme code in text files such as HTML or XML templates. You select
+the KRL language by specifying @code{--krl} on the Kawa command line.
+
+KRL is based on on @uref{http://brl.sourceforge.net/,BRL},
+Bruce Lewis's "Beautiful Report Language", and
+uses some of BRL's code, but there are some experimental differences,
+and the implementation core is different. You can run KRL in
+BRL-compatility-mode by specifying @code{--brl} instead of @code{--krl}.
+
address@hidden Differences between KRL and BRL
+
+This section summarizes the known differences between KRL and BRL.
+Unless otherwise specified, KRL in BRL-compatibility mode will
+act as BRL.
+
address@hidden
address@hidden
+In BRL a normal Scheme string @code{"mystring"} is the same
+as the inverted quote string @code{]mystring[}, and both are instances
+of the type @code{<string>}.
+In KRL @code{"mystring"} is a normal Scheme string of type @code{<string>},
+but @code{]mystring[} is special type that suppresses output escaping.
+(It is equivalent to @code{(unescaped-data "mystring")}.)
address@hidden
+When BRL writes out a string, it does not do any processing
+to escape special characters like @code{<}. However, KRL in its default
+mode does normally escape characters and strings. Thus @code{"<a>"}
+is written as @code{<a&gr;}.
+You can stop it from doing this by overriding the output format, for example
+by specifying @code{--output-format scheme} on the Kawa command line,
+or by using the @code{unescaped-data} function.
address@hidden
+Various Scheme syntax forms, including @code{lambda},
+take a @stxref{body}, which is a list of one or more declarations and
+expressions. In normal Scheme and in BRL the value of a @var{body}
+is the value of the last expression. In KRL the value of a @var{body}
+is the concatenation of all the values of the expressions,
+as if using @code{values-append}.
address@hidden
+In BRL a word starting with a colon is a keyword.
+In KRL a word starting with a colon is an identifier, which by
+default is bound to the @code{make-element} function specialized
+to take the rest of the word as the tag name (first argument).
address@hidden
+BRL has an extensive utility library. Most of this has not yet been ported
+to KRL, even in BRL-compatibility mode.
address@hidden itemize
+
address@hidden Miscellaneous
address@hidden Miscellaneous topics
+
address@hidden Procedure scheme-implementation-version
+Returns the Kawa version number as a string.
address@hidden (Compatible with slib.)
address@hidden deffn
+
address@hidden Procedure scheme-window [shared]
+Create a read-eval-print-loop in a new top-level window.
+If @var{shared} is true, it uses the same environment as the
+current @code{(interaction-environment)}; if not (the default),
+a new top-level environment is created.
+
+You can create multiple top-level window that can co-exist.
+They run in separate threads.
address@hidden deffn
+
address@hidden
+* Composable pictures::
+* Building JavaFX applications::
+* Building for Android:: Building for Android devices
+* Android view construction::
+* System inquiry::
+* Processes::
+* Time-related functions::
+* Low-level functions:: Deprecated low-level functions
address@hidden menu
+
address@hidden Composable pictures
address@hidden Composable pictures
+
+The @code{(kawa pictures)} library lets you create geometric shapes
+and images, and combine them in interesting ways.
+The @ref{Tutorial - Pictures,tutorial} gives an introduction.
+
+The easiest way to use and learn the @code{pictures} library
+is with a suitable REPL. You can use the old Swing-based console
+or any @ref{Using DomTerm,DomTerm}-based terminal emulator.
+You can create a suitable window either by starting @code{kawa}
+with the @code{-w} flag, or by running the @code{kawa} command
+inside an existing DomTerm-based terminal emulator.
+The screenshot below is of the latter,
+using the @code{qtdomterm} terminal emulator.
+
address@hidden/domterm-pictures-1}
+
+After @code{(import (kawa swing))} you can use @code{show-picture}
+to display a picture in a Swing window.
+
+A @dfn{picture} is an object that can be displayed on a screen,
+web-page, or printed page, and combined with other pictures.
+
+A picture has a method printing itself in a graphical context.
+It also has various properties.
+
+An important property of a picture is its @dfn{bounding box}.
+This is a rectangle (with edges parallel to the axes) that
+surrounds the contents of the picture.
+Usually the entire visible part of the picture is inside the
+bounding box, but in some cases part of the picture may stick
+outside the bounding box.
+For example when a circle is drawn (stroked) with a ``pen'',
+the bounding box is that of the infinitely-thin mathematical circle, so
+``ink'' from the pen that is outside the circle may be outside the bounding
box.
+
+A picture has an origin point corresponding to the (0 0) cordinates.
+The origin is commonly but not always inside the bounding box.
+Certain operations (for example @code{hbox}) combine pictures by putting
+them ``next to'' each other, where ``next to'' is defined in
+terms of the bounding box and origin point.
+
address@hidden The Racket language has a
@uref{https://docs.racket-lang.org/pict/,Pict}
address@hidden library, with a lot more functionality;
address@hidden it is used by the
@uref{https://docs.racket-lang.org/quick/,Racket tutorial}.
address@hidden Racket also has a
@uref{https://docs.racket-lang.org/teachpack/2htdpimage-guide.html,@code{2htdp/image}
library} which should also be studied.
+
address@hidden Coordinates - points and dimensions
+
+The library works with a two-dimensional grid,
+where each position has an x cordinate and y coordinate.
+Normally, x values increase as you move right on the screen/page,
+while y values increase as you move @emph{down}.
+This convention matches that used by Java 2D, SVG, and many other
+graphics library. However, note that this is different from the traditional
+mathematical convention of y values increasing as you go up.
+
+By default, one unit is one ``pixel''. (More precisely,
+it is the @code{px} unit in the CSS specification.)
+
address@hidden Type Point
+A point is a pair consisting of an x and a y coordinate.
address@hidden deffn
+
address@hidden Literal {} &address@hidden @var{x} @var{y} @stxlit{]}
+Construct a point value with the specified @var{x} and @var{y} values.
+Both @var{x} and @var{y} are expressions that evaluate to real numbers:
address@hidden
+&P[(+ old-right 10) baseline]
address@hidden example
address@hidden deftypefn
+
address@hidden Type Dimension
+A dimension value is a pair of a width and a height.
+It is used for the size of pictures in the two dimensions.
+
+In a context that expects a point, a dimension is treated
+as an offset relative to some other point.
address@hidden deffn
+
address@hidden Literal {} &address@hidden @var{width} @var{height} @stxlit{]}
+Construct a dimension value with the specified @var{width}
+and @var{height} values, which are both expressions that
+evaluate to real numbers.
address@hidden deftypefn
+
address@hidden Shapes
+
+A shape is a collection of lines and curves.
+Examples include lines, circles, and polygons.
+A shape can be @dfn{stroked}, which you can think of as
+being drawn by a very fancy calligraphic pen that
+follows the lines and curves of the shape.
+
+A @dfn{closed shape} is a shape that is continuous and ends up where it
+started. This includes circles and polygons.
+A closed shape can be filled, which means the entire ``interior''
+is painted with some color or texture.
+
+A shape is represented by the Java @code{java.awt.Shape} interface.
+The @code{picture} library only provides relatively simple shapes,
+but you can use any methods that create a @code{java.awt.Shape} object.
+
address@hidden is effectively a sub-type of @dfn{picture},
+though they're represented using using disjoint classes:
+If you use a shape where a picture is required,
+the shape is automatically converted to a picture,
+as if using the @code{draw} procedure.
+
address@hidden Procedure line p1 [p2 ...]
+In the simple case two points are specified, and the result
+is a line that goes from point @var{p1} to @var{p2}.
+If @var{n} points are specied, the result is a @dfn{polyline}:
+a path consisting of @var{n-1} line segments, connecting adjacent arguments.
+(If only a single point is specified, the result is degenerate
+single-point shape.)
+
+All of the points except the first can optionally be specified
+using a dimension, which is treated an an offset from the previous point:
address@hidden
+(line &P[30 40] &D[10 5] &D[10 -10])
address@hidden example
+is the same as:
address@hidden
+(line &P[30 40] &P[40 45] &P[50 35])
address@hidden example
address@hidden deffn
+
address@hidden Procedure polygon p1 [p2 ...]
+Constructs a closed shape from line segments.
+This is the same as calling @code{line} with the same arguments,
+with the addition of a final line segment from the last point
+back to the first point.
address@hidden deffn
+
address@hidden Procedure rectangle p1 [p2]
+A rectangle is closed polygon of 4 line segments that are
+alternatively parallel to the x-axis and the y-axis.
+I.e. if you rotate a rectangle it is no longer a rectangle by
+this definition, though of course it still has a rectangular shape.
+If @var{p2} is not specified, constructs a rectangle whose upper-left corner
+is @code{&P[0 0]} and whose lower-right corner is @var{p1}.
+If @var{p2} is specified, constructs a rectangle whose upper-left corner
+is @var{p1} and whose lower-right corner is @var{p2}.
+If @var{p2} is a dimension it is considered a relative offset from @var{p1},
+just like for @code{polygon}.
address@hidden deffn
+
address@hidden Procedure circle radius [center]
+Creates a circle with the specified @var{radius}.
+If the @var{center} is not specified, it defaults to @code{&P[0 0]}.
address@hidden deffn
+
address@hidden Colors and paints
+
+A @dfn{paint} is a color pattern used to fill part of the canvas.
+A paint can be a color, a texture (a replicated pattern), or a gradient
+(a color that gradually fades to some other color).
+
+A @dfn{color} is defined by red, green, and blue values.
+It may also have an alpha component, which specifies transparency.
+
address@hidden Procedure ->paint value
+Converts @var{value} to a color - or more general a paint.
+Specificlly, the return type is @code{java.awt.Paint}.
+The @var{value} can be any one of:
address@hidden
address@hidden
+A @code{java.awt.Paint}, commonly a @code{java.awt.Color}.
address@hidden
+A 24-bit integer value is converted to a color.
+Assume the integer is equal
+to a hexadecimal literal of the form @code{#xRRGGBB}.
+Then @code{RR} (bits 16-23) is the intensity of the red component;
address@hidden (bits 8-15) is the intensity of the green component; and
address@hidden (bits 0-7) is the intensity of the red component.
address@hidden
+One of the standard HTML/CSS/SVG color names, as a string or symbol.
+See the table in @code{gnu/kawa/models/StandardColor.java} source file.
+Case is ignored, and you can optionally use hyphens to separate words.
+For example @code{'hot-pink}, @code{'hotpink}, and @code{'hotPink}
+are all the same sRGB color @code{#xFF69B4}.
address@hidden itemize
address@hidden deffn
+
address@hidden Procedure with-paint paint picture
+Create a new picture that is the ``same'' as @var{picture}
+but use @var{paint} as the default paint.
+For @var{paint} you can use any valid argument to @code{->paint}.
+The default paint (which is the color black if none is specified)
+is used for both @code{fill} (paint interior) and @code{draw} (stroke outline).
+
address@hidden
+#|kawa:1|# @kbd{(! circ1 (circle 20 &P[20 20]))}
+#|kawa:2|# @kbd{(hbox (fill circ1) (draw circ1))}
address@hidden/paint-circ-1}
+#|kawa:3|# @kbd{(with-paint 'hot-pink (hbox (fill circ1) (draw circ1)))}
address@hidden/paint-circ-2}
address@hidden example
+Above we use @code{with-paint} to create a cloned picture, which is
+the same as the original @code{hbox}, except for the default paint,
+in this case the color @code{hot-pink}.
address@hidden
+#|kawa:4|# @kbd{(! circ2 (hbox (fill circ1) (with-paint 'hot-pink (fill
circ1))))}
+#|kawa:5|# @kbd{circ2}
address@hidden/paint-circ-3}
+#|kawa:6|# @kbd{(with-paint 'lime-green circ2)}
address@hidden/paint-circ-4}
address@hidden example
+Here @code{circ2} is an @code{hbox} of two filled circles,
+one that has unspecified paint, and one that is @code{hot-pink}.
+Printing @code{circ2} directly uses black for the
+circle with unspecified color,
+but if we wrap @code{circ2} in another @code{with-paint}
+that provides a default that is used for the first circle.
address@hidden deffn
+
address@hidden Filling a shape with a color
+
address@hidden Procedure fill shape
address@hidden Procedure fill paint shape
+
+Fill the ``inside'' of @var{shape}.
+If no @var{paint} is specified, uses the current default paint.
+Otherwise, @code{(fill @var{paint} @var{shape})}
+is the same @code{(with-paint @var{paint} (file @var{shape}))}.
address@hidden deffn
+
address@hidden Stroking (outlining) a shape
+
address@hidden Procedure draw @arbno{option} @atleastone{shape}
+
+Returns a picture that draws the outline of the @var{shape}.
+This is called @dfn{stroking}.
+An @var{option} may be one of:
address@hidden
address@hidden
+A @code{Paint} or @code{Color} object, which is used to draw the shape.
address@hidden
+A standard color name, such as @code{'red} or @code{'medium-slate-blue}.
+This is mapped to a @code{Color}.
address@hidden
+A join-specifier, which is a symbol specifying how each curve of the shape is
+connected to the next one.
+The options are @code{'miter-join}, @code{'round-join}, and @code{'bevel-join}.
+The default if none is specified is @code{'miter-join}.
address@hidden
+A end-cap-specifier, which is a symbol specifying how each end of the
+shape is terminated.
+The options are @code{'square-cap}, @code{'round-cap}, or @code{'butt-cap}.
+The default is @code{'butt-cap}.
+(This follows SVG and HTML Canvas.
+The default in plain Java AWT is a square cap.)
address@hidden
+A real number specifies the thickness of the stroke.
address@hidden
+A @code{java.awt.Stroke} object.
+This combines join-specifier, end-cap-specifier, thickness, and more
+in a single object. The @code{BasicStroke} class can specify dashes,
+though that is not yet supported for SVG output; only AWT or image output.
address@hidden itemize
+
+Let us illustrate with a sample line @code{lin}
+and a helper macro @code{show-draw}, which adds a border around a shape,
+then draws the given shape with some options, and finally
+re-draws the shape in plain form.
address@hidden
+#|kawa:10|# @kbd{(define lin (line &P[0 0] &P[300 40] &P[200 100] &P[50 70]))}
+#|kawa:11|# @kbd{(define-syntax show-draw}
+#|....:12|# @kbd{ (syntax-rules ()}
+#|....:13|# @kbd{ ((_ options ... shape)}
+#|....:14|# @kbd{ (border 12 'bisque (zbox (draw options ... shape)
shape)))))}
+#|....:15|# @kbd{(show-draw 8 'lime lin)}
address@hidden/show-draw-1}
+#|....:16|# @kbd{(show-draw 8 'lime 'round-cap 'round-join lin)}
address@hidden/show-draw-2}
+#|....:17|# @kbd{(show-draw 8 'lime 'square-cap 'bevel-join lin)}
address@hidden/show-draw-3}
address@hidden example
address@hidden deffn
+Notice how the different cap and join styles change the drawing.
+Also note how the stroke (color lime) extends beyond its bounding box,
+into the surrounding border (color bisque).
address@hidden Affine transforms
+
+A 2D affine transform is a linear mapping from coordinates to
+coordinates. It generalizes translation, scaling, flipping, shearing,
+and their composition. An affine transform maps straight parallel lines
+into other straight parallel lines, so it is only a subset of possible
+mappings - but a very useful subset.
+
address@hidden Procedure affine-transform xx xy yx yy x0 y0
address@hidden Procedure affine-transform px py p0
+Creates a new affine transform.
+The result of applying @code{(affine-transform @address@hidden @address@hidden
@address@hidden @address@hidden @address@hidden @address@hidden)}
+to the point @code{&address@hidden @var{y}]}
+is the transformed point
address@hidden
+&P[(+ (* @var{x} @address@hidden) (* @var{y} @address@hidden) @address@hidden)
+ (+ (* @var{x} @address@hidden) (* @var{y} @address@hidden) @address@hidden)]
address@hidden example
+
+If using point arguments,
address@hidden(affine-transform &address@hidden@sub{x}} @address@hidden
&address@hidden@sub{x}} @address@hidden &address@hidden@sub{0}}
@address@hidden)}
+is equivalent to:
address@hidden(affine-transform @address@hidden @address@hidden @address@hidden
@address@hidden @address@hidden @address@hidden)}.
address@hidden deffn
+
address@hidden Procedure with-transform transform picture
address@hidden Procedure with-transform transform shape
+Creates a transformed picture.
+
+If the argument is a @var{shape}, then the result is also a shape.
address@hidden deffn
+
address@hidden Procedure with-transform transform point
+Apply a transform to a single point, yielding a new point.
address@hidden deffn
+
address@hidden Procedure with-transform transform1 transform2
+Combine two transforms, yielding the composed transform.
address@hidden deffn
+
address@hidden Procedure rotate angle
address@hidden Procedure rotate angle picture
+The one-argument variant creates a new affine transform that rotates
+a picture about the origin by the specified @var{angle}.
+A positive @var{angle} yields a clockwise rotation.
+The @var{angle} can be either a quantity (with a unit of
+either @code{rad} radians, @code{deg} (degrees), or @code{grad} (gradians)),
+or it can be a unit-less real number (which is treated as degrees).
+
+The two-argument variant applies the resulting transform to
+the specified picture. It is equivalent to:
address@hidden
+(with-transform (rotate @var{angle}) @var{picture})
address@hidden example
address@hidden deffn
+
address@hidden Procedure scale factor
address@hidden Procedure scale factor picture
+Scales the @var{picture} by the given @var{factor}.
+The @var{factor} can be a real number.
+The @var{factor} can also be a point or a dimension, in which case
+the two cordinates are scaled by a different amount.
+
+The two-argument variant applies the resulting transform to
+the specified picture. It is equivalent to:
address@hidden
+(with-transform (scale @var{factor}) @var{picture})
address@hidden example
address@hidden deffn
+
address@hidden Procedure translate offset
address@hidden Procedure translate offset picture
+
+The single-argument variant creates a transform
+that adds the @var{offset} to each point.
+The @var{offset} can be either a point or a dimension (which
+are treated quivalently).
+
+The two-argument variant applies the resulting transform to
+the specified picture. It is equivalent to:
address@hidden
+(with-transform (translate @var{offset}) @var{picture})
address@hidden example
address@hidden deffn
+
address@hidden Combining pictures
+
address@hidden Procedure hbox [spacing] picture ...
address@hidden Procedure vbox [spacing] picture ...
address@hidden Procedure zbox picture ...
+Make a combined picture from multiple sub-pictures drawn
+either ``next to'' or ``on top of'' each other.
+
+The case of @code{zbox} is simplest: The sub-pictures are drawn
+in argument order at the same position (origin). The address@hidden'' refers
to
+the idea that the pictures are stacked on top of each other along
+the ``Z-axis'' (the one perpendicular to the screen).
+
+The @code{hbox} and @code{vbox} instead place the sub-pictures
+next to each other, in a row or column.
+If @var{spacing} is specified, if must be a real number.
+That much extra spacing is added between each sub-picture.
+
+More precisely: @code{hbox} shifts each sub-picture except the first
+so its left-origin control-point
+(see discussion at @code{re-center}) has the same position
+as the right-origin control point of the previous picture
address@hidden the amount of @var{spacing}.
+Similarly, @code{vbox} shifts each sub-picture except the first
+so its top-origin control point has the same position
+as the bottom-origin point of the previous picture, plus @var{spacing}.
+
+The bounding box of the result is the smallest rectangle that
+includes the bounding boxes of the (shifted) sub-pictures.
+The origin of the result is that of the first picture.
address@hidden deffn
+
address@hidden Procedure border [size [paint]] picture
+Return a picture that combines @var{picture}
+with a rectangular border (frame) around @var{picture}'s bounding box.
+The @var{size} specifies the thickness of the border:
+it can be real number, in which it is the thickness on all four sides;
+it can be a Dimension, in which case the width is the left and right
+thickness, while the height is the top and bottom thickness;
+or it can be a Rectangle, in which case it is the new bounding box.
+If @var{paint} is specified it is used for the border;
+otherwise the default paint is used.
+The border is painted before (below) the @var{picture} painted.
+The bounding box of the result is that of the border, while
+the origin point is that of the original @var{picture}.
address@hidden
+#|kawa:2|# @kbd{(with-paint 'blue (border &D[8 5] (fill 'pink (circle 30))))}
address@hidden/border-1}
address@hidden example
address@hidden deffn
+
address@hidden Procedure padding width [background] picture
+This is similar to @code{border},
+but it just adds extra space around @var{picture},
+without painting it. The @var{size} is specified the same way.
+If @var{background} is specified,
+it becomes the background paint for the entire padded
+rectangle (both @var{picture} and the extra padding).
address@hidden
+#|kawa:3|# @kbd{(define circ1 (fill 'teal (circle 25)))}
+#|kawa:4|# @kbd{(zbox (line &P[-30 20] &P[150 20])}
+#|kawa:5|# @kbd{ (hbox circ1 (padding 6 'yellow circ1) (padding 6 circ1)))}
address@hidden/padding-1}
address@hidden example
+This shows a circle drawn three ways:
+as-is; with padding and a background color;
+with padding and a transparent background.
+A line is drawn before (below) the circles to contrast
+the yellow vs transparent backgrounds.
address@hidden deffn
+
address@hidden Procedure re-center [xpos] [ypos] picture
+Translate the @var{picture} such that the point specified by @var{xpos}
+and @var{ypos} is the new origin point, adjusting the bounding box to match.
+If the @var{picture} is a shape, so is the result.
+
+The @var{xpos} can have four possible values, all of which are symbols:
address@hidden'left} (move the origin to the left edge of the bounding box);
address@hidden'right} (move the origin to the left edge of the bounding box);
address@hidden'center} (or @code{'centre}) (move the origin to halfway between
the left and right edges);
+or @code{'origin} (don't change the location along the x-axis).
+The @var{ypos} can likewise have four possible values:
address@hidden'top} (move the origin to the top edge of the bounding box);
address@hidden'bottom} (move the origin to the bottom edge of the bounding box);
address@hidden'center} (or @code{'centre}) (move the origin to halfway between
the
+top and bottom edges);
+or @code{'origin} (don't change the location along the y-axis).
+
+A single @code{'center} argument
+is the same as specifying @code{'center} for both axis; this is the default.
+A single @code{'origin} argument
+is the same as specifying @code{'origin} for both axis;
+this is the same as just @var{picture}.
+
+The 16 control points are shown below, relative to a picture's
+bounding box and the X- and Y-axes.
+The abbreviations have the obvious values, for example
address@hidden means @code{'left 'center}.
address@hidden
+LT OT CT RT
+ ┌────┬──────────┐
+ │ │ │
+ │ │ │
+LC│ OC C │RC
+LO├────O──CO──────┤RO
+ │ │ │
+ └────┴──────────┘
+LB OB CB RB
address@hidden example
+The result of (for example) @code{(re-center 'left 'center @var{P})}
+is @var{P} translated so the origin is at control point @code{LC}.
+
address@hidden
+#|kawa:1|# @kbd{(define D (fill 'light-steel-blue (polygon &P[-20 0] &P[0 -20]
&P[60 0] &P[0 40])))}
+#|kawa:2|# @kbd{(zbox D (draw 'red (circle 5)))}
address@hidden/re-center-1}
address@hidden example
+Above we defined @code{D} as a vaguely diamond-shaped quadrilateral.
+A small red circle is added to show the origin point.
+Below we display 5 versions of @code{D} in a line (an @code{hbox}),
+starting with the original @code{D} and 4 calls to @code{re-center}.
address@hidden
+#|kawa:3|# @kbd{(zbox (hbox D (re-center 'top D) (re-center 'bottom D)}
+#|....:4|# @kbd{ (re-center 'center D) (re-center 'origin D))}
+#|....:5|# @kbd{ (line &P[0 0] &P[300 0]))}
address@hidden/re-center-2}
address@hidden example
+The line at @var{y=0} shows the effects of @code{re-center}.
address@hidden deffn
+
address@hidden Images
+
+An image is a picture represented as a rectangular grid of color values.
+An image file is some encoding (usually compressed) of an image,
+and mostly commonly has the extensions @code{png}, @code{gif},
+or @code{jpg}/@code{jpeg}.
+
+A ``native image'' is an instance of @code{java.awt.image.BufferedImage},
+while a ``picture image'' is an instance of @code{gnu.kawa.models.DrawImage}.
+(Both classes implement the @code{java.awt.image.RenderedImage} interface.)
+A @code{BufferedImage} is automatically converted to a @code{DrawImage}
+when needed.
+
address@hidden Procedure image bimage
address@hidden Procedure image picture
address@hidden Procedure image src: path
+
+Creates a picture image, using either an existing native image @var{bimage},
+or an image file specified by @var{path}.
+
+Writing @code{(image src: @var{path})} is roughly the same
+as @code{(image (read-image @var{path}))} except that the former
+has the @var{path} associated with the resulting picture image.
+This can make a difference when the image is used or displayed.
+
+If the argument is a @var{picture}, it is converted to an image
+as if by @code{->image}.
address@hidden deffn
+
address@hidden Procedure image-read path
+Read an image file from the specified @var{path},
+and returns a native image object (a @code{BufferedImage}).
address@hidden
+#|kawa:10|# @kbd{(define img1 (image-read
"http://pics.bothner.com/2013/Cats/06t.jpg";))}
+#|kawa:11|# @kbd{img1}
address@hidden/image-cat-1a}
+#|kawa:12|# @kbd{(scale 0.6 (rotate 30 img1))}
address@hidden/image-cat-1b}
address@hidden example
address@hidden deffn
+
+Note that while @code{img1} above is a (native) image,
+the scaled rotated image is not an image object.
+It is a picture - a more complex value that @emph{contains} an image.
+
address@hidden Procedure image-write picture path
+The @var{picture} is converted to an image
+(as if by using @code{->image}) and then it is written
+to the specified @var{path}.
+The format used depends on (the lower-cased string value of) the path:
+A JPG file if the name ends with @code{".jpg"} or @code{".jpeg"};
+a GIF file if the name ends with @code{".gif"};
+a PNG file if the name ends with @code{".png"}.
+(Otherwise, the defalt is PNG, but that might change.)
address@hidden deffn
+
address@hidden Procedure image-width image
address@hidden Procedure image-height image
+Return the width or height of the given @var{image}, in pixels.
address@hidden deffn
+
address@hidden Procedure ->image picture
+Convert @var{picture} to an image (a @code{RenderedImage}).
+If the @var{picture} is an image, return as-is.
+Otherwise, create an empty image (a @code{BufferedImage} whose size is the
address@hidden's bounding box), and ``paint'' the @var{picture} into it.
address@hidden
+#|kawa:1|# @kbd{(define c (fill (circle 10)))}
+#|kawa:2|# @kbd{(scale 3 (hbox c (->image c)))}
address@hidden/image-scaled-1}
address@hidden example
+Here we take a circle @code{c}, and convert it to an image.
+Note how when the image is scaled, the pixel artifacts are very noticable.
+Also note how the origin of the image is the top-level corner,
+while the origin of the original circle is its center.
address@hidden deffn
+
address@hidden Compositing - Controlling how pictures are combined
+
address@hidden Procedure with-composite [[compose-op] picture] ...
+Limited support - SVG and DomTerm output has not been implemented.
address@hidden deffn
+
address@hidden Displaying and exporting pictures
+
address@hidden Export to SVG
+
address@hidden Procedure picture-write-svg picture path [headers]
+Writes the @var{picture} to the file specified @var{path},
+in SVG (Structered Vector Graphics) format.
+If @var{headers} is true (which is the default)
+first write out the XML and DOCTYPE declarations
+that should be in a well-formed standaline SVG file.
+Otherwise, just write of the @code{<svg>} element.
+(Modern browers should be able to display a file
+consisting of just the @code{<svg>} element,
+as long as it has extension @code{.svg}, @code{.xml}, or @code{.html};
+the latter may add some extra padding.)
address@hidden deffn
+
address@hidden Procedure picture->svg-node picture
+Returns a SVG representation of @code{picture},
+in the form of an @code{<svg>} element,
+similar to those discussed in @ref{Creating XML nodes}.
+If you convert the @code{<svg>} element to a string,
+you get formatted XML;
+if you @code{write} the @code{<svg>} element
+you get an @ref{XML literals,XML literal} of form @code{"#<svg>...</svg>"}.
+If you @code{display} the @code{<svg>} element
+in a DomTerm terminal you get the picture (as a picture).
+This works because when you display an element in DomTerm
+it gets inserted into the display.
address@hidden deffn
+
address@hidden Display in Swing
+
+These procedures require @code{(import (kawa swing))} in addition to
address@hidden(import (kawa pictures))}.
+
+The convenience function @code{show-picture} is useful
+for displaying a picture in a new (Swing) window.
+
address@hidden Procedure show-picture picture
+If this is the first call to @code{show-pictures},
+displays @var{picture} in a new top-level window (using the Swing toolkit).
+Sequenent calls to @code{show-picture} will reuse the window.
address@hidden
+#|kawa:1|# @kbd{(import (kawa swing) (kawa pictures))}
+#|kawa:2|# @kbd{(show-picture @var{some-picture})}
+#|kawa:3|# @kbd{(set-frame-size! &D[200 200])} ; Adjust window size
+#|kawa:4|# @kbd{(show-picture @var{some-other-picture})}
address@hidden example
address@hidden deffn
+
address@hidden Procedure picture->jpanel picture
+Return a @code{JPanel} that displays @var{picture}.
+You can change the displayed picture by:
address@hidden
+(set! @var{panel}:picture @var{some-other-picture})
address@hidden example
address@hidden deffn
+
address@hidden Procedure set-frame-size! size [frame]
+If @var{frame} is specified, set its size.
+Otherwise, remember the size for future @code{show-picture} calls;
+if there is already a @code{show-picture} window, adjust its size.
address@hidden deffn
+
address@hidden Convert to image
+
+You can convert a picture to an image using the @code{->image} procedure,
+or write it to a file using the @code{image-write} procedure.
+
address@hidden Building JavaFX applications
address@hidden Building JavaFX applications
+
address@hidden JavaFX
+Kawa makes it easy to build ``rich client'' (i.e. GUI) applications using
address@hidden://www.oracle.com/technetwork/java/javafx/overview/index.html,JavaFX}.
+For example the following program will print up a window with a button;
+clicking on the button will print a message on the console output about the
+event.
address@hidden
+(require 'javafx-defs)
+(javafx-application)
+
+(javafx-scene
+ title: "Hello Button"
+ width: 600 height: 450
+ (Button
+ text: "Click Me"
+ layout-x: 25
+ layout-y: 40
+ on-action: (lambda (e) (format #t "Event: ~s~%~!" e))))
address@hidden example
+
+JavaFX support is builtin to the pre-built @address@hidden
+It is easiest to use JDK 8; see below if you're using JDK 7.
+If you build Kawa from source, specify @code{--with-javafx} on the
address@hidden command line (assuming you're using JDK 8).
+
+Assume the above file is @code{HelloButton1.scm}, you can
+run it like this:
address@hidden
+$ kawa HelloButton1.scm
address@hidden example
+
+For more information and examples read this (slightly older)
address@hidden://per.bothner.com/blog/2011/JavaFX-using-Kawa-intro/,introduction},
+and
address@hidden://localhost/per/blog/2011/JavaFX-using-Kawa-animation/,this on
animation}.
+
+The @code{browse-kawa-manual} script in the @code{doc} directory (source only)
+uses JavaFX WebView to create a window for browsing the Kawa documentation.
+
address@hidden Using JavaFX with JDK 7
+JDK 8 ships with JavaFX, and it is in the default @code{CLASSPATH}.
+JDK 7 update 9 or later does have JavaFX included, but it is a separate
address@hidden which not in the default @code{CLASSPATH}.
+Thus you have to explicitly add @code{jfxrt.jar}.
+To run the previous @code{HelloButton1.scm} you can do:
address@hidden
+java -cp $JAVA_HOME/lib/jfxrt.jar:$KAWA_HOME/kawa.jar HelloButton1.scm
address@hidden example
+
+If you build Kawa from source, do:
address@hidden
+$ ./configure --with-javafx=$JAVA_HOME --enable-kawa-frontend ...other-args...
address@hidden example
+The resulting Kawa binary sets up the path to @code{jfxrt.jar} so you just
need to do:
address@hidden
+$ kawa HelloButton1.scm
address@hidden example
+
address@hidden Building for Android
address@hidden Building for Android
+
+Google's phone/tablet operating system
address@hidden://developers.google.com/android/,Android}
+is based on a custom virtual machine on top of a Linux kernel.
+Even though Android isn't strictly (or legally) speaking Java,
+you can build Android applications using Kawa.
+
+Below is "Hello world" written in Kawa Scheme. A slightly
+more interesting example is in @ref{Android view construction,next section}.
+
address@hidden
+(require 'android-defs)
+(activity hello
+ (on-create-view
+ (android.widget.TextView (this)
+ text: "Hello, Android from Kawa Scheme!")))
address@hidden example
+
+The following instructions have been tested on GNU/Linux,
+specifically Fedora 17.
address@hidden://asieno.com/blog/index.php/post/2012/08/16/Setting-up-the-environment-Android-Kawa,This
link} may be helpful if you're building on Windows.
+
address@hidden Downloading and setting up the Android SDK
+
+First @uref{http://code.google.com/android/download.html,download the Android
SDK}. Unzip in a suitable location, which we'll refer to as @code{ANDROID_HOME}.
+
address@hidden
+export ANDROID_HOME=/path/to/android-sdk-linux
+PATH=$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools:$PATH
address@hidden example
+
+Next you have to get the appropriate platform SDK:
+
address@hidden
+$ android update sdk
address@hidden example
+You need to select an Android ``platform''.
+Platform (API) 16 corresponds to Android 4.1.2 (Jelly Bean).
+Select that or whatever you prefer, and click @code{Install}.
+(You can install multiple platforms, but each project
+is built for a specific platform.)
+
address@hidden
+ANDROID_PLATFORM=android-16
address@hidden example
+
address@hidden Building Kawa for Android
+
+Set @code{JAVA_HOME} to where your JDK tree is.
+You should use JDK 6; JDK 7 does not work at time of writing.
+
address@hidden
+$ export JAVA_HOME=/opt/jdk1.6
address@hidden example
+
+First @ref{Getting Kawa,get the Kawa source code}.
+
+If using Ant (as is recommended on Windows):
+
address@hidden
+$ ant -Denable-android=true
address@hidden example
+Alternatively, you can use @code{configure} and @code{make}:
+
address@hidden
+$ KAWA_DIR=path_to_Kawa_sources
+$ cd $KAWA_DIR
+$ ./configure
--with-android=$ANDROID_HOME/platforms/$ANDROID_PLATFORM/android.jar
--disable-xquery --disable-jemacs
+$ make
address@hidden example
+
address@hidden Creating the application
+
+Next, we need to create a project or ``activity''.
+This tutorial assumes you want to create the project
+in the target directory @code{KawaHello},
+with the main activity being a class named @code{hello} in a
+package @code{kawa.android}:
address@hidden
+PROJECT_DIR=KawaHello
+PROJECT_CLASS=hello
+PROJECT_PACKAGE=kawa.android
+PROJECT_PACKAGE_PATH=kawa/android
address@hidden example
+
+To create the project use the following command:
address@hidden
+$ android create project --target $ANDROID_PLATFORM --name $PROJECT_DIR
--activity $PROJECT_CLASS --path ./$PROJECT_DIR --package $PROJECT_PACKAGE
address@hidden example
+
+Replace the skeleton @code{hello.java} by the Scheme code at the
+top of this note, placing in a file named @code{hello.scm}:
address@hidden
+$ cd $PROJECT_DIR
+$ HELLO_APP_DIR=`pwd`
+$ cd $HELLO_APP_DIR/src/$PROJECT_PACKAGE_PATH
+$ rm $PROJECT_CLASS.java
+$ @i{create} $PROJECT_CLASS.scm
address@hidden example
+
+We need to copy/link the Kawa jar file so the Android SDK can find it:
address@hidden
+$ cd $HELLO_APP_DIR
+$ ln -s $KAWA_DIR/address@hidden libs/kawa.jar
address@hidden example
+
+Optionally, you can use address@hidden, which is slightly smaller,
+but does not support eval, and does not get built by the Ant build:
address@hidden
+$ ln -s $KAWA_DIR/address@hidden libs/kawa.jar
address@hidden example
+
+Copy or link @code{custom_rules.xml} from the Kawa sources:
address@hidden
+ln -s $KAWA_DIR/gnu/kawa/android/custom_rules.xml .
address@hidden example
+
+Finally to build the application just do:
address@hidden
+$ ant debug
address@hidden example
+
address@hidden Running the application on the Android emulator
+
+First you need to create an
@uref{http://developer.android.com/tools/devices,Android Virtual Device (avd)}.
Start:
address@hidden
+android
address@hidden example
+Then from menu @code{Tools} select @code{Manage AVDs...}.
+In the new window click @code{New....}
+Pick a @code{Name} (we use @code{avd16} in the following),
+a @code{Target} (to match @code{$ANDROID_PLATFORM}),
+and optionally change the other properties, before clicking @code{Create AVD}.
+
+Now you can start up the Android emulator:
+
address@hidden
+$ emulator -avd avd16 &
address@hidden example
+Wait until Android has finished booting (you will see the Android home screen),
+click the menu and home buttons. Now install our new application:
+
address@hidden
+adb install bin/KawaHello-debug.apk
address@hidden example
+
address@hidden Running the application on your device
+
+If the emulator is running, kill it:
address@hidden
+$ kill %emulator
address@hidden example
+
+On your phone or other Android devude, enable USB debugging.
+(This is settable from the @code{Settings} application,
+under @code{Applications / Development}.)
+
+Connect the phone to your computer with the USB cable.
+Verify that the phone is accessible to @code{adb}:
address@hidden
+$ adb devices
+List of devices attached
+0A3A560F0C015024 device
address@hidden example
+
+If you don't see a device listed, it may be permission problem. You can figure
out which device corresponds to the phone by doing:
+
address@hidden
+$ ls -l /dev/bus/usb/*
+/dev/bus/usb/001:
+total 0
+...
+crw-rw-rw- 1 root wheel 189, 5 2010-10-18 16:52 006
+...
address@hidden example
+
+The timestamp corresponds to when you connected the phone.
+Make the USB connection readable:
address@hidden
+$ sudo chmod a+w /dev/bus/usb/001/006
address@hidden example
+
+Obviously if you spend time developing for an Androd phone you'll want to
automate this process;
address@hidden://sites.google.com/site/siteofhx/Home/android/drivers/udc,this
link}
+or
@uref{https://groups.google.com/forum/?fromgroups=#!topic/android-developers/nTfhhPktGfM,this
link} may be helpful.
+
+Anyway, once @code{adb} can talk to the phone, you install in the same way as
before:
address@hidden
+adb install bin/KawaHello-debug.apk
address@hidden example
+
address@hidden Some debugging notes
+
+You will find a copy of the SDK documentation in
@code{$ANDROID_HOME/docs/index.html}.
+
+If the emulator complains that your application has stopped unexpectedly, do:
address@hidden
+$ adb logcat
address@hidden example
+
+This shows log messages, stack traces, output from the @code{Log.i} logging
method, and other useful information.
+(You can alternatively start @code{ddms} (Dalvik Debug Monitor Service), click
on the @code{kawa.android line} in the top-left sub-window to select it, then
from the @code{Device} menu select @code{Run logcat....}).
+
+To uninstall your application, do:
address@hidden
+$ adb uninstall kawa.android
address@hidden example
+
address@hidden Other resources
+
+(A more interesting
@uref{http://androidscheme.blogspot.com/2010/10/text-to-speech-app.html,text-to-speech}
example app is on Santosh Rajan's
@uref{http://androidscheme.blogspot.com/,Android-Scheme blog}.)
+
address@hidden://github.com/ecraven/SchemeAndroidOGL}
+
address@hidden Android view construction
address@hidden Android view construction
+
+An Android user interface is constructed from @code{View} objects.
+The following is an example that illustrates some features of
+Kawa to help write views hierarchies,
+The example is self-contained, and can be built and run
+as described in @ref{Building for Android}.
+
address@hidden
+(require 'android-defs)
+(activity hello
+ (on-create-view
+ (define counter ::integer 0)
+ (define counter-view
+ (TextView text: "Not clicked yet."))
+ (LinearLayout orientation: LinearLayout:VERTICAL
+ (TextView text: "Hello, Android from Kawa Scheme!")
+ (Button
+ text: "Click here!"
+ on-click-listener: (lambda (e)
+ (set! counter (+ counter 1))
+ (counter-view:setText
+ (format "Clicked ~d times." counter))))
+ counter-view)))
address@hidden example
+
+The first @code{import} form imports various useful definitions
+from the Kawa Android library. Using these is not required for
+writing a Kawa application, but makes it more convenient.
+
+The names @code{LinearLayout}, @code{TextView}, and @code{Button}
+are just aliases for standard Android @code{View} sub-classes.
+A few are prefined by @code{(require 'android-defs)}, or you
+can define them yourself using @code{define-alias}.
+
+An Android application consists of one or more @dfn{activities},
+each of which is an instance of the @code{android.app.Activity} class.
+You can use the @code{activity} macro to define your @code{Activity} class.
+The first macro argument (in this case @code{hello}) is the class name,
+and the others are members of the class, in the syntax of
+a @stxref{field-or-method-decl}. The sub-form @code{on-create-view}
+is an abbreviation for declaring an @code{onCreate} method
+(which is called when the @code{Activity} starts up
address@hidden LOOK THIS UP - also when re-started?
+followed by a @code{setContentView}:
+The body of the @code{on-create-view} is evaluated.
+The result should be a @code{View} expression,
+which is passed to @code{setContentView}.
+
address@hidden Procedure current-activity [new-value]
+With no arguments, returns the current @code{Activity}.
+If a @var{new-value} argument is given, sets the current activity.
+It is set automatically by the @code{on-create} and @code{on-create-view}
+methods of the @code{activity} macro.
+
+Since @code{current-activity} is a @ref{Parameter objects,parameter object},
+you can
+locally change the value using @ref{parameterize-syntax,@code{parameterize}}.
address@hidden deffn
+
address@hidden View object allocation
+
+To create an instance of a @code{View} class you ``call'' the
+class as if it were a function,
+as described in @ref{Allocating objects}.
+For example:
address@hidden
+(TextView (this) text: "Hello, Android from Kawa Scheme!")
address@hidden example
+
+If you @code{(require 'android-defs)} that defines
+some special handling for @code{View} classes.
+You can leave out the @code{(this)} argument,
+which refers to the enclosing @code{Activity}:
address@hidden
+(TextView text: "Hello, Android from Kawa Scheme!")
address@hidden example
+
address@hidden Event handlers
+
+You can register event listeners on Android @code{View} objects
+using methods typically named @address@hidden
+For example @code{setOnClickListener}. When allocating
+an object you can leave out the @code{set}, and you can optionally
+use Scheme-style names: @code{on-click-listener}. The argument
+is an object of a special nested listener class,
+for example @code{View$OnClickListener}. These are
+single-method classes, so you can use a lambda expression
+and @ref{SAM-conversion} will automatically create the needed
+listener class.
+
address@hidden System inquiry
address@hidden System inquiry
+
address@hidden home-directory
+A string containing the home directory of the user.
address@hidden defvar
+
address@hidden Procedure command-line
+Returns a nonempty list of immutable strings. The first element is
+an implementation-specific name for the running top-level
+program.
+The remaining elements are the command-line arguments,
+as passed to the @code{main} method (except for those
+flags processed by Kawa itself).
+
+The first element will depend on how the Kawa module was invoked.
+Kawa uses the following rules to determine the command name:
+
address@hidden
address@hidden
+If the property @code{kawa.command.name} is set, that is used.
+This variable can be set on the @code{kawa} command line,
+for example from a script:
address@hidden
+kawa -Dkawa.command.name="$0" foo "$@@"
address@hidden example
+This variable is also set implicitly by the meta-arg option. FIXME.
address@hidden
+If we're reading a source file that starts with the Unix command-file prefix
address@hidden/} then we use the name of the source file.
+The assumption is that such a file is an executable script.
address@hidden
+If the Java property @code{kawa.command.line} is set,
+then we use that (after stripping off text that duplicates
+the remaining arguments).
+The @code{kawa} program sets this property to the
+command line used to invoke it
+(specifically the contents of the entire @code{argv} array),
+before invoking the @code{java} program.
address@hidden
+If the Java property @code{sun.java.command} is set,
+then we use that (after stripping off text that duplicates
+the remaining arguments), and then prepending the string @code{"java "}.
+The OpenJDK @code{java} program sets this property.
address@hidden
+If all else fails, the command name is @code{"kawa"}.
address@hidden enumerate
address@hidden deffn
+
address@hidden command-line-arguments
+Any command-line arguments (following flags processed by Kawa itself)
+are assigned to the global variable @samp{command-line-arguments},
+which is a vector of strings.
address@hidden defvar
+
address@hidden Procedure process-command-line-assignments
+Process any initial command-line options that set variables.
+These have the form @address@hidden@var{value}}.
+Any such command-line options (at the start of the command-line)
+are processed and removed from the command-line.
address@hidden
+$ java kawa.repl -- abc=123 def
+#|kawa:1|# (write (command-line))
+("java kawa.repl --" "abc=123" "def")
+#|kawa:2|# (process-command-line-assignments)
+#|kawa:3|# (write (command-line))
+("java kawa.repl -- abc=123" "def")
+#|kawa:4|# abc
+123
address@hidden example
+This function is mostly useful for Kawa applications
+compiled with the @code{--main} option.
+(It is used to set XQuery @code{external} variables.)
address@hidden deffn
+
address@hidden Procedure get-environment-variable name
+Many operating systems provide each running process with
+an environment conisting of environment variables.
+(This environment is not to be confused with the
+Scheme environments that can be passed to @code{eval}.)
+Both the name and value of an environment variable are
+strings. The procedure @code{get-environment-variable}
+returns the value of the environment variable @var{name},
+or @code{#f} if the environment variable is not found.
address@hidden It may use locale information to encode the name and
address@hidden decode the value of the environment variable.
+(This uses the @code{java.lang.System:getenv} method.)
+It is an error to mutate the resulting string.
address@hidden
+(get-environment-variable "PATH")
+ @result{} "/usr/local/bin:/usr/bin:/bin"
address@hidden example
address@hidden deffn
+
address@hidden Procedure get-environment-variables
+Returns the names and values of all the environment variables as an alist,
+where the car of each entry is the name of an environment variable,
+and the cdr is its value, both as strings.
+It is an error to mutate any of the strings or the alist itself.
address@hidden
+(get-environment-variables)
+ @result{} (("USER" . "root") ("HOME" . "/"))
address@hidden example
address@hidden deffn
+
address@hidden Processes
address@hidden Processes
+
+A @dfn{process} is a native (operating-system-level) application or
+program that runs separately from the current virtual machine.
+
+Many programming languages have facilities to allow access to system
+processes (commands). (For example Java has @code{java.lang.Process}
+and @code{java.lang.ProcessBuilder}.)
+These facilities let you send data to the standard input, extract the
+resulting output, look at the return code, and sometimes even pipe
+commands together. However, this is rarely as easy as it is using
+the old Bourne shell; for example command substitution is awkward.
+Kawa's solution is based on these two ideas:
address@hidden
address@hidden
+A ``process expression'' (typically a function call) evaluates to a
address@hidden value, which provides access to a Unix-style
+(or Windows) process.
address@hidden
+In a context requiring a string (or a bytevector), an @code{LProcess} is
+automatically converted to a string (or bytevector)
+comprising the standard output from the process.
address@hidden itemize
+
address@hidden Creating a process
+
+The most flexible way to start a process is with either the
address@hidden procedure or
+the @code{&address@hidden@address@hidden syntax
+for @ref{process literals}.
+
address@hidden Procedure run-process @address@hidden @meta{command}
+Creates a process object, specifically a @code{gnu.kawa.functions.LProcess}
+object.
+A @var{process-keyword-argument} can be used to set various options,
+as discussed below.
+
+The @var{command} is the process command-line (name and arguments).
+It can be an array of strings, in which case those are used as the
+command arguments directly:
address@hidden
+(run-process ["ls" "-l"])
address@hidden example
+The @var{command} can also be a single string, which is split (tokenized)
+into command arguments separated by whitespace.
+Quotation groups words together just like traditional shells:
address@hidden
+(run-process "cmd a\"b 'c\"d k'l m\"n'o")
+ @result{} (run-process ["cmd" "ab 'cd" "k'l m\"no"])
address@hidden example
+
+The syntax shorthand @code{&address@hidden@address@hidden
+or @code{&address@hidden@address@hidden (discussed below)
+is usually more convenient.
address@hidden deffn
+
address@hidden
address@hidden
+ @stxref{process-redirect-argument}
+ | @stxref{process-environment-argument}
+ | @stxref{process-misc-argument}
address@hidden display
+
+We discuss @stxref{process-redirect-argument} and
address@hidden later.
address@hidden
+The @var{process-misc-argument} options are just the following:
address@hidden @asis
address@hidden @stxlit{shell:} @var{shell}
+Currently, @var{shell} must be one of @code{#f} (which is ignored)
+or @code{#t}. The latter means to use an external shell to tokenize
+the @var{command}.
+I.e. the following are equivalent:
address@hidden
+(run-process shell: #t "@var{command}")
+(run-process ["/bin/sh" "-c" "@var{command}"])
address@hidden example
address@hidden @stxlit{directory:} @var{dir}
+Change the working directory of the new process to @var{dir}.
address@hidden table
+
address@hidden literals}
address@hidden Process literals
+
+A simple @dfn{process literal} is a kind of
address@hidden quasi-literals,named literal} that uses the backtick character
+(@code{`}) as the @stxref{cname}.
+For example:
address@hidden
+&address@hidden address@hidden
address@hidden example
+This is equivalent to:
address@hidden
+(run-process "date --utc")
address@hidden example
+
+In general the following are
+roughly equivalent (using @ref{string quasi-literals}):
address@hidden
+&address@hidden@address@hidden@rbracechar{}
+(run-process @var{args}... &@address@hidden@rbracechar{})
address@hidden example
+The reason for the ``roughly'' is if @var{command} contains
+escaped sub-expressions; in that case @code{&`} may process
+the resulting values differently from plain string-substitution,
+as discussed below.
+
+If you use @code{&sh} instead of @code{&`} then a shell is used:
address@hidden
+&address@hidden address@hidden
address@hidden example
+which is equivalent to:
address@hidden
+&address@hidden/bin/sh -c "rm *.class"@rbracechar{}
address@hidden example
+
+In general, the following are equivalent:
address@hidden
+&address@hidden@address@hidden@rbracechar{}
+&`[shell: #t @address@hidden@address@hidden
address@hidden example
+
address@hidden Process values and process output
+
+The value returned from a call to @code{run-process} or a process literal
+is an instance of @code{gnu.kawa.functions.LProcess}.
+This class extends @code{java.lang.Process}, so you can treat it as
+any other @code{Process} object.
address@hidden
+#|kawa:1|# (define p1 &address@hidden address@hidden)
+#|kawa:2|# (p1:toString)
+gnu.kawa.functions.LProcess@@377dca04
+#|kawa:3|# (write p1)
+gnu.kawa.functions.LProcess@@377dca04
address@hidden example
+
+What makes an @code{LProcess} interesting is that it is also
+a @ref{Blobs,blob}, which is automatically
+converted to a string (or bytevector) in a context that requires it.
+The contents of the blob comes from the standard output of the process.
+The blob is evaluated @ref{Lazy evaluation,lazily},
+so data it is only collected when requested.
+
address@hidden
+#|kawa:4|# (define s1 ::string p1)
+#|kawa:5|# (write s1)
+"Wed Jan 1 01:18:21 UTC 2014\n"
+#|kawa:6|# (define b1 ::bytevector p1)
+(write b1)
+#u8(87 101 100 32 74 97 110 ... 52 10)
address@hidden example
+
+The @code{display} procedure prints it in ``human'' form, as a string:
address@hidden
+#|kawa:7|# (display p1)
+Wed Jan 1 01:18:21 UTC 2014
address@hidden example
+This is also the default REPL formatting:
address@hidden
+#|kawa:8|# &address@hidden address@hidden
+Wed Jan 1 01:18:22 UTC 2014
address@hidden example
+
+When you type a command to a shell, its output goes to the console,
+Similarly, in a REPL the output from the process
+is copied to the console output - which can sometimes by optimized
+by letting the process inherit its standard output from the Kawa process.
+
address@hidden Substitution and tokenization
+
+To substitute the variable or the result of an expression
+in the command line use the usual syntax for quasi literals:
address@hidden
+(define filename (make-temporary-file))
+&address@hidden >&address@hidden
address@hidden example
+
+Since a process is convertible a string, we need no special
+syntax for command substitution:
address@hidden
address@hidden The directory is: &[&address@hidden@address@hidden
address@hidden example
+or equivalently:
address@hidden
address@hidden The directory is: &address@hidden@address@hidden
address@hidden example
+
address@hidden
+Things get more interesting when considering the interaction between
+substitution and tokenization. This is not simple string
+interpolation. For example, if an interpolated value contains a quote
+character, we want to treat it as a literal quote, rather than a token
+delimiter. This matches the behavior of traditional shells. There are
+multiple cases, depending on whether the interpolation result is a
+string or a vector/list, and depending on whether the interpolation is
+inside quotes.
+
address@hidden
address@hidden
+If the value is a string, and we're not inside quotes, then all
+non-whitespace characters (including quotes) are literal, but
+whitespace still separates tokens:
address@hidden
+(define v1 "a b'c ")
+&address@hidden x y&address@hidden @result{} (run-process ["cmd" "x" "ya"
"b'c" "z"])
address@hidden example
address@hidden
+If the value is a string, and we are inside single quotes,
+all characters (including whitespace) are literal.
address@hidden
+&address@hidden 'x y&[v1]z'@rbracechar{} @result{} (run-process ["cmd" "x
ya b'c z"])
address@hidden example
+Double quotes work the same except that newline is an argument
+separator. This is useful when you have one filename per line, and the
+filenames may contain spaces, as in the output from @code{find}:
address@hidden
+&address@hidden -l "&address@hidden . -name '*.pdf'@rbracechar{}"@rbracechar{}
address@hidden example
+This solves a problem that is quite painful with traditional shells.
address@hidden
+If the value is a vector or list (of strings), and we're not inside
+quotes, then each element of the array becomes its own argument, as-is:
address@hidden
+(define v2 ["a b" "c\"d"])
+&address@hidden &address@hidden @result{} (run-process ["cmd" "a b" "c\"d"])
address@hidden example
+However, if the enclosed expression is adjacent to non-space non-quote
+characters, those are prepended to the first element, or appended to
+the last element, respectively.
address@hidden
+&address@hidden x&address@hidden @result{} (run-process ["cmd" "xa b"
"c\"dy"])
+&address@hidden x&address@hidden @result{} (run-process ["cmd" "xy"])
address@hidden example
+This behavior is similar to how shells handle @code{"$@@"}
+(or @code{"address@hidden@@address@hidden"} for general arrays), though in
Kawa you would
+leave off the quotes.
+
+Note the equivalence:
address@hidden
+&address@hidden&address@hidden @result{} (run-process array)
address@hidden example
address@hidden
+If the value is a vector or list (of strings), and we @emph{are}
+inside quotes, it is equivalent to interpolating a single string
+resulting from concatenating the elements separated by a space:
address@hidden
+&address@hidden "&[v2]"@rbracechar{}
+ @result{} (run-process ["cmd" "a b c\"d"])
address@hidden example
+This behavior is similar to how shells handle @code{"$*"} (or
address@hidden"address@hidden@rbracechar{}"} for general arrays).
address@hidden
+If the value is the result of a call to @code{unescaped-data} then it
+is parsed as if it were literal. For example a quote in the unescaped
+data may match a quote in the literal:
address@hidden
+(define vu (unescaped-data "b ' c d '"))
+&address@hidden 'a &[vu]z'@rbracechar{} @result{} (run-process ["cmd" "a b
" "c" "d" "z"])
address@hidden example
address@hidden
+If we're using a shell to tokenize the command, then we add quotes or
+backslashes as needed so that the shell will tokenize as described
+above:
address@hidden
+(define authors ["O'Conner" "de Beauvoir"])
+&address@hidden &address@hidden
address@hidden example
+The command passed to the shell is:
address@hidden
+list-books 'O'\''Conner' 'de Beauvoir
address@hidden example
+Having quoting be handled by the @code{$construct$:sh}
+implementation automatically eliminates common code injection problems.
address@hidden itemize
+
+Smart tokenization only happens when using the quasi-literal forms such
+as @code{&address@hidden@rbracechar{}}.
+You can of course use string templates with @code{run-process}:
address@hidden
+(run-process &@lbracechar{}echo The directory is:
&address@hidden@address@hidden)
address@hidden example
+However, in that case there is no smart tokenization: The template is
+evaluated to a string, and then the resulting string is tokenized,
+with no knowledge of where expressions were substituted.
+
address@hidden Input/output redirection
+
+You can use various keyword arguments to specify standard input, output,
+and error streams. For example to lower-case the text in @code{in.txt},
+writing the result to @code{out.txt}, you can do:
address@hidden
+&`[in-from: "in.txt" out-to: "out.txt"address@hidden A-Z address@hidden
address@hidden example
+or:
address@hidden
+(run-process in-from: "in.txt" out-to: "out.txt" "tr A-Z a-z")
address@hidden example
+
address@hidden
+A @var{process-redirect-argument} can be one of the following:
+
address@hidden @asis
address@hidden @stxlit{in:} @var{value}
+The @var{value} is evaluated, converted to a string (as if
+using @code{display}), and copied to the input file of the process.
+The following are equivalent:
address@hidden
+&`[in: "text\n"address@hidden@rbracechar{}
+&`[in: &address@hidden "text"@address@hidden@rbracechar{}
address@hidden example
+You can pipe the output from @code{command1} to the input
+of @code{command2} as follows:
address@hidden
+&`[in: &address@hidden@address@hidden@rbracechar{}
address@hidden example
address@hidden @stxlit{in-from:} @var{path}
+The process reads its input from the specified @var{path}, which
+can be any value coercible to a @code{filepath}.
address@hidden @stxlit{out-to:} @var{path}
+ The process writes its output to the specified @var{path}.
address@hidden @stxlit{err-to:} @var{path}
+ Similarly for the error stream.
address@hidden @stxlit{out-append-to:} @var{path}
address@hidden @stxlit{err-append-to:} @var{path}
+ Similar to @code{out-to} and @code{err-to}, but append to the file
+ specified by @var{path}, instead of replacing it.
address@hidden @stxlit{in-from: 'pipe}
address@hidden @stxlit{out-to: 'pipe}
address@hidden @stxlit{err-to: 'pipe}
+Does not set up redirection. Instead, the specified stream is available
+using the methods @code{getOutputStream}, @code{getInputStream},
+or @code{getErrorStream}, respectively, on the resulting @code{Process} object,
+just like Java's @code{ProcessBuilder.Redirect.PIPE}.
address@hidden @stxlit{in-from: 'inherit}
address@hidden @stxlit{out-to: 'inherit}
address@hidden @stxlit{err-to: 'inherit}
+Inherits the standard input, output, or error stream from the
+current JVM process.
address@hidden @stxlit{out-to:} @var{port}
address@hidden @stxlit{err-to:} @var{port}
+Redirects the standard output or error of the process to
+the specified @var{port}.
address@hidden @stxlit{out-to: 'current}
address@hidden @stxlit{err-to: 'current}
+Same as @code{out-to: (current-output-port)},
+or @code{err-to: (current-error-port)}, respectively.
address@hidden @stxlit{in-from:} @var{port}
address@hidden @stxlit{in-from: 'current}
+Re-directs standard input to read from the @var{port}
+(or @code{(current-input-port)}). It is unspecified how much is read from
+the @var{port}. (The implementation is to use a thread that reads from the
+port, and sends it to the process, so it might read to the end of the port,
+even if the process doesn't read it all.)
address@hidden @stxlit{err-to: 'out}
+Redirect the standard error of the process to be merged with the
+standard output.
address@hidden table
+
+The default for the error stream (if neither @code{err-to} or
address@hidden is specified) is equivalent to @code{err-to: 'current}.
+
address@hidden:} Writing to a port is implemented by copying the output or error
+stream of the process. This is done in a thread, which means we don't have
+any guarantees when the copying is finished. (In the future we might
+change @code{process-exit-wait} (discussed later) wait for not only the
+process to finish, but also for these helper threads to finish.)
+
+A @uref{https://en.wikipedia.org/wiki/Here_document,here document} is
+a form a literal string, typically multi-line, and commonly used in
+shells for the standard input of a process. You can use string literals or
address@hidden quasi-literals} for this.
+For example, this passes the string @code{"line1\nline2\nline3\n"} to
+the standard input of @code{command}:
address@hidden
+(run-process [in: &@lbracechar{}
+ &|line1
+ &|line2
+ &|line3
+ @rbracechar{}] "command")
address@hidden example
+
+Note the use of @code{&|} to mark the end of ignored indentation.
+
address@hidden Pipe-lines
+
+Piping the output of one process as the input of another
+is in princple easy - just use the @code{in:}
+process argument. However, writing a multi-stage pipe-line quickly gets ugly:
address@hidden
+&`[in: &`[in: "My text\n"address@hidden a-z address@hidden@address@hidden
address@hidden example
+The convenience macro @code{pipe-process} makes this much nicer:
address@hidden
+(pipe-process
+ "My text\n"
+ &address@hidden a-z address@hidden
+ &address@hidden@rbracechar{})
address@hidden example
+
address@hidden Syntax pipe-process input @arbno{process}
+All of the @var{process} expressions must be @code{run-process} forms,
+or equivalent @code{&address@hidden@rbracechar{}} forms.
+The result of evaluating @var{input} becomes the input to the first
address@hidden; the output from the first @var{process} becomes
+the input to the second @var{process}, and so on. The result of
+whole @code{pipe-process} expression is that of the last @var{process}.
+
+Copying the output of one process to the input of the next is
+optimized: it uses a copying loop in a separate thread. Thus you can
+safely pipe long-running processes that produce huge output. This
+isn't quite as efficient as using an operating system pipe, but is
+portable and works pretty well.
address@hidden deffn
+
address@hidden Setting the process environment
+
address@hidden
+By default the new process inherits the system environment of the current
+(JVM) process as returned by @code{System.getenv()}, but you can override it.
+A @var{process-environment-argument} can be one of the following:
+
address@hidden @asis
address@hidden @address@hidden@stxlit{:} @var{value}
+In the process environment, set the @code{"@var{name}"} to the
+specified @var{value}. For example:
address@hidden
+&`[env-CLASSPATH: ".:classes"address@hidden address@hidden
address@hidden example
address@hidden @address@hidden:} @var{value}
+Same as using the @address@hidden option above, but only if the
address@hidden@var{NAME}} is uppercase (i.e. if uppercasing @address@hidden
yields
+the same string). For example the previous example could be written:
address@hidden
+&`[CLASSPATH: ".:classes"address@hidden address@hidden
address@hidden example
address@hidden @stxlit{environment:} @var{env}
+The @var{env} is evaluated and must yield a @code{HashMap}.
+This map is used as the system environment of the process.
address@hidden table
+
address@hidden Waiting for process exit
+
+When a process finishes, it returns an integer exit code.
+The code is traditionally 0 on successful completion,
+while a non-zero code indicates some kind of failure or error.
+
address@hidden Procedure process-exit-wait process
+The @var{process} expression must evaluate to a process
+(any @code{java.lang.Process} object).
+This procedure waits for the process to finish, and then returns the
+exit code as an @code{int}.
address@hidden
+(process-exit-wait (run-process "echo foo")) @result{} 0
address@hidden example
address@hidden deffn
+
address@hidden Procedure process-exit-ok? process
+Calls @code{process-exit-wait}, and then returns @code{#false}
+if the process exited it 0, and returns @code{#true} otherwise.
+
+This is useful for emulating the way traditional shell do
+logic control flow operations based on the exit code.
+For example in @code{sh} you might write:
address@hidden
+if grep Version Makefile >/dev/null
+then echo found Version
+else echo no Version
+fi
address@hidden example
+
+The equivalent in Kawa:
+
address@hidden
+(if (process-exit-ok? &address@hidden Version address@hidden)
+ &address@hidden address@hidden
+ &address@hidden not address@hidden)
address@hidden example
+
+Strictly speaking these are not quite the same, since the Kawa
+version silently throws away the output from @code{grep}
+(because no-one has asked for it). To match the output from the @code{sh},
+you can use @code{out-to: 'inherit}:
address@hidden
+(if (process-exit-ok? &`[out-to: 'address@hidden Version address@hidden)
+ &address@hidden address@hidden
+ &address@hidden not address@hidden)
address@hidden example
address@hidden deffn
+
address@hidden the current process}
address@hidden Exiting the current process
+
address@hidden Procedure exit [code]
+Exits the Kawa interpreter, and ends the Java session.
+Returns the value of @var{code} to the operating system:
+The @var{code} must be integer, or the special
+values @code{#f} (equivalent to -1), or
address@hidden (equivalent to 0).
+If @var{code} is not specified, zero is returned.
+The @var{code} is a status code; by convention a non-zero
+value indicates a non-standard (error) return.
+
+Before exiting, finally-handlers (as in @code{try-finally},
+or the @var{after} procedure of @code{dynamic-wind}) are
+executed, but only in the current thread, and only if
+the current thread was started normally. (Specifically
+if we're inside an @code{ExitCalled} block with non-zero
+nesting - see @code{gnu.kawa.util.ExitCalled}.)
+Also, JVM shutdown hooks are executed - which includes
+flushing buffers of output ports. (Specifically
address@hidden objects registered with the @code{WriterManager}.)
address@hidden deffn
+
address@hidden Procedure emergency-exit [code]
+Exits the Kawa interpreter, and ends the Java session.
+Communicates an exit value in the same manner as @code{exit}.
+Unlike @code{exit}, neither finally-handlers nor
+shutdown hooks are executed.
address@hidden deffn
+
address@hidden Deprecated functions
+
address@hidden Procedure make-process command envp
+Creates a @code{<java.lang.Process>} object, using the specified
address@hidden and @var{envp}.
+The @var{command} is converted to an array of Java strings
+(that is an object that has type @code{<java.lang.String[]>}.
+It can be a Scheme vector or list (whose elements should be
+Java strings or Scheme strings); a Java array of Java strings;
+or a Scheme string. In the latter case, the command is converted
+using @code{command-parse}.
+The @var{envp} is process environment; it should be either
+a Java array of Java strings, or the special @code{#!null} value.
+
+Except for the representation of @var{envp}, this is similar to:
address@hidden
+(run-process environment: @var{envp} @var{command})
address@hidden example
address@hidden deffn
+
address@hidden Procedure system command
+Runs the specified @var{command}, and waits for it to finish.
+Returns the return code from the command. The return code is an integer,
+where 0 conventionally means successful completion.
+The @var{command} can be any of the types handled by @code{make-process}.
+
+Equivalent to:
address@hidden
+(process-exit-wait (make-process @var{command} #!null))
address@hidden example
address@hidden deffn
+
address@hidden command-parse
+The value of this variable should be a one-argument procedure.
+It is used to convert a command from a Scheme string to a Java
+array of the constituent "words".
+The default binding, on Unix-like systems, returns a new command to
+invoke @code{"/bin/sh" "-c"} concatenated with the command string;
+on non-Unix-systems, it is bound to @code{tokenize-string-to-string-array}.
address@hidden defvar
+
address@hidden Procedure tokenize-string-to-string-array command
+Uses a @code{java.util.StringTokenizer} to parse the @var{command} string
+into an array of words. This splits the @var{command} using spaces
+to delimit words; there is no special processing for quotes or other
+special characters.
+(This is the same as what @code{java.lang.Runtime.exec(String)} does.)
address@hidden deffn
+
address@hidden Time-related functions
address@hidden Time-related functions
+
address@hidden Procedure current-second
+Returns an inexact number represent the current time on the
address@hidden://en.wikipedia.org/wiki/International_Atomic_Time,International
Atomic Time (TAI)} scale.
+The value 0.0 represents midnight on January 1, 1070 TAI (equivalent
+to 10 seconds before midnight Universal Time), and
+the value 1.0 represents on TAI second later.
+Neither high acuracy nor high precision are required; in particular
+returning Coordinated Universal Time plus a suitable
+constant might be the best an implementation cat do.
+The Kawa implementation just multiplies by 0.001 the result of calling
+the method @code{currentTimeMillis} in class @code{java.lang.System}.
address@hidden deffn
+
address@hidden Procedure current-jiffy
+Returns the number of @dfn{jiffies} as an exact integer that have
+elapses since an arbitrary implementation-defined epoch (instant).
+A jiffy is an implementation-defined fraction of a second which is
+defined by the return value of the @code{jiffies-per-second} procedure.
+The starting epoch (instant 0) is guaranteed to be constant during
+a run of the program, but may vary between runs.
+(At the time of writing, Kawa's jiffy is one nano-second.)
+
address@hidden:} Jiffies are allowed to be implementation-dependent
+so that @code{current-jiffy} can execute with minimal overhead.
+It should be very likely that a compactly represented integer will
+suffice as the return value. Any particular jiffy size will be
+inappropriate some some implementations: a microsecond is too long for
+a very fast machine, while a much smaller unit would force many
+implementations to return integers which have to allocated for most calls,
+rendering @code{current-jiffy} less useful for accurate timing measurements.
address@hidden deffn
+
address@hidden Procedure jiffies-per-second
+Returns an exact integer representing the number of jiffies
+per SI second. This value is an implementation-specified
+constant.
+(At the time of writing, the value in Kawa is 1,000,000,000.)
address@hidden deffn
+
address@hidden Procedure sleep time
+Suspends the current thread for the specified time.
+The @var{time} can be either a pure number (in secords),
+or a quantity whose unit is a time unit (such as @code{10s}).
address@hidden deffn
+
address@hidden Low-level functions
address@hidden Deprecated low-level functions
+
+These sections document older and less convenient ways
+to call Java methods, access Java fields, and use Java arrays.
+
address@hidden Method invocation}
address@hidden Low-level Method invocation
+The following lower-level primitives require you to specify
+the parameter and return types explicitly.
+You should probably use the functions @code{invoke} and @code{invoke-static}
+(@pxref{Method operations}) instead.
+
address@hidden Syntax primitive-constructor class (argtype ...)
+Returns a new anonymous procedure, which when called will create
+a new object of the specified class, and will then call the
+constructor matching the specified argument types.
address@hidden deffn
+
address@hidden Syntax primitive-virtual-method class method rtype (argtype ...)
+Returns a new anonymous procedure, which when called will
+invoke the instance method whose name is the string @var{method}
+in the class whose name is @var{class}.
address@hidden deffn
+
address@hidden Syntax primitive-static-method class method rtype (argtype ...)
+Returns a new anonymous procedure, which when called will
+invoke the static method whose name is the string @var{method}
+in the class whose name is @var{class}.
address@hidden deffn
+
address@hidden Syntax primitive-interface-method interface method rtype
(argtype ...)
+Returns a new anonymous procedure, which when called will
+invoke the matching method from the interface whose name is @var{interface}.
address@hidden deffn
+
+The macros return procedure values, just like @code{lambda}.
+If the macros are used directly as the procedure of a procedure call,
+then kawa can inline the correct bytecodes to call the specified methods.
+(Note also that neither macro
+checks that there really is a method that matches the specification.)
+Otherwise, the Java reflection facility is used.
+
address@hidden Low-level field operations
+
+The following macros evaluate to procedures that can be used to
+access or change the fields of objects or static fields.
+The compiler can inline each to a single bytecode instruction
+(not counting type conversion).
+
+These macros are deprecated.
+The @code{fields} and @code{static-field} functions
+(@pxref{Field operations}) are easier to use, more powerful, and
+just as efficient. However, the high-level functions currently do
+not provide access to non-public fields.
+
address@hidden Syntax primitive-get-field class fname ftype
+Use this to access a field named @var{fname} having type @var{type} in
+class @var{class}. Evaluates to a new one-argument procedure,
+whose argument is a reference to an object of the specified @var{class}.
+Calling that procedure returns the value of the specified field.
address@hidden deffn
+
address@hidden Syntax primitive-set-field class fname ftype
+Use this to change a field named @var{fname} having type @var{type} in
+class @var{class}. Evaluates to a new two-argument procedure,
+whose first argument is a reference to an object of the
+specified @var{class}, and the second argument is the new value.
+Calling that procedure sets the field to the specified value.
+(This macro's name does not end in a @samp{!}, because it does not actually
+set the field. Rather, it returns a function for setting the field.)
address@hidden deffn
+
address@hidden Syntax primitive-get-static class fname ftype
+Like @code{primitive-get-field}, but used to access static fields.
+Returns a zero-argument function, which when called returns
+the value of the static field.
address@hidden deffn
+
address@hidden Syntax primitive-set-static class fname ftype
+Like @code{primitive-set-field}, but used to modify static fields.
+Returns a one-argument function, which when called sets the
+value of the static field to the argument.
address@hidden deffn
+
address@hidden array macros}
address@hidden Old low-level array macros
+
+The following macros evaluate to procedures that can be used to
+manipulate primitive Java array objects.
+The compiler can inline each to a single bytecode instruction
+(not counting type conversion).
+
address@hidden Syntax primitive-array-new element-type
+Evaluates to a one-argument procedure. Applying the resulting procedure to
+an integer count allocates a new Java array of the specified length,
+and whose elements have type @var{element-type}.
address@hidden deffn
+
address@hidden Syntax primitive-array-set element-type
+Evaluates to a three-argument procedure. The first argument of
+the resulting procedure must be an array whose elements have type
address@hidden; the second argument is an index; and the third
+argument is a value (coercible to @var{element-type}) which replaces
+the value specified by the index in the given array.
address@hidden deffn
+
address@hidden Syntax primitive-array-get element-type
+Evaluates to a two-argument procedure. The first argument of
+the resulting procedure must be an array whose elements have type
address@hidden; the second argument is an index.
+Applying the procedure returns the element at the specified index.
address@hidden deffn
+
address@hidden Syntax primitive-array-length element-type
+Evaluates to a one-argument procedure. The argument of
+the resulting procedure must be an array whose elements have type
address@hidden
+Applying the procedure returns the length of the array.
+(Alternatively, you can use @code{(field @var{array} 'length)}.)
address@hidden deffn
+
address@hidden FAQs
address@hidden Frequently Asked Questions
+
address@hidden
address@hidden What is the difference between load, require, import, and
include?
+
+Handling @code{include} is all done at compile time. It's as if the text
+of the included file is copied and replaces the include command.
+If the include is inside a @code{let}, the included text can
+use the name defined in the @code{let}.
+
+In contrast @code{load} is a procedure, not syntax.
+It reads and evaluates each line in the file, one at a time,
address@hidden ignore
+
address@hidden
address@hidden What is the equivalent of Java import?
+
+To provide a short name for a class instead of the complete fully-qualified
+name use either @code{define-alias} (or @code{define-private-alias})
+or the @address@hidden combination.
+For example, to be able to write @code{ArrayList} instead
+of @code{java.util.ArrayList} do either:
address@hidden
+(import (class java.util ArrayList))
address@hidden example
+or
address@hidden
+(define-alias ArrayList java.util.ArrayList)
address@hidden example
+Using @code{import} is recommended:
+It handles errors better,
+and it allows you to define multiple aliases conveniently:
address@hidden
+(import (class java.util Map HashMap))
address@hidden example
+
+Both forms allow renaming. For example if you want to refer
+to @code{java.lang.StringBuilder} as @code{StrBuf} do:
address@hidden
+(import (class java.lang (StringBuilder StrBuf)))
address@hidden example
+or:
address@hidden
+(define-alias StrBuf java.lang.StringBuilder)
address@hidden example
+
+The name(s) defined by @code{import} are by default private.
+A name defined using @code{define-alias} is by default exported;
+to avoid that use @code{define-private-alias} instead.
+
+You can also use @code{define-namespace} to introduce an abbreviation or
+renaming of a class name, but as a matter of style @code{define-alias}
+is preferred.
+
+There is no direct equivalent to Java's @code{import PackageOrTypeName.*}
+(type-import-on-demand) declaration, but you can alias a package:
address@hidden
+(define-alias jutil java.util)
+(define mylist :: jutil:List (jutil:ArrayList))
address@hidden example
+
+To import a static member, giving it a shortened name
+(like Java's static-import-on-demand declaration), you can use
address@hidden For example:
address@hidden
+(define-alias console java.lang.System:console)
address@hidden example
+
+For static fields only (not methods or member classes) you can
+use an @code{import} form, either:
address@hidden
+(import (only (java lang System) out))
address@hidden example
+or:
address@hidden
+(import (only java.lang.System out))
address@hidden example
+This works because Kawa can treat any class as a ``library'';
+in which case it considers all public static fields as exported bindings.
+
address@hidden How do I refer to a Java member (nested) class?
+
+Consider the Java SE member class
@code{javax.swing.text.AbstractDocument.Content}.
+Using the Java syntax doesn't work in Kawa.
+Inside you should use Kawa's colon operator:
address@hidden
+javax.swing.text.AbstractDocument:Content
address@hidden example
+Alternatively, you can use the internal JVM class name:
address@hidden
+javax.swing.text.AbstractDocument$Content
address@hidden example
+
address@hidden Why does Kawa's REPL use display rather than write?
+
+The read-eval-print-loop of most Scheme implementations prints the
+evaluation result using @code{write}, while Kawa uses @code{display} by
default.
+
+First note that it is easy to override the default with the
address@hidden command-line option:
address@hidden
+$kawa --output-format readable-scheme
+#|kawa:1|# "abc"
+"abc"
address@hidden example
+
+The reason @code{display} is the default is because of a vision of the REPL
+console as more than just printing out Scheme objects in
+textual form for use by a programmer.
+Some examples:
address@hidden
address@hidden
+A math program can display equations and graphs as the
+output of an expression.
address@hidden
+An expression can evaluate to a "picture" which would
+be @uref{http://per.bothner.com/blog/2007/ReplPane/,displayed inline}.
address@hidden
+An HTML/XML obj can be insert into the output in visual
+form if the console understands HTML. (There is a prototype
+for this that works by using the JavaFX WebView as the display.)
address@hidden
+The plan for "Kawa-shell" functionality is to have expressions
+that evaluate to process objects, which would be lazy strings.
+This string would be the data from standard output. Thus the
+effect of displaying a process object would be to print out
+the standard output - just like a regular shell. Users would
+find it confusing/annoying if shell output used quotes.
address@hidden itemize
+
+This "repl-as-pad" model doesn't work as well if the repl
+uses @code{write} rather than @code{display}.
+
address@hidden Framework
address@hidden The Kawa language framework
+
+Kawa is a framework written in Java for implementing
+high-level and dynamic languages, compiling them into Java bytecodes.
+
+The Kawa distributions includes of other programming languages
+besides Scheme,
+including @uref{../qexo/index.html, XQuery (Qexo)}
+and @uref{http://JEmacs.sourceforge.net/,Emacs Lisp (JEmacs)}.
+
+For a technical overview of Kawa, see these
address@hidden://www.gnu.org/software/kawa/internals/index.html}.
+Javadoc generated @uref{http://www.gnu.org/software/kawa/api/,documentation of
the Kawa classes} is also available.
+The packages
address@hidden://www.gnu.org/software/kawa/api/gnu/bytecode/package-summary.html,@code{gnu.bytecode}},
address@hidden://www.gnu.org/software/kawa/api/gnu/math/package-summary.html,@code{gnu.math}},
address@hidden://www.gnu.org/software/kawa/api/gnu/lists/package-summary.html,@code{gnu.lists}},
address@hidden://www.gnu.org/software/kawa/api/gnu/xml/package-summary.html,@code{gnu.xml}},
address@hidden://www.gnu.org/software/kawa/api/gnu/expr/package-summary.html,@code{gnu.expr}},
address@hidden://www.gnu.org/software/kawa/api/gnu/mapping/package-summary.html,@code{gnu.mapping}},
+and
address@hidden://www.gnu.org/software/kawa/api/gnu/text/package-summary.html,@code{gnu.text}},
+are used by Kawa, and distributed with it, but may be independently useful.
+
+This @uref{gnu.bytecode/compiling-regexps.html,article} explains how to
+use @code{gnu.bytecode} to compile regular expressions to bytecode.
+
address@hidden License
address@hidden License
+
address@hidden
+* Software-License:: License for the Kawa software
+* Manual-License:: License for the Kawa manual
address@hidden menu
+
address@hidden Software-License, Manual-License, , License
address@hidden License for the Kawa software
+
+The license for the Kawa software
+(except the optional JEmacs and BRL features - see below) is the
address@hidden://opensource.org/licenses/mit-license.php, X11/MIT license}
+which is quoted below.
+
address@hidden
+The software (with related files and documentation) in these packages
+are copyright (C) 1996-2009 Per Bothner.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
address@hidden example
+
+In the past the Kawa license was a ``modified GNU GPL (General
+Public License)".
+If you find any files that contain the old license or otherwise seem
+to contradict the new license, please report that as a bug.
+
+Some of the JEmacs files are based on Emacs and have a GPL license,
+which is incompatible with non-Free (proprietary) products. For that
+reason, the @code{gnu.jemacs.*} packages are not included any more in
+the standard @code{.jar}, or by default when building from source, to
+avoid surprises.
+To build JEmacs you have to specify the @code{configure}
+flag @code{--enable-jemacs} or the @code{ant} flag
address@hidden
+
+Some code in @code{gnu/brl} and @code{gnu/kawa/brl} is copyright
+Bruce R. Lewis and Eaton Vance Management,
+with a modified-GPL license: no restrictions if used
+unmodified, but otherwise the GPL applies.
+These packages are no longer included by default in Kawa builds,
+but have to be selected with the @code{configure}
+flag @code{--enable-brl} or the @code{ant} flag @code{-Denable-brl=true}.
+
+Kawa uses some math routines from fdlib's libf77,
+which have a AT&T Bell Laboratories and Bellcore copyright.
+See the source file @code{gnu/math/DComplex.java}.
+
+The sorting routine in @code{gnu.xquery.util.OrderedTuples}
+is a re-implementatiomn in Java of code copyrighted by
+Simon Tatham.
+
+Some of the Scheme code in @code{kawa/lib} and @code{gnu/kawa/slib}
+are copyright other parties, and may have slightly different
+license wording, but I believe none of then contradicts the
+main Kawa license or impose extra restrictions.
+Search for the word @code{copyright} in these directories.
+
+Some code has been converted from other languages, with permission.
+This includes the @code{rationalize} method
+in @code{gnu/math/RatNum.java}, based on an algorithm of Alan Bawden,
+as expressed by Marc Feeley in C-Gambit.
+The concepts and algorithm of @code{gnu/text/PrettyWriter.java}
+are converted from SBCL, which is in the public domain.
+
address@hidden Manual-License, , Software-License, License
address@hidden License for the Kawa manual
+
+Here is the copyright license for this manual:
+
+Copyright @copyright{} 1996, 1997, 1998, 1999, 2005 Per Bothner
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the author.
+
+Parts of this manual are copied from the @uref{http://www.r6rs.org/,R6RS}
+or @uref{http://www.r7rs.org/,R7RS}, which both state:
address@hidden
+We intend this report to belong to the entire Scheme community, and so
+we grant permission to copy it in whole or in part without fee. In
+particular, we encourage implementors of Scheme to use this report as
+a starting point for manuals and other documentation, modifying it as
+necessary.
address@hidden quotation
+
+Parts of this manual were derived from the SLIB manual,
+copyright @copyright{} 1993-1998 Todd R. Eigenschink and Aubrey Jaffer.
+
+Parts of this manual were derived from ISO/EIC 10179:1996(E)
+(Document Style and Specifical Language) - unknown copyright.
+
+This manual has quoted from SRFI-6 (Basic String Ports),
+which is Copyright (C) William D Clinger (1999). All Rights Reserved.
+
+This manual has quoted from SRFI-8 (receive: Binding to multiple values),
+which is Copyright (C) John David Stone (1999). All Rights Reserved.
+
+This manual has quoted from SRFI-9 (Defining Record Types)
+which is Copyright (C) Richard Kelsey (1999). All Rights Reserved.
+
+This manual has quoted from SRFI-11 (Syntax for receiving multiple values),
+which is Copyright (C) Lars T. Hansen (1999). All Rights Reserved.
+
+This manual has quoted from SRFI-25 (Multi-dimensional Array Primitives),
+which is Copyright (C) Jussi Piitulainen (2001). All Rights Reserved.
+
+This manual has quoted from SRFI-26 (Notation for Specializing
+Parameters without Currying),
+which is Copyright (C) Sebastian Egner (2002). All Rights Reserved.
+
+This manual has quoted from SRFI-39 (Parameter objects),
+which is Copyright (C) Marc Feeley (2002). All Rights Reserved.
+
+The following notice applies to SRFI-6, SRFI-8, SRFI-9, SRFI-11, SRFI-25,
+SRFI-26, and SRFI-39,
+which are quoted in this manual, but it does not apply to the manual as a
whole:
+
address@hidden
+This document and translations of it may be copied and furnished to
+others, and derivative works that comment on or otherwise explain it or
+assist in its implementation may be prepared, copied, published and
+distributed, in whole or in part, without restriction of any kind,
+provided that the above copyright notice and this paragraph are included
+on all such copies and derivative works. However, this document itself
+may not be modified in any way, such as by removing the copyright notice
+or references to the Scheme Request For Implementation process or
+editors, except as needed for the purpose of developing SRFIs in which
+case the procedures for copyrights defined in the SRFI process must be
+followed, or as required to translate it into languages other than
+English.
+
+The limited permissions granted above are perpetual and will not be
+revoked by the authors or their successors or assigns.
+
+This document and the information contained herein is provided on an
+"AS IS" basis and THE AUTHOR AND THE SRFI EDITORS DISCLAIM ALL
+WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
+WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY
+RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
+PARTICULAR PURPOSE.
address@hidden quotation
+
+This manual has quoted from SRFI-69 (Basic hash tables),
+which is Copyright (C) Panu Kalliokoski (2005). All Rights Reserved.
+
+The following notice applies to SRFI-69,
+which is quoted in this manual, but it does not apply to the manual as a whole:
+
address@hidden
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+Software), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
address@hidden quotation
+
+This manual has made use of text and examples from Dorai Sitaram's
address@hidden implementation. But not where the latter talks about
address@hidden functions; the manual also talks about
+the @code{regex-xxx} functions (which are similar but use a
+slightly different regular expression syntax).
+The @code{pregexp} distribution has the following @code{COPYING} file:
address@hidden
+Copyright (c) 1999-2005, Dorai Sitaram.
+All rights reserved.
+
+Permission to copy, modify, distribute, and use this work or
+a modified copy of this work, for any purpose, is hereby
+granted, provided that the copy includes this copyright
+notice, and in the case of a modified copy, also includes a
+notice of modification. This work is provided as is, with
+no warranty of any kind.
address@hidden quotation
+
address@hidden I'd prefer to call this node plain "Index", but that causes a
clash
address@hidden with index.html when generating HTML on case-insenstive file
systems.
address@hidden Overall Index, , License, Top
address@hidden Index
address@hidden cp
+
address@hidden
Added: trunk/js/examples/kawa/news.texi
===================================================================
--- trunk/js/examples/kawa/news.texi (rev 0)
+++ trunk/js/examples/kawa/news.texi 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,3049 @@
+These changes are in more-or-less reverse chronological order, with the
+most recent changes first.
+
+See also the list of @uref{../qexo/news.html,Qexo (XQuery)-specific
+changes}.
+
address@hidden In Git repository (invoke branch) since last release
address@hidden
address@hidden
+Binary release are now built for Java 8.
+The repository source code is now set up for Java 8.
+(Biulding fro Java 6 or 7 is still supported.
+Java 5 might also work, but not not been tested recently.)
address@hidden
+Most places where you could declare a new identifier
+binding have been generalized to accept @ref{Variables and Patterns,patterns},
+including literals and boolean @stxref{guard}s.
address@hidden
+The new form @ref{def-match,@code{match}} form is a generalization
+of @code{case} using patterns.
address@hidden
+The internal calling convention used for ``apply'' (ie. calling
+an unknown-at-compile-time procedure) has been completely changed.
address@hidden
+Major changes to strings:
address@hidden
address@hidden
address@hidden change:} String literals are now
address@hidden rather than @code{java.lang.String}.
+The advantage of using @code{gnu.lists.IString} is that @code{string-ref}
+and @code{string-length} are (roughly) constant-time, rather than
+having to linearly scan the string.
address@hidden
address@hidden change:}
+The procedures @code{string-append}, @code{string-map},
address@hidden, @code{list->string}, @code{vector->string},
address@hidden, @code{string-upcase}, @code{string-foldcase},
address@hidden, and the constructor @code{string}
+return an immutable string (an @code{IString}).
+(The function @code{string-copy} is similar to @code{substring},
+but returns a mutable string.)
+This is a work-in-progress with the goal of implementing
address@hidden://srfi.schemers.org/srfi-140/srfi-140.html,SRFI-140}:
+Other procedures will be changed to return immutable strings.
+
+If you @code{(import (scheme base))} standard procedures
+such as @code{string-append} will return mutable strings;
+if you @code{(import (kawa base))} the procedures will return immutable
strings.
+The command-line options @code{--r5rs} or @code{--r6rs} or @code{--r7rs}
+override the default so these procedures return mutable strings.
address@hidden
address@hidden change:}
+Treating a string as a sequence is now simpler but possibly slower:
+The @var{I}'th element is now the @var{I}'th Unicode code point.
+Indexing with function-call syntax
address@hidden(@var{string} @var{i})} is the same as @code{(string-ref
@var{string} @var{i})} and
address@hidden(length @var{string})} is the same as @code{(string-length
@var{string})}.
+This applies to all classes that implement @code{java.lang.CharSequence}.
+Indexing may be a linear-time operation (thus much slower),
+unless the string is an @code{IString} (in which case it is constant-time),
address@hidden
address@hidden change:} Before, if a Java parameter type
+was @code{java.lang.String} Kawa would accept any value, converting it
+using Object's @code{toString} method.
+Now Kawa will reject an argument if it is not a @code{java.lang.CharSequence}.
address@hidden
+New procedures: @code{istring?}, @code{reverse-list->string},
address@hidden, @code{string-concatenate}, @code{string-concatenate-reverse},
address@hidden, @code{string-contains-right},
address@hidden, @code{string-drop}, @code{string-drop-right},
address@hidden, @code{string-filter}, @code{string-fold},
address@hidden, @code{string-for-each-index},
address@hidden, @code{string-index-right}, @code{string-join},
address@hidden, @code{string-null?},
address@hidden, @code{string-prefix-length},
address@hidden, @code{string-remove}, @code{string-replace},
address@hidden, @code{string-skip-right}, @code{string-split},
address@hidden, @code{string-suffix-length},
address@hidden, @code{string-take}, @code{string-take-right},
address@hidden, @code{string-trim-right}, @code{string-trim-both},
address@hidden, @code{string-unfold-right},
address@hidden>utf16}, @code{string->utf16be}, @code{string->utf16le},
address@hidden>string}, @code{utf16be->string}, @code{utf16le->string},
address@hidden
+These follow SRFI-140 and return immutable strings.
+(Some of these had previously been available in SRFI-13,
+but the older versions return mutable strings.)
address@hidden itemize
address@hidden
address@hidden change:} Kawa traditionally followed Java in allowing you
+to pass an array with the ``rest'' arguments to a varargs method.
+For example, you could write:
+
address@hidden
+(define args (Object[] 3 "cm"))
+(java.lang.String:format "length:%s%s" args)
address@hidden verbatim
+
+This is no longer allowed. Instead,
+use the splice operator:
+
address@hidden
+(java.lang.String:format "length:%s%s" @args)
address@hidden verbatim
address@hidden
address@hidden change:} You used to be able to write a
+type-specifier in a formal parameter or return type without
+using @samp{::}, as in:
address@hidden
+(define (incr (x int)) int (+ x 1))
address@hidden example
+This is no longer allowed, because it conflicts with the
+syntax for patterns. Instead you have to write:
address@hidden
+(define (incr (x ::int)) ::int (+ x 1))
address@hidden example
address@hidden
+New type aliases @code{bitvector} and @code{c16vector}.
+The latter is a @ref{Uniform vectors,uniform vector} type for wrapping
@code{char[]} arrays.
address@hidden
+You can convert a Java array (for example a @code{int[]} to the corresponing
uniform vector type
+(for example @code{u32vector}) using the @code{as} pseudo-function or the
corresponding
+conversion procedure (for example @code{->u32vector}). The result shares
storage with the
+array, so changes in one will update the other.
address@hidden
+The expression @code{(module-class)} evaluates to the
+containing module class.
address@hidden
+Change the @ref{Mangling,mangling} for field and local variables names
+to match the
@uref{https://blogs.oracle.com/jrose/entry/symbolic_freedom_in_the_vm,Symbolic
Freedom} style.
address@hidden
+Internally, expressions now record their ending position (line/column),
+in addition to the starting position.
address@hidden itemize
+
address@hidden @subheading In Git repository (master branch) since last release
address@hidden @anchor{#in-git-repository-since-last-release}
+
address@hidden Kawa 2.4 (April 30, 2017)
+
address@hidden
address@hidden
+Final 2.x release.
+Minor updates and fixes.
address@hidden itemize
+
address@hidden Kawa 2.3 (January 13, 2017)
+
address@hidden
address@hidden
+Moved Kawa's source code repository (version control system)
+to use git, hosted at @uref{https://gitlab.com/kashell/Kawa,GitLab}.
address@hidden
+Issues (bugs, feature requests, etc) should now be reported using the
address@hidden://gitlab.com/kashell/Kawa/issues,GitLab Issue Tracker}.
address@hidden
+New @code{with-docbook-stylesheets} to make it easier to build
+the documentation with better functionality and look.
address@hidden
+The command-line option @code{console:jline-mouse=yes}
+enables moving the input cursor using a mouse click,
+when using JLine in the REPL on common xterm-like terminals.
+This is disabled by default because it conflicts with
+other mouse actions, such as making a selection for copying text.
+You can press shift to get the terminal's standard mouse handling.
address@hidden itemize
+
address@hidden Kawa 2.2 (November 12, 2016)
+
address@hidden
address@hidden
+A binary release is no longer just a Kawa @code{.jar} file,
+but is now a @code{zip} archive that also includes
+shell/batch scripts for running Kawa, useful
+third-party libraries, and the complete documentation in EPUB format.
+The archives are named @code{kawa-version.zip}.
address@hidden
+The @code{kawa --browse-manual} switch makes it easy to
address@hidden,browse the local documentation}.
address@hidden
+The @ref{Composable pictures,@code{(kawa pictures}) library} lets
+you create ``picture'' objects,
+display them, transform them, combine them, and more.
address@hidden
+There is a new @ref{Pretty-printing,API for pretty-printing}.
address@hidden
+Basic support for Java 9 (though still some issues).
address@hidden
+Generated files like @code{Makefile.in} and @code{configure} are no
+longer in the Subversion source code repository, though they are still
+included in the distributed @code{kawa-version.tar.gz} releases. The new
+top-level script @code{autogen.sh} should be run before
address@hidden
address@hidden
+Kawa traditionally followed Java in allowing you to pass an array with
+the "rest" arguments to a varargs method. (A "varargs" method includes
+Java varargs methods, as well as Kawa methods with a @code{#!rest}
+parameter that is explicitly typed to be an array type.) For example,
+you could write:
+
address@hidden
+(define args (Object[] 3 "cm"))
+(java.lang.String:format "length:%s%s" args)
address@hidden verbatim
+
+This is deprecated, and may stop working in a future release. Instead,
+use the splice operator:
+
address@hidden
+(java.lang.String:format "length:%s%s" @args)
address@hidden verbatim
+
address@hidden
+More options for @ref{Ranges,range objects}. For example,
+you can write @code{[1 by: 2 <=: 9]}.
+
address@hidden
+Many enhancements to @ref{Arrays,arrays} and vectors:
+
address@hidden
address@hidden
+Shape specifiers (used when creating an array) can now be one of a
+rank-2 array of low/high-bounds, as in SRFI-25; a vector of upper
+bounds; or a vector of ranges.
address@hidden
+New type specifiers for array: @code{array} is any array (i.e. any
address@hidden); @address@hidden is the same restricted to rank
address@hidden@var{N}}; @code{array[etype]} or @code{arrayN[etype]} restrict
the types
+of elements to @code{etype}.
+
+If the @code{etype} is a primitive type (for example
address@hidden) then indexing is optimized to method calls that
+avoid object allocation.
+
address@hidden
+Generalized array indexing: If A is an array (or a vector), then the
+expression:@*
address@hidden(A I J K ...)address@hidden
+in general evaluates to an array B such that:@*
address@hidden(B i1 i2 ... j1 j2 ... k1 k2 ... ...)} address@hidden
address@hidden(A (I i1 i2 ..) (J j1 j2 ...) (K k1 k2 ...) ...)}
+
+If an index I is an integer, it is treated as a zero-index array - a
+scalar.
+
+For example: if @code{(define B (A 2 [4 <: 10]))} then @code{(B i)} is
address@hidden(A 2 (+ i 4))}.
+
address@hidden
+The procedure @code{array-index-ref} is does the above indexing
+explicitly: @code{(array-index-ref A I J K ...)} is
address@hidden(A I J K ...)}. The result is a read-only snapshot.
address@hidden
+The procedure @code{array-index-share} is like @code{array-index-ref}
+but creates a modifiable view into argument array.
address@hidden
address@hidden(build-array shape procedure)} is a general constructor for lazy
+arrays: If @code{A} is the result, then @code{(A i j k ...)} is
address@hidden(procedure [I J K ...])}.
address@hidden
address@hidden creates a view, with a mapping of the indexes.
address@hidden
+Other new procedures (like those in the Racket math package):
address@hidden, @code{array-fill!}, @code{array-copy!},
address@hidden, @code{array-reshape}, @code{array-flatten},
address@hidden>vector}, @code{index-array}, @code{build-array}.
address@hidden
+Add Common Lisp array reader syntax (@code{#rankA}) with
address@hidden://www.gnu.org/software/guile/manual/html_node/Array-Syntax.html,Guile
+extensions}, including reader sypport for multi-dimensional uniform
+(primitive) arrays. This is also used when printing arrays.
address@hidden
+New @code{format-array} procedure print an array a tabular 2-dimensional
+(APL-like) format. This format is used by default in the top-level of
+the REPL.
address@hidden itemize
+
address@hidden
+Print bit-vectors using the Common Lisp (and Guile) reader syntax.
+For example @code{#*1100110}. Enhanced the reader to read this format.
+
address@hidden
+Various REPL enhancements and new features:
+
address@hidden
address@hidden
+The @code{-w} switch to create a new REPL window
+can be followed by various sub-options to control @emph{how} and
+where the window is created.
+For example @code{-wbrowser} creates a new window
+using your default web browser.
address@hidden
+Prompts are now normally specified using @code{printf}-style templates.
+The normal prompt template is specified by the @code{input-prompt1}
+variable, while continuation lines use @code{input-prompt2}. These can
+be initialized by command-line options @code{console:prompt1} and
address@hidden:prompt2}, or otherwise use language-specific defaults. You
+can still use @code{set-input-port-prompter!} to set a more general
+prompt-procedure, but it is now only called for the initial line of a
+command, not continuation lines.
address@hidden
+The new @code{--with-jline3} configure option builds support for the
address@hidden://github.com/jline/jline3,JLine (version 3)} library for
+handling console input, similar to GNU readline.
address@hidden
+Context-dependent command-completion (tab-completion) works when using
+JLine.
address@hidden itemize
+
address@hidden
+Various REPL enhancements when using @uref{http://domterm.org/,DomTerm}.
address@hidden
address@hidden
+If you ``print'' an XML/HTML node, it gets inserted into the DomTerm
+objects. You print images, tables, fancy text, and more.
address@hidden
+If you ``print'' a picture object or a @code{BuferredImage}
+the picture is shown in the DomTerm console.
address@hidden
+You can load or modify styles with the @code{domterm-load-stylesheet}
+procedure.
address@hidden
+When pretty-printing, calculation of line-breaks and indentation
+is handled by DomTerm.
+If you change the window width, DomTerm will dynamically
+re-calculate the line-breaks of previous pretten output.
+This works even in the case of a session saved to an HTML
+file, as long as JavaScript is enabled.
address@hidden
+Hide/show buttons are emitted as part of the default prompt.
address@hidden itemize
address@hidden
+Multiple literals that have the same value (as in @code{equal?}) get
+compiled to the same object.
address@hidden
+The syntax @code{&<[expr]} is now equivalent to @code{&<@{&address@hidden,
+assuming @code{expr} is an expression that evaluates to a string that
+named an existing file. That file is read is the result is the contents
+of the file (as if by @code{(path-data expr)}).
+
address@hidden itemize
+
address@hidden Kawa 2.1 (October 26, 2015)
address@hidden
+Lots of little changes, and some big changes to sequences and strings.
+
address@hidden
address@hidden
+Enhancements to the Kawa tutorial.
address@hidden
+Added @code{parameter} as a new typename, for Scheme parameter objects.
+It can be parameterized (for example @code{parameter[string]}) for
+better type inference when "calling" (reading) the parameter.
address@hidden
+We now define ``interactive mode'' as a REPL or a source module that
+uses the default global top-level environment @emph{or} a source module
+imported/required by a interactive module. Interactive mode attempts to
+support dynamic re-definition and re-loading of function and other
+definitions. This is a work-in-progres; interactive mode currently uses
+extra indirection to support re-definitions (at a slight performance
+cost).
address@hidden
+Various changes and fixes in Path/URI handling. Most significantly, the
+resolve argorithm used by @code{resolve-uri} was re-written to use the
+algorithm from RFC-3986, rather than the obsolete RFC-2396 algorithm
+used by @code{java.net.URI.resolve}.
address@hidden
+Change to mangle class and package name in
address@hidden://blogs.oracle.com/jrose/entry/symbolic_freedom_in_the_vm,Symbolic
+Freedom} style. This means that class names and class filenames usually
+match the source file, even if special charaters are used, except for a
+small number of disallowed characters. Note this is currently
address@hidden used for class and package names.
address@hidden
+Allow @code{'synchronized} and @code{'strictfp} as access flags for
+methods.
address@hidden
+You can now have a type-specifier for @code{define-variable}.
+
address@hidden
+Better support for forward references between macros.
+
address@hidden
+Added unsigned primitive integer types @code{ubyte}, @code{ushort},
address@hidden, and @code{ulong}. These are represented at run-time by the
+corresponding signed types, but Kawa generates code to do unsigned
+arithmethic and comparisons. Corresponding boxed classes are
address@hidden, @code{gnu.math.UShort}, @code{gnu.math.UInt}, and
address@hidden
+
address@hidden
+Improvements and unification of sequences and strings:
+
address@hidden
address@hidden
+The new @code{sequence} type generalizes lists, vectors, arrays,
+strings, and more. It is implemented as the @code{java.util.List}
+interface, but strings (@code{java.lang.CharSequence}) and Java arrays
+are compatible with @code{sequence} and converted as needed.
address@hidden
+The @code{length} function is generalized to arbitrary sequences. (For
+strings it uses the @code{CharSequence.length} method, which returns the
+number of (16-bit) code units. This is different from the
address@hidden function, which returns the number of Unicode code
+points.)
address@hidden
+A new pseudo-character value @code{#\ignorable-char} is introduced. It
+is ignored in string-construction contexts.
address@hidden
+The function-call syntax for indexing works for all sequences. If the
+sequence is a string, the result is the Unicode (20-bit) scalar value at
+the specified index. If index references the trailing surrogate of a
+surrogate pair the result is @code{#\ignorable-char}. This allows
+efficient indexing of strings: Handing of surrogate pairs are handled
+automatically as long as @code{#\ignorable-char} is skipped.
address@hidden
+Indexing of uniform vector types (such as @code{s64vector} or
address@hidden or @code{u16vector}) now return the ``standard''
+primitive type (such as @code{long} or @code{double}) or the new
+unsigned primitive (such as @code{ushort}). This improves performance
+(since we can generally use primitive types), and improves compatibility
+with Java arrays. Specifically, @code{s64vector} now implements
address@hidden<Long>}, and thus @code{java.util.List<Long>} Note that
+indexing a @code{f64vector} returns a @code{double} which as an object
+is a @code{java.lang.Double}, not the Kawa floating-point type
address@hidden The result is usually the same, but @code{eqv?}
+might return a different result than previously.
address@hidden
+The arguments to @code{map}, @code{for-each}, and @code{vector-for-each}
+can now be any sequence (including strings and native arrays). The
+arguments to @code{vector-for-each} can now be arbitrary
address@hidden values. All of these are inlined. If the sequence
+type is known, more efficient custom code is generated.
+
address@hidden
+A range represents an enumerable sequence, normally integers, but it is
+represented compactly using the start value, the step (usually 1), and
+size. There is a new convenient syntax for writing a range: if @code{i}
+and @code{j} are integers then @code{[i <=: j]} is the sequence of
+integers starting at @code{i} and ending at @code{j} (inclusive). You
+can also write @code{[i <=: j]} (excludes the upper bound),
address@hidden >: j]} (counts down to @code{j}, exclusive), and
address@hidden >=: j]} (counts down to @code{j}, inclusive).
address@hidden
+You can use a sequences of integers to index a sequence. The result is
+the sequence of the selected elements. In general
address@hidden(seq [i0 ... in])} is @code{[(seq i0) ... (seq in)]}. This work
+well with ranges: @code{(seq [i <: j])} is the subsequence of @code{seq}
+from @code{i} to @code{j} (exclusive).
+
+If the @code{seq} is a string (a @code{CharSequence}) then the result is
+also a string. In this case the indexing behavior is slightly different
+in that indexing selects (16-bit) code units, which are combined to a
+string.
+
address@hidden itemize
+
address@hidden
+A new @code{dynamic} type is like @code{Object}. However, it forces
+runtime lookup and type-checking, and supresses compile-time type check
+and errors. (This is similar to C#. It is useful as an escape hatch if
+we ever implement traditional strict static type-checking.)
address@hidden
+Specifying the parameter type or return type of a function or method
+without a '@code{::}' is deprecated and results in a warning.
+
address@hidden
+In @code{--r7rs} mode: The '@code{l}' exponent suffix of a number
+literal creates a floating-point double, rather than a
address@hidden
address@hidden
+Added the hyperbolic functions: sinh, cosh, tanh, asinh, acosh, atanh.
address@hidden
+The @code{equal?} function can now handle cyclic lists and vectors. So
+can @code{equal-hash}.
address@hidden
+The command-line option @code{--with-arg-count=N} allows finer control
+of command-line-processing. It is used before an ``action'', and
+specifies the @code{N} arguments following the action are set as the
+command-line-arguments. After the action, command-line-processing
+continues following those @code{N} arguments.
address@hidden
+Added the R6RS module @code{(rnrs arithmetic bitwise)}.
address@hidden
+The @code{kawa.repl} argument processor now handles @code{-D} options.
address@hidden
+The new @code{class} sub-form of @code{import} allows you to import
+classes, and give them abbreviated names, like the Java @code{import}
+statement. The new form is more compact and convenient than
address@hidden
+
+You can also use a classname directly, as a symbol, instead of writing
+it in the form of a list:
+
address@hidden
+(import (only java.lang.Math PI))
address@hidden verbatim
+
address@hidden
+In the @code{only} clause of the @code{import} syntax you can now
+directly rename, without having to write a @code{rename} clause.
address@hidden
+Changes in the calling-convention for @code{--full-tailcalls} yields a
+substantial speed-up in some situations.
address@hidden
+The type of boolean literals @code{#f} and @code{#t} is now primitive
address@hidden rather than @code{java.lang.Boolean}.
address@hidden
+General multi-dimensional arrays can be indexed with function call
+notation. E.g. @code{(arr i j k)} is equivalent to
address@hidden(array-ref a i j k)}. You can also use @code{set!} with either
address@hidden or function call notation.
address@hidden
+The @code{#!null} value (Java @code{null}) is now considered false, not
+true. Likewise for non-canonical false Boolean objects (i.e. all
+instances of @code{java.lang.Boolean} for which @code{booleanValue}
+returns false, not just @code{Boolean.FALSE}).
+
address@hidden
+New standard libraries @code{(kawa base)} and @code{(kawa reflect)}.
address@hidden
+You can now use patterns in the @code{let} form and related forms.
+
address@hidden
+Implemented the @uref{http://en.wikipedia.org/wiki/Lambda_lifting,lambda
+lifting} optimzation.
address@hidden
+An expression that has type T is now considered compatible with a
+context requiring an interface type I only if T implements I (or T is
+Object). (Before they were considered possibly-compatible if T was
+non-final because the run-time class might be a subclass of T that
+implements I.)
address@hidden
+New @code{--console} flag forces input to be treated as an interactive
+console, with prompting. This is needed on Windows under Emacs, where
address@hidden()} gives the wrong result.
address@hidden
+You can now in a sub-class reference fields from not-yet-compiled
+super-classes. (This doesn't work for methods yet.)
address@hidden
+The @code{(? name::type value)} operator supports conditional binding.
+The @code{(! name::type value)} operator supports unconditional binding;
+it is similar to @code{define-constant}, but supports patterns.
+
address@hidden
+More efficient implementation of @code{call-with-values}: If either
+argument is a fixed-arity lambda expression it is inlined. Better
+type-checking of both @code{call-with-values} and @code{values}.
+
address@hidden
+Jamison Hope enhanced the support for quaternions, primarily the new
address@hidden(kawa rotations)} library.
address@hidden itemize
+
address@hidden Kawa 2.0 (December 2 2014)
address@hidden
+There are many new features, but the big one is R7RS compatibility.
+
address@hidden
address@hidden
+New @code{define-alias} can define aliases for static class members.
address@hidden
+The treatment of keywords is changing to not be self-evaluating (in
+Scheme). If you want a literal keyword, you should quote it. Unquoted
+keywords should only be used for keyword arguments. (This will be
+enforced in a future release.) The compiler now warns about badly formed
+keyword arguments, for example if a value is missing following a
+keyword.
address@hidden
+The default is now Java 7, rather than Java 6. This means the checked-in
+source code is pre-processed for Java 7, and future binary releases will
+require Java 7.
address@hidden
+The behavior of parameters and fluid variables has changed. Setting a
+parameter no longer changes its value in already-running sub-threads.
+The implementation is simpler and should be more efficient.
+
address@hidden
+The form @code{define-early-constant} is similar to
address@hidden, but it is evaluated in a module's class
+initializer (or constructor in the case of a non-static definition).
address@hidden
+Almost all of R7RS is now working:
+
address@hidden
address@hidden
+Importing a SRFI library can now use the syntax
address@hidden(import (srfi N [name]))}
address@hidden
+The various standard libraries such as @code{(scheme base)} are
+implemented.
address@hidden
+The functions @code{eval} and @code{load} can now take an
+environment-specifier. Implemented the @code{environment} function.
address@hidden
+Extended @code{numerator}, @code{denominator}, @code{gcd}, and
address@hidden to inexacts.
address@hidden
+The full R7RS library functionality is working, including
address@hidden The keyword @code{export} is now a synonym for
address@hidden, and both support the @code{rename} keyword. The
address@hidden option of @code{import} now works.
+
address@hidden
+The @code{cond-expand} form now supports the @code{library} clause.
address@hidden
+Implemented @code{make-promise} and @code{delay-force} (equivalent to
+the older name @code{lazy}).
address@hidden
+Changed @code{include} so that by default it first seaches the directory
+containing the included file, so by default it has the same effect as
address@hidden However, you can override the search path with
+the @code{-Dkawa.include.path} property. Also implemented
address@hidden
address@hidden
+Implemented @code{define-values}.
address@hidden
+Fixed @code{string->number} to correctly handle a radix specifier in the
+string.
address@hidden
+The @code{read} procedure now returns mutable pairs.
address@hidden
+If you need to use @code{...} in a @code{syntax-rules} template you can
+use @code{(... template)}, which disables the special meaning of
address@hidden in @code{template}. (This is an extension of the older
address@hidden(... ...)}.)
address@hidden
+Alternatively, you can can write
address@hidden(syntax-rules dots (literals) rules)}. The symbol @code{dots}
+replaces the functionality of @code{...} in the @code{rules}.
address@hidden
+An underscore @code{_} in a @code{syntax-rules} pattern matches
+anything, and is ignored.
address@hidden
+The @code{syntax-error} syntax (renamed from @code{%syntax-error})
+allows error reporting in @code{syntax-rules} macros. (The older
+Kawa-specific @code{syntax-error} procedure was renamed to
address@hidden)
address@hidden
+Implemented and documented R7RS exception handling: The syntax
address@hidden and the procedures @code{with-exception-handler},
address@hidden, and @code{raise-continuable} all work. The @code{error}
+procedure is R7RS-compatible, and the procedures @code{error-object?},
address@hidden, @code{error-object-irritants},
address@hidden, and @code{read-error?} were implemented.
+
address@hidden
+Implemented @code{emergency-exit}, and modified @code{exit} so
+finally-blocks are executed.
+
address@hidden
+Implemented @code{exact-integer?}, @code{floor/}, @code{floor-quotient},
address@hidden, @code{truncate/}, @code{truncate-quotient}, and
address@hidden
address@hidden
+The @code{letrec*} syntax is now supported. (It works the same as
address@hidden, which is an allowed extension of @code{letrec}.)
+
address@hidden
+The functions @code{utf8->string} and @code{string->utf8} are now
+documented in the manual.
+
address@hidden itemize
+
address@hidden
+The changes to characters and strings are worth covering separately:
+
address@hidden
address@hidden
+The @code{character} type is now a new primitive type (implemented as
address@hidden). This can avoid boxing (object allocation)
address@hidden
+There is also a new @code{character-or-eof}. (A union of
address@hidden and the EOF value, except the latter is encoded as -1,
+thus avoiding object allocation.) The functions read-char and
address@hidden now return a @code{character-or-eof} value.
address@hidden
+Functions like @code{string-ref} that take a character index would not
+take into account non-BMP characters (those whose value is greater than
address@hidden, thus requiring two surrogate characters). This was
+contrary to R6RS/R7RS. This has been fixed, though at some performance
+cost . (For example @code{string-ref} and @code{string-length} are no
+longer constant-time.)
address@hidden
+Implemented a @uref{Strings.html#String-Cursor-API,@code{string-cursor}
+API} (based on Chibi Scheme). Thes allow efficient indexing, based on
+opaque cursors (actually counts of 16-bits @code{char}s).
address@hidden
+Optimized @code{string-for-each}, which is now the preferred way to
+iterate through a string.
address@hidden
+Implemented @code{string-map}.
address@hidden
+New function @code{string-append!} for in-place appending to a mutable
+string.
address@hidden
+New function @code{string-replace!} for replacing a substring of a
+string with some other string.
address@hidden
+The SRFI-13 function @code{string-append/shared} is no longer
+automatically visible; you have to @code{(import (srfi :13 strings))} or
+similar.
address@hidden itemize
+
address@hidden
+The @code{module-name} form allows the name to be a list, as in a
+R6RS/R7RS-style library name.
address@hidden
+The syntax @code{@@expression} is a @emph{splicing form}. The
address@hidden must evaluate to a sequence (vector, list, array,
+etc). The function application or constructor form is equivalent to all
+the elements of the sequence.
address@hidden
+The parameter object @code{current-path} returns (or sets) the default
+directory of the current thread.
address@hidden
+Add convenience procedures and syntax for @uref{Processes.html,working
+with processes}: @code{run-process}, @code{process-exit-wait},
address@hidden, @code{&cmd}, @code{&`}, @code{&sh}.
address@hidden
+The functions @code{path-bytes}, and @code{path-data} can
address@hidden://www.gnu.org/software/kawa/Reading-and-writing-whole-files.html,read
+or write the entire contents of a file}. Alternatively, you can use the
+short-hand syntax: @code{&<@address@hidden @code{&>@address@hidden
address@hidden&>>@address@hidden These work with "blobs" which may be text or
binary
+depending on context.
address@hidden
+The initial values of @code{(current-output-port)} and
address@hidden(current-error-port)} are now hybrid textual/binary ports. This
+means you can call @code{write-bytevector} and @code{write-u8} on them,
+making it possible for an application to write binary data to standard
+output. Similarly, initial value of @code{(current-input-port)} is a
+hybrid textual/binary port, but only if there is no console (standard
+input is not a tty).
+
address@hidden
+Jamison Hope contributed support for
address@hidden://en.wikipedia.org/wiki/Quaternion,quaternions}, a
+generalization of complex numbers containing 4 real components.
+
address@hidden
+Andrea Bernardini contributed an optimized implementation of @code{case}
+expressions. He was sponsored by Google Summer of Code.
address@hidden
+The @code{kawa.sh} shell script (which is installed as @code{kawa} when
address@hidden configuring with @code{--enable-kawa-frontend}) now handles
address@hidden and @code{-J} options. The @code{kawa.sh} script is now also
+built when usint Ant.
address@hidden
+The @code{cond-expand} features @code{java-6} though @code{java-9} are
+now set based on the @code{System} property @code{"java.version"}
+(rather than how Kawa was configured).
address@hidden
+An Emacs-style @code{coding} declaration allows you to specify the
+encoding of a Scheme source file.
address@hidden
+The command-line option @code{--debug-syntax-pattern-match} prints
+logging importation to standard error when a @code{syntax-rules} or
address@hidden pattern matches.
address@hidden
address@hidden://srfi.schemers.org/srfi-60/srfi-60.html,SRFI-60 (Integers as
+Bits)} is now fully implemented.
+
address@hidden
+Ported @uref{http://srfi.schemers.org/srfi-101/srfi-101.html,SRFI-101}.
+These are immutable (read-only) lists with fast (logarithmic) indexing
+and functional update (i.e. return a modified list). These are
+implemented by a @code{RAPair} class which extends the generic
address@hidden type, which means that most code that expects a standard
+list will work on these lists as well.
+
address@hidden
+The class @code{kawa.lib.kawa.expressions} contains an experimental
+Scheme API for manipulating and validating expressions.
address@hidden
+Internal: Changed representation used for multiple values to an abstract
+class with multiple implementations.
+
address@hidden
+Internal: Started converting to more standard Java code formatting and
+indentation conventions, rather than GNU conventions. Some files
+converted; this is ongoing work.
address@hidden
+Internal: Various I/O-related classes moved to new package
address@hidden
+
address@hidden
+Various changes to the @code{configure+make} build framework: A C
+compiler is now only needed if you configure with
address@hidden Improved support for building under
+Windows (using MinGW/MSYS).
+
address@hidden
+Support for building with @uref{http://gcc.gnu.org/java/,GCJ} was
+removed.
+
address@hidden itemize
+
address@hidden Kawa 1.14 (October 4, 2013)
address@hidden
address@hidden
address@hidden
+You can pass flags from the @code{kawa} front-end to the @code{java}
+launcher using @code{-J} and @code{-D} flags. The @code{kawa} front-end
+now passes the @code{kawa.command.line} property to Java; this is used
+by the @code{(command-line)} procedure.
address@hidden
+Various improvements to the shell-script handling, including
address@hidden,re-written documentation}.
address@hidden
+Some initial support for Java 8.
+
address@hidden
+More of R7RS is now working:
+
address@hidden
address@hidden
+After adding list procedures @code{make-list}, @code{list-copy},
address@hidden all the R7RS list procedures are implemented.
address@hidden
+Other added procedures: @code{square}, @code{boolean=?},
address@hidden, @code{digit-value},
address@hidden, @code{get-environment-variables},
address@hidden, @code{current-jiffy}, @code{jiffies-per-second},
+and @code{features}.
address@hidden
+The predicates @code{finite?}, @code{infinite?}, and @code{nan?} are
+generalized to complex numbers.
address@hidden
+The procedures @code{write}, @code{write-simple}, and
address@hidden are now consistent with R7RS.
address@hidden
+String and character comparison functions are generalized to more than
+two arguments (but restricted to strings or characters, respectively).
address@hidden
+The procedures @code{string-copy}, @code{string->list}, and
address@hidden now take optional (start,end)-bounds. All of the
+R7RS string functions are now implemented.
address@hidden
+Support @code{=>} syntax in @code{case} form.
address@hidden
+Support backslash-escaped special characters in symbols when inside
+vertical bars, such as @code{'|Hello\nworld|}.
address@hidden
+The new functions and syntax are documented in the @uref{index.html,Kawa
+manual}; look for the functions in the @uref{Overall-Index.html,index}.
address@hidden itemize
+
address@hidden
+Added @code{define-private-alias} keyword.
address@hidden
+Extended @uref{Strings.html#String-templates,string quasi-literals
+(templates)} as specified by
address@hidden://srfi.schemers.org/srfi-109/srfi-109.html,SRFI-109}. For
+example, if @code{name} has the value @code{"John"}, then:
+
address@hidden
+&{Hello &[name]!}
address@hidden verbatim
+
+evaluates to: @code{"Hello John!"}.
+
address@hidden
+Named quasi-literal constructors as specified by
address@hidden://srfi.schemers.org/srfi-108/srfi-108.html,SRFI-108}.
address@hidden
+A symbol having the form @code{->type} is a type conversion function
+that converts a value to @code{type}.
address@hidden
+New and improved check for void-valued expressions in a context
+requiring a value. This is controlled by the new option
address@hidden, which defaults to true.
+
address@hidden
+The @code{datum->syntax} procedure takes an optional third parameter to
+specify the source location. See @code{testsuite/srfi-108-test.scm} for
+an example.
address@hidden
+Instead of specifying @code{--main} the command line, you can now
+specify @code{(module-compile-options: main: #t)} in the Scheme file.
+This makes it easier to compile one or more application (main) modules
+along with other modules.
address@hidden
+A change to the data structure used to detect never-returning procedure
+uses a lot less memory. (Kawa 1.13 implemented a conservative detection
+of when a procedure cannot return. This analysis would sometimes cause
+the Kawa compiler to run out of memory. The improved analysis uses the
+same basic algorithm, but with a more space-efficient ``inverted'' data
+structure.)
address@hidden
+Multiple fixes to get Emacs Lisp (JEmacs) working (somewhat) again.
address@hidden itemize
+
address@hidden Kawa 1.13 (December 10, 2012)
address@hidden
address@hidden
address@hidden
+We now do a simple (conservative) analysis of when a procedure cannot
+return. This is combined with earlier and more precise analysis of
+reachable code. Not only does this catch programmer errors better, but
+it also avoids some internal compiler errors, because Kawa could get
+confused by unreachable code.
address@hidden
+Implement 2-argument version of @code{log} function, as specified by
+R6RS and R7RS (and, prematurely, the Kawa documentation).
address@hidden
+Implement the R7RS @code{bytevector} functions. The @code{bytevector}
+type is a synonym for older @code{u8vector} type.
+
address@hidden
+Implement R7RS @code{vector} procedures. Various procedures now take
+(start,end)-bounds.
+
address@hidden
+Implement most of the R7RS input/output proecdures. Most significant
+enhancement is support for R7RS-conforming binary ports.
address@hidden
+Various enhancements to the manual, including merging in lots of text
+from R7RS.
address@hidden
+Improved Android support, including a more convenient Ant script
+contributed by Julien Rousseau. Also, documentation merged into manual.
address@hidden itemize
+
address@hidden Kawa 1.12 (May 30, 2012)
address@hidden
address@hidden
address@hidden
+Implement a compile-time data-flow framework, similar to Single Static
+Assignment. This enables better type inference, improves some
+warnings/errors, and enables some optimizations.
+
address@hidden
+Jamison Hope added support for co-variant return types and bridge
+methods for generics.
address@hidden
+Macros were improved and more standards-conforming:
address@hidden
address@hidden
address@hidden>syntax} and @code{syntax->datum} are preferred names for
address@hidden>syntax-object} and @code{syntax-object->datum}.
address@hidden
+Implemented @code{bound-identifier=?} and re-wrote implementation of
address@hidden
+
address@hidden
+Implement @code{unsyntax} and @code{unsyntax-splicing}, along with the
+reader prefixes @code{#,} and @code{#,@@}.
address@hidden itemize
+
address@hidden
+New and improved lazy evaluation functionality:
+
address@hidden
address@hidden
+Lazy values (resulting from @code{delay} or @code{future}) are
+implicitly forced as needed. This makes ``lazy programming'' more
+convenient.
address@hidden
+New type @code{promise}.
address@hidden
+The semantics of promises (@code{delay} etc) is now compatible with
address@hidden://srfi.schemers.org/srfi-45/srfi-45.html,SRFI 45}.
address@hidden
+``Blank promises'' are useful for passing data between processes, logic
+programmming, and more. New functions @code{promise-set-value!},
address@hidden, @code{promise-set-exception!}, and
address@hidden
address@hidden
+The stream functions of
address@hidden://srfi.schemers.org/srfi-41/srfi-41.html,SRFI-41} were
+re-implemented to use the new promise functionality.
address@hidden itemize
+
address@hidden
+Different functions in the same module can be compiled with or without
+full tailcall support. You can control this by using
address@hidden in @code{with-compile-options}. You can also
+control @code{full-tailcalls} using @code{module-compile-options}.
+
address@hidden
+Charles Turner (sponsored by @uref{http://code.google.com/soc/,Google's
+Summer of Code}) enhanced the printer with support for
address@hidden://srfi.schemers.org/srfi-38/,SRFI-38: External Representation
+for Data With Shared Structure}.
+
address@hidden
+Optimize tail-recursion in module-level procedures. (We used to only do
+this for internal functions, for reasons that are no longer relevant.)
+
address@hidden
+Add support for building Kawa on Windows using configure+make
+(autotools) and Cygwin.
+
address@hidden
+Some support for parameterized (generic) types:
+
address@hidden
+ Type[Arg1 Arg2 ... ArgN]
address@hidden verbatim
+
+is more-or-less equivalent to Java's:
+
address@hidden
+ Type<Arg1, Arg2, ..., ArgN>
address@hidden verbatim
+
address@hidden
+New language options @code{--r5rs}, @code{--r6rs}, and @code{--r7rs}
+provide better compatibility with those Scheme standards. (This is a
+work-in-progress.) For example @code{--r6rs} aims to disable Kawa
+extensions that conflict with R6RS. It does not aim to disable all
+extensions, only incompatible extensions. So far these extensions
+disable the colon operator and keyword literals. Selecting @code{--r5rs}
+makes symbols by default case-insensitive.
+
address@hidden
+The special tokens @code{#!fold-case} and @code{#!no-fold-case} act like
+comments except they enable or disable case-folding of symbols. The old
address@hidden global is now only checked when a LispReader is
+created, not each time a symbol is read.
address@hidden
+You can now use square brackets to construct immutable sequences
+(vectors).
address@hidden
+A record type defined using @code{define-record-type} is now compiled to
+a class that is a member of the module class.
+
address@hidden
+Annotations are now supported.
address@hidden://per.bothner.com/blog/2011/Using-JAXB-annotations/,This
+example} shows how to use
address@hidden://java.sun.com/xml/downloads/jaxb.html,JAXB} annotations to
+automatically convert between between Java objects and XML files.
address@hidden
+Prevent mutation of vector literals.
+
address@hidden
+More R6RS procedures: @code{vector-map}, @code{vector-for-each},
address@hidden, @code{real-valued?}, @code{rational-valued?},
address@hidden, @code{finite?}, @code{infinite?}, @code{nan?},
address@hidden
+
address@hidden
address@hidden://srfi.schemers.org/srfi-14/srfi-14.html,SRFI-14} ("character
+sets") and @uref{http://srfi.schemers.org/srfi-41/srfi-41.html,SRFI-41}
+("streams") are now supported, thanks to porting done by Jamison Hope.
+
address@hidden
+Kawa now runs under JDK 1.7. This mostly involved fixing some errors in
address@hidden generation.
+
address@hidden
+You can now have a class created by @code{define-simple-class} with the
+same name as the module class. For example
address@hidden(define-simple-class foo ...)} in a file @code{foo.scm}. The
+defined class will serve dual-purpose as the module class.
address@hidden
+Improvements in separating compile-time from run-time code, reducing the
+size of the runtime jar used for compiled code.
address@hidden
+In the @code{cond-expand} conditional form you can now use
address@hidden:ClassName} as a feature ``name'' to tests that
address@hidden exists.
address@hidden itemize
+
address@hidden Kawa 1.11 (November 11, 2010)
address@hidden
address@hidden
address@hidden
+A new Kawa logo, contributed by @uref{http://jcubic.pl,Jakub
+Jankiewicz}.
address@hidden
+A new @code{--warn-unknown-member} option, which generalizes
address@hidden to fields as well as methods.
address@hidden
+A new @uref{ant-kawac.html,@code{kawac} task}, useful for Ant
address@hidden files, contributed by Jamison Hope.
address@hidden
address@hidden://per.bothner.com/blog/2010/AndroidHelloScheme,Updated
+Android support}.
address@hidden
+New @uref{Enumerations.html,@code{define-enum} macro} contributed by
+Jamison Hope.
address@hidden
+Access specifiers @code{'final} and @code{'enum} are now allowed in
address@hidden and related forms.
address@hidden
+Optimized @code{odd?} and @code{even?}.
address@hidden
+If you specify the type of a @code{#!rest} parameter as an array type,
+that will now be used for the "varargs" method parameter. (Before only
+object arrays did this.)
address@hidden
+When constructing an object and there is no matching constructor method,
+look for "@code{add}" methods in addition to "@code{set}" methods. Also,
+allow passing constructor args as well as keyword setters.
address@hidden,See here} for the gory details.
address@hidden
+New @code{expand} function (contributed by Helmut Eller, and enabled by
address@hidden(require 'syntax-utils)}) for converting Scheme expressions to
+macro-expanded forms.
address@hidden
address@hidden,SAM-conversion}: In a
+context that expects a Single Abstract Method (SAM) type (for example
address@hidden), if you pass a lambda you will get an
address@hidden where the lambda implements the abstract method.
+
address@hidden
+In interactive mode allow dynamic rebinding of procedures. I.e. if you
+re-define a procedure, the old procedure objects gets modified in-place
+and re-used, rather than creating a new procedure object. Thus calls in
+existing procedures will call the new version.
+
address@hidden
+Fix various threading issues related to compilation and eval.
+
address@hidden
+When @code{format} returns a string, return a @code{java.lang.String}
+rather than a @code{gnu.lists.FString}. Also, add some minor
+optimization.
address@hidden
+Inheritance of environments and fluid variables now work properly for
+all child threads, not just ones created using @code{future}.
+
address@hidden itemize
+
address@hidden Kawa 1.10 (July 24, 2010)
address@hidden
address@hidden
address@hidden
+Now defaults to using Java 6, when compiling from source. The pre-built
address@hidden works with Java 5, but makes use of some Java 6 features
+(@code{javax.script}, built-in HTTP server) if available.
address@hidden
+You can write @uref{XML-literals.html,XML literals} in Scheme code
+prefixed by a @code{#}, for example:
+
address@hidden
+#<p>The result is &{result}.</p>
address@hidden verbatim
+
address@hidden
+New functions @code{element-name} and @code{attribute-name}.
address@hidden
+Various @uref{Server-side-scripts.html,Web server improvements}. You
+have the option of using JDK 6's builtin
address@hidden,web-server} for
address@hidden,auto-configued web pages}.
+Automatic import of web server functions, so you should not need to
address@hidden(import 'http)} any more.
address@hidden
+Kawa @uref{Hash-tables.html,hashtables} now extend @code{java.util.Map}.
+
address@hidden
+If a source file is specified on the @code{kawa} command line without
+any options, it is read and compiled as a whole module before it is run.
+In contrast, if you want to read and evaluate a source file line-by-line
+you must use the @code{-f} flag.
+
address@hidden
+You can specify a class name on the @code{kawa} command line:
+
address@hidden
+$ kawa fully.qualified.name
address@hidden verbatim
+
+This is like the @code{java} command. but you don't need to specify the
+path to the Kawa runtime library, and you don't need a @code{main}
+method (as long as the class is @code{Runnable}).
+
address@hidden
+The usual bug-fixes, including better handling of the @code{~F}
address@hidden directive; and fix in handling of macro hygiene of the
address@hidden (@uref{https://savannah.gnu.org/bugs/index.php?27042,bug
+#27042}).
+
address@hidden
+Spaces are now optional before and after the '::' in type specifiers.
+The preferred syntax leave no space after the '::', as in:
+
address@hidden
+(define xx ::int 1)
address@hidden verbatim
+
address@hidden
address@hidden and @code{begin-for-syntax} work.
+
address@hidden
+You can now use @code{car}, @code{cdr} etc to work with @code{syntax}
+objects that wrap lists, as in SRFI-72.
+
address@hidden
+You can now define a package alias:
+
address@hidden
+(define-alias jutil java.util)
+(define mylist :: jutil:List (jutil:ArrayList))
address@hidden verbatim
+
address@hidden
address@hidden is now the default. A new
address@hidden (or @code{--no-module-static}) option can be
+used to get the old behavior.
+
address@hidden
+You can use @code{access:} to specify that a field is @code{'volatile}
+or @code{'transient}.
+
address@hidden
+You can now have type-specifiers for multiple variables in a @code{do}.
+
address@hidden
+Imported variables are read-only.
+
address@hidden
+Exported variables are only made into Locations when needed.
+
address@hidden
+The letter used for the exponent in a floating-point literal determines
+its type: @code{12s2} is a @code{java.lang.Float}, @code{12d2} is a
address@hidden, @code{12l2} is a @code{java.math.BigInteger},
address@hidden is a @code{gnu.math.DFloat}.
+
address@hidden
+Internal: Asking for a @code{.class} file using
address@hidden on an @code{ArrayClassLoader} will now open a
address@hidden on the class bytes.
+
address@hidden
+A new @code{disassemble} function.
+
address@hidden
+If @code{exp1} has type @code{int}, the type of @code{(+ exp1 1)} is now
+(32-bit) @code{int}, rather than (unlimited-precision) @code{integer}.
+Similar for @code{long} expressions, other arithmetic operations (as
+appropriate), and other untyped integer literals (as long as they fit in
+32/64 bits respectively).
+
address@hidden
+Many more oprimization/specializations of arithmetic, especially when
+argument types are known.
+
address@hidden
+Top-level bindings in a module compiled with @code{--main} are now
+implicitly module-private, unless there is an explicit
address@hidden
+
address@hidden
address@hidden://srfi.schemers.org/srfi-2/srfi-2.html,SRFI-2}
+(@code{and-let*}: an @code{and} with local bindings, a guarded @code{*}
+special form) is now supported.
+
address@hidden
+The reader now supports shared sub-objects, as in
address@hidden://srfi.schemers.org/srfi-38/srfi-38.html,SRFI-38} and Common
+Lisp: @code{(#2=(3 4) 9 #2# #2#)}. (Writing shared sub-objects is not
+yet implemented.)
+
address@hidden
+A module compiled with @code{--main} by default exports no bindings
+(unless overriden by an explicit @code{module-export}).
+
address@hidden
+Factor out compile-time only code from run-time code. The new
address@hidden is smaller because it has less compile-time
+only code. (Work in progress.)
address@hidden
+More changes for R6RS compatibility:
+
address@hidden
address@hidden
+The reader now recognizes @code{+nan.0}, @code{+inf.0} and variations.
+
address@hidden
+The @code{div}, @code{mod}, @code{div0}, @code{mod0},
address@hidden, @code{div0-and-mod0}, @code{inexact} and
address@hidden functions were implemented.
+
address@hidden
address@hidden and @code{exit}.
+
address@hidden itemize
+
address@hidden itemize
+
address@hidden Kawa 1.9.90 (August 8, 2009)
address@hidden
address@hidden
address@hidden
+Support for @code{javax.script}.
+
address@hidden
+Support for @uref{Regular-expressions.html,regular expressions}.
+
address@hidden
+Performance improvements:
+
address@hidden
address@hidden
+Emit @code{iinc} instruction (to increment a local @code{int} by a
+constant).
+
address@hidden
+Inline the @code{not} function if the argument is constant.
+
address@hidden
+If @code{call-with-current-continuation} is only used to exit a block in
+the current method, optimize to a @code{goto}.
+
address@hidden
+Generate @code{StackMapTable} attributes when targeting Java 6.
+
address@hidden
+Kawa can now inline a function with multiple calls (without code
+duplication) if all call sites have the same return location
+(continuation). For example: @code{(if p (f a) (f b))}. Also mutually
+tail-recursive functions are inlined, so you get constant stack space
+even without @code{--full-tailcalls}. (Thanks for Helmut Eller for a
+prototype.)
address@hidden itemize
+
address@hidden
+A number of changes for R6RS compatibility:
+
address@hidden
address@hidden
+The @code{char-titlecase}, @code{char-foldcase}, @code{char-title-case?}
+library functions are implemented.
+
address@hidden
+Imported variables are read-only.
+
address@hidden
+Support the R6RS @code{import} keyword, including support for renaming.
+
address@hidden
+Support the R6RS @code{export} keyword (though without support for
+renaming).
+
address@hidden
+Implemented the @code{(rnrs hashtables)} library.
+
address@hidden
+Implemented the @code{(rnrs sorting)} library.
+
address@hidden
+CommonLisp-style keyword syntax is no longer supported (for Scheme): A
+colon followed by an identifier is no longer a keyword (though an
+identifier followed by a colon is still a keyword). (One reason for this
+change is to support SRFI-97.)
+
address@hidden
+The character names @code{#\delete}, @code{#\alarm}, @code{#\vtab} are
+now supported. The old names @code{#\del}, @code{#\rubout}, and
address@hidden are deprecated.
+
address@hidden
+Hex escapes in character literals are supported. These are now printed
+where we before printed octal escapes.
+
address@hidden
+A hex escape in a string literal should be terminated by a semi-colon,
+but for compatibily any other non-hex-digit will also terminate the
+escape. (A terminating semi-colon will be skipped, though a different
+terminator will be included in the string.)
+
address@hidden
+A backslash-whitespace escape in a string literal will not only ignore
+the whitespace through the end of the line, but also any initial
+whitespace at the start of the following line.
+
address@hidden
+The comment prefix @code{#;} skips the following S-expression, as
+specified by
address@hidden://srfi.schemers.org/srfi-62/srfi-62.html,SRFI-62}.
+
address@hidden
+All the
address@hidden://www.r6rs.org/final/html/r6rs-lib/r6rs-lib-Z-H-12.html#node_sec_11.4,R6RS
+exact bitwise arithmetic} functions are now implemented and
address@hidden,documented in the manual}. The new
+standard functions (for example @code{bitwise-and}) are now preferred
+over the old functions (for example @code{logand}).
+
address@hidden
+If @code{delete-file} fails, throws an exception instead of returning
address@hidden
+
address@hidden itemize
+
address@hidden
+The code-base now by default assumes Java 5 (JDK 1.5 or newer), and
+pre-built @code{jar} files will require Java 5. Also, the Kawa source
+code now uses generics, so you need to use a generics-aware
address@hidden, passing it the appropriate @code{--target} flag.
+
address@hidden
+New SRFIs supported:
+
address@hidden
address@hidden
address@hidden://srfi.schemers.org/srfi-62/srfi-62.html,SRFI-62} -
+S-expression comments.
+
address@hidden
address@hidden://srfi.schemers.org/srfi-64/srfi-64.html,SRFI-64} - Scheme
+API for test suites.
+
address@hidden
address@hidden://srfi.schemers.org/srfi-95/srfi-95.html,SRFI-95} - Sorting
+and Merging.
+
address@hidden
address@hidden://srfi.schemers.org/srfi-97/srfi-97.html,SRFI-97} - Names for
+SRFI Libraries. This is a naming convention for R6RS @code{import}
+statements to reference SRFI libraries.
+
address@hidden itemize
+
address@hidden
+In BRL text outside square brackets (or nested like @code{]this[}) now
+evaluates to @code{UnescapedData}, which a Scheme quoted string
+evaluates to @code{String}, rather than an @code{FString}. (All of the
+mentioned types implement @code{java.lang.CharSequence}.)
+
address@hidden
+You can now
address@hidden://per.bothner.com/blog/2009/AndroidHelloScheme/,run Kawa
+Scheme programs on Android}, Google's mobile-phone operating system.
+
address@hidden
+The macro @code{resource-url} is useful for accessing resources.
+
address@hidden
+A new command-line option @code{--target} (or @code{-target}) similar to
address@hidden's @code{-target} option.
+
address@hidden
+If there is no console, by default create a window as if @code{-w} was
+specificed.
+
address@hidden
+If a class method (defined in @code{define-class},
address@hidden or @code{object}) does not have its parameter
+or return type specified, search the super-classes/interfaces for
+matching methods (same name and number of parameters), and if these are
+consistent, use that type.
+
address@hidden
+Trying to modify the @code{car} or @code{cdr} of a literal list now
+throws an exception.
+
address@hidden
+The @code{.zip} archive created by @code{compile-file} is now
+compressed.
+
address@hidden
+Java5-style varargs-methods are recognized as such.
+
address@hidden
+When evaluating or loading a source file, we now always compile to
+bytecode, rather than interpreting ``simple'' expressions. This makes
+semantics and performance more consistent, and gives us better exception
+stack traces.
+
address@hidden
+The Scheme type specifier @code{<integer>} now handles automatic
+conversion from @code{java.math.BigInteger} and the @code{java.lang}
+classes @code{Long}, @code{Integer}, @code{Short}, and @code{Byte}. The
+various standard functions that work on @code{<integer>} (for example
address@hidden and @code{arithmetic-shift}) can be passed (say) a
address@hidden The generic functions such as @code{+} and the
+real function @code{modulo} should also work. (The result is still a
address@hidden)
+
address@hidden
+If a name such as (@code{java.util}) is lexically unbound, and there is
+a known package with that name, return the @code{java.lang.Package}
+instance. Also, the colon operator is extended so that
address@hidden:name} evaluates to the @code{Class} for
address@hidden
+
address@hidden
address@hidden:,expression} works - it finds a symbol in @code{prefix}'s
+package (aka namespace), whose local-name is the value of
address@hidden
+
address@hidden
+A quantity @code{3.0cm} is now syntactic sugar for
address@hidden(* 3.0 unit:cm)}. Similarly:@*
address@hidden(define-unit name value)address@hidden
+is equivalent to:@*
address@hidden(define-constant unit:name value)address@hidden
+This means that unit names follow normal name-lookup rules (except being
+in the @code{unit} ``package''), so for example you can have local unit
+definitions.
+
address@hidden
+You can specify whether a class has public or package access, and
+whether it is translated to an interface or class.
+
address@hidden
+You can declare an abstract method by writing @code{#!abstract} as its
+body.
+
address@hidden
+If a name of the form @code{type?} is undefined, but @code{type} is
+defined, then treat the former as
address@hidden(lambda (x) (instance? x type))}.
address@hidden
+A major incompatible (but long-sought) change: Java strings (i.e.
address@hidden values) are now Scheme strings, rather than
+Scheme symbols. Since Scheme strings are mutable, while Java
address@hidden are not, we use a different type for mutable strings:
address@hidden (this is not a change). Scheme string literals
+are @code{java.lang.String} values. The common type for Scheme string is
address@hidden (which was introducted in JDK 1.4).
+
+Scheme symbols are now instances of
address@hidden/gnu/mapping/Symbol.html,@code{gnu.mapping.Symbol}},
+specifically the @code{SimpleSymbol} class.
+
address@hidden
+A fully-qualified class name such as @code{java.lang.Integer} now
+evaluates to the corresponding @code{java.lang.Class} object. I.e. it is
+equivalent to the Java term @code{java.lang.Integer.class}. This assumes
+that the name does not have a lexical binding, @emph{and} that it exists
+in the class-path at compile time.
+
+Array class names (such as @code{java.lang.Integer[]}) and primitive
+types (such as @code{int}) also work.
+
+The older angle-bracket syntax @code{<java.lang.Integer>} also works and
+has the same meaning. It also evaluates to a @code{Class}. It used to
+evaluate to a @uref{api/gnu/bytecode/Type.html,@code{Type}}, so this is
+a change.
+
+The name bound by a @code{define-simple-class} now evaluates to a
address@hidden, rather than a
address@hidden/gnu/bytecode/ClassType.html,@code{ClassType}}. A
address@hidden is not allowed to reference non-static
+module-level bindings; for that use @code{define-class}.
+
address@hidden
+New convenience macro
address@hidden,@code{define-syntax-case}}.
+
address@hidden itemize
+
address@hidden Kawa 1.9.1 (January 23, 2007)
address@hidden
address@hidden
address@hidden
+Fix some problems building Kawa from source using @code{configure+make}.
address@hidden itemize
+
address@hidden Kawa 1.9.0 (January 21, 2007)
address@hidden
address@hidden
address@hidden
+New types and functions for working with @uref{Paths.html,paths and
+URIs}.
+
address@hidden
+Reader macros URI, namespace, duration.
+
address@hidden
+Simplified @uref{Source-distribution.html,build using gcj}, and added
+configure flag --with-gcj-dbtool.
+
address@hidden
+If two ``word'' values are written, a space is written between them. A
+word is most Scheme values, including numbers and lists. A Scheme string
+is treated as a word by @code{write} but by not @code{display}.
+
address@hidden
+A new @code{--pedantic} command-line flag. It currently only affects the
+XQuery parser.
+
address@hidden
+The @code{load-compile} procedure was removed.
+
address@hidden
+The string printed by the @code{--version} switch now includes the
+Subversion revision and date (but only if Kawa was built using
address@hidden rather than @code{ant} from a checked-out Subversion tree).
+
address@hidden
+Kawa development now uses the
address@hidden://subversion.tigris.org/,Subversion (svn)} version control
+system instead of CVS.
+
address@hidden
+Show file/line/column on unbound symbols (both when interpreted and when
+compiled).
+
address@hidden
+Cycles are now allowed between @code{require}'d modules. Also, compiling
+at set of modules that depend on each other can now specified on the
+compilation command line in any order, as long as needed @code{require}
+forms are given.
+
address@hidden
+The @uref{PathExpressions.html,``colon notation'' has been
+generalized.}. The syntax @code{object:name} generally means to extract
+a component with a given @code{name} from @code{object}, which may be an
+object, a class, or a namespace.
+
address@hidden
+New command-line options @code{--debug-error-prints-stack-trace} and
address@hidden provide stack trace on static
+error messages.
+
address@hidden
+The @uref{Software-License.html,license for the Kawa software} has been
+changed to the
address@hidden://opensource.org/licenses/mit-license.php,X11/MIT license}.
+
address@hidden
+A much more @uref{Array-operations.html,convenient syntax for working
+with Java arrays}.
+
+The same function-call syntax also works for Scheme vectors, uniform
+vectors, strings, lists - and anything else that implements
address@hidden
+
address@hidden
+The fields and methods of a class and its bases classes are in scope
+within methods of the class.
address@hidden
+Unnamed procedures (such as lambda expressions) are printed with the
+source filename and line.
+
address@hidden
+The numeric compare functions (@code{=}, @code{<=}, etc) and
address@hidden>string} now work when passed standard Java @code{Number}
+objects (such as @code{java.lang.Long} or @code{java.math.BigDecimal}).
address@hidden
address@hidden://srfi.schemers.org/srfi-10/srfi-10.html,SRFI-10} is now
+implemented, providing the @code{#,(name args ...)} form. Predefined
+constructor @code{name}s so far are @code{URI} and @code{namespace}. The
address@hidden function is available if you
address@hidden(require 'srfi-10)}.
+
address@hidden
+A new @code{--script} option makes it easier to write Unix shell
+scripts.
+
address@hidden
+Allow general URLs for loading (including the @code{-f} flag),
+compilation and @code{open-input-file}, if the ``file name'' starts with
+a URL ``scheme'' like @code{http:}.
+
address@hidden
+Classes defined (@emph{e.g.} with @code{define-simple-class}) in a
+module can now mutually reference each other. On the other hand, you can
+no longer @code{define-class} if the class extends a class rather than
+an interface; you must use @code{define-simple-class}.
+
address@hidden
address@hidden now automatically selects language.
+
address@hidden
address@hidden macro.
address@hidden
address@hidden and the convenience syntax @code{#`}, from
address@hidden://srfi.schemers.org/srfi-72/srfi-72.html,SRFI-72}.
address@hidden
address@hidden, @code{syntax-source}, @code{syntax-line}, and
address@hidden, for better compatibility with mzscheme.
address@hidden
address@hidden://srfi.schemers.org/srfi-34/srfi-34.html,SRFI-34} (Exception
+Handling for Programs), which implements @code{with-exception-handler},
address@hidden, and @code{raise}, is now available, if you
address@hidden(require 'srfi-34)address@hidden
+Also, @uref{http://srfi.schemers.org/srfi-35/srfi-35.html,SRFI-35}
+(Conditions) is available, if you @code{(require 'srfi-35)}.
address@hidden
+The @code{case-lambda} form from
address@hidden://srfi.schemers.org/srfi-16/srfi-16.html,SRFI-16} is now
+implemented more efficiently.
+
address@hidden itemize
+
address@hidden Kawa 1.8 (October 18, 2005)
address@hidden
address@hidden://srfi.schemers.org/srfi-69/srfi-69.html,SRFI-69 ``Basic hash
+tables''} is now available, if you @code{(require 'hash-table)} or
address@hidden(require 'srfi-69)}. This is an optimized and Java-compatible port
+whose default hash function calls the standard @code{hashCode} method.
+
+A @code{define-simple-class} can now have one (or more) explicit
+constructor methods. These have the spcial name @code{*init*}. You can
+call superclass constructors or sibling constructors (@code{this}
+constructor calls) using the (admittedly verbose but powerful)
address@hidden form.
+
+The @code{runnable} function creates a @code{Runnable} from a
address@hidden It is implemented using the new class
address@hidden, which is now also used to implement
address@hidden
+
+The @code{kawa} command can now be run ``in-place'' from the build
+directory: @code{$build_dir/bin/kawa}.
+
+The special field name @code{class} in @code{(static-name type 'class)}
+or @code{(prefix:.class)} returns the @code{java.lang.Class} object
+corresponding to the @code{type} or @code{prefix}. This is similar to
+the Java syntax.
+
+Contructing an instance (perhaps using @code{make}) of a class defined
+using @code{define-simple-class} in the current module is much more
+efficient, since it no longer uses reflection. (Optimizing classes
+defined using @code{define-class} is more difficult.) The constructor
+function defined by the @code{define-record-type} macro is also
+optimized.
+
+You can now access instance methods using this short-hand:
address@hidden(*:methodname instance arg ...)address@hidden
+This is equivalent to: @code{(invoke instance 'methodname arg ...)}
+
+You can now also access a fields using the same colon-notation as used
+for accessing methods, except you write a dot before the field name:@*
address@hidden(type:.fieldname)} @code{ ;; }is like:
address@hidden(static-field type 'fieldname)address@hidden
address@hidden(*:.fieldname instance)} @code{;;} is like:
address@hidden(field 'fieldname instance)address@hidden
address@hidden(type:.fieldname instance)} @code{;;} is like:
address@hidden(*:.fieldname (as instance type))address@hidden
+These all work with @code{set!} - for example:
address@hidden(set! (*:.fieldname instance) value)}.
+
+In the above uses of colon-notation, a @code{type} can be any one of:@*
+- a namespace prefix bound using @code{define-namespace} to a namespace
+uri of the form @code{"class:classname"};@*
+- a namespace prefix using @code{define-namespace} bound to a
address@hidden<classname>} name, which can be a fully-qualified class name or a
+locally-declared class, or an alias (which might be an imported
+class);@*
+- a fully qualified name of a class (that exists at compile-time), as in
address@hidden(java.lang.Integer:toHexString 123)}; address@hidden
+- a @code{<classname>} variable, for example:
address@hidden(<list>:list3 11 12 13)}.
+
+New fluid variables @code{*print-base*}, @code{*print-radix*},
address@hidden, and @code{*print-miser-width*} can control
+output formatting. (These are based on Common Lisp.)
+
+You can new emit elipsis (@code{...}) in the output of a @code{syntax}
+template using the syntax @code{(... ...)}, as in other
address@hidden implementations.
+
+The @code{args-fold} program-argument processor from
address@hidden://srfi.schemers.org/srfi-37/srfi-37.html,SRFI-37} is
+available after you @code{(require 'args-fold)} or
address@hidden(require 'srfi-37)}.
+
+The @code{fluid-let} form now works with lexical bindings, and should be
+more compatible with other Scheme implementations.
+
address@hidden(module-export namespace:prefix)} can be used to export a
+namespace prefix.
+
+Static modules are now implemented more similarly to non-static modules.
+Specifically, the module body is not automatically run by the class
+initializer. To get the old behavior, use the new
address@hidden flag. Alternatively, instead of
address@hidden(module-static #t)} use @code{(module-static 'init-run)}.
+
+Implement @uref{http://srfi.schemers.org/srfi-39/srfi-39.html,SRFI-39}
+"Parameter-objects". These are like anonymous fluid values and use the
+same implementation. @code{current-input-port},
address@hidden, and @code{current-error-port} are now
+parameters.
+
+Infer types of variables declared with a @code{let}.
+
+Character comparisons (such as @code{char-=?}, @code{char-ci<?})
+implemented much more efficiently --- and (if using Java5) work for
+characters not in the Basic Multilingual Plane.
+
+Major re-write of symbol and namespace handling. A
address@hidden/gnu/mapping/Symbol.html,@code{Symbol}} is now immutable,
+consisting of a "print-name" and a pointer to a
address@hidden/gnu/mapping/Namespace.html,@code{Namespace}} (package). An
address@hidden/gnu/mapping/Environment.html,@code{Environment}} is a mapping
+from @code{Symbol} to
address@hidden/gnu/mapping/Location.html,@code{Location}}.
+
+Rename @code{Interpreter} to
address@hidden/gnu/expr/Language.html,@code{Language}} and
address@hidden to
address@hidden/gnu/kawa/lispexpr/LispLanguage.html,@code{LispLanguage}}.
+
+Constant-time property list operations.
+
+Namespace-prefixes are now always resolved at compile-time, never at
+run-time.
+
address@hidden(define-namespace PREFIX <CLASS>)} is loosely the same as
address@hidden(define-namespace PREFIX "class:CLASS")} but does the right thing
+for classes defined in this module, including nested or non-simple
+classes.
+
+Macros capture proper scope automatically, not just when using require.
+This allows some internal macros to become private.
+
+Major re-write of the macro-handling and hygiene framework. Usable
+support for @code{syntax-case}; in fact some of the primitives (such as
address@hidden) are now implemented using @code{syntax-case}.
address@hidden(syntax form)} (or the short-cut @code{#!form)} evaluates to a
+syntax object. @code{(define-syntax (mac x) tr)} same as
address@hidden(define-syntax mac (lambda (x) tr))}. The following non-hygienic
+forms are equivalent:
+
address@hidden
+ (define-macro (macro-name (param ...) transformer)
+ (define-macro macro-name (lambda (param ...) transformer))
+ (defmacro macro-name (PARAM ...) transformer)
address@hidden verbatim
+
+Allow vectors and more general ellipsis-forms in patterns and templates.
+
+A new configure switch @code{--with-java-source=version} allows you to
+tweak the Kawa sources to match Java compiler and libraries you're
+using. The default (and how the sources are distributed) is @code{2}
+(for "Java 2" -- jdk 1.2 or better), but you can also select "@code{1}"
+(for jdk 1.1.x), and "@code{5}" for Java 5 (jdk 1.5). You can also
+specify a jdk version number: "@code{1.4.1}" is equivalent to "2" (for
+now). Note the default source-base is incompatible with Java 5 (or more
+generally JAXB 1.3 or DOM 3), unless you also @code{--disable-xml}.
+
+Configure argument @address@hidden
+replaces @code{--enable-servlet}.
+
+Function argument in error message are now numbered starting at one.
+Type errors now give better error messages.
+
+A new function calling convention, used for @code{--full-tailcalls}. A
+function call is split up in two parts: A
address@hidden/.../@code{matchN} method checks that the actual arguments
+match the expected formal arguments, and leaves them in the per-thread
address@hidden/gnu/mapping/CallContext.html,@code{CallContext}}. Then after
+the calling function returns, a zero-argument @code{apply()} methods
+evaluates the function body. This new convention has long-term
+advantages (performance, full continuations), but the most immediate
+benefit is better handling of generic (otherloaded) functions. There are
+also improved error messages.
+
+Real numbers, characters, Lisp/Scheme strings
+(@uref{api/gnu/lists/FString.html,@code{FString}}) and symbols all now
+implement the @code{Comparable} interface.
+
+In @code{define-class}/@code{define-simple-class}: [Most of this work
+was funded by @uref{http://www.mercedsystems.com/,Merced Systems}.]
+
address@hidden
address@hidden
+You can specify
address@hidden:
address@hidden'private}|@code{'protected}|@code{'publi}c|@code{'package}]
+to set the Java access permissions of fields and methods.
address@hidden
+Methods can be static by using the @code{access: 'static} specifier.
address@hidden
+The reflective routines @code{invoke} , @code{field} ,
address@hidden , @code{slot-ref} , @code{slot-set!} can now access
+non-public methods/fields when appropriate.
address@hidden
+Such classes are no longer initialized when the containing module is
+loaded.
address@hidden
+The @code{expr} in @code{init-form: expr} is now evaluated in the outer
+scope.
address@hidden
+A new @code{init: expr} evalues @code{expr} in the inner scope.
address@hidden
+An option name following @code{allocation:} can now be a string literal
+or a quoted symbol. The latter is preferred: @code{allocation: 'class}.
address@hidden
+Added @code{'static} as a synonym for @code{'class} following
address@hidden:}.
address@hidden
+Initialization of static field (@code{allocation: 'class init: expr})
+now works, and is performed at class initialization time.
address@hidden
+You can use unnamed ``dummy fields'' to add initialization-time actions
+not tied to a field:
+
address@hidden
+ (define-simple-class Foo ()
+ (:init (perform-some-action)))
address@hidden verbatim
+
address@hidden itemize
+
address@hidden Kawa 1.7.90 (2003)
address@hidden
+Various fixes and better error messages in number parsing. Some
+optimizations for the divide function.
+
+New framework for controlling compiler warnings and other features,
+supporting command-line flags, and the Scheme forms
address@hidden and @code{module-compile-options}. The flag
address@hidden is useful for catching typos.
+Implementation funded by @uref{http://www.mercedsystems.com/,Merced
+Systems}.
+
+New @code{invoke-special} syntax form (implemented by Chris Dean).
+
+New @code{define-variable} form (similar to Common Lisp's
address@hidden).
+
address@hidden Kawa 1.7 (June 7, 2003)
address@hidden
address@hidden/gnu/kawa/servlet/KawaPageServlet.html,@code{KawaPageServlet}}
+allows automatic loading and on-the-fly compilation in a servlet engine.
+See
address@hidden/qexo/simple-xquery-webapp.html,http://www.gnu.org/software/qexo/simple-xquery-webapp.html}.
+
+The default source-base requires various Java 2 features, such as
+collection. However, @code{make-select1} will comment out Java2
+dependencies, allowing you to build Kawa with an older Java
+implementation.
+
+The @code{-f} flag and the load function can take an absolute URL. New
+Scheme functions @code{load-relative} and @code{base-uri}.
+
+Imported implementation of cut and cute from
address@hidden://srfi.schemers.org/srfi-26/srfi-26.html,SRFI-26} (Notation
+for Specializing Parameters without Currying).
+
+The way top-level definitions (including Scheme procedures) are mapped
+into Java fields is changed to use a mostly reversible mapping. (The
+mapping to method names remains more natural but non-reversible.)
+
address@hidden of types can now be exported from a module.
+
+New @code{--no-inline} and @code{--inline=none} options.
+
+You can use @code{define-namespace} to define ``namespace aliases''.
+This is used for the new short-hard syntax for method invocation:@*
address@hidden(define-namespace Int32 "class:java.lang.Integer")address@hidden
address@hidden(Int32:toHexString 255)} => @code{"ff"address@hidden
address@hidden(Int32:toString (Int32:new "00255"))} => @code{"255"address@hidden
+Alternatively, you can write:@*
address@hidden(java.lang.Integer:toHexString 255)} => @code{"ff"}
+
address@hidden://srfi.schemers.org/srfi-9/srfi-9.html,SRFI-9}
+(define-record-type) has been implemented, and compiled to a
address@hidden, with efficient code.
+
+The configure option @code{--with-collections} is now the default.
+
+Unknowns are no longer automatically static.
+
+If type not specified in a declaration, don't infer it from it initial
+value. If no return type is specified for a function, default to
address@hidden, rather than the return type of the body. (The latter
+leads to undesirable different behaviour if definitions are
+re-arranged.)
+
+You can now define and use classes defined using @code{object},
address@hidden, and @code{define-simple-class} from the
+``interpreter'', as well as the compiler. Also, a bug where inherited
+fields did not get initialized has been fixed.
+
+There are several new procedures useful for servlets.
+
+Numerical comparisions (@code{<}, @code{<=}, etc) now generates
+optimized bytecode if the types of the operands have certain known
+types. including efficient code for @code{<int>}, @code{<long>},
address@hidden<double>}, and @code{<integer>}. Much more code can now (with type
+declaration) be written just as efficiently in Scheme as in Java.
+
+There have been some internal re-arranging of how Expressions are
+processed. The Scheme-specific Translator type now inherits from
+Compilation, which replaces the old Parser class. A Complation is now
+allocated much earlier, as part of parsing, and includes a
+SourceMessages object. SourcesMessages now includes (default) line
+number, which is used by Compilation for the "current" line numbers. The
+ExpWalker class includes a SourceMessages instance (which it gets from
+the Compilation). CanInline.inline method now takes ExpWalker parameter.
+Checking of the number or parameters, and mapping known procedures to
+Java methods are now both done during the inlining pass.
+
+The user-visible effect is that Kawa can now emit error mesages more
+cleanly more places; the inlining pass can be more agressive, and can
+emit better error messages, which yields better type information. This
+gives us better code with fewer warnings about unknown methods.
+
address@hidden Changes from Kawa 1.6.98 to 1.6.99.
address@hidden
+A new language front-end handles a tiny subset of XSLT. An example is
+the check-format-users test in gnu/xquery/testsuite/Makefile.
+
+There are now converters between SAX2 and Consumer events, and a basic
+implementation of XMLReader based on XMLParser.
+
+The function as-xml prints a value in XML format.
+
+Srfi-0 (cond-expand), srfi-8 (receive), and srfi-25 (multi-dimensional
+arrays) are now implemented. So is srfi-1 (list library), though that
+requires doing (require 'list-lib).
+
+The JEmacs code is being re-organized, splitting out the Swing-dependent
+code into a separate gnu.jemacs.swing package. This should make it
+easier to add JEmacs implementation without Swing.
+
+The class gnu.expr.Interpreter has various new 'eval' methods that are
+useful for evaluating Scheme/BRL/XQuery/... expressions from Java.
+
+Kawa now uses current versions of autoconf, autoamke, and libtool,
+allowing the use of automake file inclusion.
+
+The comparisons @code{<<}, @code{<=}, @code{-}, @code{>}, and @code{=>}
+now compile to optimized Java arithmetic if both operands are
address@hidden<int>} or a literal that fits in @code{<int>}.
+
address@hidden Changes from Kawa 1.6.97 to 1.6.98
address@hidden
+Generated HTML and Postscrpt documents are no longer included in the
+source distribution. Get @code{kawa-doc-version.tar.gz} instead.
+
+(format #t ...) and (format PORT ...) now returns #!void instead of #t.
+
+Support fluid bindings (fluid-let) for any thread, not just Future and
+main.
+
+A Unix script header @code{#!/PROGRAM} is ignored.
+
+You can now take the same Kawa "web" program (written in Scheme,
+KRL/BRL, or XQuery) and run it as either a servlet or a CGI script.
+
+There are a number of new functions for accessing HTTP requests and
+generating HTTP responses.
+
+Kawa now supports a new experimental programming KRL (the "Kawa Report
+Language"). You select this language using --krl on the Kawa command
+link. It allows Scheme code to be inside template files, like HTML
+pages, using a syntax based on BRL (brl.sourceforge.net). However, KRL
+has soem experimental changes to both BRL and standard Scheme. There is
+also a BRL-compatibile mode, selected using --brl, though that currently
+only supports a subset of BRL functions.
+
+If language is not explicitly specified and you're running a source file
+(e.g. "java kawa.repl myscript.xql"), Kawa tried to derive the language
+from the the filename extension (e.g. "xql"). It still defaults to
+Scheme if there is no extension or the extension is unrecognized.
+
+New command-line option --output-format alias --format can be used to
+over-ride the format used to write out top-level (repl, load) values.
+
+XMLPrinter can now print in (non-well-formed-XML) HTML.
+
address@hidden Changes from Kawa 1.6.96 to 1.6.97
address@hidden
+Changed lots of error messages to use pairs of single quotes rather than
+starting with a backquote (accent grave): 'name' instead of `name'. Many
+newer fonts make the latter look bad, so it is now discouraged.
+
+The types @code{<String>} and @code{<java.lang.String>} new behave
+differently. The type @code{<java.lang.String>} now works just like
+(say) @code{<java.util.Hashtable>}. Converting an object to a
address@hidden<java.lang.String>} is done by a simple coercion, so the incoming
+value must be a java.lang.String reference or null. The special type
address@hidden<String>} converts any object to a java.string.String by calling
+toString; it also handles null by specially testing for it.
+
+For convenience (and backwards compatibility) Kawa uses the type
address@hidden<String>} (rather than @code{<java.lang.String>}) when it sees the
+Java type @code{java.lang}.String, for example in the argument to an
address@hidden
+
+The default behaviour of '[' and '] was changed back to be token (word)
+constituents, matching R5RS and Common Lisp. However, you can easily
+change this behaviour using the new setBrackMode method or the
+defaultBracketMode static field in ReadTable.
+
+You can now build Kawa from source using the Ant build system (from
+Apache's Jakarta project), as an alternative to using the traditional
+configure+make system. An advantage of Ant is that it works on most Java
+systems, without requiring a Unix shell and commands. Specifically, this
+makes it easy to build Kawa under MS-Windows. Thanks to James White for
+contributing this support.
+
+Added (current-error-port) which does the obvious.
+
+The new let-values and let-values* macros from srfi-11 provide a more
+convenient way to use multiple values.
+
+All the abstract apply* and eval* methods now specify 'throws
+Throwable'. A bunch of code was changed to match. The main visible
+advantage is that the throw and primitive-throw procedures work for any
+Throwable without requiring it to be (confusingly) wrapped.
+
address@hidden Changes from Kawa 1.6.95 to 1.6.96
address@hidden
+A new compilation flag --servlet generates a Servlet which can be
+deployed in a servlet engin like Tomcat. This is experimental, but it
+seesm to work for both Scheme source and XQuery source.
+
+The interface gnu.lists.CharSequence was renamed to avoid conflitcs with
+the (similar) interface java.lang.CharSequence in JDK 1.4beta.
+
+New --help option (contributed by Andreas Schlapbach).
+
+Changed the code generation used when --full-tailcalls. It now is closer
+to that used by default, in that we don't generate a class for each
+non-inlined procedure. In both cases calling an unknown procedure
+involves executing a switch statement to select a method. In addition to
+generating fewer classes and simplifying one of the more fragile parts
+of Kawa, it is also a step towards how full continuations will be
+implemented.
+
+Changed the convention for name "mangling" - i.e. how Scheme names are
+mapped into Java names. Now, if a Scheme name is a valid Java name it is
+used as is; otherwise a reversible mangling using "$" characters is
+used. Thus the Scheme names @code{'<} and @code{'$Leq} are both mapped
+into the same Java name @code{"$Leq"}. However, other names not
+containing "@code{$}" should no longer clash, including pairs like
+"@code{char-letter?}" and "@code{charLetter?}" and "@code{isCharLetter}"
+which used to be all mapped to "@code{isCharLetter}". Now only names
+containing "@code{$}" can be ambiguous.
+
+If the compiler can determine that all the operands of (+ ...) or (-
+...) are floating-point, then it will generate optimized code using Java
+primitive arithmetic.
+
+Guile-style keyword syntax '#:KEYWORD' is recognized. (Note this
+conflicts with Common Lisp syntax for uninterned symbols.)
+
+New syntax forms define-class and define-simple-class allow you to
+define classes more easily. define-class supports true multiple
+inheritance and first class class values, where each Scheme class is
+compiled to a pair of an inteface and a class. define-simple-class
+generates more efficient and Java-compatible classes.
+
address@hidden Changes from Kawa 1.6.94 to 1.6.95.
address@hidden
+A new language "xquery" implements a (so far small subset of) XQuery,
+the draft XML Query languaage.
+
+Various internal (Java API) changes: Changes to gnu.expr.Interpreter to
+make it easier to add non-Lisp-like languages; gnu.lists.Consumer now
+has an endAttribute method that need to be called after each attribute,
+rather than endAttributes that was called after all of them.
+
+If configured with --with-gcj, Kawa builds and intalls a 'gckawa' script
+to simlify linking with needed libraries.
+
+The @code{setter} function is now inlined, and
address@hidden(set! (field X 'N) V)} and @code{(set! (static-field <T> "N) V)}
+are now inlined.
+
+If configured @code{--with-gcj}, then a @code{gckawa} helper script is
+installed, to make it easier to link Kawa+gcj-compiled applications.
+
address@hidden Changes from Kawa 1.6.92 to 1.6.94
address@hidden
+The JEmacs code now depends on CommonLisp, rather than vice versa, which
+means Commonlisp no longer depends on Swing, and can be built with GCJ.
+CommonLisp and JEmacs symbols are now implemented using Binding, not
+String.
+
address@hidden Changes from Kawa 1.6.90 to 1.6.92
address@hidden
+Kawa now installs as a .jar file (kawa.jar symlinked to
+kawa-VERSION.jar), rather than a collection of .class files.
+
+The Kawa manual includes instructions for how to build Kawa using GCJ,
+and how to compile Scheme code to a native executable using GCJ.
+
+Kawa now has builtin pretty-printer support, using an algorithm from
+Steel Bank Common Lisp converted from Lisp to Java. The high-level
+Common Lisp pretty-printing features are mostly not yet implemented, but
+the low-level support is there. The standard output and error ports
+default to pretty-printing.
+
+A new formatting framework uses the Consumer interface from gnu.lists.
+You can associate a format with an output port. Common Lisp and JEmacs
+finally print using their respective syntaxes.
+
+All output ports (OutPort instances) are now automatically flushed on
+program exit, using a new WriterManager helper class.
+
+The new commmand-line option --debug-print-expr causes the Expression
+for each expression to be printed. The option --debug-print-final-expr
+is similar, but prints Expressions after optimization and just before
+compilation. They are printed using the new pretty-printer.
+
+Changed calling convention for --full-tailcalls to write results to a
+Consumer, usually a TreeList or something to be printed. A top-level
+ModuleBody now uses the same CpsProcedure convention. This is useful for
+generating xml or html.
+
+New libtool support allows kawa to be built as a shared library.
+
+The new configure flag --with-gcj uses gcj to compile Kawa to both
+.class files and native code. This is experimental.
+
address@hidden Changes from Kawa 1.6.70 to 1.6.90
address@hidden
+The reader (for Scheme and Lisp) has been re-written to be table-driven,
+based on the design of Common Lisp readtables.
+
+The new gnu.lists package has new implementations of sequence-related
+classes. It replaces most of gnu.kawa.util. See the package.html file.
+
+If the expected type of a non-unary @code{+} or @code{-} is @code{<int>}
+or @code{<long>} and the operands are integeral types, then the operands
+will converted to the primitive integer type and the addition or
+subtraction done using primitive arithmetic. Similarly if the expected
+type is @code{<float>} or @code{<long>} and the operands have
+appropriate type. This optimization an make a big performance
+difference. (We still need to also optimize compare operations like
address@hidden(< x y)} to really benefit from @code{<int>} declarations of loop
+variables.)
+
+The implementation of procedure closures has been changed to basically
+be the same as top-level procedures (except when --full-tailcalls is
+specified): Each procedure is now an instance of a ModuleMethod, which
+each "frame" is an instance of ModuleBody, just like for top-level
+functions. This sometimes reduces the number of classes generated, but
+more importantly it simplifies the implementation.
+
+A new @uref{api/gnu/xml/package-summary.html,@code{gnu.xml}} package
+contains XML-related code, currently an XML parser and printer, plus
+some XPath support. The class
address@hidden/gnu/lists/TreeList.html,@code{gnu.lists.TreeList}} (alias
address@hidden<document>}) is useful for compactly representing nested
+structures, including XML documents. If you @code{(require 'xml)} you
+will get Scheme interfaces (@code{print-as-xml} and
address@hidden) to these classes.
+
+New package gnu.kawa.functions, for primitive functions (written in
+Java).
+
+The map and for-each procedure is now inlined. This is most especially
+beneficial when it allows the mapped-over procedure to also be inlined,
+such as when that procedure is a lambda expression.
+
+Added documentation on compiling with Jikes. Renamed some classes to
+avoid warning when compiling with Jikes.
+
+The reverse! procedure was added.
+
+Internal changes: * If a variable reference is unknown, create a
+Declaration instance with the IS_UNKNOWN flag to represent an imported
+binding. * The ExpWalker framework for "tree walking" Expressions had a
+bit of reorganization. * New package gnu.kawa.functions, for primitive
+functions (written in Java).
+
+Added a hook for constant-folding and other optimization/inlining at
+traversal (ExpWalker) time. Optimization of + and - procedures to use
+primitive Java operations when the operands are primitive types.
+
+Implementation of SRFI-17. Change the definitions of (set! (f x ...)
+val) to ((setter f) x ... val), rather then the old ((setter f) val x
+...). You can now associate a setter with a procedure, either using
+make-procedure or set-procedure-property!. Also, (setter f) is now
+inlined, when possible.
+
+Internally, Syntax (and hence Macro) no longer extend Declaration.
+
+Various Java-level changes, which may be reflected in Scheme later: *
+gnu.kawa.util.Consumer interface is similar to ObjectOutput and SAX's
+ContentHandler interfaces. * A gnu.expr.ConsumerTarget is used when
+evaluating to an implicit Consumer. * These interfaces will make it easy
+to write functional-style but efficient code for transforming data
+streams, including XML. * gnu.kawa.util.FString is now variable-size.
+
address@hidden Changes from Kawa 1.6.68 to 1.6.70
address@hidden
+The bare beginnings of Common Lisp support, enabled by the --commonlisp
+(or --clisp) command line option. This is so far little more than a hack
+of the EmacsLisp support, but with lexical scoping and CL-style format.
+
address@hidden Changes from Kawa 1.6.66 to 1.6.68
address@hidden
+JEmacs news:
+
address@hidden
address@hidden
+Define emacs-version as Kawa version but with leading 0 instead of 1.
+For example, the current value is "0.6.68 JEmacs".
address@hidden
+New testsuite directory.
address@hidden
+Improved autoload framework. Handle ELisp autoload comments.
address@hidden
+Handle escape and meta-key.
address@hidden
+Handle lot more of ELisp.
address@hidden
+Lots more is now done in ELisp, using .el files imported from XEmacs.
address@hidden
+Incomplete support for setting mark, including using selection.
address@hidden
+Basic (but incomplete) implementation of (interactive spec).
address@hidden
+Common Lisp extensions: typep, default arguments.
address@hidden
+A new status.html file to note what works and what doesn't.
address@hidden itemize
+
+You can now specify in @code{define} and @code{define-private} the type
+of a variable. If the variable is module-level,
address@hidden(define name :: <type> value)} creates a field named
address@hidden'' having the specified type and initial value. (If type is
+not specified, the default is not @code{Object}, but rather a
address@hidden that @emph{contains} the variable's value.)
+
+You can now define the type of a module-level variable: In
+(define[-private] :: type expression) New (define-constant name [::
+type] expression) definition form.
+
+A procedure can now have arbitrary properties associated with it. Use
+procedure-property and set-procedure-property! to get and set them.
+
+The new procedure make-procedure creates a generic procedure that may
+contain one or more methods, as well as specified properties.
+
+New declaration form define-base-unit. Both it and define-unit have been
+re-implemented to be module-safe. Basically '(define-unit ft 12in)' is
+sugar for '(define-constant ft$unit (... (* 12 in$unit)))', where
+ft$unit and in$unit are standard identifiers managed by the module
+system. Also, the output syntax for units and quantities is cleaner.
+
+The new declaration (module-export name ...) allows control over the
+names exported from a module. The new declaration (module-static ...)
+allows control over which definitions are static and which are
+non-static. This makes it easier to use a module as a Java class.
+
+Procedures names that accidentally clash with inherited method names
+(such as "run") are now re-named.
+
+Simple aliases (define-aliases defining an alias for a variable name)
+are implemented more efficiently.
+
+The package hierarchy is getter cleaner, with fewer cyclic dependencies:
+The gnu.math package no longer has any dependencies on kawa.* or gnu.*.
+Two classes were moved from gnu.text to other classes, avoiding another
+cyclic package dependency between gnu.text and gnu.mapping. The new
+gnu.kawa.lispexpr is for compile-time handling of Lisp-like languages.
+
+Compliation of literals has been re-done. A class that can be used in a
+literal no longer needs to be declared as Compilable. Instead, you
+declare it as implementaing java.io.Externalizable, and make sure it has
+appropriate methods.
+
+All the standard "data" types (i.e. not procedures or ports) now
+implement java.io.Externalizable, and can thus be serialized. If they
+appear in literals, they can also be compiled.
+
+Created a new class gnu.kawa.util.AbstractString, with the Scheme alias
address@hidden<abstract-string>}. The old gnu.kawa.util.FString now extends
+AbstractString. A new class CharBuffer provides an growable buffer, with
+markers (automatically-adjusted positions). Many of the Scheme
address@hidden<string>} procedures now work on @code{<abstract-string>}. The
+JEmacs BufferContnat class (contains the characters of a buffer) now
+extends CharBuffer.
+
+Some JEmacs changes to support a "mode" concept, as well as preliminary
+support for inferior-process and telnet modes.
+
+New section in manual / web page for projects using Kawa.
+
+The record feasture (make-record-type etc) how handles "funny" type and
+fields names that need to be "mangled" to Java names.
+
+Re-did implementation of define-alias. For example, you can define
+type-aliases:@*
address@hidden(define-alias <marker> <gnu.jemacs.buffer.Marker>)address@hidden
+and then use <marker> instead of <gnu.jemacs.buffer.Marker>.
+
address@hidden(field array 'length)} now works.
+
address@hidden Changes from Kawa 1.6.64 to 1.6.66
address@hidden
+Added documentation to the manual for Homogeneous numeric vector
+datatypes (SRFI-4).
+
+You can now specify characters using their Unicode value: #\u05d0 is
+alef.
+
+Kawa now uses a more mnemonic name mangling Scheme. For example, a
+Scheme function named @code{<=} would get compiled to method
address@hidden
+
+There is now working and useful module support, thought not all features
+are implemented. The basic idea is that a module can be any class that
+has a default constructor (or all of whose fields and methods are
+static); the public fields and methods of such a class are its exported
+definitions. Compiling a Scheme file produces such a module. Doing:@*
address@hidden (require <classname>)address@hidden
+will create an anonymous instance of @code{<classname>} (if needed), and
+add all its exported definitions to the current environment. Note that
+if you import a class in a module you are compiling, then an instance of
+the module will be created at compile-time, and imported definitions are
+not re-imported. (For now you must compile a module, you cannot just
+load it.)
+
+The define-private keyword creates a module-local definition.
+
+New syntax to override some properties of the current module:@*
address@hidden(module-name <name>)} overrides the default name for a
address@hidden
address@hidden(module-extends <class>)} specifies the address@hidden
address@hidden(module-implements <interface> ...)} specfies the implemented
+interfaces.
+
+The syntax: (require 'keyword) is syntactic sugar for (require
+<classname>) where the classname is find is a "module catalog"
+(currently hard-wired). This provides compatibility with Slib. The Slib
+"features" gen-write, pretty-print, pprint-file, and printf are now
+available in Kawa; more will be added, depending on time and demand. See
+the package directory gnu/kawa/slib for what is available.
+
address@hidden Changes from Kawa 1.6.62 to 1.6.64
address@hidden
+A lot of improvements to JEmacs (see JEmacs.SourceForge.net).
+
+kawa-compiled-VERSION.zip is replaced by kawa-compiled-VERSION.jar.
+
+You can now use Kawa to generate applets, using the new --applet switch,
+Check the "Applet compilation" section in the manual. Generating an
+application using the --main flag should work again. Neither --applet
+nor --main has Scheme hard-wired any more.
+
+A new macro `(this)' evaluates to the "this object" - the current
+instance of the current class. The current implementation is incomplete,
+and buggy, but it will have to do for now.
+
+The command-line argument -f FILENAME will load the same files types as
+load.
+
+When a source file is compiled, the top-level definitions (procedures,
+variables, and macros) are compiled to final fields on the resulting
+class. This are not automatically entered into the current environment;
+instead that is the responsibility of whoever loads the compiled class.
+This is a major step towards a module system for Kawa.
+
+There is a new form define-private which is like define, except that the
+defined name is not exported from the current module.
+
+A procedure that has optional arguments is now typically compiled into
+multiple methods. If it's a top-level procedure, these will be methods
+in the modules "ModuleBody" class, with the same (mangled) name. The
+compiler can in many cases call the appropriate method directly.
+Usually, each method takes a fixed number of arguments, which means we
+save the overhead of creating an array for the arguments.
+
+A top-level procedure declared using the form (define (NAME ARS ...)
+BODY ..) is assumed to be "constant" if it isn't assigned to in the
+current compilation unit. A call in the same compilation unit will now
+be implemented as a direct method call. This is not done if the prcedure
+is declared with the form: (define NAME (lambda (ARGS ,,,) BODY ...)
+
+gnu.expr.Declaration no longer inherits from gnu.bytecode.Variable.
+
+A gnu.mapping.Environment now resolves hash index collisions using
+"double hashing" and "open addressing" instead of "chaining" through
+Binding. This allows a Binding to appear in multiple Environments.
+
+The classes Sequence, Pair, PairWithPosition, FString, and Char were
+moved from kawa.lang to the new package gnu.kawa.util. It seems that
+these classes (except perhaps Char) belong together. The classes List
+and Vector were also moved, and at the same time renamed to LList and
+FVector, respectively, to avoid clashed with classes in java.util.
+
+New data types and procedures for "uniform vectors" of primitive types
+were implemented. These follow the SRFI-4 specification, which you can
+find at http://srfi.schemers.org/srfi-4/srfi-4.html .
+
+You can now use the syntax @code{name :: type} to specify the type of a
+parameter. For example:@*
address@hidden(define (vector-length x :: <vector>) (invoke x
'length))address@hidden
+The following also works:@*
address@hidden(define (vector-length (x :: <vector>)) ...)}.
+
address@hidden(define-member-alias name object [fname])} is new syntactic sugar
+for @code{(define-alias name (field object fname))}, where the default
+for @code{fname} is the mangling of @code{name}.
+
address@hidden Changes from Kawa 1.6.60 to 1.6.62
address@hidden
+The new function `invoke' allows you to call a Java method. All of
+`invoke', `invoke-static' and `make' now select the bets method. They
+are also inlined at compile time in many cases. Specifically, if there
+is a method known to be definitely applicable, based on compile-time
+types of the argument expressions, the compiler will choose the most
+specific such method.
+
+The functions slot-ref, slot-set!, field, and static-field are now
+inlined by the compiler when it can.
+
+Added open-input-string, open-output-string, get-output-string from
+SRFI-6. See http://srfi.schemers.org/srfi-6/srfi-6.html.
+
+The manual has a new section "Mapping Scheme names to Java names", and a
+new chapter "Types". The chapters "Extensions", "Objects and Classes",
+and "Low-level functions" have been extensivley re-organized.
+
+The Kawa license has been simplified. There used to be two licenses: One
+for the packages gnu.*, and one for the packages kawa.*. There latter
+has been replaced by the former. The "License" section of the manual was
+also improved.
+
address@hidden Changes from Kawa 1.6.59 to 1.6.60
address@hidden
+There is a new package gnu.kawa.reflect. Some classes that used to be in
+kawa.lang or kawa.standard are now there.
+
+The procedures slot-ref and slot-set! are now available. They are
+equivalent to the existing `field', but reading a field `x' will look
+for `getX' method if there is no public `x' field; writing to a field
+will look for `setX'.
+
+The procedure `make' makes it convenient to create new objects.
+
+There is now a teaser screen snapshot of "JEmacs" at
+http://www.bothner.com/~per/papers/jemacs.png.
+
+The html version of the manual now has a primitive index. The manual has
+been slightly re-organized, with a new "Classes and Objects" chapter.
+
+The new functions invoke-static and class-methods allow you to call an
+arbitary Java method. They both take a class specification and a method
+name. The result of class-methods is a generic procedure consisting of
+those methods whose names match. (Instance methods are also matched;
+they are treated the asme as class methods with an extra initial
+argument.) The invoke-static function also takes extra arguments, and
+actually calls the "best"-matching method. An example:
+
address@hidden
+ (invoke-static <java.lang.Thread> 'sleep 100)
address@hidden verbatim
+
+Many fewer classes are now generated when compiling a Scheme file. It
+used to be that each top-level procedure got compiled to its own class;
+that is no longer the case. The change should lead to faster startup and
+less resource use, but procedure application will probably be noticably
+slower (though not so much slower as when reflection is used). The
+reason for the slowdown is that we in the general case now do an extra
+method call, plus a not-yet-optimized switch statement. This change is
+part of the new Kawa module system. That will allow the compiler to
+substitute direct methods calls in more cases, which I hope will more
+than make up for the slowdown.
+
+A Scheme procedure is now in general compiled to a Java method whose
+name is a "mangling" of the Scheme procedure's name. If the procedure
+takes a variable number of parameters, then "$V" is added to the name;
+this indicates that the last argument is a Java array containing the
+rest of the arguments. Conversely, calling a Java method whose name ends
+in "$V" passes any excess arguments in the last argument, which must be
+an array type.
+
+Many changes to the "Emacs-emulation" library in gnu.jemacs.buffer: *
+Implemented commands to read and save files. * We ask for file and
+buffer names using a dialog pop-up window. * Split windows correctly, so
+that the windows that are not split keep their sizes, the windows being
+split gets split as specified, and the frame does not change size. Now
+also handles horizonal splits. * Fairly good support for buffer-local
+keymaps and Emacs-style keymap search order. A new class BufferKeymap
+manages the active keymaps of a buffer. Multi-key key-sequences are
+handled. Pending prefix keys are remembered on a per-buffer basis
+(whereas Emacs does it globally).
+
+There is now some low-level support for generic procedures.
+
+The R5RS primitives let-syntax and letrec-syntax for defining local
+syntax extensions (macros) should now work. Also define-syntax works as
+an internal definition. All of these should now be properly "hygienic".
+(There is one known exception: symbols listed among the literals lists
+are matched as raw symbols, rather that checking that the symbol has the
+same binding, if any, as at the defining site.) The plan is to support
+general functions as hygienic rewriters, as in the Chez Scheme
+"syntax-case" system; as one part of that plan, the syntax-case
+primitive is available, but so far without any of the supporting
+machinary to support hygiene.
+
+The read-line procedure was added. This allows you to efficiently read a
+line from an input port. The interface is the same as scsh and Guile.
+
address@hidden Changes from Kawa 1.6.58 to 1.6.59
address@hidden
+define-alias now works both top-level and inside a function.
+
+Optimized eqv? so if one of the arguments is constant and not Char or
+Numeric, inline it the same way eq? is. (This helps case when the labels
+are symbols, which help the "lattice" benchmark.) ???
+
+The Emacs-related packages are now grouped under a new gnu.jemacs
+package.
+
+Improved framework for catching errors. This means improved error
+messages when passing a parameter of the wrong type. Many standard
+procedures have been improved.
+
+Simplified, documented, and tested (!) procedure for building Kawa from
+source under Windows (95/98/NT).
+
+New macros trace and untrace for tracing procedures. After executing
+(trace PROCEDURE), debugging output will be written (to the standard
+error port) every time PROCEDURE is called, with the parameters and
+return value. Use (untrace PROCEDURE) to turn tracing off.
+
+New utility functions (system-tmpdir) and (make-temporary-file
+[format]).
+
+A new (unfinished) framework supports multiple languages. The
+command-line option --elisp selects Emacs Lisp, while --scheme (the
+default) selects Scheme. (The only difference so far is the reader
+syntax; that will change.)
+
+The `format' function now provides fairly complete functionality for
+CommonLisp-style formatting. (See the Comon Lisp hyperspec at
+http://www.harlequin.com/education/books/HyperSpec/Body/sec_22-3.html.)
+The floating point formatters (~F, ~E, ~G, ~$) now pass the formatst.scm
+test (from Slib, but with some "fixes"; in the testsuite directory).
+Also, output ports now track column numbers, so @code{~T} and @code{~&}
+also work correctly.
+
+A new package gnu.emacs provides various building blocks for building an
+Emacs-like text editor. These classes are only compiled when Kawa is
+configured with the new --with-swing configuration option. This is a
+large initial step towards "JEmacs" - an Emacs re-implemented to use
+Kawa, Java, and Swing, but with full support (using gnu.elisp) for
+traditional Emacs Lisp. For more imformation see
+gnu/emacs/overview.html.
+
+A new configuration option --with-swing can be used if Swing is
+available. It is currently only used in gnu.emacs, but that may change.
+
address@hidden Changes from Kawa 1.6.56 to 1.6.58
address@hidden
+Kawa is now "properly tail-recursive" if you invoke it with the
+--full-tail-calls flag. (Exception: the eval procedure does not perform
+proper tail calls, in violation of R5RS. This will be fixed in a future
+release.) Code compiled when --full-tail-calls is in effect is also
+properly tail-recursive. Procedures compiled with --full-tail-calls can
+call procedures compiled without it, and vice versa (but of course
+without doing proper tail calls). The default is still
+--no-full-tail-calls, partly because of performance concerns, partly
+because that provides better compatibility with Java conventions and
+tools.
+
+The keywords let (including named let), let*, and letrec support type
+specifiers for the declared variables For example:
+
address@hidden
+ (let ((lst :: <list> (foo x))) (reverse lst))
address@hidden verbatim
+
+Square brackets [ ... ] are allowed as a synonym of parentheses ( ... ).
+
address@hidden Changes from Kawa 1.6.55 to 1.6.57
address@hidden
+A new command-line flag --server PORT specifies that Kawa should run as
+a telnet server on the specified PORT, creating a new read-eval-print
+loop for each connection. This allows you to connect using any telnet
+client program to a remote "Kawa server".
+
+A new front-end program, written in C, that provides editing of input
+lines, using the GNU readline library. This is a friendlier interface
+than the plain "java kawa.repl". However, because kawa.c needs readline
+and suitable networking library support, it is not built by default, but
+only when you configure Kawa with the --enable-kawa-frontend flag.
+
+The way Scheme names are mapped ("mangled") into Java identifiers is now
+more natural. E.g. "foo-bar?" now is mapped to "isFooBar".
+
+New syntax (object (SUPERS ...) FIELD-AND-METHODS ...) for creating a
+new object instance of an anonymous class. Now fairly powerful.
+
+New procedures field and static-field for more convenient field access.
+
+Syntactic sugar: @code{(lambda args <type> body)} ->
address@hidden(lambda args (as <type> body))}. This is especially useful for
+declaring methods in classes.
+
+A new synchonized form allows you to synchronize on an arbitrary Java
+object, and execute some forms while having an exclusive lock on the
+object. (The syntax matches that used by Skij.)
+
address@hidden Changes from Kawa 1.6.53 to 1.6.55
address@hidden
+New --debug-dump-zip option writes out a .zip file for compilation.
+(Useful for debugging Kawa.)
+
+You can now declare parameter types.
+
+Lot of work on more efficient procedure representation and calling
+convention: Inlining, directly callable statics method, plus some
+procedures no longer generate a separate Class.
+
+Local functions that are only called from one locations, except for
+tail-recursion, are now inlined. This inlines do loops, and most "named
+let" loops.
+
+New representation of closures (closures with captured local variables).
+We no longer use an array for the closure. Instead we store the captured
+variables in the Procedure itself. This should be faster (since we can
+use field accesses rather than array indexing, which requires bounds
+checking), and avoids a separate environment object.
+
+If the compiler sees a function call whose (non-lexically-bound) name
+matches an existing (globally-defined) procedure, and that procedure
+instance has a static method named either "apply" or the mangled
+procedure name, them the compiler emits a direct call to that method.
+This can make a very noticable speed difference, though it may violate
+strict Scheme sementics, and some code may break.
+
+Partial support for first-class "location" variables.
+
address@hidden Changes from Kawa 1.6.53 to 1.6.54
address@hidden
+Created new packages gnu.mapping and gnu.expr. Many classes were moved
+from kawa.lang to the new packages. (This is part of the long-term
+process of splitting Kawa into more manageable chunks, separating the
+Scheme-specific code from the language-independent code, and moving
+classes under the gnu hierarchy.)
+
+You can now write keywords with the colon first (e.g. :KEYWORD), which
+has exactly the same effect and meaning as putting the colon last (e.g.
+KEYWORD:). The latter is preferred is being more consistent with normal
+English use of punctuation, but the former is allowed for compatibility
+with soem other Scheme implementations and Common Lisp.
+
address@hidden Changes from Kawa 1.6.52 to 1.6.53
address@hidden
+The new package gnu.text contains facilities for reading, formatting,
+and manipulating text. Some classes in kawa.lang where moved to there.
+
+Added string-upcase!, string-downcase!, string-capitalize!,
+string-upcase, string-downcase, and string-capitalize; compatible with
+Slib.
+
+Character constants can now use octal notation (as in Guile). Writing a
+character uses octal format when that seems best.
+
+A format function, similar to that in Common Lisp (and Slib) has been
+added.
+
+The default parameter of a #!optional or #!key parameter can now be
+#!null.
+
address@hidden Changes since Kawa 1.6.51
address@hidden
+The "record" feature has been changed to that a "record-type descriptor"
+is now a gnu.bytecode.ClassType (a @code{<record-type>}), rather than a
+java.lang.Class. Thus make-record-type now returns a
address@hidden<record-typee>}, not a Class, and @code{record-type-descriptor}
+takes a @code{<record-typee>}, not a Class.
+
+More robust Eval interfaces.
+
+New Lexer abstract class. New ScmRead class (which extends Lexer) now
+contains the Scheme reader (moved from Inport). Now read errors are kept
+in queue, and can be recovered from.
+
+Comparing an exact rational and an inexact real (double) is now done as
+if by first converting the double to exact, to satisfy R5RS.
+
address@hidden Changes since Kawa 1.6.1
address@hidden
+The compile virtual method in Expression now takes a Target object,
+representing the "destination". The special ConditionalTarget is used to
+evaluate the test of an 'if expression. This allows us to generate much
+better code for and, or, eq?, not and nested if inside an if.
+
+Added port-line, port-column, and set-port-line! to match Guile.
+
+The Makefiles have been written so all out-of-date .java (or .scm).
+files in a directory are compiled using a single invocation of javac (or
+kawa). Building Kawa should now be much faster. (But note that this
+depends on unreleased recent autoamke changes.)
+
+How the Kawa version number is compiled into Kawa was changed to make it
+easier for people who want to build from source on non-Unix-like
+systems.
+
+A new gnu.ecmascript package contains an extremely incomplete
+implementation of ECMSScript, the ECMA standardized version of
+JavaScript. It includes an ECMAScript lexer (basically complete), parser
+(the framework is there but most of the language is missing), incomplete
+expression evaluation, and a read-eval-print-loop (for testing only).
+
address@hidden Changes in Kawa 1.6.1
address@hidden
+Improved Kawa home page with extra links, pointer to Java-generated api
+docs, and homepages for gnu.math and gnu.bytecode.
+
+Implemented system, make-process, and some related procedures.
+
+Added macros for primitive access to object fields, static fields, and
+Java arrays. Added constant-fold syntax, and used it for the other
+macros.
+
+The --main flag compiles Scheme code to an application (containing a
+main method), which can be be invoked directly by a Java interpreter.
+
+Implemented --version (following GNU standards) as kawa.repl
+command-line flag.
+
address@hidden Changes since Kawa 1.5.93
address@hidden
+Adding make procedure to create new objects/records.
+
+Extended (set! (f . args) value) to be equivalent to ((setter f) value .
+args). Implemented setter, as well as (setter car) and (setter cdr).
+
+Can now get and set a record field value using an application: (rec
+'fname) gets the value of the field named fname in record rec. (set!
+(rec 'fname) value) sets the value of the field named fname in rec.
+
+A partial re-write of the implementation of input ports and the Scheme
+reader, to fix some problems, add some features, and improve
+performance.
+
+Compiled .class files are now installed in $(datadir)/java, rather than
+$(prefix)/java. By default, that means they are installed in
+/usr/local/shared/java, rather than /usr/local/java.
+
+There is now internal infrastructure to support inlining of procedures,
+and general procedure-specific optimized code generation.
+
+There is better testing that the right number of arguments are passed to
+a procedure, and better error messages when you don't. If the procedure
+is inlined, you get a compile-time error message.
+
+The functions created by primitive-constructor,
+primitive-virtual-method, primitive-static-method, and
+primitive-interface-method are now first-class procedure values. They
+use the Java reflection facily, except when the compiler can directly
+inline them (in which case it generates the same efficient bytecodes as
+before).
+
+New functions instance? (tests type membership) and as (converts).
+
+The kawa.html is now split into several files, one per chapter. The
+table of contents is now kawa_toc.html.
+
+The syntactic form try-catch provides low-level exception handler
+support. It is basically the same as Java's try/catch form, but in
+Scheme syntax. The new procedure primitive-throw throws an exception
+object.
+
+The higher-level catch and throw procedures implement exception handling
+where the handler is specified with a "key" (a symbol). These functions
+were taken from Guile.
+
+The error function has been generalized to take multiple arguments (as
+in Guile). It is now a wrapper around (throw 'misc-error ...).
+
+There is a new "friendly" GUI access to the Kawa command-line. If you
+invoke kawa.repl with the -w flag, a new interaction window is created.
+This is uses the AWT TextArea class. You can create multiple "consoles".
+They can either share top-level enevironments, or have separate
+environments. This window interface has some nice features, including
+editing. Added a scheme-window procedure, which is another way to create
+a window.
+
address@hidden Changes since Kawa 1.5
address@hidden
+The default prompt now shows continuations lines differently.
+
+The copy-file function was added.
+
+The variable port-char-encoding controls how external files are
+converted to/from internal Unicode characters. It also controls whether
+CR and CR-LF are converted to LF.
+
+The reader by default no longer down-cases letters in symbols. A new
+variable symbol-read-case control how case is handled: 'P (the default)
+preserves case; 'U upper-cases letters; 'D or -" down-cases letters; and
+'I inverts case.
+
+The gnu.bytecode package now supports exception handlers. The new
+syntactic form try-finally supports a cleanup hook that is run after
+some other code finishes (normally or abnormally). Try-finally is used
+to implement dynamic-wind and fluid-let.
+
+The environment handling has been improved to support thread-specific
+environments, a thread-safe fluid-let, and multiple top-levels. (The
+latter still needs a bit of work.)
+
+The gnu.bytecode package has been extensively changed. There are new
+classes representing the various standard Attributes, and data
+associated with an attribute is now stored there.
+
+Added new procedures environment-bound? and
+scheme-implementation-version.
+
+Scheme symbols are represented as java.lang.String objects. Interned
+symbols are interned Strings; uninterned symbols are uninterned Strings.
+Note that Java strings literals are automatically interned in JDK 1.1.
+This change makes symbols slightly more efficient, and moves Kawa closer
+to Java.
+
+Ports now use the JDK 1.1 character-based Reader and Writer classes,
+rather than the byte-oriented InputStream and OutputStream classes. This
+supports different reading and writing different character encodings [in
+theory - there is no support yet for other than Ascii or binary files].
+
+An interactive input port now has a prompt function associated with it.
+It is settable with set-input-port-prompter!. The prompt function takes
+one argument (the input port), and returns a prompt string. There are
+also user functions for inquiring about the current line and column
+number of an input port.
+
+The R4RS procedures transcript-on and transcript-off are implemented.
+
+Standard types can be referred to using syntax similar to RScheme. For
+example Scheme strings now have the type @code{<string>} which is
+preferred to "@code{kawa.lang.FString}" (which in addition to being
+longer, is also more suspectible to changes in internal implementation).
+Though these types are first-class values, this is so far mainly useful
+for invoking primitive methods.
+
address@hidden Changes from Kawa 1.4 to 1.5
address@hidden
+Execute a ~/.kawarc.scm file on startup, if it exists.
+
+Add a number of functions for testing, renaming, and deleting files.
+These are meant to be compatible with scsh, Guile, and MIT Scheme:
+file-exists?, file-directory?, file-readable?, file-writable?,
+delete-file, rename-file, create-diretory, and the variable
+home-directory.
+
+Fixed some small bugs, mainly in gnu.math and in load.
+
+Generalize apply to accept an arbitrary Sequence, or a primitive Java
+array.
+
address@hidden Changes from Kawa 1.2 to 1.4
address@hidden
+The codegen package has been renamed gnu.bytecode. The kawa.math package
+has been moved to gnu.math. Both packages have new license: No
+restrictions if you use an unmodified release, but GNU General Public
+License. Let me know if that causes problems. The rest of Kawa still has
+the old license.
+
+Implement defmacro and gentemp.
+
+Implement make-record-type and related functions to create and use new
+record types. A record type is implemented as a java.lang.Class object,
+and this feature depends on the new reflection features of JDK 1.1.
+
+Implement keywords, and extend lambda parameter lists to support
+#!optional #!rest and #!keyword parameters (following DSSSL).
+
+Added more primitives to call arbitrary interface and constructor
+methods.
+
address@hidden Changes from Kawa 1.0 to 1.2
address@hidden
+Added primitives to make it easy to call arbitrary Java methods from
+Scheme.
+
+Exact rational arithetic is now fully implemented. All integer functions
+now believed to correctly handle bignums. Logical operations on exact
+integers have been implemented. These include all the logical functions
+from Guile.
+
+Complex numbers are implemented (except
@{,address@hidden@{sin,cos,address@hidden).
+Quantities (with units) are implemented (as in DSSSL).
+
+Eval is available, as specified for R5RS. Also implemented are
+scheme-report-environment, null-environment, and
+interaction-environment.
+
+Internal define is implemented.
+
+Rough support for multiple threads is implemented.
+
+Moved kawa class to kawa/repl. Merged in kawac (compiler) functionality.
+A 'kawa' shell-script is now created. This is now the preferred
+interface to both the interactive evaluator and the compiler (on
+Unix-like systems).
+
+Now builds "without a snag" using Cafe 1.51 under Win95. (Symantec JIT
+(ver 2.00b19) requires disabling JIT - @code{JAVA_COMPCMD=disable}.)
+Compiles under JDK 1.1 beta (with some warnings).
+
+A testsuite (and testing framework) was added.
+
+Documentation moved to doc directory. There is now an internals
+overview, in doc/kawa-tour.ps.
+
address@hidden Changes since 0.4
address@hidden
+The numeric classes have been re-written. There is partial support for
+bignums (infinite-precision integers), but divide (for example) has not
+been implemented yet. The representation of bignums uses 2's complement,
+where the "big digits" are laid out so as to be compatible with the mpn
+functions of the GNU Multi-Precision library (gmp). (The intent is that
+a future version of Kawa will support an option to use gmp native
+functions for speed.)
+
+The kawa application takes a number of useful command-line switches.
+
+Basically all of R4RS has been implemented. All the essential forms and
+functions are implemented. Almost all of the optional forms are
+implemented. The exceptions are transcript-on, transcript-off, and the
+functions for complex numbers, and fractions (exact non-integer
+rationals).
+
+Loading a source file with load now wraps the entire file in a lambda
+(named "atFileLevel"). This is for better error reporting, and
+consistency with compile-file.
+
address@hidden Changes since 0.3
address@hidden
+The hygienic macros described in the appendix to R4RS are now impemented
+(but only the define-syntax form). They are used to implement the
+standard "do" form.
+
+The R5RS multiple value functions @code{values} and
address@hidden are implemented.
+
+Macros (and primitive syntax) can now be autoloaded as well as
+procedures.
+
+New kawac application compiles to one or more .class files.
+
+Compile time errors include line numbers. Uncaught exceptions cause a
+stack trace that includes .scm line numbers. This makes it more
+practical to debug Kawa with a Java debugger.
+
+Quasiquotation is implemented.
+
+Various minor bug fixes and optimizations.
+
address@hidden Changes since 0.2
address@hidden
+The biggest single change is that Scheme procedures are now compiled to
+Java bytecodes. This is mainly for efficiency, but it also allows us to
+do tail-recursion-elimination in some cases.
+
+The "codegen" library is included. This is a toolkit that handles most
+of the details needed to generate Java bytecode (.class) files.
+
+The internal structure of Kawa has been extensively re-written,
+especially how syntax transforms, eval, and apply are done, largely due
+to the needs for compilation.
+
+Almost all the R4RS procedures are now implemented, except that there
+are still large gaps in Section 6.5 "Numbers".
Added: trunk/js/examples/kawa/version.texi
===================================================================
--- trunk/js/examples/kawa/version.texi (rev 0)
+++ trunk/js/examples/kawa/version.texi 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,4 @@
address@hidden UPDATED 5 July 2017
address@hidden UPDATED-MONTH July 2017
address@hidden EDITION 2.93
address@hidden VERSION 2.93
Added: trunk/js/info.js
===================================================================
--- trunk/js/info.js (rev 0)
+++ trunk/js/info.js 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,1996 @@
+/* info.js - Javascript UI for Texinfo manuals
+ Copyright © 2017 Free Software Foundation, Inc.
+
+ This file is part of GNU Texinfo.
+
+ GNU Texinfo is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ GNU Texinfo is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with GNU Texinfo. If not, see <http://www.gnu.org/licenses/>. */
+
+(function (features, user_config) {
+ "use strict";
+
+ /*-------------------.
+ | Define constants. |
+ `-------------------*/
+
+ /** To override those default parameters, define 'INFO_CONFIG' in the global
+ environment before loading this script. */
+ var config = {
+ EXT: ".html",
+ INDEX_NAME: "index.html",
+ INDEX_ID: "index",
+ MAIN_ANCHORS: ["Top", "SEC_Contents"],
+ WARNING_TIMEOUT: 3000,
+ SCREEN_MIN_WIDTH: 700,
+ hooks: {
+ /** Define a function called after 'DOMContentLoaded' event in
+ the INDEX_NAME context.
+ @type {function (): void}*/
+ on_main_load: null,
+ /** Define a function called after 'DOMContentLoaded' event in
+ the iframe context.
+ @type {(function (): void)} */
+ on_iframe_load: null
+ }
+ };
+
+ /*-------------------.
+ | State Management. |
+ `-------------------*/
+
+ /** A 'store' is an object managing the state of the application and having
+ a dispatch method which accepts actions as parameter. This method is
+ the only way to update the state.
+ @typedef {function (Action): void} Action_consumer
+ @type {{dispatch: Action_consumer, state?: any, listeners?: any[]}}. */
+ var store;
+
+ /** Create a Store that calls its listeners at each state change.
+ @arg {function (Object, Action): Object} reducer
+ @arg {Object} state */
+ function
+ Store (reducer, state)
+ {
+ this.listeners = [];
+ this.reducer = reducer;
+ this.state = state;
+ }
+
+ /** @arg {Action} action */
+ Store.prototype.dispatch = function dispatch (action) {
+ var new_state = this.reducer (this.state, action);
+ if (new_state !== this.state)
+ {
+ this.state = new_state;
+ if (window["INFO_DEBUG"])
+ console.log ("state: ", new_state);
+ this.listeners.forEach (function (listener) {
+ listener (new_state);
+ });
+ }
+ };
+
+ /** Build a store delegate that will forward its actions to a "real"
+ store that can be in a different browsing context. */
+ function
+ Remote_store ()
+ {
+ /* The browsing context containing the real store. */
+ this.delegate = top;
+ }
+
+ /** Dispatch ACTION to the delegate browing context. This method must be
+ used in conjunction of an event listener on "message" events in the
+ delegate browsing context which must forwards ACTION to an actual store.
+ @arg {Action} action */
+ Remote_store.prototype.dispatch = function dispatch (action) {
+ this.delegate.postMessage ({ message_kind: "action", action: action },
"*");
+ };
+
+ /** @typedef {{type: string, [x: string]: any}} Action - Payloads
+ of information meant to be treated by the store which can receive them
+ using the 'store.dispatch' method. */
+
+ /* Place holder for action creators. */
+ var actions = {
+ /** Return an action that makes LINKID the current page.
+ @arg {string} linkid - link identifier
+ @arg {string|false} [history] - method name that will be applied on
+ the 'window.history' object. */
+ set_current_url: function (linkid, history) {
+ if (undef_or_null (history))
+ history = "pushState";
+ return { type: "current-url", url: linkid, history: history };
+ },
+
+ /** Set current URL to the node corresponding to POINTER which is an
+ id refering to a linkid (such as "*TOP*" or "*END*"). */
+ set_current_url_pointer: function (pointer) {
+ return { type: "current-url", pointer: pointer, history: "pushState" };
+ },
+
+ /** @arg {string} dir */
+ navigate: function (dir) {
+ return { type: "navigate", direction: dir, history: "pushState" };
+ },
+
+ /** @arg {{[id: string]: string}} links */
+ cache_links: function (links) {
+ return { type: "cache-links", links: links };
+ },
+
+ /** @arg {NodeListOf<Element>} links */
+ cache_index_links: function (links) {
+ var dict = {};
+ for (var i = 0; i < links.length; i += 1)
+ {
+ var link = links[i];
+ dict[link.textContent] = href_hash (link.getAttribute ("href"));
+ }
+ return { type: "cache-index-links", links: dict };
+ },
+
+ /** Show or hide the help screen. */
+ show_help: function () {
+ return { type: "help", visible: true };
+ },
+
+ /** Make the text input INPUT visible. If INPUT is a falsy value then
+ hide current text input.
+ @arg {string} input */
+ show_text_input: function (input) {
+ return { type: "input", input: input };
+ },
+
+ /** Hide the current current text input. */
+ hide_text_input: function () {
+ return { type: "input", input: null };
+ },
+
+ /** @arg {string} msg */
+ warn: function (msg) {
+ return { type: "warning", msg: msg };
+ },
+
+ /** Search EXP in the whole manual.
+ @arg {RegExp|string} exp*/
+ search: function (exp) {
+ var rgxp;
+ if (typeof exp === "object")
+ rgxp = exp;
+ else if (exp === "")
+ rgxp = null;
+ else
+ rgxp = new RegExp (exp, "i");
+
+ return { type: "search-init", regexp: rgxp, input: exp };
+ }
+ };
+
+ /** Update STATE based on the type of ACTION. This update is purely
+ fonctional since STATE is not modified in place and a new state object
+ is returned instead.
+ @arg {Object} state
+ @arg {Action} action
+ @return {Object} a new state */
+ /* eslint-disable complexity */
+ /* A "big" switch has been preferred over splitting each case in a separate
+ function combined with a dictionary lookup. */
+ function
+ updater (state, action)
+ {
+ var res = Object.assign ({}, state, { action: action });
+ var linkid;
+ switch (action.type)
+ {
+ case "cache-links":
+ {
+ var nodes = Object.assign ({}, state.loaded_nodes);
+ Object
+ .keys (action.links)
+ .forEach (function (key) {
+ if (typeof action.links[key] === "object")
+ nodes[key] = Object.assign ({}, nodes[key], action.links[key]);
+ else
+ nodes[key] = action.links[key];
+ });
+
+ return Object.assign (res, { loaded_nodes: nodes });
+ }
+ case "cache-index-links":
+ {
+ res.index = Object.assign ({}, res.index, action.links);
+ return res;
+ }
+ case "current-url":
+ {
+ linkid = (action.pointer) ?
+ state.loaded_nodes[action.pointer] : action.url;
+
+ res.current = linkid;
+ res.history = action.history;
+ res.text_input = null;
+ res.warning = null;
+ res.help = false;
+ res.focus = false;
+ res.highlight = null;
+ res.loaded_nodes = Object.assign ({}, res.loaded_nodes);
+ res.loaded_nodes[linkid] = res.loaded_nodes[linkid] || {};
+ return res;
+ }
+ case "unfocus":
+ {
+ if (!res.focus)
+ return state;
+ else
+ {
+ res.help = false;
+ res.text_input = null;
+ res.focus = false;
+ return res;
+ }
+ }
+ case "help":
+ {
+ res.help = action.visible;
+ res.focus = true;
+ return res;
+ }
+ case "navigate":
+ {
+ var current = state.current;
+ var link = linkid_split (state.current);
+
+ /* Handle inner 'config.INDEX_NAME' anchors specially. */
+ if (link.pageid === config.INDEX_ID)
+ current = config.INDEX_ID;
+
+ var ids = state.loaded_nodes[current];
+ linkid = ids[action.direction];
+ if (!linkid)
+ {
+ /* When CURRENT is in index but doesn't have the requested
+ direction, ask its corresponding 'pageid'. */
+ var is_index_ref =
+ Object.keys (state.index)
+ .reduce (function (acc, val) {
+ return acc || state.index[val] === current;
+ }, false);
+ if (is_index_ref)
+ {
+ ids = state.loaded_nodes[link.pageid];
+ linkid = ids[action.direction];
+ }
+ }
+
+ if (!linkid)
+ return state;
+ else
+ {
+ res.current = linkid;
+ res.history = action.history;
+ res.text_input = null;
+ res.warning = null;
+ res.help = false;
+ res.highlight = null;
+ res.focus = false;
+ res.loaded_nodes = Object.assign ({}, res.loaded_nodes);
+ res.loaded_nodes[action.url] = res.loaded_nodes[action.url] ||
{};
+ return res;
+ }
+ }
+ case "search-init":
+ {
+ res.search = {
+ regexp: action.regexp || state.search.regexp,
+ input: action.input || state.search.input,
+ status: "ready",
+ current_pageid: linkid_split (state.current).pageid,
+ found: false
+ };
+ res.focus = false;
+ res.help = false;
+ res.text_input = null;
+ res.warning = null;
+ return res;
+ }
+ case "search-query":
+ {
+ res.search = Object.assign ({}, state.search);
+ res.search.status = "searching";
+ return res;
+ }
+ case "search-result":
+ {
+ res.search = Object.assign ({}, state.search);
+ if (action.found)
+ {
+ res.search.status = "done";
+ res.search.found = true;
+ res.current = res.search.current_pageid;
+ res.history = "pushState";
+ res.highlight = res.search.regexp;
+ }
+ else
+ {
+ var fwd = forward_pageid (state, state.search.current_pageid);
+ if (fwd === null)
+ {
+ res.search.status = "done";
+ res.warning = "Search failed: \"" + res.search.input + "\"";
+ res.highlight = null;
+ }
+ else
+ {
+ res.search.current_pageid = fwd;
+ res.search.status = "ready";
+ }
+ }
+ return res;
+ }
+ case "input":
+ {
+ var needs_update = (state.text_input && !action.input)
+ || (!state.text_input && action.input)
+ || (state.text_input && action.input
+ && state.text_input !== action.input);
+
+ if (!needs_update)
+ return state;
+ else
+ {
+ res.focus = Boolean (action.input);
+ res.help = false;
+ res.text_input = action.input;
+ res.warning = null;
+ return res;
+ }
+ }
+ case "iframe-ready":
+ {
+ res.ready = Object.assign ({}, res.ready);
+ res.ready[action.id] = true;
+ return res;
+ }
+ case "echo":
+ {
+ res.echo = action.msg;
+ return res;
+ }
+ case "warning":
+ {
+ res.warning = action.msg;
+ if (action.msg !== null)
+ res.text_input = null;
+ return res;
+ }
+ default:
+ console.error ("no reducer for action type:", action.type);
+ return state;
+ }
+ }
+ /* eslint-enable complexity */
+
+ /*-----------------------.
+ | Context initializers. |
+ `-----------------------*/
+
+ /** Initialize the index page of the manual which manages the state of the
+ application. */
+ function
+ init_index_page ()
+ {
+ /*--------------------------.
+ | Component for help page. |
+ `--------------------------*/
+
+ function
+ Help_page ()
+ {
+ this.id = "help-screen";
+ /* Create help div element.*/
+ var div = document.createElement ("div");
+ div.setAttribute ("hidden", "true");
+ div.classList.add ("modal");
+ div.innerHTML = "\
+<div class=\"modal-content\">\
+<span class=\"close\">×</span>\
+<h2>Keyboard Shortcuts</h2>\
+<table id=\"keyboard-shortcuts\">\
+ <tbody>\
+ <tr><th colspan=\"2\">Moving around</th></tr>\
+ <tr><td><code><b>n / p</b></code></td>\
+ <td>goto the next / previous section</td></tr>\
+ <tr><td><code><b>[ / ]</b></code></td>\
+ <td>goto the next / previous sibling</td></tr>\
+ <tr><td><code><b>< / ></b></code></td>\
+ <td>goto the first / last section</td></tr>\
+ <tr><td><code><b>t</b></code></td><td>goto the first section</td></tr>\
+ <tr><td><code><b>u</b></code></td>\
+ <td>go one level up (parent section)</td></tr>\
+ <tr><td><code><b>l / r</b></code></td>\
+ <td>go back / forward in history.</td></tr>\
+ </tbody>\
+ <tbody>\
+ <tr><th colspan=\"2\">Searching</th></tr>\
+ <tr><td><code><b>i</b></code></td><td>search in the index</td></tr>\
+ <tr><td><code><b>s</b></code></td>\
+ <td>global text search in the manual</td></tr>\
+ <tr><td><code><b>m</b></code></td>\
+ <td>search in current node menu</td></tr>\
+ </tbody>\
+ <tbody>\
+ <tr><th colspan=\"2\">Misc</th></tr>\
+ <tr><td><code><b>?</b></code></td><td>show this help screen</td></tr>\
+ <tr><td><code><b>Esc</b></code></td><td>hide this help screen</td></tr>\
+ </tbody>\
+</table>\
+</div>\
+";
+ var span = div.querySelector (".close");
+ div.addEventListener ("click", function (event) {
+ if (event.target === span || event.target === div)
+ store.dispatch ({ type: "unfocus" });
+ }, false);
+
+ this.element = div;
+ }
+
+ Help_page.prototype.render = function render (state) {
+ if (!state.help)
+ this.element.style.display = "none";
+ else
+ {
+ this.element.style.display = "block";
+ this.element.focus ();
+ }
+ };
+
+ /*---------------------------------.
+ | Components for menu navigation. |
+ `---------------------------------*/
+
+ /** @arg {string} id */
+ function
+ Search_input (id)
+ {
+ this.id = id;
+ this.render = null;
+ this.prompt = document.createTextNode ("Text search" + ": ");
+
+ /* Create input div element.*/
+ var div = document.createElement ("div");
+ div.setAttribute ("hidden", "true");
+ div.appendChild (this.prompt);
+ this.element = div;
+
+ /* Create input element.*/
+ var input = document.createElement ("input");
+ input.setAttribute ("type", "search");
+ this.input = input;
+ this.element.appendChild (input);
+
+ /* Define a special key handler when 'this.input' is focused and
+ visible.*/
+ this.input.addEventListener ("keyup", (function (event) {
+ if (is_escape_key (event.key))
+ store.dispatch ({ type: "unfocus" });
+ else if (event.key === "Enter")
+ store.dispatch (actions.search (this.input.value));
+ event.stopPropagation ();
+ }).bind (this));
+ }
+
+ Search_input.prototype.show = function show () {
+ /* Display previous search. */
+ var search = store.state.search;
+ var input = search && (search.status === "done") && search.input;
+ if (input)
+ this.prompt.textContent = "Text search (default " + input + "): ";
+ this.element.removeAttribute ("hidden");
+ this.input.focus ();
+ };
+
+ Search_input.prototype.hide = function hide () {
+ this.element.setAttribute ("hidden", "true");
+ this.input.value = "";
+ };
+
+ /** @arg {string} id */
+ function
+ Text_input (id)
+ {
+ this.id = id;
+ this.data = null;
+ this.datalist = null;
+ this.render = null;
+
+ /* Create input div element.*/
+ var div = document.createElement ("div");
+ div.setAttribute ("hidden", "true");
+ div.appendChild (document.createTextNode (id + ": "));
+ this.element = div;
+
+ /* Create input element.*/
+ var input = document.createElement ("input");
+ input.setAttribute ("type", "search");
+ input.setAttribute ("list", id + "-data");
+ this.input = input;
+ this.element.appendChild (input);
+
+ /* Define a special key handler when 'this.input' is focused and
+ visible.*/
+ this.input.addEventListener ("keyup", (function (event) {
+ if (is_escape_key (event.key))
+ store.dispatch ({ type: "unfocus" });
+ else if (event.key === "Enter")
+ {
+ var linkid = this.data[this.input.value];
+ if (linkid)
+ store.dispatch (actions.set_current_url (linkid));
+ }
+ event.stopPropagation ();
+ }).bind (this));
+ }
+
+ /* Display a text input for searching through DATA.*/
+ Text_input.prototype.show = function show (data) {
+ if (!features || features.datalistelem)
+ {
+ var datalist = create_datalist (data);
+ datalist.setAttribute ("id", this.id + "-data");
+ this.data = data;
+ this.datalist = datalist;
+ this.element.appendChild (datalist);
+ }
+ this.element.removeAttribute ("hidden");
+ this.input.focus ();
+ };
+
+ Text_input.prototype.hide = function hide () {
+ this.element.setAttribute ("hidden", "true");
+ this.input.value = "";
+ if (this.datalist)
+ {
+ this.datalist.remove ();
+ this.datalist = null;
+ }
+ };
+
+ function
+ Minibuffer ()
+ {
+ /* Create global container.*/
+ var elem = document.createElement ("div");
+ elem.classList.add ("text-input");
+
+ var menu = new Text_input ("menu");
+ menu.render = function (state) {
+ if (state.text_input === "menu")
+ {
+ var current_menu = state.loaded_nodes[state.current].menu;
+ if (current_menu)
+ this.show (current_menu);
+ else
+ store.dispatch (actions.warn ("No menu in this node"));
+ }
+ };
+
+ var index = new Text_input ("index");
+ index.render = function (state) {
+ if (state.text_input === "index")
+ this.show (state.index);
+ };
+
+ var search = new Search_input ("regexp-search");
+ search.render = function (state) {
+ if (state.text_input === "regexp-search")
+ this.show ();
+ };
+
+ elem.appendChild (menu.element);
+ elem.appendChild (index.element);
+ elem.appendChild (search.element);
+
+ /* Create a container for warning when no menu in current page.*/
+ var warn$ = document.createElement ("div");
+ warn$.setAttribute ("hidden", "true");
+ elem.appendChild (warn$);
+
+ this.element = elem;
+ this.menu = menu;
+ this.index = index;
+ this.search = search;
+ this.warn = warn$;
+ this.toid = null;
+ }
+
+ Minibuffer.prototype.render = function render (state) {
+ if (!state.warning)
+ {
+ this.warn.setAttribute ("hidden", "true");
+ this.toid = null;
+ }
+ else if (!this.toid)
+ {
+ console.warn (state.warning);
+ var toid = window.setTimeout (function () {
+ store.dispatch ({ type: "warning", msg: null });
+ }, config.WARNING_TIMEOUT);
+ this.warn.innerHTML = state.warning;
+ this.warn.removeAttribute ("hidden");
+ this.toid = toid;
+ }
+
+ if (!state.text_input || state.warning)
+ {
+ this.menu.hide ();
+ this.index.hide ();
+ this.search.hide ();
+ }
+ else
+ {
+ this.index.render (state);
+ this.menu.render (state);
+ this.search.render (state);
+ }
+ };
+
+ function
+ Echo_area ()
+ {
+ var elem = document.createElement ("div");
+ elem.classList.add ("echo-area");
+ elem.setAttribute ("hidden", "true");
+
+ this.element = elem;
+ this.toid = null;
+ }
+
+ Echo_area.prototype.render = function render (state) {
+ if (!state.echo)
+ {
+ this.element.setAttribute ("hidden", "true");
+ this.toid = null;
+ }
+ else if (!this.toid)
+ {
+ console.info (state.echo);
+ var toid = window.setTimeout (function () {
+ store.dispatch ({ type: "echo", msg: null });
+ }, config.WARNING_TIMEOUT);
+ this.element.innerHTML = state.echo;
+ this.element.removeAttribute ("hidden");
+ this.toid = toid;
+ }
+ };
+
+ /*----------------------------.
+ | Component for the sidebar. |
+ `----------------------------*/
+
+ function
+ Sidebar ()
+ {
+ this.element = document.createElement ("div");
+ this.element.setAttribute ("id", "slider");
+ var div = document.createElement ("div");
+ div.classList.add ("toc-sidebar");
+ var toc = document.querySelector (".contents");
+ toc.remove ();
+
+ /* Move contents of <body> into a a fresh <div> to let the components
+ treat the index page like other iframe page. */
+ var nav = document.createElement ("nav");
+ nav.classList.add ("contents");
+ for (var ch = toc.firstChild; ch; ch = toc.firstChild)
+ nav.appendChild (ch);
+
+ var div$ = document.createElement ("div");
+ div$.classList.add ("toc");
+ div$.appendChild (nav);
+ div.appendChild (div$);
+ this.element.appendChild (div);
+
+ /* Remove table of contents header. */
+ document.querySelector (".contents-heading").remove ();
+ }
+
+ /* Render 'sidebar' according to STATE which is a new state. */
+ Sidebar.prototype.render = function render (state) {
+ /* Update sidebar to highlight the title corresponding to
+ 'state.current'.*/
+ var msg = { message_kind: "update-sidebar", selected: state.current };
+ window.postMessage (msg, "*");
+ };
+
+ /*--------------------------.
+ | Component for the pages. |
+ `--------------------------*/
+
+ /** @arg {HTMLDivElement} index_div */
+ function
+ Pages (index_div)
+ {
+ index_div.setAttribute ("id", config.INDEX_ID);
+ index_div.setAttribute ("node", config.INDEX_ID);
+ index_div.setAttribute ("hidden", "true");
+ this.element = document.createElement ("div");
+ this.element.setAttribute ("id", "sub-pages");
+ this.element.appendChild (index_div);
+ /** @type {string[]} Currently created divs. */
+ this.ids = [config.INDEX_ID];
+ /** @type {string} */
+ this.prev_id = null;
+ /** @type {HTMLElement} */
+ this.prev_div = null;
+ this.prev_search = null;
+ }
+
+ Pages.prototype.add_div = function add_div (pageid) {
+ var div = document.createElement ("div");
+ div.setAttribute ("id", pageid);
+ div.setAttribute ("node", pageid);
+ div.setAttribute ("hidden", "true");
+ this.ids.push (pageid);
+ this.element.appendChild (div);
+ if (linkid_contains_index (pageid))
+ load_page (pageid);
+ };
+
+ Pages.prototype.render = function render (state) {
+ var that = this;
+
+ /* Create div elements for pages corresponding to newly added
+ linkids from 'state.loaded_nodes'.*/
+ Object.keys (state.loaded_nodes)
+ .map (function (id) { return id.replace (/\..*$/, ""); })
+ .filter (function (id) { return !that.ids.includes (id); })
+ .reduce (function (acc, id) {
+ return ((acc.includes (id)) ? acc : acc.concat ([id]));
+ }, [])
+ .forEach (function (id) { return that.add_div (id); });
+
+ /* Blur pages if help screen is on. */
+ this.element.classList[(state.help) ? "add" : "remove"] ("blurred");
+
+ if (state.current !== this.prev_id)
+ {
+ if (this.prev_id)
+ {
+ this.prev_div.setAttribute ("hidden", "true");
+ /* Remove previous highlights. */
+ var old = linkid_split (this.prev_id);
+ var msg = { message_kind: "highlight", regexp: null };
+ post_message (old.pageid, msg);
+ }
+ var div = resolve_page (state.current, true);
+ update_history (state.current, state.history);
+ this.prev_id = state.current;
+ this.prev_div = div;
+ }
+
+ if (state.search
+ && (this.prev_search !== state.search)
+ && state.search.status === "ready")
+ {
+ this.prev_search = state.search;
+ if (state.search.current_pageid === config.INDEX_ID)
+ {
+ window.setTimeout (function () {
+ store.dispatch ({ type: "search-query" });
+ var res = search (document.getElementById (config.INDEX_ID),
+ state.search.regexp);
+ store.dispatch ({ type: "search-result", found: res });
+ }, 0);
+ }
+ else
+ {
+ window.setTimeout (function () {
+ store.dispatch ({ type: "search-query" });
+ var msg = {
+ message_kind: "search",
+ regexp: state.search.regexp,
+ id: state.search.current_pageid
+ };
+ post_message (state.search.current_pageid, msg);
+ }, 0);
+ }
+ }
+
+ /* Update highlight of current page. */
+ if (!state.highlight)
+ {
+ if (state.current === config.INDEX_ID)
+ remove_highlight (document.getElementById (config.INDEX_ID));
+ else
+ {
+ var link = linkid_split (state.current);
+ var msg$ = { message_kind: "highlight", regexp: null };
+ post_message (link.pageid, msg$);
+ }
+ }
+
+ /* Scroll to highlighted search result. */
+ if (state.search
+ && (this.prev_search !== state.search)
+ && state.search.status === "done"
+ && state.search.found === true)
+ {
+ var link$ = linkid_split (state.current);
+ var msg$$ = { message_kind: "scroll-to", hash: "#search-result" };
+ post_message (link$.pageid, msg$$);
+ this.prev_search = state.search;
+ }
+ };
+
+ /*--------------.
+ | Utilitaries. |
+ `--------------*/
+
+ /** Load PAGEID.
+ @arg {string} pageid */
+ function
+ load_page (pageid)
+ {
+ var div = resolve_page (pageid, false);
+ /* Making the iframe visible triggers the load of the iframe DOM. */
+ if (div.hasAttribute ("hidden"))
+ {
+ div.removeAttribute ("hidden");
+ div.setAttribute ("hidden", "true");
+ }
+ }
+
+ /** Return the div element that correspond to LINKID. If VISIBLE is true
+ then display the div and position the corresponding iframe to the
+ anchor specified by LINKID.
+ @arg {string} linkid - link identifier
+ @arg {boolean} [visible]
+ @return {HTMLElement} the div element. */
+ function
+ resolve_page (linkid, visible)
+ {
+ var msg;
+ var link = linkid_split (linkid);
+ var pageid = link.pageid;
+ var div = document.getElementById (link.pageid);
+ if (!div)
+ {
+ msg = "no iframe container correspond to identifier: " + pageid;
+ throw new ReferenceError (msg);
+ }
+
+ /* Create iframe if necessary unless the div is refering to the Index
+ page. */
+ if ((pageid === config.INDEX_ID) && visible)
+ {
+ div.removeAttribute ("hidden");
+ /* Unlike iframes, Elements are unlikely to be scrollable (CSSOM
+ Scroll-behavior), so choose an arbitrary element inside "index"
+ div and at the top of it. */
+ document.getElementById ("icon-bar").scrollIntoView ();
+ }
+ else
+ {
+ var iframe = div.querySelector ("iframe");
+ if (!iframe)
+ {
+ iframe = document.createElement ("iframe");
+ iframe.classList.add ("node");
+ iframe.setAttribute ("src", linkid_to_url (pageid));
+ div.appendChild (iframe);
+ iframe.addEventListener ("load", function () {
+ store.dispatch ({ type: "iframe-ready", id: pageid });
+ }, false);
+ }
+ if (visible)
+ {
+ div.removeAttribute ("hidden");
+ msg = { message_kind: "scroll-to", hash: link.hash };
+ post_message (pageid, msg);
+ }
+ }
+
+ return div;
+ }
+
+ /** Create a datalist element containing option elements corresponding
+ to the keys in MENU. */
+ function
+ create_datalist (menu)
+ {
+ var datalist = document.createElement ("datalist");
+ Object.keys (menu)
+ .sort ()
+ .forEach (function (title) {
+ var opt = document.createElement ("option");
+ opt.setAttribute ("value", title);
+ datalist.appendChild (opt);
+ });
+ return datalist;
+ }
+
+ /** Mutate the history of page navigation. Store LINKID in history
+ state, The actual way to store LINKID depends on HISTORY_MODE.
+ @arg {string} linkid
+ @arg {string} history_mode */
+ function
+ update_history (linkid, history_mode)
+ {
+ var method = window.history[history_mode];
+ if (method)
+ {
+ /* Pretend that the current page is the one corresponding to the
+ LINKID iframe. Handle errors since changing the visible file
+ name can fail on some browsers with the "file:" protocol. */
+ var visible_url =
+ dirname (window.location.pathname) + linkid_to_url (linkid);
+ try
+ {
+ method.call (window.history, linkid, null, visible_url);
+ }
+ catch (err)
+ {
+ /* Fallback to changing only the hash part which is safer. */
+ visible_url = window.location.pathname;
+ if (linkid !== config.INDEX_ID)
+ visible_url += ("#" + linkid);
+ method.call (window.history, linkid, null, visible_url);
+ }
+ }
+ }
+
+ /** Send MSG to the browsing context corresponding to PAGEID. This is a
+ wrapper around 'Window.postMessage' which ensures that MSG is sent
+ after PAGEID is loaded.
+ @arg {string} pageid
+ @arg {any} msg */
+ function
+ post_message (pageid, msg)
+ {
+ if (pageid === config.INDEX_ID)
+ window.postMessage (msg, "*");
+ else
+ {
+ load_page (pageid);
+ var iframe = document.getElementById (pageid)
+ .querySelector ("iframe");
+ /* Semantically this would be better to use "promises" however
+ they are not available in IE. */
+ if (store.state.ready[pageid])
+ iframe.contentWindow.postMessage (msg, "*");
+ else
+ {
+ iframe.addEventListener ("load", function handler () {
+ this.contentWindow.postMessage (msg, "*");
+ this.removeEventListener ("load", handler, false);
+ }, false);
+ }
+ }
+ }
+
+ /*--------------------------------------------
+ | Event handlers for the top-level context. |
+ `-------------------------------------------*/
+
+ /* Initialize the top level 'config.INDEX_NAME' DOM. */
+ function
+ on_load ()
+ {
+ fix_links (document.links);
+ add_icons ();
+ document.body.classList.add ("mainbar");
+
+ /* Move contents of <body> into a a fresh <div> to let the components
+ treat the index page like other iframe page. */
+ var index_div = document.createElement ("div");
+ for (var ch = document.body.firstChild; ch; ch =
document.body.firstChild)
+ index_div.appendChild (ch);
+
+ /* Aggregation of all the sub-components. */
+ var components = {
+ element: document.body,
+ components: [],
+
+ add: function add (component) {
+ this.components.push (component);
+ this.element.appendChild (component.element);
+ },
+
+ render: function render (state) {
+ this.components
+ .forEach (function (cmpt) { cmpt.render (state); });
+
+ /* Ensure that focus is on the current node unless some component is
+ focused. */
+ if (!state.focus)
+ {
+ var link = linkid_split (state.current);
+ var elem = document.getElementById (link.pageid);
+ if (link.pageid !== config.INDEX_ID)
+ elem.querySelector ("iframe").focus ();
+ else
+ {
+ /* Move the focus to top DOM. */
+ document.documentElement.focus ();
+ /* Allow the spacebar scroll in the main page to work. */
+ elem.focus ();
+ }
+ }
+ }
+ };
+
+ components.add (new Pages (index_div));
+ components.add (new Sidebar ());
+ components.add (new Help_page ());
+ components.add (new Minibuffer ());
+ components.add (new Echo_area ());
+ store.listeners.push (components.render.bind (components));
+
+ if (window.location.hash)
+ {
+ var linkid = normalize_hash (window.location.hash);
+ store.dispatch (actions.set_current_url (linkid, "replaceState"));
+ }
+
+ /* Retrieve NEXT link and local menu. */
+ var links = {};
+ links[config.INDEX_ID] = navigation_links (document);
+ store.dispatch (actions.cache_links (links));
+ store.dispatch ({ type: "iframe-ready", id: config.INDEX_ID });
+ store.dispatch ({
+ type: "echo",
+ msg: "Welcome to Texinfo documentation viewer 6.1, type '?' for help."
+ });
+
+ /* Call user hook. */
+ if (config.hooks.on_main_load)
+ config.hooks.on_main_load ();
+ }
+
+ /* Handle messages received via the Message API.
+ @arg {MessageEvent} event */
+ function
+ on_message (event)
+ {
+ var data = event.data;
+ if (data.message_kind === "action")
+ {
+ /* Follow up actions to the store. */
+ store.dispatch (data.action);
+ }
+ }
+
+ /* Event handler for 'popstate' events. */
+ function
+ on_popstate (event)
+ {
+ /* When EVENT.STATE is 'null' it means that the user has manually
+ changed the hash part of the URL bar. */
+ var linkid = (event.state === null) ?
+ normalize_hash (window.location.hash) : event.state;
+ store.dispatch (actions.set_current_url (linkid, false));
+ }
+
+ return {
+ on_load: on_load,
+ on_message: on_message,
+ on_popstate: on_popstate
+ };
+ }
+
+ /** Initialize the iframe which contains the lateral table of content. */
+ function
+ init_sidebar ()
+ {
+ /* Keep children but remove grandchildren (Exception: don't remove
+ anything on the current page; however, that's not a problem in the Kawa
+ manual). */
+ function
+ hide_grand_child_nodes (ul, excluded)
+ {
+ var lis = ul.children;
+ for (var i = 0; i < lis.length; i += 1)
+ {
+ if (lis[i] === excluded)
+ continue;
+ var first = lis[i].firstElementChild;
+ if (first && first.matches ("ul"))
+ hide_grand_child_nodes (first);
+ else if (first && first.matches ("a"))
+ {
+ var ul$ = first && first.nextElementSibling;
+ if (ul$)
+ ul$.setAttribute ("toc-detail", "yes");
+ }
+ }
+ }
+
+ /** Make the parent of ELEMS visible.
+ @arg {HTMLElement} elem */
+ function
+ mark_parent_elements (elem)
+ {
+ if (elem && elem.parentElement && elem.parentElement.parentElement)
+ {
+ var pparent = elem.parentElement.parentElement;
+ for (var sib = pparent.firstElementChild; sib;
+ sib = sib.nextElementSibling)
+ {
+ if (sib !== elem.parentElement
+ && sib.firstElementChild
+ && sib.firstElementChild.nextElementSibling)
+ {
+ sib.firstElementChild
+ .nextElementSibling
+ .setAttribute ("toc-detail", "yes");
+ }
+ }
+ }
+ }
+
+ /** Scan ToC entries to see which should be hidden.
+ @arg {HTMLElement} elem
+ @arg {string} linkid */
+ function
+ scan_toc (elem, linkid)
+ {
+ /** @type {Element} */
+ var res;
+ var url = with_sidebar_query (linkid_to_url (linkid));
+
+ /** Set CURRENT to the node corresponding to URL linkid.
+ @arg {Element} elem */
+ function
+ find_current (elem)
+ {
+ /* XXX: No template literals for IE compatibility. */
+ if (elem.matches ("a[href=\"" + url + "\"]"))
+ {
+ elem.setAttribute ("toc-current", "yes");
+ var sib = elem.nextElementSibling;
+ if (sib && sib.matches ("ul"))
+ hide_grand_child_nodes (sib);
+ res = elem;
+ }
+ }
+
+ var ul = elem.querySelector ("ul");
+ if (linkid === config.INDEX_ID)
+ {
+ hide_grand_child_nodes (ul);
+ res = elem.querySelector ("a[name=\"" + linkid + "\"]");
+ }
+ else
+ {
+ depth_first_walk (ul, find_current, Node.ELEMENT_NODE);
+ /* Mark every parent node. */
+ var current = res;
+ while (current && current !== ul)
+ {
+ mark_parent_elements (current);
+ /* XXX: Special case for manuals with '@part' commands. */
+ if (current.parentElement === ul)
+ hide_grand_child_nodes (ul, current);
+ current = current.parentElement;
+ }
+ }
+ return res;
+ }
+
+ /* Build the global dictionary containing navigation links from NAV. NAV
+ must be an 'ul' DOM element containing the table of content of the
+ manual. */
+ function
+ create_link_dict (nav)
+ {
+ var prev_id = config.INDEX_ID;
+ var links = {};
+
+ function
+ add_link (elem)
+ {
+ if (elem.matches ("a") && elem.hasAttribute ("href"))
+ {
+ var id = href_hash (elem.getAttribute ("href"));
+ links[prev_id] =
+ Object.assign ({}, links[prev_id], { forward: id });
+ links[id] = Object.assign ({}, links[id], { backward: prev_id });
+ prev_id = id;
+ }
+ }
+
+ depth_first_walk (nav, add_link, Node.ELEMENT_NODE);
+ /* Add a reference to the first and last node of the manual. */
+ links["*TOP*"] = config.INDEX_ID;
+ links["*END*"] = prev_id;
+ return links;
+ }
+
+ /* Add a link from the sidebar to the main index file. ELEM is the first
+ sibling of the newly created header. */
+ function
+ add_header (elem)
+ {
+ var h1 = document.querySelector ("h1.settitle");
+ if (h1)
+ {
+ var header = document.createElement ("header");
+ var a = document.createElement ("a");
+ a.setAttribute ("href", config.INDEX_NAME);
+ a.setAttribute ("name", config.INDEX_ID);
+ header.appendChild (a);
+ var div = document.createElement ("div");
+ a.appendChild (div);
+ var span = document.createElement ("span");
+ span.textContent = h1.textContent;
+ div.appendChild (span);
+ elem.parentElement.insertBefore (header, elem);
+ }
+ }
+
+ /*------------------------------------------
+ | Event handlers for the sidebar context. |
+ `-----------------------------------------*/
+
+ /* Initialize TOC_FILENAME which must be loaded in the context of an
+ iframe. */
+ function
+ on_load ()
+ {
+ var toc_div = document.getElementById ("slider");
+ add_header (toc_div.querySelector (".toc"));
+
+ /* Specify the base URL to use for all relative URLs. */
+ /* FIXME: Add base also for sub-pages. */
+ var base = document.createElement ("base");
+ base.setAttribute ("href",
+ window.location.href.replace (/[/][^/]*$/, "/"));
+ document.head.appendChild (base);
+
+ scan_toc (toc_div, config.INDEX_NAME);
+
+ /* Get 'backward' and 'forward' link attributes. */
+ var dict = create_link_dict (toc_div.querySelector ("nav.contents ul"));
+ store.dispatch (actions.cache_links (dict));
+ }
+
+ /* Handle messages received via the Message API. */
+ function
+ on_message (event)
+ {
+ var data = event.data;
+ if (data.message_kind === "update-sidebar")
+ {
+ var toc_div = document.getElementById ("slider");
+
+ /* Reset previous calls to 'scan_toc'. */
+ depth_first_walk (toc_div, function clear_toc_styles (elem) {
+ elem.removeAttribute ("toc-detail");
+ elem.removeAttribute ("toc-current");
+ }, Node.ELEMENT_NODE);
+
+ /* Remove the hash part for the main page. */
+ var pageid = linkid_split (data.selected).pageid;
+ var selected = (pageid === config.INDEX_ID) ? pageid : data.selected;
+ /* Highlight the current LINKID in the table of content. */
+ var elem = scan_toc (toc_div, selected);
+ if (elem)
+ elem.scrollIntoView (true);
+ }
+ }
+
+ return {
+ on_load: on_load,
+ on_message: on_message
+ };
+ }
+
+ /** Initialize iframes which contain pages of the manual. */
+ function
+ init_iframe ()
+ {
+ /* Initialize the DOM for generic pages loaded in the context of an
+ iframe. */
+ function
+ on_load ()
+ {
+ fix_links (document.links);
+ var links = {};
+ var linkid = basename (window.location.pathname, /[.]x?html$/);
+ links[linkid] = navigation_links (document);
+ store.dispatch (actions.cache_links (links));
+
+ if (linkid_contains_index (linkid))
+ {
+ /* Scan links that should be added to the index. */
+ var index_links = document.querySelectorAll ("td[valign=top] a");
+ store.dispatch (actions.cache_index_links (index_links));
+ }
+
+ add_icons ();
+
+ /* Call user hook. */
+ if (config.hooks.on_iframe_load)
+ config.hooks.on_iframe_load ();
+ }
+
+ /* Handle messages received via the Message API. */
+ function
+ on_message (event)
+ {
+ var data = event.data;
+ if (data.message_kind === "highlight")
+ remove_highlight (document.body);
+ else if (data.message_kind === "search")
+ {
+ var found = search (document.body, data.regexp);
+ store.dispatch ({ type: "search-result", found: found });
+ }
+ else if (data.message_kind === "scroll-to")
+ {
+ /* Scroll to the anchor corresponding to HASH. */
+ if (data.hash)
+ window.location.replace (data.hash);
+ else
+ window.scroll (0, 0);
+ }
+ }
+
+ return {
+ on_load: on_load,
+ on_message: on_message
+ };
+ }
+
+ /*-------------------------
+ | Common event handlers. |
+ `------------------------*/
+
+ /** Handle click events. */
+ function
+ on_click (event)
+ {
+ for (var target = event.target; target !== null; target =
target.parentNode)
+ {
+ if ((target instanceof Element) && target.matches ("a"))
+ {
+ var href = target.getAttribute ("href");
+ if (href && !absolute_url_p (href))
+ {
+ var linkid = href_hash (href) || config.INDEX_ID;
+ store.dispatch (actions.set_current_url (linkid));
+ event.preventDefault ();
+ event.stopPropagation ();
+ return;
+ }
+ }
+ }
+ }
+
+ /** Handle unload events. */
+ function
+ on_unload ()
+ {
+ /* Cross origin requests are not supported in file protocol. */
+ if (window.location.protocol !== "file:")
+ {
+ var request = new XMLHttpRequest ();
+ request.open ("GET", "(WINDOW-CLOSED)");
+ request.send (null);
+ }
+ }
+
+ /** Handle Keyboard 'keyup' events.
+ @arg {KeyboardEvent} event */
+ function
+ on_keyup (event)
+ {
+ if (is_escape_key (event.key))
+ store.dispatch ({ type: "unfocus" });
+ else
+ {
+ var val = on_keyup.dict[event.key];
+ if (val)
+ {
+ if (typeof val === "function")
+ val ();
+ else
+ store.dispatch (val);
+ }
+ }
+ }
+
+ /* Associate an Event 'key' property to an action or a thunk. */
+ on_keyup.dict = {
+ i: actions.show_text_input ("index"),
+ l: window.history.back.bind (window.history),
+ m: actions.show_text_input ("menu"),
+ n: actions.navigate ("next"),
+ p: actions.navigate ("prev"),
+ r: window.history.forward.bind (window.history),
+ s: actions.show_text_input ("regexp-search"),
+ t: actions.set_current_url_pointer ("*TOP*"),
+ u: actions.navigate ("up"),
+ "]": actions.navigate ("forward"),
+ "[": actions.navigate ("backward"),
+ "<": actions.set_current_url_pointer ("*TOP*"),
+ ">": actions.set_current_url_pointer ("*END*"),
+ "?": actions.show_help ()
+ };
+
+ /** Some standard methods used in this script might not be implemented by
+ the current browser. If that is the case then augment the prototypes
+ appropriately. */
+ function
+ register_polyfills ()
+ {
+ function
+ includes (search, start)
+ {
+ start = start || 0;
+ return ((start + search.length) <= this.length)
+ && (this.indexOf (search, start) !== -1);
+ }
+
+ /* eslint-disable no-extend-native */
+ if (!Array.prototype.includes)
+ Array.prototype.includes = includes;
+
+ if (!String.prototype.includes)
+ String.prototype.includes = includes;
+
+ if (!String.prototype.endsWith)
+ {
+ String.prototype.endsWith = function endsWith (search, position) {
+ var subject_string = this.toString ();
+ if (typeof position !== "number"
+ || !isFinite (position)
+ || Math.floor (position) !== position
+ || position > subject_string.length)
+ position = subject_string.length;
+
+ position -= search.length;
+ var last_index = subject_string.lastIndexOf (search, position);
+ return last_index !== -1 && last_index === position;
+ };
+ }
+
+ if (!Element.prototype.matches)
+ {
+ Element.prototype.matches = Element.prototype["matchesSelector"]
+ || Element.prototype["mozMatchesSelector"]
+ || Element.prototype["mozMatchesSelector"]
+ || Element.prototype["msMatchesSelector"]
+ || Element.prototype["webkitMatchesSelector"]
+ || function element_matches (str) {
+ var document = (this.document || this.ownerDocument);
+ var matches = document.querySelectorAll (str);
+ var i = matches.length;
+ while ((i -= 1) >= 0 && matches.item (i) !== this);
+ return i > -1;
+ };
+ }
+
+ if (typeof Object.assign != "function")
+ {
+ Object.assign = function assign (target) {
+ if (undef_or_null (target))
+ throw new TypeError ("Cannot convert undefined or null to object");
+
+ var to = Object (target);
+ for (var index = 1; index < arguments.length; index += 1)
+ {
+ var next_source = arguments[index];
+ if (undef_or_null (next_source))
+ continue;
+ for (var key in next_source)
+ {
+ /* Avoid bugs when hasOwnProperty is shadowed. */
+ if (Object.prototype.hasOwnProperty.call (next_source, key))
+ to[key] = next_source[key];
+ }
+ }
+ return to;
+ };
+ }
+
+ (function (protos) {
+ protos.forEach (function (proto) {
+ if (!proto.hasOwnProperty ("remove"))
+ {
+ Object.defineProperty (proto, "remove", {
+ configurable: true,
+ enumerable: true,
+ writable: true,
+ value: function value () {
+ this.parentNode.removeChild (this);
+ }
+ });
+ }
+ });
+ } ([Element.prototype, CharacterData.prototype, DocumentType.prototype]));
+ /* eslint-enable no-extend-native */
+ }
+
+ /*---------------------.
+ | Common utilitaries. |
+ `---------------------*/
+
+ /** Check portably if KEY correspond to "Escape" key value.
+ @arg {string} key */
+ function
+ is_escape_key (key)
+ {
+ /* In Internet Explorer 9 and Firefox 36 and earlier, the Esc key
+ returns "Esc" instead of "Escape". */
+ return key === "Escape" || key === "Esc";
+ }
+
+ /** Check if OBJ is equal to 'undefined' or 'null'. */
+ function
+ undef_or_null (obj)
+ {
+ return (obj === null || typeof obj === "undefined");
+ }
+
+ /** Return a relative URL corresponding to HREF, which refers to an anchor
+ of 'config.INDEX_NAME'. HREF must be a USVString representing an
+ absolute or relative URL. For example "foo/bar.html" will return
+ "config.INDEX_NAME#bar".
+
+ @arg {string} href.*/
+ function
+ with_sidebar_query (href)
+ {
+ if (basename (href) === config.INDEX_NAME)
+ return config.INDEX_NAME;
+ else
+ {
+ /* XXX: Do not use the URL API for IE portability. */
+ var url = with_sidebar_query.url;
+ url.setAttribute ("href", href);
+ var new_hash = "#" + basename (url.pathname, /[.]x?html/);
+ /* XXX: 'new_hash !== url.hash' is a workaround to work with links
+ produced by makeinfo which link to an anchor element in a page
+ instead of directly to the page. */
+ if (url.hash && new_hash !== url.hash)
+ new_hash += ("." + url.hash.slice (1));
+ return config.INDEX_NAME + new_hash;
+ }
+ }
+
+ /* Use the same DOM element for every function call. */
+ with_sidebar_query.url = document.createElement ("a");
+
+ /** Modify LINKS to handle the iframe based navigation properly. Relative
+ links will be opened inside the corresponding iframe and absolute links
+ will be opened in a new tab. If ID is true then define an "id"
+ attribute with a linkid value for relative links.
+
+ @typedef {HTMLAnchorElement|HTMLAreaElement} Links
+ @arg {Links[]|HTMLCollectionOf<Links>} links
+ @arg {boolean} [id]
+ @return void */
+ function
+ fix_links (links, id)
+ {
+ for (var i = 0; i < links.length; i += 1)
+ {
+ var link = links[i];
+ var href = link.getAttribute ("href");
+ if (!href)
+ continue;
+ else if (absolute_url_p (href))
+ link.setAttribute ("target", "_blank");
+ else
+ {
+ var href$ = with_sidebar_query (href);
+ link.setAttribute ("href", href$);
+ if (id)
+ {
+ var linkid = (href$ === config.INDEX_NAME) ?
+ config.INDEX_ID : href_hash (href$);
+ link.setAttribute ("id", linkid);
+ }
+ }
+ }
+ }
+
+ /** Convert HASH which is something that can be found 'Location.hash' to a
+ "linkid" which can be handled in our model.
+ @arg {string} hash
+ @return {string} linkid */
+ function
+ normalize_hash (hash)
+ {
+ var text = hash.slice (1);
+ /* Some anchor elements are present in 'config.INDEX_NAME' and we need to
+ handle link to them specially (i.e. not try to find their corresponding
+ iframe).*/
+ if (config.MAIN_ANCHORS.includes (text))
+ return config.INDEX_ID + "." + text;
+ else
+ return text;
+ }
+
+ /** Return an object composed of the filename and the anchor of LINKID.
+ LINKID can have the form "foobar.anchor" or just "foobar".
+ @arg {string} linkid
+ @return {{pageid: string, hash: string}} */
+ function
+ linkid_split (linkid)
+ {
+ if (!linkid.includes ("."))
+ return { pageid: linkid, hash: "" };
+ else
+ {
+ var ref = linkid.match (/^(.+)\.(.*)$/).slice (1);
+ return { pageid: ref[0], hash: "#" + ref[1] };
+ }
+ }
+
+ /** Convert LINKID which has the form "foobar.anchor" or just "foobar", to
+ an URL of the form `foobar${config.EXT}#anchor`.
+ @arg {string} linkid */
+ function
+ linkid_to_url (linkid)
+ {
+ if (linkid === config.INDEX_ID)
+ return config.INDEX_NAME;
+ else
+ {
+ var link = linkid_split (linkid);
+ return link.pageid + config.EXT + link.hash;
+ }
+ }
+
+ /** Check if 'URL' is an absolute URL. Return true if this is the case
+ otherwise return false. 'URL' must be a USVString representing a valid
+ URL. */
+ function
+ absolute_url_p (url)
+ {
+ if (typeof url !== "string")
+ throw new TypeError ("'" + url + "' is not a string");
+
+ return url.includes (":");
+ }
+
+ /** Return PATHNAME with any leading directory components removed. If
+ specified, also remove a trailing SUFFIX. */
+ function
+ basename (pathname, suffix)
+ {
+ var res = pathname.replace (/.*[/]/, "");
+ if (!suffix)
+ return res;
+ else if (suffix instanceof RegExp)
+ return res.replace (suffix, "");
+ else /* typeof SUFFIX === "string" */
+ return res.replace (new RegExp ("[.]" + suffix), "");
+ }
+
+ /** Strip last component from PATHNAME and keep the trailing slash. For
+ example if PATHNAME is "/foo/bar/baz.html" then return "/foo/bar/".
+ @arg {string} pathname */
+ function
+ dirname (pathname)
+ {
+ var res = pathname.match (/\/?.*\//);
+ if (res)
+ return res[0];
+ else
+ throw new Error ("'location.pathname' is not recognized");
+ }
+
+ /** Apply FUNC to each nodes in the NODE subtree. The walk follows a depth
+ first algorithm. Only consider the nodes of type NODE_TYPE. */
+ function
+ depth_first_walk (node, func, node_type)
+ {
+ if (!node_type || (node.nodeType === node_type))
+ func (node);
+
+ for (var child = node.firstChild; child; child = child.nextSibling)
+ depth_first_walk (child, func, node_type);
+ }
+
+ /** Return the hash part of HREF without the '#' prefix. HREF must be a
+ string. If there is no hash part in HREF then return the empty
+ string. */
+ function
+ href_hash (href)
+ {
+ if (typeof href !== "string")
+ throw new TypeError (href + " is not a string");
+
+ if (href.includes ("#"))
+ return href.replace (/.*#/, "");
+ else
+ return "";
+ }
+
+ /** Check if LINKID corresponds to a page containing index links. */
+ function
+ linkid_contains_index (linkid)
+ {
+ return linkid.match (/^.*-index$/i);
+ }
+
+ /** Retrieve PREV, NEXT, and UP links, and local menu from CONTENT and
+ return an object containing references to those links. CONTENT must be
+ an object implementing the ParentNode interface (Element,
+ Document...). */
+ function
+ navigation_links (content)
+ {
+ var links = content.querySelectorAll ("a[accesskey][href]");
+ var res = {};
+ /* links have the form MAIN_FILE.html#FRAME-ID. For convenience
+ only store FRAME-ID. */
+ for (var i = 0; i < links.length; i += 1)
+ {
+ var link = links[i];
+ var nav_id = navigation_links.dict[link.getAttribute ("accesskey")];
+ if (nav_id)
+ {
+ var href = basename (link.getAttribute ("href"));
+ if (href === config.INDEX_NAME)
+ res[nav_id] = config.INDEX_ID;
+ else
+ res[nav_id] = href_hash (href);
+ }
+ else /* this link is part of local table of content. */
+ {
+ res.menu = res.menu || {};
+ res.menu[link.text] = href_hash (link.getAttribute ("href"));
+ }
+ }
+
+ return res;
+ }
+
+ navigation_links.dict = { n: "next", p: "prev", u: "up" };
+
+ function
+ add_icons ()
+ {
+ var div = document.createElement ("div");
+ div.setAttribute ("id", "icon-bar");
+ var span = document.createElement ("span");
+ span.innerHTML = "?";
+ span.classList.add ("icon");
+ span.addEventListener ("click", function () {
+ store.dispatch (actions.show_help ());
+ }, false);
+ div.appendChild (span);
+ document.body.insertBefore (div, document.body.firstChild);
+ }
+
+ /** Check if ELEM matches SEARCH
+ @arg {Element} elem
+ @arg {RegExp} rgxp
+ @return {boolean} */
+ function
+ search (elem, rgxp)
+ {
+ /** @type {Text} */
+ var text = null;
+
+ /** @arg {Text} node */
+ function
+ find (node)
+ {
+ if (rgxp.test (node.textContent))
+ {
+ /* Ignore previous match. */
+ var prev = node.parentElement.matches ("span.highlight");
+ text = (prev) ? null : (text || node);
+ }
+ }
+
+ depth_first_walk (elem, find, Node.TEXT_NODE);
+ remove_highlight (elem);
+ if (!text)
+ return false;
+ else
+ {
+ highlight_text (rgxp, text);
+ return true;
+ }
+ }
+
+ /** Find the pageid corresponding to forward direction.
+ @arg {any} state
+ @arg {string} linkid
+ @return {string} the forward pageid */
+ function
+ forward_pageid (state, linkid)
+ {
+ var data = state.loaded_nodes[linkid];
+ if (!data)
+ throw new Error ("page not loaded: " + linkid);
+ else if (!data.forward)
+ return null;
+ else
+ {
+ var cur = linkid_split (linkid);
+ var fwd = linkid_split (data.forward);
+ if (!fwd.hash && fwd.pageid !== cur.pageid)
+ return fwd.pageid;
+ else
+ return forward_pageid (state, data.forward);
+ }
+ }
+
+ /** Highlight text in NODE which match RGXP.
+ @arg {RegExp} rgxp
+ @arg {Text} node */
+ function
+ highlight_text (rgxp, node)
+ {
+ /* Skip elements corresponding to highlighted words to avoid infinite
+ recursion. */
+ if (node.parentElement.matches ("span.highlight"))
+ return;
+
+ var matches = rgxp.exec (node.textContent);
+ if (matches)
+ {
+ /* Create an highlighted element containing first match. */
+ var span = document.createElement ("span");
+ span.appendChild (document.createTextNode (matches[0]));
+ span.setAttribute ("id", "search-result");
+ span.classList.add ("highlight");
+
+ var right_node = node.splitText (matches.index);
+ /* Remove first match from right node. */
+ right_node.textContent = right_node.textContent
+ .slice (matches[0].length);
+ node.parentElement.insertBefore (span, right_node);
+ }
+ }
+
+ /** Remove every highlighted elements and inline their text content.
+ @arg {Element} elem */
+ function
+ remove_highlight (elem)
+ {
+ var spans = elem.getElementsByClassName ("highlight");
+ /* Replace spans with their inner text node. */
+ while (spans.length > 0)
+ {
+ var span = spans[0];
+ var parent = span.parentElement;
+ parent.replaceChild (span.firstChild, span);
+ }
+ }
+
+ /*--------------.
+ | Entry point. |
+ `--------------*/
+
+ /** Depending on the role of the document launching this script, different
+ event handlers are registered. This script can be used in the context
of:
+
+ - the index page of the manual which manages the state of the application
+ - the iframe which contains the lateral table of content
+ - other iframes which contain other pages of the manual
+
+ This is done to allow referencing the same script inside every HTML page.
+ This has the benefits of reducing the number of HTTP requests required to
+ fetch the Javascript code and simplifying the work of the Texinfo HTML
+ converter. */
+
+ /* Display MSG bail out message portably. */
+ function
+ error (msg)
+ {
+ /* XXX: This code needs to be highly portable.
+ Check <https://quirksmode.org/dom/core/> for details. */
+ return function () {
+ var div = document.createElement ("div");
+ div.setAttribute ("class", "error");
+ div.innerHTML = msg;
+ var elem = document.body.firstChild;
+ document.body.insertBefore (div, elem);
+ window.setTimeout (function () {
+ document.body.removeChild (div);
+ }, config.WARNING_TIMEOUT);
+ };
+ }
+
+ /* Check if current browser supports the minimum requirements required for
+ properly using this script, otherwise bails out. */
+ if (features && !(features.es5
+ && features.classlist
+ && features.eventlistener
+ && features.hidden
+ && features.history
+ && features.postmessage
+ && features.queryselector))
+ {
+ window.onload = error ("'info.js' is not compatible with this browser");
+ return;
+ }
+
+ /* Until we have a responsive design implemented, fallback to basic
+ HTML navigation for small screen. */
+ if (window.screen.availWidth < config.SCREEN_MIN_WIDTH)
+ {
+ window.onload =
+ error ("screen width is too small to display the table of content");
+ return;
+ }
+
+ register_polyfills ();
+ /* Let the config provided by the user mask the default one. */
+ config = Object.assign (config, user_config);
+
+ var inside_iframe = top !== window;
+ var inside_index_page = window.location.pathname === config.INDEX_NAME
+ || window.location.pathname.endsWith ("/" + config.INDEX_NAME)
+ || window.location.pathname.endsWith ("/");
+
+ if (inside_index_page)
+ {
+ var initial_state = {
+ /* Dictionary associating page ids to next, prev, up, forward,
+ backward link ids. */
+ loaded_nodes: {},
+ /* Dictionary associating keyword to linkids. */
+ index: {},
+ /* page id of the current page. */
+ current: config.INDEX_ID,
+ /* dictionary associating a page id to a boolean. */
+ ready: {},
+ /* Current mode for handling history. */
+ history: "replaceState",
+ /* Define the name of current text input. */
+ text_input: null
+ };
+
+ store = new Store (updater, initial_state);
+ var index = init_index_page ();
+ var sidebar = init_sidebar ();
+ window.addEventListener ("DOMContentLoaded", function () {
+ index.on_load ();
+ sidebar.on_load ();
+ }, false);
+ window.addEventListener ("message", index.on_message, false);
+ window.addEventListener ("message", sidebar.on_message, false);
+ window.onpopstate = index.on_popstate;
+ }
+ else if (inside_iframe)
+ {
+ store = new Remote_store ();
+ var iframe = init_iframe ();
+ window.addEventListener ("DOMContentLoaded", iframe.on_load, false);
+ window.addEventListener ("message", iframe.on_message, false);
+ }
+ else
+ {
+ /* Jump to 'config.INDEX_NAME' and adapt the selected iframe. */
+ window.location.replace (with_sidebar_query (window.location.href));
+ }
+
+ /* Register common event handlers. */
+ window.addEventListener ("beforeunload", on_unload, false);
+ window.addEventListener ("click", on_click, false);
+ /* XXX: handle 'keyup' event instead of 'keypress' since Chromium
+ doesn't handle the 'Escape' key properly. See
+ https://bugs.chromium.org/p/chromium/issues/detail?id=9061. */
+ window.addEventListener ("keyup", on_keyup, false);
+} (window["Modernizr"], window["INFO_CONFIG"]));
Added: trunk/js/modernizr.js
===================================================================
--- trunk/js/modernizr.js (rev 0)
+++ trunk/js/modernizr.js 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,767 @@
+/*!
+ * modernizr v3.5.0
+ * Build
https://modernizr.com/download?-classlist-datalistelem-es5-eventlistener-framed-hidden-history-postmessage-queryselector-dontmin
+ *
+ * Copyright (c)
+ * Faruk Ates
+ * Paul Irish
+ * Alex Sexton
+ * Ryan Seddon
+ * Patrick Kettner
+ * Stu Cox
+ * Richard Herrera
+
+ * MIT License
+ */
+
+/*
+ * Modernizr tests which native CSS3 and HTML5 features are available in the
+ * current UA and makes the results available to you in two ways: as
properties on
+ * a global `Modernizr` object, and as classes on the `<html>` element. This
+ * information allows you to progressively enhance your pages with a granular
level
+ * of control over the experience.
+*/
+
+;(function(window, document, undefined){
+ var tests = [];
+
+
+ /**
+ *
+ * ModernizrProto is the constructor for Modernizr
+ *
+ * @class
+ * @access public
+ */
+
+ var ModernizrProto = {
+ // The current version, dummy
+ _version: '3.5.0',
+
+ // Any settings that don't work as separate modules
+ // can go in here as configuration.
+ _config: {
+ 'classPrefix': '',
+ 'enableClasses': true,
+ 'enableJSClass': true,
+ 'usePrefixes': true
+ },
+
+ // Queue of tests
+ _q: [],
+
+ // Stub these for people who are listening
+ on: function(test, cb) {
+ // I don't really think people should do this, but we can
+ // safe guard it a bit.
+ // -- NOTE:: this gets WAY overridden in src/addTest for actual async
tests.
+ // This is in case people listen to synchronous tests. I would leave it
out,
+ // but the code to *disallow* sync tests in the real version of this
+ // function is actually larger than this.
+ var self = this;
+ setTimeout(function() {
+ cb(self[test]);
+ }, 0);
+ },
+
+ addTest: function(name, fn, options) {
+ tests.push({name: name, fn: fn, options: options});
+ },
+
+ addAsyncTest: function(fn) {
+ tests.push({name: null, fn: fn});
+ }
+ };
+
+
+
+ // Fake some of Object.create so we can force non test results to be non
"own" properties.
+ var Modernizr = function() {};
+ Modernizr.prototype = ModernizrProto;
+
+ // Leak modernizr globally when you `require` it rather than force it here.
+ // Overwrite name so constructor name is nicer :D
+ Modernizr = new Modernizr();
+
+
+
+ var classes = [];
+
+
+ /**
+ * is returns a boolean if the typeof an obj is exactly type.
+ *
+ * @access private
+ * @function is
+ * @param {*} obj - A thing we want to check the type of
+ * @param {string} type - A string to compare the typeof against
+ * @returns {boolean}
+ */
+
+ function is(obj, type) {
+ return typeof obj === type;
+ }
+ ;
+
+ /**
+ * Run through all tests and detect their support in the current UA.
+ *
+ * @access private
+ */
+
+ function testRunner() {
+ var featureNames;
+ var feature;
+ var aliasIdx;
+ var result;
+ var nameIdx;
+ var featureName;
+ var featureNameSplit;
+
+ for (var featureIdx in tests) {
+ if (tests.hasOwnProperty(featureIdx)) {
+ featureNames = [];
+ feature = tests[featureIdx];
+ // run the test, throw the return value into the Modernizr,
+ // then based on that boolean, define an appropriate className
+ // and push it into an array of classes we'll join later.
+ //
+ // If there is no name, it's an 'async' test that is run,
+ // but not directly added to the object. That should
+ // be done with a post-run addTest call.
+ if (feature.name) {
+ featureNames.push(feature.name.toLowerCase());
+
+ if (feature.options && feature.options.aliases &&
feature.options.aliases.length) {
+ // Add all the aliases into the names list
+ for (aliasIdx = 0; aliasIdx < feature.options.aliases.length;
aliasIdx++) {
+
featureNames.push(feature.options.aliases[aliasIdx].toLowerCase());
+ }
+ }
+ }
+
+ // Run the test, or use the raw value if it's not a function
+ result = is(feature.fn, 'function') ? feature.fn() : feature.fn;
+
+
+ // Set each of the names on the Modernizr object
+ for (nameIdx = 0; nameIdx < featureNames.length; nameIdx++) {
+ featureName = featureNames[nameIdx];
+ // Support dot properties as sub tests. We don't do checking to make
sure
+ // that the implied parent tests have been added. You must call them
in
+ // order (either in the test, or make the parent test a dependency).
+ //
+ // Cap it to TWO to make the logic simple and because who needs that
kind of subtesting
+ // hashtag famous last words
+ featureNameSplit = featureName.split('.');
+
+ if (featureNameSplit.length === 1) {
+ Modernizr[featureNameSplit[0]] = result;
+ } else {
+ // cast to a Boolean, if not one already
+ if (Modernizr[featureNameSplit[0]] &&
!(Modernizr[featureNameSplit[0]] instanceof Boolean)) {
+ Modernizr[featureNameSplit[0]] = new
Boolean(Modernizr[featureNameSplit[0]]);
+ }
+
+ Modernizr[featureNameSplit[0]][featureNameSplit[1]] = result;
+ }
+
+ classes.push((result ? '' : 'no-') + featureNameSplit.join('-'));
+ }
+ }
+ }
+ }
+ ;
+
+ /**
+ * docElement is a convenience wrapper to grab the root element of the
document
+ *
+ * @access private
+ * @returns {HTMLElement|SVGElement} The root element of the document
+ */
+
+ var docElement = document.documentElement;
+
+/*!
+{
+ "name": "classList",
+ "caniuse": "classlist",
+ "property": "classlist",
+ "tags": ["dom"],
+ "builderAliases": ["dataview_api"],
+ "notes": [{
+ "name": "MDN Docs",
+ "href": "https://developer.mozilla.org/en/DOM/element.classList";
+ }]
+}
+!*/
+
+ Modernizr.addTest('classlist', 'classList' in docElement);
+
+
+ /**
+ * A convenience helper to check if the document we are running in is an SVG
document
+ *
+ * @access private
+ * @returns {boolean}
+ */
+
+ var isSVG = docElement.nodeName.toLowerCase() === 'svg';
+
+
+ /**
+ * createElement is a convenience wrapper around document.createElement.
Since we
+ * use createElement all over the place, this allows for (slightly) smaller
code
+ * as well as abstracting away issues with creating elements in contexts
other than
+ * HTML documents (e.g. SVG documents).
+ *
+ * @access private
+ * @function createElement
+ * @returns {HTMLElement|SVGElement} An HTML or SVG element
+ */
+
+ function createElement() {
+ if (typeof document.createElement !== 'function') {
+ // This is the case in IE7, where the type of createElement is "object".
+ // For this reason, we cannot call apply() as Object is not a Function.
+ return document.createElement(arguments[0]);
+ } else if (isSVG) {
+ return document.createElementNS.call(document,
'http://www.w3.org/2000/svg', arguments[0]);
+ } else {
+ return document.createElement.apply(document, arguments);
+ }
+ }
+
+ ;
+/*!
+{
+ "name": "[hidden] Attribute",
+ "property": "hidden",
+ "tags": ["dom"],
+ "notes": [{
+ "name": "WHATWG: The hidden attribute",
+ "href": "https://developers.whatwg.org/editing.html#the-hidden-attribute";
+ }, {
+ "name": "original implementation of detect code",
+ "href":
"https://github.com/aFarkas/html5shiv/blob/bf4fcc4/src/html5shiv.js#L38";
+ }],
+ "polyfills": ["html5shiv"],
+ "authors": ["Ron Waldon (@jokeyrhyme)"]
+}
+!*/
+/* DOC
+Does the browser support the HTML5 [hidden] attribute?
+*/
+
+ Modernizr.addTest('hidden', 'hidden' in createElement('a'));
+
+
+ /**
+ * since we have a fairly large number of input tests that don't mutate the
input
+ * we create a single element that can be shared with all of those tests for
a
+ * minor perf boost
+ *
+ * @access private
+ * @returns {HTMLInputElement}
+ */
+ var inputElem = createElement('input');
+
+/*!
+{
+ "name": "Input attributes",
+ "property": "input",
+ "tags": ["forms"],
+ "authors": ["Mike Taylor"],
+ "notes": [{
+ "name": "WHATWG spec",
+ "href":
"https://html.spec.whatwg.org/multipage/forms.html#input-type-attr-summary";
+ }],
+ "knownBugs": ["Some blackberry devices report false positive for
input.multiple"]
+}
+!*/
+/* DOC
+Detects support for HTML5 `<input>` element attributes and exposes Boolean
subproperties with the results:
+
+```javascript
+Modernizr.input.autocomplete
+Modernizr.input.autofocus
+Modernizr.input.list
+Modernizr.input.max
+Modernizr.input.min
+Modernizr.input.multiple
+Modernizr.input.pattern
+Modernizr.input.placeholder
+Modernizr.input.required
+Modernizr.input.step
+```
+*/
+
+ // Run through HTML5's new input attributes to see if the UA understands any.
+ // Mike Taylr has created a comprehensive resource for testing these
attributes
+ // when applied to all input types:
+ // miketaylr.com/code/input-type-attr.html
+
+ // Only input placeholder is tested while textarea's placeholder is not.
+ // Currently Safari 4 and Opera 11 have support only for the input
placeholder
+ // Both tests are available in feature-detects/forms-placeholder.js
+
+ var inputattrs = 'autocomplete autofocus list placeholder max min multiple
pattern required step'.split(' ');
+ var attrs = {};
+
+ Modernizr.input = (function(props) {
+ for (var i = 0, len = props.length; i < len; i++) {
+ attrs[ props[i] ] = !!(props[i] in inputElem);
+ }
+ if (attrs.list) {
+ // safari false positive's on datalist: webk.it/74252
+ // see also github.com/Modernizr/Modernizr/issues/146
+ attrs.list = !!(createElement('datalist') && window.HTMLDataListElement);
+ }
+ return attrs;
+ })(inputattrs);
+
+/*!
+{
+ "name": "datalist Element",
+ "caniuse": "datalist",
+ "property": "datalistelem",
+ "tags": ["elem"],
+ "builderAliases": ["elem_datalist"],
+ "warnings": ["This test is a dupe of Modernizr.input.list. Only around for
legacy reasons."],
+ "notes": [{
+ "name": "CSS Tricks Article",
+ "href":
"https://css-tricks.com/15346-relevant-dropdowns-polyfill-for-datalist/";
+ },{
+ "name": "Mike Taylor Code",
+ "href": "https://miketaylr.com/code/datalist.html";
+ }]
+}
+!*/
+
+ // lol. we already have a test for datalist built in! silly you.
+ // Leaving it around in case anyone's using it
+
+ Modernizr.addTest('datalistelem', Modernizr.input.list);
+
+/*!
+{
+ "name": "ES5 Array",
+ "property": "es5array",
+ "notes": [{
+ "name": "ECMAScript 5.1 Language Specification",
+ "href": "http://www.ecma-international.org/ecma-262/5.1/";
+ }],
+ "polyfills": ["es5shim"],
+ "authors": ["Ron Waldon (@jokeyrhyme)"],
+ "tags": ["es5"]
+}
+!*/
+/* DOC
+Check if browser implements ECMAScript 5 Array per specification.
+*/
+
+ Modernizr.addTest('es5array', function() {
+ return !!(Array.prototype &&
+ Array.prototype.every &&
+ Array.prototype.filter &&
+ Array.prototype.forEach &&
+ Array.prototype.indexOf &&
+ Array.prototype.lastIndexOf &&
+ Array.prototype.map &&
+ Array.prototype.some &&
+ Array.prototype.reduce &&
+ Array.prototype.reduceRight &&
+ Array.isArray);
+ });
+
+/*!
+{
+ "name": "ES5 Date",
+ "property": "es5date",
+ "notes": [{
+ "name": "ECMAScript 5.1 Language Specification",
+ "href": "http://www.ecma-international.org/ecma-262/5.1/";
+ }],
+ "polyfills": ["es5shim"],
+ "authors": ["Ron Waldon (@jokeyrhyme)"],
+ "tags": ["es5"]
+}
+!*/
+/* DOC
+Check if browser implements ECMAScript 5 Date per specification.
+*/
+
+ Modernizr.addTest('es5date', function() {
+ var isoDate = '2013-04-12T06:06:37.307Z',
+ canParseISODate = false;
+ try {
+ canParseISODate = !!Date.parse(isoDate);
+ } catch (e) {
+ // no ISO date parsing yet
+ }
+ return !!(Date.now &&
+ Date.prototype &&
+ Date.prototype.toISOString &&
+ Date.prototype.toJSON &&
+ canParseISODate);
+ });
+
+/*!
+{
+ "name": "ES5 Function",
+ "property": "es5function",
+ "notes": [{
+ "name": "ECMAScript 5.1 Language Specification",
+ "href": "http://www.ecma-international.org/ecma-262/5.1/";
+ }],
+ "polyfills": ["es5shim"],
+ "authors": ["Ron Waldon (@jokeyrhyme)"],
+ "tags": ["es5"]
+}
+!*/
+/* DOC
+Check if browser implements ECMAScript 5 Function per specification.
+*/
+
+ Modernizr.addTest('es5function', function() {
+ return !!(Function.prototype && Function.prototype.bind);
+ });
+
+/*!
+{
+ "name": "ES5 Object",
+ "property": "es5object",
+ "notes": [{
+ "name": "ECMAScript 5.1 Language Specification",
+ "href": "http://www.ecma-international.org/ecma-262/5.1/";
+ }],
+ "polyfills": ["es5shim", "es5sham"],
+ "authors": ["Ron Waldon (@jokeyrhyme)"],
+ "tags": ["es5"]
+}
+!*/
+/* DOC
+Check if browser implements ECMAScript 5 Object per specification.
+*/
+
+ Modernizr.addTest('es5object', function() {
+ return !!(Object.keys &&
+ Object.create &&
+ Object.getPrototypeOf &&
+ Object.getOwnPropertyNames &&
+ Object.isSealed &&
+ Object.isFrozen &&
+ Object.isExtensible &&
+ Object.getOwnPropertyDescriptor &&
+ Object.defineProperty &&
+ Object.defineProperties &&
+ Object.seal &&
+ Object.freeze &&
+ Object.preventExtensions);
+ });
+
+/*!
+{
+ "name": "ES5 Strict Mode",
+ "property": "strictmode",
+ "caniuse": "sctrict-mode",
+ "notes": [{
+ "name": "ECMAScript 5.1 Language Specification",
+ "href": "http://www.ecma-international.org/ecma-262/5.1/";
+ }],
+ "authors": ["@kangax"],
+ "tags": ["es5"],
+ "builderAliases": ["es5_strictmode"]
+}
+!*/
+/* DOC
+Check if browser implements ECMAScript 5 Object strict mode.
+*/
+
+ Modernizr.addTest('strictmode', (function() {'use strict'; return !this;
})());
+
+/*!
+{
+ "name": "ES5 String",
+ "property": "es5string",
+ "notes": [{
+ "name": "ECMAScript 5.1 Language Specification",
+ "href": "http://www.ecma-international.org/ecma-262/5.1/";
+ }],
+ "polyfills": ["es5shim"],
+ "authors": ["Ron Waldon (@jokeyrhyme)"],
+ "tags": ["es5"]
+}
+!*/
+/* DOC
+Check if browser implements ECMAScript 5 String per specification.
+*/
+
+ Modernizr.addTest('es5string', function() {
+ return !!(String.prototype && String.prototype.trim);
+ });
+
+/*!
+{
+ "name": "JSON",
+ "property": "json",
+ "caniuse": "json",
+ "notes": [{
+ "name": "MDN documentation",
+ "href": "https://developer.mozilla.org/en-US/docs/Glossary/JSON";
+ }],
+ "polyfills": ["json2"]
+}
+!*/
+/* DOC
+Detects native support for JSON handling functions.
+*/
+
+ // this will also succeed if you've loaded the JSON2.js polyfill ahead of
time
+ // ... but that should be obvious. :)
+
+ Modernizr.addTest('json', 'JSON' in window && 'parse' in JSON && 'stringify'
in JSON);
+
+/*!
+{
+ "name": "ES5 Syntax",
+ "property": "es5syntax",
+ "notes": [{
+ "name": "ECMAScript 5.1 Language Specification",
+ "href": "http://www.ecma-international.org/ecma-262/5.1/";
+ }, {
+ "name": "original implementation of detect code",
+ "href": "http://kangax.github.io/es5-compat-table/";
+ }],
+ "authors": ["Ron Waldon (@jokeyrhyme)"],
+ "warnings": ["This detect uses `eval()`, so CSP may be a problem."],
+ "tags": ["es5"]
+}
+!*/
+/* DOC
+Check if browser accepts ECMAScript 5 syntax.
+*/
+
+ Modernizr.addTest('es5syntax', function() {
+ var value, obj, stringAccess, getter, setter, reservedWords,
zeroWidthChars;
+ try {
+ /* eslint no-eval: "off" */
+ // Property access on strings
+ stringAccess = eval('"foobar"[3] === "b"');
+ // Getter in property initializer
+ getter = eval('({ get x(){ return 1 } }).x === 1');
+ eval('({ set x(v){ value = v; } }).x = 1');
+ // Setter in property initializer
+ setter = value === 1;
+ // Reserved words as property names
+ eval('obj = ({ if: 1 })');
+ reservedWords = obj['if'] === 1;
+ // Zero-width characters in identifiers
+ zeroWidthChars = eval('_\u200c\u200d = true');
+
+ return stringAccess && getter && setter && reservedWords &&
zeroWidthChars;
+ } catch (ignore) {
+ return false;
+ }
+ });
+
+/*!
+{
+ "name": "ES5 Immutable Undefined",
+ "property": "es5undefined",
+ "notes": [{
+ "name": "ECMAScript 5.1 Language Specification",
+ "href": "http://www.ecma-international.org/ecma-262/5.1/";
+ }, {
+ "name": "original implementation of detect code",
+ "href": "http://kangax.github.io/es5-compat-table/";
+ }],
+ "authors": ["Ron Waldon (@jokeyrhyme)"],
+ "tags": ["es5"]
+}
+!*/
+/* DOC
+Check if browser prevents assignment to global `undefined` per ECMAScript 5.
+*/
+
+ Modernizr.addTest('es5undefined', function() {
+ var result, originalUndefined;
+ try {
+ originalUndefined = window.undefined;
+ window.undefined = 12345;
+ result = typeof window.undefined === 'undefined';
+ window.undefined = originalUndefined;
+ } catch (e) {
+ return false;
+ }
+ return result;
+ });
+
+/*!
+{
+ "name": "ES5",
+ "property": "es5",
+ "notes": [{
+ "name": "ECMAScript 5.1 Language Specification",
+ "href": "http://www.ecma-international.org/ecma-262/5.1/";
+ }],
+ "polyfills": ["es5shim", "es5sham"],
+ "authors": ["Ron Waldon (@jokeyrhyme)"],
+ "tags": ["es5"]
+}
+!*/
+/* DOC
+Check if browser implements everything as specified in ECMAScript 5.
+*/
+
+ Modernizr.addTest('es5', function() {
+ return !!(
+ Modernizr.es5array &&
+ Modernizr.es5date &&
+ Modernizr.es5function &&
+ Modernizr.es5object &&
+ Modernizr.strictmode &&
+ Modernizr.es5string &&
+ Modernizr.json &&
+ Modernizr.es5syntax &&
+ Modernizr.es5undefined
+ );
+ });
+
+/*!
+{
+ "name": "Event Listener",
+ "property": "eventlistener",
+ "authors": ["Andrew Betts (@triblondon)"],
+ "notes": [{
+ "name": "W3C Spec",
+ "href":
"https://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-Registration-interfaces";
+ }],
+ "polyfills": ["eventlistener"]
+}
+!*/
+/* DOC
+Detects native support for addEventListener
+*/
+
+ Modernizr.addTest('eventlistener', 'addEventListener' in window);
+
+/*!
+{
+ "name": "History API",
+ "property": "history",
+ "caniuse": "history",
+ "tags": ["history"],
+ "authors": ["Hay Kranen", "Alexander Farkas"],
+ "notes": [{
+ "name": "W3C Spec",
+ "href": "https://www.w3.org/TR/html51/browsers.html#the-history-interface";
+ }, {
+ "name": "MDN documentation",
+ "href": "https://developer.mozilla.org/en-US/docs/Web/API/window.history";
+ }],
+ "polyfills": ["historyjs", "html5historyapi"]
+}
+!*/
+/* DOC
+Detects support for the History API for manipulating the browser session
history.
+*/
+
+ Modernizr.addTest('history', function() {
+ // Issue #733
+ // The stock browser on Android 2.2 & 2.3, and 4.0.x returns positive on
history support
+ // Unfortunately support is really buggy and there is no clean way to
detect
+ // these bugs, so we fall back to a user agent sniff :(
+ var ua = navigator.userAgent;
+
+ // We only want Android 2 and 4.0, stock browser, and not Chrome which
identifies
+ // itself as 'Mobile Safari' as well, nor Windows Phone (issue #1471).
+ if ((ua.indexOf('Android 2.') !== -1 ||
+ (ua.indexOf('Android 4.0') !== -1)) &&
+ ua.indexOf('Mobile Safari') !== -1 &&
+ ua.indexOf('Chrome') === -1 &&
+ ua.indexOf('Windows Phone') === -1 &&
+ // Since all documents on file:// share an origin, the History apis are
+ // blocked there as well
+ location.protocol !== 'file:'
+ ) {
+ return false;
+ }
+
+ // Return the regular check
+ return (window.history && 'pushState' in window.history);
+ });
+
+/*!
+{
+ "name": "postMessage",
+ "property": "postmessage",
+ "caniuse": "x-doc-messaging",
+ "notes": [{
+ "name": "W3C Spec",
+ "href": "http://www.w3.org/TR/html5/comms.html#posting-messages";
+ }],
+ "polyfills": ["easyxdm", "postmessage-jquery"]
+}
+!*/
+/* DOC
+Detects support for the `window.postMessage` protocol for cross-document
messaging.
+*/
+
+ Modernizr.addTest('postmessage', 'postMessage' in window);
+
+/*!
+{
+ "name": "QuerySelector",
+ "property": "queryselector",
+ "caniuse": "queryselector",
+ "tags": ["queryselector"],
+ "authors": ["Andrew Betts (@triblondon)"],
+ "notes": [{
+ "name" : "W3C Selectors reference",
+ "href": "https://www.w3.org/TR/selectors-api/#queryselectorall";
+ }],
+ "polyfills": ["css-selector-engine"]
+}
+!*/
+/* DOC
+Detects support for querySelector.
+*/
+
+ Modernizr.addTest('queryselector', 'querySelector' in document &&
'querySelectorAll' in document);
+
+/*!
+{
+ "name": "Framed window",
+ "property": "framed",
+ "tags": ["window"],
+ "builderAliases": ["window_framed"]
+}
+!*/
+/* DOC
+Tests if page is iframed.
+*/
+
+ // github.com/Modernizr/Modernizr/issues/242
+
+ Modernizr.addTest('framed', window.location != top.location);
+
+
+ // Run each test
+ testRunner();
+
+ delete ModernizrProto.addTest;
+ delete ModernizrProto.addAsyncTest;
+
+ // Run the things that are supposed to run after the tests
+ for (var i = 0; i < Modernizr._q.length; i++) {
+ Modernizr._q[i]();
+ }
+
+ // Leak Modernizr namespace
+ window.Modernizr = Modernizr;
+
+
+;
+
+})(window, document);
\ No newline at end of file
Added: trunk/js/package.json
===================================================================
--- trunk/js/package.json (rev 0)
+++ trunk/js/package.json 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,25 @@
+{
+ "name": "texinfo",
+ "version": "0.1.0",
+ "main": "info.js",
+ "repository": {
+ "type": "git",
+ "url": "https://notabug.org/mthl/texinfo.git";
+ },
+ "email": "address@hidden",
+ "homepage": "https://www.gnu.org/texinfo";,
+ "contributors": [
+ "Per Bothner <address@hidden>",
+ "Mathieu Lirzin <address@hidden>"
+ ],
+ "license": "GPL-3.0",
+ "dependencies": {},
+ "devDependencies": {
+ "eslint": "^4.4.1",
+ "finalhandler": "^1.0.4",
+ "modernizr": "^3.5.0",
+ "serve-static": "^1.12.4",
+ "typescript": "^2.4.2",
+ "uglify-js": "^3.0.27"
+ }
+}
Added: trunk/js/server.js
===================================================================
--- trunk/js/server.js (rev 0)
+++ trunk/js/server.js 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,13 @@
+var finalhandler = require ('finalhandler');
+var http = require ('http');
+var serveStatic = require ('serve-static');
+
+var serve = serveStatic ('examples', {
+ 'index': ['index.html', 'index.htm']
+});
+
+var server = http.createServer ((req, res) => {
+ serve (req, res, finalhandler (req, res));
+});
+
+server.listen (3000);
Added: trunk/js/style/info.css
===================================================================
--- trunk/js/style/info.css (rev 0)
+++ trunk/js/style/info.css 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,172 @@
+/*-----------.
+| Sub pages |
+`-----------*/
+
+div[node] {
+ left: 25%;
+ width: 75%;
+ height: auto;
+ top: 0pt;
+ bottom: 0pt;
+ position: absolute;
+ overflow: hidden;
+}
+
+div[node][hidden] {
+ display: none;
+}
+
+/* Non-iframed main page */
+div[node]#index {
+ overflow: auto
+}
+
+/* Iframed sub pages */
+iframe.node {
+ width: 100%;
+ height: 100%;
+ border: none;
+ margin: 0px;
+ padding: 0px;
+}
+
+#sub-pages.blurred {
+ opacity: 0.2;
+}
+
+.highlight {
+ background: lightgrey;
+}
+
+/*--------------------------.
+| Lateral table of content |
+`--------------------------*/
+
+#slider {
+ position: fixed;
+ top: 0em;
+ right: 25%;
+ bottom: 0em;
+ left: 0em;
+ height: 100%;
+ width: 25%;
+ overflow: auto;
+ border: none;
+ margin: 0px;
+ padding: 0px;
+}
+
+div.toc-sidebar header {
+ font-size: xx-large;
+}
+
+div.toc-sidebar div {
+ padding: 0.25em;
+ overflow: auto;
+}
+
+div.toc ul[toc-detail] {
+ display: none
+}
+
+div.toc ul, div toc nav {
+ margin: 0px;
+ padding: 0px;
+}
+
+div.toc ul ul {
+ margin-left: 1em;
+}
+
+div.toc a[toc-current] {
+ font-weight: bold
+}
+
+/*-------------.
+| Help screen |
+`-------------*/
+
+table#keyboard-shortcuts {
+ margin: 20px;
+}
+
+table#keyboard-shortcuts td {
+ padding: 5px;
+}
+
+table#keyboard-shortcuts th {
+ text-align: left;
+}
+
+/* The Modal (background) hidden by default */
+.modal {
+ display: none;
+ position: fixed;
+ z-index: 1;
+ padding-top: 100px;
+ left: 25%;
+ top: 0;
+ width: 75%;
+ height: 100%;
+ overflow: auto;
+ background-color: rgb(0,0,0); /* Fallback color */
+ background-color: rgba(0,0,0,0.5); /* Black w/ opacity */
+}
+
+/* Modal Content */
+.modal-content {
+ background-color: white;
+ margin: auto;
+ padding: 20px;
+ width: 80%;
+}
+
+/*-------.
+| Icons |
+`-------*/
+
+/* The Close Button */
+.close {
+ color: darkgrey;
+ float: right;
+ font-size: xx-large;
+}
+
+#icon-bar {
+ float: right;
+}
+
+.icon {
+ color: darkgrey;
+ font-size: x-large;
+}
+
+.icon:hover, .icon:focus, .close:hover, .close:focus {
+ color: black;
+ cursor: pointer;
+}
+
+/*--------.
+| popups |
+`--------*/
+
+.text-input, .echo-area, .error {
+ background: lightgrey;
+ z-index: 10;
+ position: fixed;
+ right: 0;
+}
+
+.error .text-input {
+ top: 0;
+ right: 0;
+}
+
+.error {
+ background-color: orange;
+ padding: 5px;
+}
+
+.echo-area {
+ bottom: 0;
+}
Added: trunk/js/style/kawa.css
===================================================================
--- trunk/js/style/kawa.css (rev 0)
+++ trunk/js/style/kawa.css 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,39 @@
+body.mainbar {
+ background: #fffff5;
+}
+
+pre.example kbd {
+ background-color: #FFFFD0;
+ font-style: normal;
+ font-weight: bold;
+}
+
+#slider {
+ background-color: #F4FCFF;
+}
+
+div.toc-sidebar a {
+ text-decoration: none;
+}
+
+div.toc-sidebar a:hover, div.toc-sidebar a:hover div {
+ color: #fff;
+ background-color: #69C;
+}
+
+div.display {
+ white-space: pre-wrap;
+ font-family: monospace;
+}
+
+div.toc li {
+ display: block;
+ text-indent: 0;
+ text-align: left;
+ border: solid;
+ border-width: 1px 0px 0px 1px;
+ border-color: #AAA #666 #666 #AAA;
+ list-style: none; /* Remove triangle from H2 */
+ padding: 0px 4px;
+ margin: 0;
+}
Added: trunk/js/tsconfig.json
===================================================================
--- trunk/js/tsconfig.json (rev 0)
+++ trunk/js/tsconfig.json 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,9 @@
+{
+ "compilerOptions": {
+ "lib": ["dom", "es2017"],
+ "allowJs": true,
+ "checkJs": true,
+ "noEmit": true
+ },
+ "files": ["info.js"]
+}
Added: trunk/js/yarn.lock
===================================================================
--- trunk/js/yarn.lock (rev 0)
+++ trunk/js/yarn.lock 2017-11-09 18:52:07 UTC (rev 7983)
@@ -0,0 +1,1206 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+
address@hidden:
+ version "3.0.1"
+ resolved
"https://registry.yarnpkg.com/acorn-jsx/-/acorn-jsx-3.0.1.tgz#afdf9488fb1ecefc8348f6fb22f464e32a58b36b";
+ dependencies:
+ acorn "^3.0.4"
+
address@hidden:
+ version "3.3.0"
+ resolved
"https://registry.yarnpkg.com/acorn/-/acorn-3.3.0.tgz#45e37fb39e8da3f25baee3ff5369e2bb5f22017a";
+
address@hidden:
+ version "5.1.1"
+ resolved
"https://registry.yarnpkg.com/acorn/-/acorn-5.1.1.tgz#53fe161111f912ab999ee887a90a0bc52822fd75";
+
address@hidden:
+ version "1.5.1"
+ resolved
"https://registry.yarnpkg.com/ajv-keywords/-/ajv-keywords-1.5.1.tgz#314dd0a4b3368fad3dfcdc54ede6171b886daf3c";
+
address@hidden:
+ version "4.11.8"
+ resolved
"https://registry.yarnpkg.com/ajv/-/ajv-4.11.8.tgz#82ffb02b29e662ae53bdc20af15947706739c536";
+ dependencies:
+ co "^4.6.0"
+ json-stable-stringify "^1.0.1"
+
address@hidden:
+ version "5.2.2"
+ resolved
"https://registry.yarnpkg.com/ajv/-/ajv-5.2.2.tgz#47c68d69e86f5d953103b0074a9430dc63da5e39";
+ dependencies:
+ co "^4.6.0"
+ fast-deep-equal "^1.0.0"
+ json-schema-traverse "^0.3.0"
+ json-stable-stringify "^1.0.1"
+
address@hidden:
+ version "2.0.0"
+ resolved
"https://registry.yarnpkg.com/ansi-escapes/-/ansi-escapes-2.0.0.tgz#5bae52be424878dd9783e8910e3fc2922e83c81b";
+
address@hidden:
+ version "2.1.1"
+ resolved
"https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-2.1.1.tgz#c3b33ab5ee360d86e0e628f0468ae7ef27d654df";
+
address@hidden:
+ version "3.0.0"
+ resolved
"https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-3.0.0.tgz#ed0317c322064f79466c02966bddb605ab37d998";
+
address@hidden:
+ version "2.2.1"
+ resolved
"https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-2.2.1.tgz#b432dd3358b634cf75e1e4664368240533c1ddbe";
+
address@hidden:
+ version "3.2.0"
+ resolved
"https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-3.2.0.tgz#c159b8d5be0f9e5a6f346dab94f16ce022161b88";
+ dependencies:
+ color-convert "^1.9.0"
+
address@hidden:
+ version "1.0.9"
+ resolved
"https://registry.yarnpkg.com/argparse/-/argparse-1.0.9.tgz#73d83bc263f86e97f8cc4f6bae1b0e90a7d22c86";
+ dependencies:
+ sprintf-js "~1.0.2"
+
address@hidden:
+ version "0.1.16"
+ resolved
"https://registry.yarnpkg.com/argparse/-/argparse-0.1.16.tgz#cfd01e0fbba3d6caed049fbd758d40f65196f57c";
+ dependencies:
+ underscore "~1.7.0"
+ underscore.string "~2.4.0"
+
address@hidden:
+ version "1.0.2"
+ resolved
"https://registry.yarnpkg.com/array-union/-/array-union-1.0.2.tgz#9a34410e4f4e3da23dea375be5be70f24778ec39";
+ dependencies:
+ array-uniq "^1.0.1"
+
address@hidden:
+ version "1.0.3"
+ resolved
"https://registry.yarnpkg.com/array-uniq/-/array-uniq-1.0.3.tgz#af6ac877a25cc7f74e058894753858dfdb24fdb6";
+
address@hidden:
+ version "1.0.1"
+ resolved
"https://registry.yarnpkg.com/arrify/-/arrify-1.0.1.tgz#898508da2226f380df904728456849c1501a4b0d";
+
address@hidden:
+ version "0.15.3"
+ resolved
"https://registry.yarnpkg.com/autolinker/-/autolinker-0.15.3.tgz#342417d8f2f3461b14cf09088d5edf8791dc9832";
+
address@hidden:
+ version "6.26.0"
+ resolved
"https://registry.yarnpkg.com/babel-code-frame/-/babel-code-frame-6.26.0.tgz#63fd43f7dc1e3bb7ce35947db8fe369a3f58c74b";
+ dependencies:
+ chalk "^1.1.3"
+ esutils "^2.0.2"
+ js-tokens "^3.0.2"
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/balanced-match/-/balanced-match-1.0.0.tgz#89b4d199ab2bee49de164ea02b89ce462d71b767";
+
address@hidden:
+ version "1.1.8"
+ resolved
"https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-1.1.8.tgz#c07b211c7c952ec1f8efd51a77ef0d1d3990a292";
+ dependencies:
+ balanced-match "^1.0.0"
+ concat-map "0.0.1"
+
address@hidden:
+ version "1.1.1"
+ resolved
"https://registry.yarnpkg.com/builtin-modules/-/builtin-modules-1.1.1.tgz#270f076c5a72c02f5b65a47df94c5fe3a278892f";
+
address@hidden:
+ version "0.1.0"
+ resolved
"https://registry.yarnpkg.com/caller-path/-/caller-path-0.1.0.tgz#94085ef63581ecd3daa92444a8fe94e82577751f";
+ dependencies:
+ callsites "^0.2.0"
+
address@hidden:
+ version "0.2.0"
+ resolved
"https://registry.yarnpkg.com/callsites/-/callsites-0.2.0.tgz#afab96262910a7f33c19a5775825c69f34e350ca";
+
address@hidden:
+ version "3.0.0"
+ resolved
"https://registry.yarnpkg.com/camelcase/-/camelcase-3.0.0.tgz#32fc4b9fcdaf845fcdf7e73bb97cac2261f0ab0a";
+
address@hidden, address@hidden:
+ version "1.1.3"
+ resolved
"https://registry.yarnpkg.com/chalk/-/chalk-1.1.3.tgz#a8115c55e4a702fe4d150abd3872822a7e09fc98";
+ dependencies:
+ ansi-styles "^2.2.1"
+ escape-string-regexp "^1.0.2"
+ has-ansi "^2.0.0"
+ strip-ansi "^3.0.0"
+ supports-color "^2.0.0"
+
address@hidden, address@hidden:
+ version "2.1.0"
+ resolved
"https://registry.yarnpkg.com/chalk/-/chalk-2.1.0.tgz#ac5becf14fa21b99c6c92ca7a7d7cfd5b17e743e";
+ dependencies:
+ ansi-styles "^3.1.0"
+ escape-string-regexp "^1.0.5"
+ supports-color "^4.0.0"
+
address@hidden:
+ version "0.3.3"
+ resolved
"https://registry.yarnpkg.com/circular-json/-/circular-json-0.3.3.tgz#815c99ea84f6809529d2f45791bdf82711352d66";
+
address@hidden:
+ version "2.1.0"
+ resolved
"https://registry.yarnpkg.com/cli-cursor/-/cli-cursor-2.1.0.tgz#b35dac376479facc3e94747d41d0d0f5238ffcb5";
+ dependencies:
+ restore-cursor "^2.0.0"
+
address@hidden:
+ version "2.2.0"
+ resolved
"https://registry.yarnpkg.com/cli-width/-/cli-width-2.2.0.tgz#ff19ede8a9a5e579324147b0c11f0fbcbabed639";
+
address@hidden:
+ version "3.2.0"
+ resolved
"https://registry.yarnpkg.com/cliui/-/cliui-3.2.0.tgz#120601537a916d29940f934da3b48d585a39213d";
+ dependencies:
+ string-width "^1.0.1"
+ strip-ansi "^3.0.1"
+ wrap-ansi "^2.0.0"
+
address@hidden:
+ version "4.6.0"
+ resolved
"https://registry.yarnpkg.com/co/-/co-4.6.0.tgz#6ea6bdf3d853ae54ccb8e47bfa0bf3f9031fb184";
+
address@hidden:
+ version "1.1.0"
+ resolved
"https://registry.yarnpkg.com/code-point-at/-/code-point-at-1.1.0.tgz#0d070b4d043a5bea33a2f1a40e2edb3d9a4ccf77";
+
address@hidden:
+ version "1.9.0"
+ resolved
"https://registry.yarnpkg.com/color-convert/-/color-convert-1.9.0.tgz#1accf97dd739b983bf994d56fec8f95853641b7a";
+ dependencies:
+ color-name "^1.1.1"
+
address@hidden:
+ version "1.1.3"
+ resolved
"https://registry.yarnpkg.com/color-name/-/color-name-1.1.3.tgz#a7d0558bd89c42f795dd42328f740831ca53bc25";
+
address@hidden:
+ version "2.11.0"
+ resolved
"https://registry.yarnpkg.com/commander/-/commander-2.11.0.tgz#157152fd1e7a6c8d98a5b715cf376df928004563";
+
address@hidden:
+ version "0.0.1"
+ resolved
"https://registry.yarnpkg.com/concat-map/-/concat-map-0.0.1.tgz#d8a96bd77fd68df7793a73036a3ba0d5405d477b";
+
address@hidden:
+ version "1.6.0"
+ resolved
"https://registry.yarnpkg.com/concat-stream/-/concat-stream-1.6.0.tgz#0aac662fd52be78964d5532f694784e70110acf7";
+ dependencies:
+ inherits "^2.0.3"
+ readable-stream "^2.2.2"
+ typedarray "^0.0.6"
+
address@hidden:
+ version "1.0.2"
+ resolved
"https://registry.yarnpkg.com/core-util-is/-/core-util-is-1.0.2.tgz#b5fd54220aa2bc5ab57aab7140c940754503c1a7";
+
address@hidden:
+ version "5.1.0"
+ resolved
"https://registry.yarnpkg.com/cross-spawn/-/cross-spawn-5.1.0.tgz#e8bd0efee58fcff6f8f94510a0a554bbfa235449";
+ dependencies:
+ lru-cache "^4.0.1"
+ shebang-command "^1.2.0"
+ which "^1.2.9"
+
address@hidden, address@hidden:
+ version "2.6.8"
+ resolved
"https://registry.yarnpkg.com/debug/-/debug-2.6.8.tgz#e731531ca2ede27d188222427da17821d68ff4fc";
+ dependencies:
+ ms "2.0.0"
+
address@hidden:
+ version "1.2.0"
+ resolved
"https://registry.yarnpkg.com/decamelize/-/decamelize-1.2.0.tgz#f6534d15148269b20352e7bee26f501f9a191290";
+
address@hidden:
+ version "0.1.3"
+ resolved
"https://registry.yarnpkg.com/deep-is/-/deep-is-0.1.3.tgz#b369d6fb5dbc13eecf524f91b070feedc357cf34";
+
address@hidden:
+ version "2.2.2"
+ resolved
"https://registry.yarnpkg.com/del/-/del-2.2.2.tgz#c12c981d067846c84bcaf862cff930d907ffd1a8";
+ dependencies:
+ globby "^5.0.0"
+ is-path-cwd "^1.0.0"
+ is-path-in-cwd "^1.0.0"
+ object-assign "^4.0.1"
+ pify "^2.0.0"
+ pinkie-promise "^2.0.0"
+ rimraf "^2.2.8"
+
address@hidden, address@hidden:
+ version "1.1.1"
+ resolved
"https://registry.yarnpkg.com/depd/-/depd-1.1.1.tgz#5783b4e1c459f06fa5ca27f991f3d06e7a310359";
+
address@hidden:
+ version "1.0.4"
+ resolved
"https://registry.yarnpkg.com/destroy/-/destroy-1.0.4.tgz#978857442c44749e4206613e37946205826abd80";
+
address@hidden:
+ version "1.2.3"
+ resolved
"https://registry.yarnpkg.com/doctrine/-/doctrine-1.2.3.tgz#6aec6bbd62cf89dd498cae70c0ed9f49da873a6a";
+ dependencies:
+ esutils "^2.0.2"
+ isarray "^1.0.0"
+
address@hidden:
+ version "2.0.0"
+ resolved
"https://registry.yarnpkg.com/doctrine/-/doctrine-2.0.0.tgz#c73d8d2909d22291e1a007a395804da8b665fe63";
+ dependencies:
+ esutils "^2.0.2"
+ isarray "^1.0.0"
+
address@hidden:
+ version "1.1.1"
+ resolved
"https://registry.yarnpkg.com/ee-first/-/ee-first-1.1.1.tgz#590c61156b0ae2f4f0255732a158b266bc56b21d";
+
address@hidden:
+ version "1.0.1"
+ resolved
"https://registry.yarnpkg.com/encodeurl/-/encodeurl-1.0.1.tgz#79e3d58655346909fe6f0f45a5de68103b294d20";
+
address@hidden:
+ version "1.3.1"
+ resolved
"https://registry.yarnpkg.com/error-ex/-/error-ex-1.3.1.tgz#f855a86ce61adc4e8621c3cda21e7a7612c3a8dc";
+ dependencies:
+ is-arrayish "^0.2.1"
+
address@hidden:
+ version "1.0.3"
+ resolved
"https://registry.yarnpkg.com/escape-html/-/escape-html-1.0.3.tgz#0258eae4d3d0c0974de1c169188ef0051d1d1988";
+
address@hidden, address@hidden:
+ version "1.0.5"
+ resolved
"https://registry.yarnpkg.com/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz#1b61c0562190a8dff6ae3bb2cf0200ca130b86d4";
+
address@hidden:
+ version "3.7.1"
+ resolved
"https://registry.yarnpkg.com/eslint-scope/-/eslint-scope-3.7.1.tgz#3d63c3edfda02e06e01a452ad88caacc7cdcb6e8";
+ dependencies:
+ esrecurse "^4.1.0"
+ estraverse "^4.1.1"
+
address@hidden:
+ version "4.5.0"
+ resolved
"https://registry.yarnpkg.com/eslint/-/eslint-4.5.0.tgz#bb75d3b8bde97fb5e13efcd539744677feb019c3";
+ dependencies:
+ ajv "^5.2.0"
+ babel-code-frame "^6.22.0"
+ chalk "^2.1.0"
+ concat-stream "^1.6.0"
+ cross-spawn "^5.1.0"
+ debug "^2.6.8"
+ doctrine "^2.0.0"
+ eslint-scope "^3.7.1"
+ espree "^3.5.0"
+ esquery "^1.0.0"
+ estraverse "^4.2.0"
+ esutils "^2.0.2"
+ file-entry-cache "^2.0.0"
+ functional-red-black-tree "^1.0.1"
+ glob "^7.1.2"
+ globals "^9.17.0"
+ ignore "^3.3.3"
+ imurmurhash "^0.1.4"
+ inquirer "^3.0.6"
+ is-resolvable "^1.0.0"
+ js-yaml "^3.9.1"
+ json-stable-stringify "^1.0.1"
+ levn "^0.3.0"
+ lodash "^4.17.4"
+ minimatch "^3.0.2"
+ mkdirp "^0.5.1"
+ natural-compare "^1.4.0"
+ optionator "^0.8.2"
+ path-is-inside "^1.0.2"
+ pluralize "^4.0.0"
+ progress "^2.0.0"
+ require-uncached "^1.0.3"
+ semver "^5.3.0"
+ strip-ansi "^4.0.0"
+ strip-json-comments "~2.0.1"
+ table "^4.0.1"
+ text-table "~0.2.0"
+
address@hidden:
+ version "3.5.0"
+ resolved
"https://registry.yarnpkg.com/espree/-/espree-3.5.0.tgz#98358625bdd055861ea27e2867ea729faf463d8d";
+ dependencies:
+ acorn "^5.1.1"
+ acorn-jsx "^3.0.0"
+
address@hidden:
+ version "4.0.0"
+ resolved
"https://registry.yarnpkg.com/esprima/-/esprima-4.0.0.tgz#4499eddcd1110e0b218bacf2fa7f7f59f55ca804";
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/esquery/-/esquery-1.0.0.tgz#cfba8b57d7fba93f17298a8a006a04cda13d80fa";
+ dependencies:
+ estraverse "^4.0.0"
+
address@hidden:
+ version "4.2.0"
+ resolved
"https://registry.yarnpkg.com/esrecurse/-/esrecurse-4.2.0.tgz#fa9568d98d3823f9a41d91e902dcab9ea6e5b163";
+ dependencies:
+ estraverse "^4.1.0"
+ object-assign "^4.0.1"
+
address@hidden, address@hidden, address@hidden, address@hidden:
+ version "4.2.0"
+ resolved
"https://registry.yarnpkg.com/estraverse/-/estraverse-4.2.0.tgz#0dee3fed31fcd469618ce7342099fc1afa0bdb13";
+
address@hidden:
+ version "2.0.2"
+ resolved
"https://registry.yarnpkg.com/esutils/-/esutils-2.0.2.tgz#0abf4f1caa5bcb1f7a9d8acc6dea4faaa04bac9b";
+
address@hidden:
+ version "1.8.0"
+ resolved
"https://registry.yarnpkg.com/etag/-/etag-1.8.0.tgz#6f631aef336d6c46362b51764044ce216be3c051";
+
address@hidden:
+ version "2.0.4"
+ resolved
"https://registry.yarnpkg.com/external-editor/-/external-editor-2.0.4.tgz#1ed9199da9cbfe2ef2f7a31b2fde8b0d12368972";
+ dependencies:
+ iconv-lite "^0.4.17"
+ jschardet "^1.4.2"
+ tmp "^0.0.31"
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/fast-deep-equal/-/fast-deep-equal-1.0.0.tgz#96256a3bc975595eb36d82e9929d060d893439ff";
+
address@hidden:
+ version "2.0.6"
+ resolved
"https://registry.yarnpkg.com/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz#3d8a5c66883a16a30ca8643e851f19baa7797917";
+
address@hidden:
+ version "2.0.0"
+ resolved
"https://registry.yarnpkg.com/figures/-/figures-2.0.0.tgz#3ab1a2d2a62c8bfb431a0c94cb797a2fce27c962";
+ dependencies:
+ escape-string-regexp "^1.0.5"
+
address@hidden:
+ version "2.0.0"
+ resolved
"https://registry.yarnpkg.com/file-entry-cache/-/file-entry-cache-2.0.0.tgz#c392990c3e684783d838b8c84a45d8a048458361";
+ dependencies:
+ flat-cache "^1.2.1"
+ object-assign "^4.0.1"
+
address@hidden:
+ version "0.2.2"
+ resolved
"https://registry.yarnpkg.com/file/-/file-0.2.2.tgz#c3dfd8f8cf3535ae455c2b423c2e52635d76b4d3";
+
address@hidden:
+ version "1.0.4"
+ resolved
"https://registry.yarnpkg.com/finalhandler/-/finalhandler-1.0.4.tgz#18574f2e7c4b98b8ae3b230c21f201f31bdb3fb7";
+ dependencies:
+ debug "2.6.8"
+ encodeurl "~1.0.1"
+ escape-html "~1.0.3"
+ on-finished "~2.3.0"
+ parseurl "~1.3.1"
+ statuses "~1.3.1"
+ unpipe "~1.0.0"
+
address@hidden:
+ version "0.3.0"
+ resolved
"https://registry.yarnpkg.com/find-parent-dir/-/find-parent-dir-0.3.0.tgz#33c44b429ab2b2f0646299c5f9f718f376ff8d54";
+
address@hidden:
+ version "1.1.2"
+ resolved
"https://registry.yarnpkg.com/find-up/-/find-up-1.1.2.tgz#6b2e9822b1a2ce0a60ab64d610eccad53cb24d0f";
+ dependencies:
+ path-exists "^2.0.0"
+ pinkie-promise "^2.0.0"
+
address@hidden:
+ version "1.2.2"
+ resolved
"https://registry.yarnpkg.com/flat-cache/-/flat-cache-1.2.2.tgz#fa86714e72c21db88601761ecf2f555d1abc6b96";
+ dependencies:
+ circular-json "^0.3.1"
+ del "^2.0.2"
+ graceful-fs "^4.1.2"
+ write "^0.2.1"
+
address@hidden:
+ version "0.5.0"
+ resolved
"https://registry.yarnpkg.com/fresh/-/fresh-0.5.0.tgz#f474ca5e6a9246d6fd8e0953cfa9b9c805afa78e";
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/fs.realpath/-/fs.realpath-1.0.0.tgz#1504ad2523158caa40db4a2787cb01411994ea4f";
+
address@hidden:
+ version "1.0.1"
+ resolved
"https://registry.yarnpkg.com/functional-red-black-tree/-/functional-red-black-tree-1.0.1.tgz#1b0ab3bd553b2a0d6399d29c0e3ea0b252078327";
+
address@hidden:
+ version "1.0.2"
+ resolved
"https://registry.yarnpkg.com/get-caller-file/-/get-caller-file-1.0.2.tgz#f702e63127e7e231c160a80c1554acb70d5047e5";
+
address@hidden, address@hidden, address@hidden:
+ version "7.1.2"
+ resolved
"https://registry.yarnpkg.com/glob/-/glob-7.1.2.tgz#c19c9df9a028702d678612384a6552404c636d15";
+ dependencies:
+ fs.realpath "^1.0.0"
+ inflight "^1.0.4"
+ inherits "2"
+ minimatch "^3.0.4"
+ once "^1.3.0"
+ path-is-absolute "^1.0.0"
+
address@hidden:
+ version "9.18.0"
+ resolved
"https://registry.yarnpkg.com/globals/-/globals-9.18.0.tgz#aa3896b3e69b487f17e31ed2143d69a8e30c2d8a";
+
address@hidden:
+ version "5.0.0"
+ resolved
"https://registry.yarnpkg.com/globby/-/globby-5.0.0.tgz#ebd84667ca0dbb330b99bcfc68eac2bc54370e0d";
+ dependencies:
+ array-union "^1.0.1"
+ arrify "^1.0.0"
+ glob "^7.0.3"
+ object-assign "^4.0.1"
+ pify "^2.0.0"
+ pinkie-promise "^2.0.0"
+
address@hidden:
+ version "4.1.11"
+ resolved
"https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-4.1.11.tgz#0e8bdfe4d1ddb8854d64e04ea7c00e2a026e5658";
+
address@hidden:
+ version "2.0.0"
+ resolved
"https://registry.yarnpkg.com/has-ansi/-/has-ansi-2.0.0.tgz#34f5049ce1ecdf2b0649af3ef24e45ed35416d91";
+ dependencies:
+ ansi-regex "^2.0.0"
+
address@hidden:
+ version "2.0.0"
+ resolved
"https://registry.yarnpkg.com/has-flag/-/has-flag-2.0.0.tgz#e8207af1cc7b30d446cc70b734b5e8be18f88d51";
+
address@hidden:
+ version "2.5.0"
+ resolved
"https://registry.yarnpkg.com/hosted-git-info/-/hosted-git-info-2.5.0.tgz#6d60e34b3abbc8313062c3b798ef8d901a07af3c";
+
address@hidden:
+ version "1.6.2"
+ resolved
"https://registry.yarnpkg.com/http-errors/-/http-errors-1.6.2.tgz#0a002cc85707192a7e7946ceedc11155f60ec736";
+ dependencies:
+ depd "1.1.1"
+ inherits "2.0.3"
+ setprototypeof "1.0.3"
+ statuses ">= 1.3.1 < 2"
+
address@hidden:
+ version "0.4.18"
+ resolved
"https://registry.yarnpkg.com/iconv-lite/-/iconv-lite-0.4.18.tgz#23d8656b16aae6742ac29732ea8f0336a4789cf2";
+
address@hidden:
+ version "3.3.3"
+ resolved
"https://registry.yarnpkg.com/ignore/-/ignore-3.3.3.tgz#432352e57accd87ab3110e82d3fea0e47812156d";
+
address@hidden:
+ version "0.1.4"
+ resolved
"https://registry.yarnpkg.com/imurmurhash/-/imurmurhash-0.1.4.tgz#9218b9b2b928a238b13dc4fb6b6d576f231453ea";
+
address@hidden:
+ version "1.0.6"
+ resolved
"https://registry.yarnpkg.com/inflight/-/inflight-1.0.6.tgz#49bd6331d7d02d0c09bc910a1075ba8165b56df9";
+ dependencies:
+ once "^1.3.0"
+ wrappy "1"
+
address@hidden, address@hidden, address@hidden, address@hidden:
+ version "2.0.3"
+ resolved
"https://registry.yarnpkg.com/inherits/-/inherits-2.0.3.tgz#633c2c83e3da42a502f52466022480f4208261de";
+
address@hidden:
+ version "3.2.2"
+ resolved
"https://registry.yarnpkg.com/inquirer/-/inquirer-3.2.2.tgz#c2aaede1507cc54d826818737742d621bef2e823";
+ dependencies:
+ ansi-escapes "^2.0.0"
+ chalk "^2.0.0"
+ cli-cursor "^2.1.0"
+ cli-width "^2.0.0"
+ external-editor "^2.0.4"
+ figures "^2.0.0"
+ lodash "^4.3.0"
+ mute-stream "0.0.7"
+ run-async "^2.2.0"
+ rx-lite "^4.0.8"
+ rx-lite-aggregates "^4.0.8"
+ string-width "^2.1.0"
+ strip-ansi "^4.0.0"
+ through "^2.3.6"
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/invert-kv/-/invert-kv-1.0.0.tgz#104a8e4aaca6d3d8cd157a8ef8bfab2d7a3ffdb6";
+
address@hidden:
+ version "0.2.1"
+ resolved
"https://registry.yarnpkg.com/is-arrayish/-/is-arrayish-0.2.1.tgz#77c99840527aa8ecb1a8ba697b80645a7a926a9d";
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/is-builtin-module/-/is-builtin-module-1.0.0.tgz#540572d34f7ac3119f8f76c30cbc1b1e037affbe";
+ dependencies:
+ builtin-modules "^1.0.0"
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/is-fullwidth-code-point/-/is-fullwidth-code-point-1.0.0.tgz#ef9e31386f031a7f0d643af82fde50c457ef00cb";
+ dependencies:
+ number-is-nan "^1.0.0"
+
address@hidden:
+ version "2.0.0"
+ resolved
"https://registry.yarnpkg.com/is-fullwidth-code-point/-/is-fullwidth-code-point-2.0.0.tgz#a3b30a5c4f199183167aaab93beefae3ddfb654f";
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/is-path-cwd/-/is-path-cwd-1.0.0.tgz#d225ec23132e89edd38fda767472e62e65f1106d";
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/is-path-in-cwd/-/is-path-in-cwd-1.0.0.tgz#6477582b8214d602346094567003be8a9eac04dc";
+ dependencies:
+ is-path-inside "^1.0.0"
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/is-path-inside/-/is-path-inside-1.0.0.tgz#fc06e5a1683fbda13de667aff717bbc10a48f37f";
+ dependencies:
+ path-is-inside "^1.0.1"
+
address@hidden:
+ version "2.1.0"
+ resolved
"https://registry.yarnpkg.com/is-promise/-/is-promise-2.1.0.tgz#79a2a9ece7f096e80f36d2b2f3bc16c1ff4bf3fa";
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/is-resolvable/-/is-resolvable-1.0.0.tgz#8df57c61ea2e3c501408d100fb013cf8d6e0cc62";
+ dependencies:
+ tryit "^1.0.1"
+
address@hidden:
+ version "0.2.1"
+ resolved
"https://registry.yarnpkg.com/is-utf8/-/is-utf8-0.2.1.tgz#4b0da1442104d1b336340e80797e865cf39f7d72";
+
address@hidden, address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/isarray/-/isarray-1.0.0.tgz#bb935d48582cba168c06834957a54a3e07124f11";
+
address@hidden:
+ version "2.0.0"
+ resolved
"https://registry.yarnpkg.com/isexe/-/isexe-2.0.0.tgz#e8fbf374dc556ff8947a10dcb0572d633f2cfa10";
+
address@hidden:
+ version "3.0.2"
+ resolved
"https://registry.yarnpkg.com/js-tokens/-/js-tokens-3.0.2.tgz#9866df395102130e38f7f996bceb65443209c25b";
+
address@hidden:
+ version "3.9.1"
+ resolved
"https://registry.yarnpkg.com/js-yaml/-/js-yaml-3.9.1.tgz#08775cebdfdd359209f0d2acd383c8f86a6904a0";
+ dependencies:
+ argparse "^1.0.7"
+ esprima "^4.0.0"
+
address@hidden:
+ version "1.5.1"
+ resolved
"https://registry.yarnpkg.com/jschardet/-/jschardet-1.5.1.tgz#c519f629f86b3a5bedba58a88d311309eec097f9";
+
address@hidden:
+ version "0.3.1"
+ resolved
"https://registry.yarnpkg.com/json-schema-traverse/-/json-schema-traverse-0.3.1.tgz#349a6d44c53a51de89b40805c5d5e59b417d3340";
+
address@hidden:
+ version "1.0.1"
+ resolved
"https://registry.yarnpkg.com/json-stable-stringify/-/json-stable-stringify-1.0.1.tgz#9a759d39c5f2ff503fd5300646ed445f88c4f9af";
+ dependencies:
+ jsonify "~0.0.0"
+
address@hidden:
+ version "0.0.0"
+ resolved
"https://registry.yarnpkg.com/jsonify/-/jsonify-0.0.0.tgz#2c74b6ee41d93ca51b7b5aaee8f503631d252a73";
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/lcid/-/lcid-1.0.0.tgz#308accafa0bc483a3867b4b6f2b9506251d1b835";
+ dependencies:
+ invert-kv "^1.0.0"
+
address@hidden, address@hidden:
+ version "0.3.0"
+ resolved
"https://registry.yarnpkg.com/levn/-/levn-0.3.0.tgz#3b09924edf9f083c0490fdd4c0bc4421e04764ee";
+ dependencies:
+ prelude-ls "~1.1.2"
+ type-check "~0.3.2"
+
address@hidden:
+ version "1.1.0"
+ resolved
"https://registry.yarnpkg.com/load-json-file/-/load-json-file-1.1.0.tgz#956905708d58b4bab4c2261b04f59f31c99374c0";
+ dependencies:
+ graceful-fs "^4.1.2"
+ parse-json "^2.2.0"
+ pify "^2.0.0"
+ pinkie-promise "^2.0.0"
+ strip-bom "^2.0.0"
+
address@hidden, address@hidden, address@hidden, address@hidden:
+ version "4.17.4"
+ resolved
"https://registry.yarnpkg.com/lodash/-/lodash-4.17.4.tgz#78203a4d1c328ae1d86dca6460e369b57f4055ae";
+
address@hidden:
+ version "4.1.1"
+ resolved
"https://registry.yarnpkg.com/lru-cache/-/lru-cache-4.1.1.tgz#622e32e82488b49279114a4f9ecf45e7cd6bba55";
+ dependencies:
+ pseudomap "^1.0.2"
+ yallist "^2.1.2"
+
address@hidden:
+ version "1.3.4"
+ resolved
"https://registry.yarnpkg.com/mime/-/mime-1.3.4.tgz#115f9e3b6b3daf2959983cb38f149a2d40eb5d53";
+
address@hidden:
+ version "1.1.0"
+ resolved
"https://registry.yarnpkg.com/mimic-fn/-/mimic-fn-1.1.0.tgz#e667783d92e89dbd342818b5230b9d62a672ad18";
+
address@hidden, address@hidden:
+ version "3.0.4"
+ resolved
"https://registry.yarnpkg.com/minimatch/-/minimatch-3.0.4.tgz#5166e286457f03306064be5497e8dbb0c3d32083";
+ dependencies:
+ brace-expansion "^1.1.7"
+
address@hidden:
+ version "0.0.8"
+ resolved
"https://registry.yarnpkg.com/minimist/-/minimist-0.0.8.tgz#857fcabfc3397d2625b8228262e86aa7a011b05d";
+
address@hidden, address@hidden:
+ version "0.5.1"
+ resolved
"https://registry.yarnpkg.com/mkdirp/-/mkdirp-0.5.1.tgz#30057438eac6cf7f8c4767f38648d6697d75c903";
+ dependencies:
+ minimist "0.0.8"
+
address@hidden:
+ version "3.5.0"
+ resolved
"https://registry.yarnpkg.com/modernizr/-/modernizr-3.5.0.tgz#396a02231bdc54628bbde2c0813a8e884c7e8060";
+ dependencies:
+ doctrine "1.2.3"
+ file "0.2.2"
+ find-parent-dir "0.3.0"
+ lodash "4.17.4"
+ mkdirp "0.5.1"
+ remarkable "^1.6.2"
+ requirejs "2.1.22"
+ yargs "7.0.2"
+
address@hidden:
+ version "2.0.0"
+ resolved
"https://registry.yarnpkg.com/ms/-/ms-2.0.0.tgz#5608aeadfc00be6c2901df5f9861788de0d597c8";
+
address@hidden:
+ version "0.0.7"
+ resolved
"https://registry.yarnpkg.com/mute-stream/-/mute-stream-0.0.7.tgz#3075ce93bc21b8fab43e1bc4da7e8115ed1e7bab";
+
address@hidden:
+ version "1.4.0"
+ resolved
"https://registry.yarnpkg.com/natural-compare/-/natural-compare-1.4.0.tgz#4abebfeed7541f2c27acfb29bdbbd15c8d5ba4f7";
+
address@hidden:
+ version "2.4.0"
+ resolved
"https://registry.yarnpkg.com/normalize-package-data/-/normalize-package-data-2.4.0.tgz#12f95a307d58352075a04907b84ac8be98ac012f";
+ dependencies:
+ hosted-git-info "^2.1.4"
+ is-builtin-module "^1.0.0"
+ semver "2 || 3 || 4 || 5"
+ validate-npm-package-license "^3.0.1"
+
address@hidden:
+ version "1.0.1"
+ resolved
"https://registry.yarnpkg.com/number-is-nan/-/number-is-nan-1.0.1.tgz#097b602b53422a522c1afb8790318336941a011d";
+
address@hidden:
+ version "4.1.1"
+ resolved
"https://registry.yarnpkg.com/object-assign/-/object-assign-4.1.1.tgz#2109adc7965887cfc05cbbd442cac8bfbb360863";
+
address@hidden:
+ version "2.3.0"
+ resolved
"https://registry.yarnpkg.com/on-finished/-/on-finished-2.3.0.tgz#20f1336481b083cd75337992a16971aa2d906947";
+ dependencies:
+ ee-first "1.1.1"
+
address@hidden:
+ version "1.4.0"
+ resolved
"https://registry.yarnpkg.com/once/-/once-1.4.0.tgz#583b1aa775961d4b113ac17d9c50baef9dd76bd1";
+ dependencies:
+ wrappy "1"
+
address@hidden:
+ version "2.0.1"
+ resolved
"https://registry.yarnpkg.com/onetime/-/onetime-2.0.1.tgz#067428230fd67443b2794b22bba528b6867962d4";
+ dependencies:
+ mimic-fn "^1.0.0"
+
address@hidden:
+ version "0.8.2"
+ resolved
"https://registry.yarnpkg.com/optionator/-/optionator-0.8.2.tgz#364c5e409d3f4d6301d6c0b4c05bba50180aeb64";
+ dependencies:
+ deep-is "~0.1.3"
+ fast-levenshtein "~2.0.4"
+ levn "~0.3.0"
+ prelude-ls "~1.1.2"
+ type-check "~0.3.2"
+ wordwrap "~1.0.0"
+
address@hidden:
+ version "1.4.0"
+ resolved
"https://registry.yarnpkg.com/os-locale/-/os-locale-1.4.0.tgz#20f9f17ae29ed345e8bde583b13d2009803c14d9";
+ dependencies:
+ lcid "^1.0.0"
+
address@hidden:
+ version "1.0.2"
+ resolved
"https://registry.yarnpkg.com/os-tmpdir/-/os-tmpdir-1.0.2.tgz#bbe67406c79aa85c5cfec766fe5734555dfa1274";
+
address@hidden:
+ version "2.2.0"
+ resolved
"https://registry.yarnpkg.com/parse-json/-/parse-json-2.2.0.tgz#f480f40434ef80741f8469099f8dea18f55a4dc9";
+ dependencies:
+ error-ex "^1.2.0"
+
address@hidden:
+ version "1.3.1"
+ resolved
"https://registry.yarnpkg.com/parseurl/-/parseurl-1.3.1.tgz#c8ab8c9223ba34888aa64a297b28853bec18da56";
+
address@hidden:
+ version "2.1.0"
+ resolved
"https://registry.yarnpkg.com/path-exists/-/path-exists-2.1.0.tgz#0feb6c64f0fc518d9a754dd5efb62c7022761f4b";
+ dependencies:
+ pinkie-promise "^2.0.0"
+
address@hidden:
+ version "1.0.1"
+ resolved
"https://registry.yarnpkg.com/path-is-absolute/-/path-is-absolute-1.0.1.tgz#174b9268735534ffbc7ace6bf53a5a9e1b5c5f5f";
+
address@hidden, address@hidden:
+ version "1.0.2"
+ resolved
"https://registry.yarnpkg.com/path-is-inside/-/path-is-inside-1.0.2.tgz#365417dede44430d1c11af61027facf074bdfc53";
+
address@hidden:
+ version "1.1.0"
+ resolved
"https://registry.yarnpkg.com/path-type/-/path-type-1.1.0.tgz#59c44f7ee491da704da415da5a4070ba4f8fe441";
+ dependencies:
+ graceful-fs "^4.1.2"
+ pify "^2.0.0"
+ pinkie-promise "^2.0.0"
+
address@hidden:
+ version "2.3.0"
+ resolved
"https://registry.yarnpkg.com/pify/-/pify-2.3.0.tgz#ed141a6ac043a849ea588498e7dca8b15330e90c";
+
address@hidden:
+ version "2.0.1"
+ resolved
"https://registry.yarnpkg.com/pinkie-promise/-/pinkie-promise-2.0.1.tgz#2135d6dfa7a358c069ac9b178776288228450ffa";
+ dependencies:
+ pinkie "^2.0.0"
+
address@hidden:
+ version "2.0.4"
+ resolved
"https://registry.yarnpkg.com/pinkie/-/pinkie-2.0.4.tgz#72556b80cfa0d48a974e80e77248e80ed4f7f870";
+
address@hidden:
+ version "4.0.0"
+ resolved
"https://registry.yarnpkg.com/pluralize/-/pluralize-4.0.0.tgz#59b708c1c0190a2f692f1c7618c446b052fd1762";
+
address@hidden:
+ version "1.1.2"
+ resolved
"https://registry.yarnpkg.com/prelude-ls/-/prelude-ls-1.1.2.tgz#21932a549f5e52ffd9a827f570e04be62a97da54";
+
address@hidden:
+ version "1.0.7"
+ resolved
"https://registry.yarnpkg.com/process-nextick-args/-/process-nextick-args-1.0.7.tgz#150e20b756590ad3f91093f25a4f2ad8bff30ba3";
+
address@hidden:
+ version "2.0.0"
+ resolved
"https://registry.yarnpkg.com/progress/-/progress-2.0.0.tgz#8a1be366bf8fc23db2bd23f10c6fe920b4389d1f";
+
address@hidden:
+ version "1.0.2"
+ resolved
"https://registry.yarnpkg.com/pseudomap/-/pseudomap-1.0.2.tgz#f052a28da70e618917ef0a8ac34c1ae5a68286b3";
+
address@hidden:
+ version "1.2.0"
+ resolved
"https://registry.yarnpkg.com/range-parser/-/range-parser-1.2.0.tgz#f49be6b487894ddc40dcc94a322f611092e00d5e";
+
address@hidden:
+ version "1.0.1"
+ resolved
"https://registry.yarnpkg.com/read-pkg-up/-/read-pkg-up-1.0.1.tgz#9d63c13276c065918d57f002a57f40a1b643fb02";
+ dependencies:
+ find-up "^1.0.0"
+ read-pkg "^1.0.0"
+
address@hidden:
+ version "1.1.0"
+ resolved
"https://registry.yarnpkg.com/read-pkg/-/read-pkg-1.1.0.tgz#f5ffaa5ecd29cb31c0474bca7d756b6bb29e3f28";
+ dependencies:
+ load-json-file "^1.0.0"
+ normalize-package-data "^2.3.2"
+ path-type "^1.0.0"
+
address@hidden:
+ version "2.3.3"
+ resolved
"https://registry.yarnpkg.com/readable-stream/-/readable-stream-2.3.3.tgz#368f2512d79f9d46fdfc71349ae7878bbc1eb95c";
+ dependencies:
+ core-util-is "~1.0.0"
+ inherits "~2.0.3"
+ isarray "~1.0.0"
+ process-nextick-args "~1.0.6"
+ safe-buffer "~5.1.1"
+ string_decoder "~1.0.3"
+ util-deprecate "~1.0.1"
+
address@hidden:
+ version "1.7.1"
+ resolved
"https://registry.yarnpkg.com/remarkable/-/remarkable-1.7.1.tgz#aaca4972100b66a642a63a1021ca4bac1be3bff6";
+ dependencies:
+ argparse "~0.1.15"
+ autolinker "~0.15.0"
+
address@hidden:
+ version "2.1.1"
+ resolved
"https://registry.yarnpkg.com/require-directory/-/require-directory-2.1.1.tgz#8c64ad5fd30dab1c976e2344ffe7f792a6a6df42";
+
address@hidden:
+ version "1.0.1"
+ resolved
"https://registry.yarnpkg.com/require-main-filename/-/require-main-filename-1.0.1.tgz#97f717b69d48784f5f526a6c5aa8ffdda055a4d1";
+
address@hidden:
+ version "1.0.3"
+ resolved
"https://registry.yarnpkg.com/require-uncached/-/require-uncached-1.0.3.tgz#4e0d56d6c9662fd31e43011c4b95aa49955421d3";
+ dependencies:
+ caller-path "^0.1.0"
+ resolve-from "^1.0.0"
+
address@hidden:
+ version "2.1.22"
+ resolved
"https://registry.yarnpkg.com/requirejs/-/requirejs-2.1.22.tgz#dd78fd2d34180c0d62c724b5b8aebc0664e0366f";
+
address@hidden:
+ version "1.0.1"
+ resolved
"https://registry.yarnpkg.com/resolve-from/-/resolve-from-1.0.1.tgz#26cbfe935d1aeeeabb29bc3fe5aeb01e93d44226";
+
address@hidden:
+ version "2.0.0"
+ resolved
"https://registry.yarnpkg.com/restore-cursor/-/restore-cursor-2.0.0.tgz#9f7ee287f82fd326d4fd162923d62129eee0dfaf";
+ dependencies:
+ onetime "^2.0.0"
+ signal-exit "^3.0.2"
+
address@hidden:
+ version "2.6.1"
+ resolved
"https://registry.yarnpkg.com/rimraf/-/rimraf-2.6.1.tgz#c2338ec643df7a1b7fe5c54fa86f57428a55f33d";
+ dependencies:
+ glob "^7.0.5"
+
address@hidden:
+ version "2.3.0"
+ resolved
"https://registry.yarnpkg.com/run-async/-/run-async-2.3.0.tgz#0371ab4ae0bdd720d4166d7dfda64ff7a445a6c0";
+ dependencies:
+ is-promise "^2.1.0"
+
address@hidden:
+ version "4.0.8"
+ resolved
"https://registry.yarnpkg.com/rx-lite-aggregates/-/rx-lite-aggregates-4.0.8.tgz#753b87a89a11c95467c4ac1626c4efc4e05c67be";
+ dependencies:
+ rx-lite "*"
+
address@hidden, address@hidden:
+ version "4.0.8"
+ resolved
"https://registry.yarnpkg.com/rx-lite/-/rx-lite-4.0.8.tgz#0b1e11af8bc44836f04a6407e92da42467b79444";
+
address@hidden, address@hidden:
+ version "5.1.1"
+ resolved
"https://registry.yarnpkg.com/safe-buffer/-/safe-buffer-5.1.1.tgz#893312af69b2123def71f57889001671eeb2c853";
+
+"address@hidden || 3 || 4 || 5", address@hidden:
+ version "5.4.1"
+ resolved
"https://registry.yarnpkg.com/semver/-/semver-5.4.1.tgz#e059c09d8571f0540823733433505d3a2f00b18e";
+
address@hidden:
+ version "0.15.4"
+ resolved
"https://registry.yarnpkg.com/send/-/send-0.15.4.tgz#985faa3e284b0273c793364a35c6737bd93905b9";
+ dependencies:
+ debug "2.6.8"
+ depd "~1.1.1"
+ destroy "~1.0.4"
+ encodeurl "~1.0.1"
+ escape-html "~1.0.3"
+ etag "~1.8.0"
+ fresh "0.5.0"
+ http-errors "~1.6.2"
+ mime "1.3.4"
+ ms "2.0.0"
+ on-finished "~2.3.0"
+ range-parser "~1.2.0"
+ statuses "~1.3.1"
+
address@hidden:
+ version "1.12.4"
+ resolved
"https://registry.yarnpkg.com/serve-static/-/serve-static-1.12.4.tgz#9b6aa98eeb7253c4eedc4c1f6fdbca609901a961";
+ dependencies:
+ encodeurl "~1.0.1"
+ escape-html "~1.0.3"
+ parseurl "~1.3.1"
+ send "0.15.4"
+
address@hidden:
+ version "2.0.0"
+ resolved
"https://registry.yarnpkg.com/set-blocking/-/set-blocking-2.0.0.tgz#045f9782d011ae9a6803ddd382b24392b3d890f7";
+
address@hidden:
+ version "1.0.3"
+ resolved
"https://registry.yarnpkg.com/setprototypeof/-/setprototypeof-1.0.3.tgz#66567e37043eeb4f04d91bd658c0cbefb55b8e04";
+
address@hidden:
+ version "1.2.0"
+ resolved
"https://registry.yarnpkg.com/shebang-command/-/shebang-command-1.2.0.tgz#44aac65b695b03398968c39f363fee5deafdf1ea";
+ dependencies:
+ shebang-regex "^1.0.0"
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/shebang-regex/-/shebang-regex-1.0.0.tgz#da42f49740c0b42db2ca9728571cb190c98efea3";
+
address@hidden:
+ version "3.0.2"
+ resolved
"https://registry.yarnpkg.com/signal-exit/-/signal-exit-3.0.2.tgz#b5fdc08f1287ea1178628e415e25132b73646c6d";
+
address@hidden:
+ version "0.0.4"
+ resolved
"https://registry.yarnpkg.com/slice-ansi/-/slice-ansi-0.0.4.tgz#edbf8903f66f7ce2f8eafd6ceed65e264c831b35";
+
address@hidden:
+ version "0.5.7"
+ resolved
"https://registry.yarnpkg.com/source-map/-/source-map-0.5.7.tgz#8a039d2d1021d22d1ea14c80d8ea468ba2ef3fcc";
+
address@hidden:
+ version "1.0.2"
+ resolved
"https://registry.yarnpkg.com/spdx-correct/-/spdx-correct-1.0.2.tgz#4b3073d933ff51f3912f03ac5519498a4150db40";
+ dependencies:
+ spdx-license-ids "^1.0.2"
+
address@hidden:
+ version "1.0.4"
+ resolved
"https://registry.yarnpkg.com/spdx-expression-parse/-/spdx-expression-parse-1.0.4.tgz#9bdf2f20e1f40ed447fbe273266191fced51626c";
+
address@hidden:
+ version "1.2.2"
+ resolved
"https://registry.yarnpkg.com/spdx-license-ids/-/spdx-license-ids-1.2.2.tgz#c9df7a3424594ade6bd11900d596696dc06bac57";
+
address@hidden:
+ version "1.0.3"
+ resolved
"https://registry.yarnpkg.com/sprintf-js/-/sprintf-js-1.0.3.tgz#04e6926f662895354f3dd015203633b857297e2c";
+
+"statuses@>= 1.3.1 < 2", address@hidden:
+ version "1.3.1"
+ resolved
"https://registry.yarnpkg.com/statuses/-/statuses-1.3.1.tgz#faf51b9eb74aaef3b3acf4ad5f61abf24cb7b93e";
+
address@hidden, address@hidden:
+ version "1.0.2"
+ resolved
"https://registry.yarnpkg.com/string-width/-/string-width-1.0.2.tgz#118bdf5b8cdc51a2a7e70d211e07e2b0b9b107d3";
+ dependencies:
+ code-point-at "^1.0.0"
+ is-fullwidth-code-point "^1.0.0"
+ strip-ansi "^3.0.0"
+
address@hidden, address@hidden:
+ version "2.1.1"
+ resolved
"https://registry.yarnpkg.com/string-width/-/string-width-2.1.1.tgz#ab93f27a8dc13d28cac815c462143a6d9012ae9e";
+ dependencies:
+ is-fullwidth-code-point "^2.0.0"
+ strip-ansi "^4.0.0"
+
address@hidden:
+ version "1.0.3"
+ resolved
"https://registry.yarnpkg.com/string_decoder/-/string_decoder-1.0.3.tgz#0fc67d7c141825de94282dd536bec6b9bce860ab";
+ dependencies:
+ safe-buffer "~5.1.0"
+
address@hidden, address@hidden:
+ version "3.0.1"
+ resolved
"https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-3.0.1.tgz#6a385fb8853d952d5ff05d0e8aaf94278dc63dcf";
+ dependencies:
+ ansi-regex "^2.0.0"
+
address@hidden:
+ version "4.0.0"
+ resolved
"https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-4.0.0.tgz#a8479022eb1ac368a871389b635262c505ee368f";
+ dependencies:
+ ansi-regex "^3.0.0"
+
address@hidden:
+ version "2.0.0"
+ resolved
"https://registry.yarnpkg.com/strip-bom/-/strip-bom-2.0.0.tgz#6219a85616520491f35788bdbf1447a99c7e6b0e";
+ dependencies:
+ is-utf8 "^0.2.0"
+
address@hidden:
+ version "2.0.1"
+ resolved
"https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-2.0.1.tgz#3c531942e908c2697c0ec344858c286c7ca0a60a";
+
address@hidden:
+ version "2.0.0"
+ resolved
"https://registry.yarnpkg.com/supports-color/-/supports-color-2.0.0.tgz#535d045ce6b6363fa40117084629995e9df324c7";
+
address@hidden:
+ version "4.2.1"
+ resolved
"https://registry.yarnpkg.com/supports-color/-/supports-color-4.2.1.tgz#65a4bb2631e90e02420dba5554c375a4754bb836";
+ dependencies:
+ has-flag "^2.0.0"
+
address@hidden:
+ version "4.0.1"
+ resolved
"https://registry.yarnpkg.com/table/-/table-4.0.1.tgz#a8116c133fac2c61f4a420ab6cdf5c4d61f0e435";
+ dependencies:
+ ajv "^4.7.0"
+ ajv-keywords "^1.0.0"
+ chalk "^1.1.1"
+ lodash "^4.0.0"
+ slice-ansi "0.0.4"
+ string-width "^2.0.0"
+
address@hidden:
+ version "0.2.0"
+ resolved
"https://registry.yarnpkg.com/text-table/-/text-table-0.2.0.tgz#7f5ee823ae805207c00af2df4a84ec3fcfa570b4";
+
address@hidden:
+ version "2.3.8"
+ resolved
"https://registry.yarnpkg.com/through/-/through-2.3.8.tgz#0dd4c9ffaabc357960b1b724115d7e0e86a2e1f5";
+
address@hidden:
+ version "0.0.31"
+ resolved
"https://registry.yarnpkg.com/tmp/-/tmp-0.0.31.tgz#8f38ab9438e17315e5dbd8b3657e8bfb277ae4a7";
+ dependencies:
+ os-tmpdir "~1.0.1"
+
address@hidden:
+ version "1.0.3"
+ resolved
"https://registry.yarnpkg.com/tryit/-/tryit-1.0.3.tgz#393be730a9446fd1ead6da59a014308f36c289cb";
+
address@hidden:
+ version "0.3.2"
+ resolved
"https://registry.yarnpkg.com/type-check/-/type-check-0.3.2.tgz#5884cab512cf1d355e3fb784f30804b2b520db72";
+ dependencies:
+ prelude-ls "~1.1.2"
+
address@hidden:
+ version "0.0.6"
+ resolved
"https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777";
+
address@hidden:
+ version "2.5.1"
+ resolved
"https://registry.yarnpkg.com/typescript/-/typescript-2.5.1.tgz#ce7cc93ada3de19475cc9d17e3adea7aee1832aa";
+
address@hidden:
+ version "3.0.28"
+ resolved
"https://registry.yarnpkg.com/uglify-js/-/uglify-js-3.0.28.tgz#96b8495f0272944787b5843a1679aa326640d5f7";
+ dependencies:
+ commander "~2.11.0"
+ source-map "~0.5.1"
+
address@hidden:
+ version "2.4.0"
+ resolved
"https://registry.yarnpkg.com/underscore.string/-/underscore.string-2.4.0.tgz#8cdd8fbac4e2d2ea1e7e2e8097c42f442280f85b";
+
address@hidden:
+ version "1.7.0"
+ resolved
"https://registry.yarnpkg.com/underscore/-/underscore-1.7.0.tgz#6bbaf0877500d36be34ecaa584e0db9fef035209";
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/unpipe/-/unpipe-1.0.0.tgz#b2bf4ee8514aae6165b4817829d21b2ef49904ec";
+
address@hidden:
+ version "1.0.2"
+ resolved
"https://registry.yarnpkg.com/util-deprecate/-/util-deprecate-1.0.2.tgz#450d4dc9fa70de732762fbd2d4a28981419a0ccf";
+
address@hidden:
+ version "3.0.1"
+ resolved
"https://registry.yarnpkg.com/validate-npm-package-license/-/validate-npm-package-license-3.0.1.tgz#2804babe712ad3379459acfbe24746ab2c303fbc";
+ dependencies:
+ spdx-correct "~1.0.0"
+ spdx-expression-parse "~1.0.0"
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/which-module/-/which-module-1.0.0.tgz#bba63ca861948994ff307736089e3b96026c2a4f";
+
address@hidden:
+ version "1.3.0"
+ resolved
"https://registry.yarnpkg.com/which/-/which-1.3.0.tgz#ff04bdfc010ee547d780bec38e1ac1c2777d253a";
+ dependencies:
+ isexe "^2.0.0"
+
address@hidden:
+ version "1.0.0"
+ resolved
"https://registry.yarnpkg.com/wordwrap/-/wordwrap-1.0.0.tgz#27584810891456a4171c8d0226441ade90cbcaeb";
+
address@hidden:
+ version "2.1.0"
+ resolved
"https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-2.1.0.tgz#d8fc3d284dd05794fe84973caecdd1cf824fdd85";
+ dependencies:
+ string-width "^1.0.1"
+ strip-ansi "^3.0.1"
+
address@hidden:
+ version "1.0.2"
+ resolved
"https://registry.yarnpkg.com/wrappy/-/wrappy-1.0.2.tgz#b5243d8f3ec1aa35f1364605bc0d1036e30ab69f";
+
address@hidden:
+ version "0.2.1"
+ resolved
"https://registry.yarnpkg.com/write/-/write-0.2.1.tgz#5fc03828e264cea3fe91455476f7a3c566cb0757";
+ dependencies:
+ mkdirp "^0.5.1"
+
address@hidden:
+ version "3.2.1"
+ resolved
"https://registry.yarnpkg.com/y18n/-/y18n-3.2.1.tgz#6d15fba884c08679c0d77e88e7759e811e07fa41";
+
address@hidden:
+ version "2.1.2"
+ resolved
"https://registry.yarnpkg.com/yallist/-/yallist-2.1.2.tgz#1c11f9218f076089a47dd512f93c6699a6a81d52";
+
address@hidden:
+ version "5.0.0"
+ resolved
"https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-5.0.0.tgz#275ecf0d7ffe05c77e64e7c86e4cd94bf0e1228a";
+ dependencies:
+ camelcase "^3.0.0"
+
address@hidden:
+ version "7.0.2"
+ resolved
"https://registry.yarnpkg.com/yargs/-/yargs-7.0.2.tgz#115b97df1321823e8b8648e8968c782521221f67";
+ dependencies:
+ camelcase "^3.0.0"
+ cliui "^3.2.0"
+ decamelize "^1.1.1"
+ get-caller-file "^1.0.1"
+ os-locale "^1.4.0"
+ read-pkg-up "^1.0.1"
+ require-directory "^2.1.1"
+ require-main-filename "^1.0.1"
+ set-blocking "^2.0.0"
+ string-width "^1.0.2"
+ which-module "^1.0.0"
+ y18n "^3.2.1"
+ yargs-parser "^5.0.0"
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [7983] add js directory to hold work from mthl's GSOC project in 2017,
gavinsmith0123 <=