~ chicken-core (chicken-5) 9f515cf3a69331612da30de41d2af59a6b150601
commit 9f515cf3a69331612da30de41d2af59a6b150601
Author: felix <bunny351@gmail.com>
AuthorDate: Tue May 18 07:31:29 2010 +0200
Commit: felix <bunny351@gmail.com>
CommitDate: Tue May 18 07:31:29 2010 +0200
merged wiki manual
diff --git a/manual/C interface b/manual/C interface
index 1fd00c9d..7db21ff7 100644
--- a/manual/C interface
+++ b/manual/C interface
@@ -147,7 +147,7 @@ bytevectors ("blobs"). However, it does ''not'' return true for
SRFI-4 vectors, as those are actually bytevectors wrapped in a
structure with a type tag.
-===== C_vectorp
+===== C_bytevectorp
[C macro] C_word C_bytevectorp(C_word x)
diff --git a/manual/Data representation b/manual/Data representation
index 451ddbcf..fcbf0772 100644
--- a/manual/Data representation
+++ b/manual/Data representation
@@ -1,7 +1,6 @@
[[toc:]]
[[tags: manual]]
-
== Data representation
There exist two different kinds of data objects in the CHICKEN system:
diff --git a/manual/Deviations from the standard b/manual/Deviations from the standard
index a36dd3e9..41a9168e 100644
--- a/manual/Deviations from the standard
+++ b/manual/Deviations from the standard
@@ -3,71 +3,104 @@
== Confirmed deviations
Identifiers are by default case-sensitive (see
-[[http://galinha.ucpel.tche.br:8080/Using%20the%20compiler#Compiler%20command%20line%20format|Compiler command line format]]).
+[[http://chicken.wiki.br.br/Using%20the%20compiler#Compiler%20command%20line%20format|Compiler command line format]]).
-[4.1.3] The maximal number of arguments that may be passed to a
+=== Number of arguments to procedures and macros
+
+The maximal number of arguments that may be passed to a
compiled procedure or macro is 120. (However, a macro-definition
that has a single rest-parameter can have any number of arguments.)
-Likewise, [6.4] the maximum number of values that can be passed
+Likewise, the maximum number of values that can be passed
to continuations captured using {{call-with-current-continuation}}
is 120. This is an implementation restriction that is unlikely
to be lifted.
-[6.2.5] The {{numerator}} and {{denominator}} procedures cannot be
+
+=== {{numerator}}, {{denominator}} and {{rationalize}}
+
+The {{numerator}} and {{denominator}} procedures cannot be
applied to inexact numbers, and the procedure {{rationalize}} is not
implemented at all. This will be fixed in a later release.
-[6.2.4] The runtime system uses the numerical string-conversion
+
+=== Numeric string-conversion considerations
+
+The runtime system uses the numerical string-conversion
routines of the underlying C library and so does only understand
standard (C-library) syntax for floating-point constants. Consequently,
-the procedures [6.2.6] {{string->number}}, [6.6.2] {{read}},
-[6.6.3] {{write}}, and [6.6.3] {{display}} do not obey
+the procedures {{string->number}}, {{read}}, {{write}}, and {{display}} do not obey
read/write invariance to inexact numbers.
-[6.5] Code evaluated in {{scheme-report-environment}} or
+
+=== Environments and non-standard syntax
+
+Code evaluated in {{scheme-report-environment}} or
{{null-environment}} still sees non-standard syntax.
+
+
== Unconfirmed deviations
-[6.6.2] The procedure {{char-ready?}} always returns {{#t}} for
+=== {{char-ready?}}
+
+The procedure {{char-ready?}} always returns {{#t}} for
terminal ports.
+
+
== Doubtful deviations
-[4.2.2] {{letrec}} does evaluate the initial values for the bound
+=== {{letrec}}
+
+{{letrec}} does evaluate the initial values for the bound
variables sequentially and not in parallel, that is:
- (letrec ((x 1) (y 2)) (cons x y))
+<enscript highlight="scheme">
+(letrec ((x 1) (y 2)) (cons x y))
+</enscript>
is equivalent to
- (let ((x (void)) (y (void)))
- (set! x 1)
- (set! y 2)
- (cons x y) )
+<enscript highlight="scheme">
+(let ((x (void)) (y (void)))
+ (set! x 1)
+ (set! y 2)
+ (cons x y) )
+</enscript>
where R5RS requires
- (let ((x (void)) (y (void)))
- (let ((tmp1 1) (tmp2 2))
- (set! x tmp1)
- (set! y tmp2)
- (cons x y) ) )
+<enscript highlight="scheme">
+(let ((x (void)) (y (void)))
+ (let ((tmp1 1) (tmp2 2))
+ (set! x tmp1)
+ (set! y tmp2)
+ (cons x y) ) )
+</enscript>
It is unclear whether R5RS permits this behavior or not; in any case,
this only affects letrecs where the bound values are not
lambda-expressions.
+
== Non-deviations that might surprise you
-[4.3.1] {{let-syntax}} and {{letrec-syntax}} introduce a new scope.
+=== {{let-syntax}} and {{letrec-syntax}}
+
+{{let-syntax}} and {{letrec-syntax}} introduce a new scope.
+
-[6.1] {{equal?}} compares all structured data recursively, while R5RS
+=== {{equal?}} compares all structured data recursively
+
+{{equal?}} compares all structured data recursively, while R5RS
specifies that {{eqv?}} is used for data other than pairs, strings and
vectors. However, R5RS does not dictate the treatment of data types
that are not specified by R5RS.
-[6.2.5] There is no built-in support for exact rationals, complex
+
+=== No built-in support for bignums
+
+There is no built-in support for exact rationals, complex
numbers or extended-precision integers (bignums). The routines
{{complex?}}, {{real?}} and {{rational?}} are identical to
the standard procedure {{number?}}. The procedures {{make-rectangular}}
@@ -76,7 +109,10 @@ and {{make-polar}} are not implemented. Fixnums are limited to
on 64-bit hardware). Support for the full numeric tower is available
as a separate package, provided the GNU multiprecision library is installed.
-[6.6.4] The {{transcript-on}} and {{transcript-off}} procedures are
+
+=== {{transcript-on}} and {{transcript-off}} are not implemented
+
+The {{transcript-on}} and {{transcript-off}} procedures are
not implemented. R5RS does not require them.
---
diff --git a/manual/Exceptions b/manual/Exceptions
new file mode 100644
index 00000000..1a28cf96
--- /dev/null
+++ b/manual/Exceptions
@@ -0,0 +1,345 @@
+[[tags: manual]]
+[[toc:]]
+
+== Exceptions
+
+Chicken's exception handling is based on the
+[[http://srfi.schemers.org/srfi-12/srfi-12.html|SRFI-12]] exception
+system. This document contains the core of the SRFI-12 spec
+as well as Chicken implementation specifics.
+
+== Chicken implementation
+
+=== System conditions
+
+All error-conditions signaled by the system are of kind {{exn}}.
+The following composite conditions are additionally defined:
+
+<table>
+
+<tr><td> (exn arity) </td><td>
+
+Signaled when a procedure is called with the wrong number of arguments.
+
+</td></tr><tr><td> (exn type) </td><td>
+
+Signaled on type-mismatch errors, for example when an argument of the wrong
+type is passed to a built-in procedure.
+
+</td></tr><tr><td> (exn arithmetic) </td><td>
+
+Signaled on arithmetic errors, like division by zero.
+
+</td></tr><tr><td> (exn i/o) </td><td>
+
+Signaled on input/output errors.
+
+</td></tr><tr><td> (exn i/o file) </td><td>
+
+Signaled on file-related errors.
+
+</td></tr><tr><td> (exn i/o net) </td><td>
+
+Signaled on network errors.
+
+</td></tr><tr><td> (exn bounds) </td><td>
+
+Signaled on errors caused by accessing non-existent elements of a collection.
+
+</td></tr><tr><td> (exn runtime) </td><td>
+
+Signaled on low-level runtime-system error-situations.
+
+</td></tr><tr><td> (exn runtime limit) </td><td>
+
+Signaled when an internal limit is exceeded (like running out of memory).
+
+</td></tr><tr><td> (exn match) </td><td>
+
+Signaled on errors raised by failed matches (see the section on {{match}}).
+
+</td></tr><tr><td> (exn syntax) </td><td>
+
+Signaled on syntax errors.
+
+</td></tr>
+
+</table>
+
+=== Notes
+
+* All error-exceptions (of the kind {{exn}}) are non-continuable.
+
+* Error-exceptions of the {{exn}} kind have additional {{arguments}} and
+{{location}} properties that contain the arguments passed to the
+exception-handler and the name of the procedure where the error occurred (if
+available).
+
+* When the {{posix}} unit is available and used, then a user-interrupt
+({{signal/int}}) signals an exception of the kind {{user-interrupt}}.
+
+* The procedure {{condition-property-accessor}} accepts an optional third
+argument. If the condition does not have a value for the desired property and
+if the optional argument is given, no error is signaled and the accessor
+returns the third argument.
+
+=== Additional API
+
+<macro>(condition-case EXPRESSION CLAUSE ...)</macro>
+
+Evaluates {{EXPRESSION}} and handles any exceptions that are covered by
+{{CLAUSE ...}}, where {{CLAUSE}} should be of the following form:
+
+<enscript highlight=scheme>
+CLAUSE = ([VARIABLE] (KIND ...) BODY ...)
+</enscript>
+
+If provided, {{VARIABLE}} will be bound to the signaled exception
+object. {{BODY ...}} is executed when the exception is a property-
+or composite condition with the kinds given {{KIND ...}} (unevaluated).
+If no clause applies, the exception is re-signaled in the same dynamic
+context as the {{condition-case}} form.
+
+<enscript highlight=scheme>
+(define (check thunk)
+ (condition-case (thunk)
+ [(exn file) (print "file error")]
+ [(exn) (print "other error")]
+ [var () (print "something else")] ) )
+
+(check (lambda () (open-input-file ""))) ; -> "file error"
+(check (lambda () some-unbound-variable)) ; -> "othererror"
+(check (lambda () (signal 99))) ; -> "something else"
+
+(condition-case some-unbound-variable
+ [(exn file) (print "ignored")] ) ; -> signals error
+</enscript>
+
+<procedure>(get-condition-property CONDITION KIND PROPERTY [DEFAULT])</procedure>
+
+A slightly more convenient condition property accessor, equivalent to
+
+ ((condition-property-accessor KIND PROPERTY [DEFAULT]) CONDITION)
+
+== SRFI-12 specification
+
+A Scheme implementation ("the system") raises an exception whenever an
+error is to be signaled or whenever the system determines that evaluation
+cannot proceed in a manner consistent with the semantics of Scheme. A
+program may also explicitly raise an exception.
+
+Whenever the system raises an exception, it invokes the current exception
+handler with a condition object (encapsulating information about the
+exception) as its only argument. Any procedure accepting one argument
+may serve as an exception handler. When a program explicitly raises an
+exception, it may supply any object to the exception handler.
+
+An exception is either continuable or non-continuable. When the current
+exception handler is invoked for a continuable exception, the continuation
+uses the handler's result(s) in an exception-specific way to continue.
+When an exception handler is invoked for a non-continuable exception,
+the continuation raises a non-continuable exception indicating that the
+exception handler returned. On Chicken, system error exceptions
+(of kind {{exn}}) are non-continuable.
+
+=== Exception Handlers
+
+<procedure>(current-exception-handler)</procedure><br>
+
+Returns the current exception handler.
+
+<procedure>(with-exception-handler handler thunk)</procedure><br>
+
+Returns the result(s) of invoking ''thunk''. The ''handler'' procedure
+is installed as the current exception handler in the dynamic context of
+invoking ''thunk''.
+
+Example:
+
+ (call-with-current-continuation
+ (lambda (k)
+ (WITH-EXCEPTION-HANDLER (lambda (x) (k '()))
+ (lambda () (car '())))))
+ ;=> '()
+
+<macro>(handle-exceptions var handle-expr expr1 expr2 ...)</macro><br>
+
+Evaluates the body expressions ''expr1'', ''expr2'', ... in sequence with
+an exception handler constructed from ''var'' and ''handle-expr''. Assuming
+no exception is raised, the result(s) of the last body expression is(are)
+the result(s) of the HANDLE-EXCEPTIONS expression.
+
+The exception handler created by HANDLE-EXCEPTIONS restores the dynamic
+context (continuation, exception handler, etc.) of the HANDLE-EXCEPTIONS
+expression, and then evaluates ''handle-expr'' with ''var'' bound to the
+value provided to the handler.
+
+Examples:
+
+ (HANDLE-EXCEPTIONS exn
+ (begin
+ (display "Went wrong")
+ (newline))
+ (car '()))
+ ; displays "Went wrong"
+
+ (HANDLE-EXCEPTIONS exn
+ (cond
+ ((eq? exn 'one) 1)
+ (else (ABORT exn)))
+ (case (random-number)
+ [(0) 'zero]
+ [(1) (ABORT 'one)]
+ [else (ABORT "Something else")]))
+ ;=> 'zero, 1, or (ABORT "Something else")
+
+=== Raising Exceptions
+
+<procedure>(abort obj)</procedure><br>
+
+Raises a non-continuable exception represented by ''obj''. The ABORT
+procedure can be implemented as follows:
+
+ (define (abort obj)
+ ((current-exception-handler) obj)
+ (abort (make-property-condition
+ 'exn
+ 'message
+ "Exception handler returned")))
+
+The ABORT procedure does not ensure that its argument is a condition.
+If its argument is a condition, ABORT does not ensure that the condition
+indicates a non-continuable exception.
+
+<procedure>(signal obj)</procedure><br>
+
+Raises a continuable exception represented by ''obj''. The SIGNAL procedure
+can be implemented as follows:
+
+ (define (signal exn)
+ ((current-exception-handler) exn))
+
+The SIGNAL procedure does not ensure that its argument is a condition.
+If its argument is a condition, SIGNAL does not ensure that the condition
+indicates a continuable exception.
+
+=== Condition Objects
+
+<procedure>(condition? obj)</procedure><br>
+
+Returns #t if ''obj'' is a condition, otherwise returns #f. If any of
+the predicates listed in Section 3.2 of the R5RS is true of ''obj'', then
+CONDITION? is false of ''obj''.
+
+Rationale: Any Scheme object may be passed to an exception handler. This
+would cause ambiguity if conditions were not disjoint from all of Scheme's
+standard types.
+
+<procedure>(make-property-condition kind-key prop-key value ...)</procedure><br>
+
+This procedure accepts any even number of arguments after ''kind-key'',
+which are regarded as a sequence of alternating ''prop-key'' and ''value''
+objects. Each ''prop-key'' is regarded as the name of a property, and
+each ''value'' is regarded as the value associated with the ''key'' that
+precedes it. Returns a ''kind-key'' condition that associates the given
+''prop-key''s with the given ''value''s.
+
+<procedure>(make-composite-condition condition ...)</procedure><br>
+
+Returns a newly-allocated condition whose components correspond to the the
+given ''condition''s. A predicate created by CONDITION-PREDICATE returns
+true for the new condition if and only if it returns true for one or more
+of its component conditions.
+
+<procedure>(condition-predicate kind-key)</procedure><br>
+
+Returns a predicate that can be called with any object as its argument.
+Given a condition that was created by MAKE-PROPERTY-CONDITION, the
+predicate returns #t if and only if ''kind-key'' is EQV? to the kind key
+that was passed to MAKE-PROPERTY-CONDITION. Given a composite condition
+created with MAKE-COMPOSITE-CONDITION, the predicate returns #t if and only
+if the predicate returns #t for at least one of its components.
+
+<procedure>(condition-property-accessor kind-key prop-key [default])</procedure><br>
+
+Returns a procedure that can be called with any condition that satisfies
+(CONDITION-PREDICATE ''kind-key''). Given a condition that was created
+by MAKE-PROPERTY-CONDITION and ''kind-key'', the procedure returns the
+value that is associated with ''prop-key''. Given a composite condition
+created with MAKE-COMPOSITE-CONDITION, the procedure returns the value that
+is associated with ''prop-key'' in one of the components that satisfies
+(CONDITION-PREDICATE ''kind-key'').
+
+On Chicken, this procedure accepts an optional third argument
+DEFAULT. If the condition does not have a value for the desired
+property and if the optional argument is given, no error is signaled
+and the accessor returns the third argument.
+
+When the system raises an exception, the condition it passes to the
+exception handler includes the {{'exn}} kind with the following
+properties:
+
+; message : the error message
+; arguments: the arguments passed to the exception handler
+; location: the name of the procedure where the error occurred (if available)
+
+Thus, if ''exn'' is a condition representing a system exception,
+then
+
+ ((condition-property-accessor 'exn 'message) exn)
+
+extracts the error message from ''exn''. Example:
+
+ (HANDLE-EXCEPTIONS exn
+ (begin
+ (display "Went wrong: ")
+ (display
+ ((condition-property-accessor 'exn 'message) exn))
+ (newline))
+ (car '()))
+ ; displays something like "Went wrong: can't take car of nil"
+
+=== More Examples
+
+ (define (try-car v)
+ (let ((orig (current-exception-handler)))
+ (WITH-EXCEPTION-HANDLER
+ (lambda (exn)
+ (orig (make-composite-condition
+ (make-property-condition
+ 'not-a-pair
+ 'value
+ v)
+ exn)))
+ (lambda () (car v)))))
+
+ (try-car '(1))
+ ;=> 1
+
+ (HANDLE-EXCEPTIONS exn
+ (if ((condition-predicate 'not-a-pair) exn)
+ (begin
+ (display "Not a pair: ")
+ (display
+ ((condition-property-accessor 'not-a-pair 'value) exn))
+ (newline))
+ (ABORT exn))
+ (try-car 0))
+ ; displays "Not a pair: 0"
+
+ (let* ((cs-key (list 'color-scheme))
+ (bg-key (list 'background))
+ (color-scheme? (condition-predicate cs-key))
+ (color-scheme-background
+ (condition-property-accessor cs-key bg-key))
+ (condition1 (make-property-condition cs-key bg-key 'green))
+ (condition2 (make-property-condition cs-key bg-key 'blue))
+ (condition3 (make-composite-condition condition1 condition2)))
+ (and (color-scheme? condition1)
+ (color-scheme? condition2)
+ (color-scheme? condition3)
+ (color-scheme-background condition3)))
+ ; => 'green or 'blue
+
+----
+Previous: [[Parameters]] Next: [[Unit library]]
diff --git a/manual/Extensions b/manual/Extensions
index eb392a3a..cc283e69 100644
--- a/manual/Extensions
+++ b/manual/Extensions
@@ -160,7 +160,7 @@ files in {{FILELIST}} to executable (for installing shell-scripts).
==== standard-extension
- [procedure] (standard-extension ID VERSION #!key static info)
+<procedure>(standard-extension ID VERSION #!key static info)</procedure>
A convenience procedure that combines the compilation and installation of
a simple single-file extension. This is roughly equivalent to:
diff --git a/manual/Foreign type specifiers b/manual/Foreign type specifiers
index b8a6093c..e3ad9878 100644
--- a/manual/Foreign type specifiers
+++ b/manual/Foreign type specifiers
@@ -281,7 +281,7 @@ struct NAME
</td></tr><tr><td>(ref TYPE)</td><td>
TYPE &
</td></tr><tr><td>(template T1 T2 ...)</td><td>
-T1<T2, ...>
+T1<T2, ...>
</td></tr><tr><td>(union NAME)</td><td>
union NAME
</td></tr><tr><td>(function RTYPE (ATYPE ...) [CALLCONV])</td><td>
diff --git a/manual/Getting started b/manual/Getting started
index 255803af..942d8b0c 100644
--- a/manual/Getting started
+++ b/manual/Getting started
@@ -192,7 +192,7 @@ resources.
The Chicken wiki ([[http://chicken.wiki.br]]) contains the most
current version of the User's manual, along with various tutorials and
other useful documents. The list of eggs is at
-[[http://chicken.wiki.br/Eggs%20Unlimited]].
+[[http://chicken.wiki.br/chicken-projects/egg-index-4.html#category-list]].
A very useful search facility for questions about Chicken is found at
[[http://www.callcc.org]]. The Chicken issue tracker is at
diff --git a/manual/Modules and macros b/manual/Modules and macros
index 4c7addf6..30bc97fe 100644
--- a/manual/Modules and macros
+++ b/manual/Modules and macros
@@ -167,11 +167,11 @@ references to {{exit}} in the body of the loop, so {{exit}} is not
renamed.
(define-syntax loop
- (lambda (x r c)
- (let ((body (cdr x)))
- `(,(r 'call-with-current-continuation)
- (,(r 'lambda) (exit)
- (,(r 'let) ,(r 'f) () ,@body (,(r 'f))))))))
+ (lambda (x r c)
+ (let ((body (cdr x)))
+ `(,(r 'call-with-current-continuation)
+ (,(r 'lambda) (exit)
+ (,(r 'let) ,(r 'f) () ,@body (,(r 'f))))))))
Suppose a {{while}} macro is implemented using {{loop}}, with the intent
that {{exit}} may be used to escape from the {{while}} loop. The {{while}}
@@ -189,12 +189,12 @@ inserted by the {{loop}} macro. In other words, this {{while}} macro is
not hygienic. Like {{loop}}, it must be written using procedurally:
(define-syntax while
- (lambda (x r c)
- (let ((test (cadr x))
- (body (cddr x)))
- `(,(r 'loop)
- (,(r 'if) (,(r 'not) ,test) (exit #f))
- ,@body))))
+ (lambda (x r c)
+ (let ((test (cadr x))
+ (body (cddr x)))
+ `(,(r 'loop)
+ (,(r 'if) (,(r 'not) ,test) (exit #f))
+ ,@body))))
Note: this implementation of explicit-renaming macros allows passing
arbitrary expressions to the renaming and comparison procedures. When
@@ -361,7 +361,7 @@ are kept separate correctly).
==== reexport
- [syntax] (reexport IMPORT ...)
+<macro>(reexport IMPORT ...)</macro>
Imports {{IMPORT ...}} and automatically exports all imported identifiers.
This can be used to build ''compound modules'': modules that just extend
diff --git a/manual/Parameters b/manual/Parameters
index aa8ddc51..2d9b22ca 100644
--- a/manual/Parameters
+++ b/manual/Parameters
@@ -42,36 +42,53 @@ Certain behavior of the interpreter and compiled programs can be
customized via the following built-in parameters:
=== case-sensitive
+
+<parameter>(case-sensitive)</parameter>
+
If true, then {{read}} reads symbols and identifiers in
case-sensitive mode and uppercase characters in symbols are printed
escaped. Defaults to {{#t}}.
=== dynamic-load-libraries
+
+<parameter>(dynamic-load-libraries)</parameter>
+
A list of strings containing shared libraries that should be checked
for explicitly loaded library units (this facility is not available on
all platforms). See {{load-library}}.
=== command-line-arguments
+
+<parameter>(command-line-arguments)</parameter>
+
Contains the list of arguments passed to this program, with the name of
the program and any runtime options (all options starting with {{-:}})
removed.
-
=== current-read-table
+
+<parameter>(current-read-table)</parameter>
+
A read-table object that holds read-procedures for special non-standard
read-syntax (see {{set-read-syntax!}} for more information).
=== exit-handler
+
+<parameter>(exit-handler)</parameter>
+
A procedure of a single optional argument. When {{exit}} is called,
then this procedure will be invoked with the exit-code as argument. The
default behavior is to terminate the program.
=== eval-handler
+
+<parameter>(eval-handler)</parameter>
+
A procedure of one or two arguments. When {{eval}} is invoked, it
calls the value of this parameter with the same arguments. The default
behavior is to evaluate the argument expression and to ignore the
@@ -79,18 +96,27 @@ second parameter.
=== force-finalizers
+
+<parameter>(force-finalizers)</parameter>
+
If true, force and execute all pending finalizers before exiting the
program (either explicitly by {{exit}} or implicitly when the last
toplevel expression has been executed). Default is {{#t}}.
=== implicit-exit-handler
+
+<parameter>(implicit-exit-handler)</parameter>
+
A procedure of no arguments. When the last toplevel expression of the
program has executed, then the value of this parameter is called. The
default behaviour is to invoke all pending finalizers.
=== keyword-style
+
+<parameter>(keyword-style)</parameter>
+
Enables alternative keyword syntax, where {{STYLE}} may be either
{{#:prefix}} (as in Common Lisp), which recognizes symbols beginning
with a colon as keywords, or {{#:suffix}} (as in DSSSL), which recognizes
@@ -100,37 +126,53 @@ the default is {{#:suffix}}.
=== parenthesis-synonyms
+
+<parameter>(parenthesis-synonyms)</parameter>
+
If true, then the list delimiter synonyms {{#\[}} {{#\]}} and {{#\{}} {{#\}}} are enabled. Defaults to {{#t}}.
=== symbol-escape
+
+<parameter>(symbol-escape)</parameter>
+
If true, then the symbol escape {{#\|}} {{#\|}} is enabled. Defaults to {{#t}}.
=== load-verbose
+
+<parameter>(load-verbose)</parameter>
+
A boolean indicating whether loading of source files, compiled code
(if available) and compiled libraries should display a message.
=== program-name
+
+<parameter>(program-name)</parameter>
+
The name of the currently executing program. This is equivalent to
{{(car (argv))}} for compiled programs or the filename following the
{{-script}} option in interpreted scripts.
=== repl-prompt
+
+<parameter>(repl-prompt)</parameter>
+
A procedure that should evaluate to a string that will be printed before reading
interactive input from the user in a read-eval-print loop. Defaults to
{{(lambda () "#;N> ")}}.
=== reset-handler
+
+<parameter>(reset-handler)</parameter>
+
A procedure of zero arguments that is called via {{reset}}. The
default behavior in compiled code is to invoke the value of
{{(exit-handler)}}. The default behavior in the interpreter is to
abort the current computation and to restart the read-eval-print loop.
----
-Previous: [[Declarations]]
-
-Next: [[Unit library]]
+----
+Previous: [[Declarations]] Next: [[Exceptions]]
diff --git a/manual/Supported language b/manual/Supported language
index 4ffdd9d6..ccbf3790 100644
--- a/manual/Supported language
+++ b/manual/Supported language
@@ -1,4 +1,4 @@
-[[tags: manual]]
+[[tags: manual]]
== Supported language
@@ -10,6 +10,7 @@
* [[Modules and macros]]
* [[Declarations]]
* [[Parameters]]
+* [[Exceptions]]
* [[Unit library]] Basic Scheme definitions
* [[Unit eval]] Evaluation
* [[Unit expand]] Modules and macros handling
diff --git a/manual/Unit eval b/manual/Unit eval
index aea201ea..c0b2a5ae 100644
--- a/manual/Unit eval
+++ b/manual/Unit eval
@@ -117,7 +117,8 @@ loading of compiled code. Currently Linux, BSD, Solaris, Windows (with Cygwin) a
==== repository-path
-; [parameter] repository-path :
+<parameter>repository-path</parameter>
+
Contains a string naming the path to the extension repository, which defaults to
either the value of the environment variable {{CHICKEN_REPOSITORY}}
or the default library path
diff --git a/manual/Unit expand b/manual/Unit expand
index f024fc9a..7f863b33 100644
--- a/manual/Unit expand
+++ b/manual/Unit expand
@@ -36,7 +36,7 @@ Signals an exception of the kind {{(exn syntax)}}. Otherwise identical to
==== er-macro-transformer
- [procedure] (er-macro-transformer TRANSFORMER)
+<procedure>(er-macro-transformer TRANSFORMER)</procedure>
This procedure does nothing and is available for writing low-level
macros in a more portable fashion, without hard-coding the signature
diff --git a/manual/Unit extras b/manual/Unit extras
index 4eb46d4b..a36a50e6 100644
--- a/manual/Unit extras
+++ b/manual/Unit extras
@@ -33,10 +33,22 @@ random number generator is initialized with the current time.
<procedure>(random N)</procedure>
-Returns a random {{integer}} in {{[0 N-1]}}. {{N}} is an {{integer}}.
+Returns a pseudo-random {{integer}} in {{[0, N-1]}}. {{N}} is an {{integer}}.
-On '''Windows''' {{N}} and the random value are {{exact integer}}.
+On Windows, {{N}} and the random value are {{exact integer}}.
+'''Warning''': This procedure uses ''rand(3)'' internally and exhibits
+its deficiencies, including low quality pseudo-randomness:
+
+* On Windows and Solaris, only 32768 unique random values can be
+generated in the range {{[0, N-1]}}. If {{N >= 32768}}, there
+will be gaps in the result set.
+* On Mac OS X, Windows and some other platforms, little variance in output is seen
+with nearby seeds. Since the random generator is seeded
+with {{current-seconds}} at startup, new processes may see similar or
+identical random sequences for up to a minute.
+* On Linux, ''rand(3)'' is an alias to ''random(3)'', which provides
+output of reasonable quality.
=== Formatted output
@@ -110,9 +122,10 @@ of {{(current-output-port)}}.
==== pretty-print-width
-(Parameter) Specifies the maximal line-width for pretty printing, after which line
-wrap will occur.
+<parameter>pretty-print-width</parameter>
+Specifies the maximal line-width for pretty printing, after which line
+wrap will occur.
=== Input/Output extensions
diff --git a/manual/Unit library b/manual/Unit library
index ef0f01d3..4e1fc7c0 100644
--- a/manual/Unit library
+++ b/manual/Unit library
@@ -85,22 +85,15 @@ Returns {{#t}} if {{X}} is a fixnum, or {{#f}} otherwise.
==== Fixnum limits
-{{most-positive-fixnum}}
-
-{{most-negative-fixnum}}
-
-{{fixnum-bits}}
-
-{{fixnum-precision}}
+<constant>most-positive-fixnum</constant><br>
+<constant>most-negative-fixnum</constant><br>
+<constant>fixnum-bits</constant><br>
+<constant>fixnum-precision</constant><br>
+Platform-specific fixnum limits.
==== Arithmetic floating-point operations
-In safe mode, these procedures throw a type error when given non-float
-arguments. In unsafe mode, these procedures do not check their
-arguments. A non-flonum argument in unsafe mode can crash the
-application.
-
<procedure>(fp+ X Y)</procedure>
<procedure>(fp- X Y)</procedure>
<procedure>(fp* X Y)</procedure>
@@ -131,6 +124,13 @@ application.
<procedure>(fpabs X)</procedure>
<procedure>(fpinteger? X)</procedure>
+Arithmetic floating-point operations.
+
+In safe mode, these procedures throw a type error when given non-float
+arguments. In unsafe mode, these procedures do not check their
+arguments. A non-flonum argument in unsafe mode can crash the
+application.
+
Note: {{fpround}} uses the rounding mode that your C library
implements, which is usually different from R5RS.
@@ -142,25 +142,18 @@ Returns {{#t}} if {{X}} is a flonum, or {{#f}} otherwise.
==== Flonum limits
-{{maximum-flonum}}
-
-{{minimum-flonum}}
-
-{{flonum-radix}}
-
-{{flonum-epsilon}}
-
-{{flonum-precision}}
-
-{{flonum-decimal-precision}}
-
-{{flonum-maximum-exponent}}
-
-{{flonum-minimum-exponent}}
-
-{{flonum-maximum-decimal-exponent}}
+<constant>maximum-flonum</constant><br>
+<constant>minimum-flonum</constant><br>
+<constant>flonum-radix</constant><br>
+<constant>flonum-epsilon</constant><br>
+<constant>flonum-precision</constant><br>
+<constant>flonum-decimal-precision</constant><br>
+<constant>flonum-maximum-exponent</constant><br>
+<constant>flonum-minimum-exponent</constant><br>
+<constant>flonum-maximum-decimal-exponent</constant><br>
+<constant>flonum-minimum-decimal-exponent</constant><br>
-{{flonum-minimum-decimal-exponent}}
+Platform-specific flonum limits.
==== finite?
@@ -400,141 +393,8 @@ Transforms {{KEYWORD}} into a string.
Returns a keyword with the name {{STRING}}.
-
-
-
-=== Exceptions
-
-
-CHICKEN implements the (currently withdrawn)
-[[http://srfi.schemers.org/srfi-12/srfi-12.html|SRFI-12]] exception system. For
-more information, see the
-[[http://srfi.schemers.org/srfi-12/srfi-12.html|SRFI-12]] document.
-
-
-
-==== condition-case
-
-<macro>(condition-case EXPRESSION CLAUSE ...)</macro>
-
-Evaluates {{EXPRESSION}} and handles any exceptions that are covered by
-{{CLAUSE ...}}, where {{CLAUSE}} should be of the following form:
-
-<enscript highlight=scheme>
-CLAUSE = ([VARIABLE] (KIND ...) BODY ...)
-</enscript>
-
-If provided, {{VARIABLE}} will be bound to the signaled exception
-object. {{BODY ...}} is executed when the exception is a property-
-or composite condition with the kinds given {{KIND ...}} (unevaluated).
-If no clause applies, the exception is re-signaled in the same dynamic
-context as the {{condition-case}} form.
-
-<enscript highlight=scheme>
-(define (check thunk)
- (condition-case (thunk)
- [(exn file) (print "file error")]
- [(exn) (print "other error")]
- [var () (print "something else")] ) )
-
-(check (lambda () (open-input-file ""))) ; -> "file error"
-(check (lambda () some-unbound-variable)) ; -> "othererror"
-(check (lambda () (signal 99))) ; -> "something else"
-
-(condition-case some-unbound-variable
- [(exn file) (print "ignored")] ) ; -> signals error
-
-</enscript>
-
-
-==== get-condition-property
-
-<procedure>(get-condition-property CONDITION KIND PROPERTY [DEFAULT])</procedure>
-
-A slightly more convenient condition property accessor, equivalent to
-
- ((condition-property-accessor KIND PROPERTY [DEFAULT]) CONDITION)
-
-
-==== System conditions
-
-All error-conditions signaled by the system are of kind {{exn}}.
-The following composite conditions are additionally defined:
-
-<table>
-
-<tr><td> (exn arity) </td><td>
-
-Signaled when a procedure is called with the wrong number of arguments.
-
-</td></tr><tr><td> (exn type) </td><td>
-
-Signaled on type-mismatch errors, for example when an argument of the wrong
-type is passed to a built-in procedure.
-
-</td></tr><tr><td> (exn arithmetic) </td><td>
-
-Signaled on arithmetic errors, like division by zero.
-
-</td></tr><tr><td> (exn i/o) </td><td>
-
-Signaled on input/output errors.
-
-</td></tr><tr><td> (exn i/o file) </td><td>
-
-Signaled on file-related errors.
-
-</td></tr><tr><td> (exn i/o net) </td><td>
-
-Signaled on network errors.
-
-</td></tr><tr><td> (exn bounds) </td><td>
-
-Signaled on errors caused by accessing non-existent elements of a collection.
-
-</td></tr><tr><td> (exn runtime) </td><td>
-
-Signaled on low-level runtime-system error-situations.
-
-</td></tr><tr><td> (exn runtime limit) </td><td>
-
-Signaled when an internal limit is exceeded (like running out of memory).
-
-</td></tr><tr><td> (exn match) </td><td>
-
-Signaled on errors raised by failed matches (see the section on {{match}}).
-
-</td></tr><tr><td> (exn syntax) </td><td>
-
-Signaled on syntax errors.
-
-</td></tr>
-
-</table>
-
-Notes:
-
-* All error-exceptions (of the kind {{exn}}) are non-continuable.
-
-* Error-exceptions of the {{exn}} kind have additional {{arguments}} and
-{{location}} properties that contain the arguments passed to the
-exception-handler and the name of the procedure where the error occurred (if
-available).
-
-* When the {{posix}} unit is available and used, then a user-interrupt
-({{signal/int}}) signals an exception of the kind {{user-interrupt}}.
-
-* the procedure {{condition-property-accessor}} accepts an optional third
-argument. If the condition does not have a value for the desired property and
-if the optional argument is given, no error is signaled and the accessor
-returns the third argument.
-
-
-
=== Environment information and system interface
-
-
==== argv
<procedure>(argv)</procedure>
@@ -1273,7 +1133,5 @@ all values are {{#f}}.
{{PROPERTIES}} may also be an atom, in which case it is treated as a list of
one element.
----
-Previous: [[Parameters]]
-
-Next: [[Unit eval]]
+----
+Previous: [[Exceptions]] Next: [[Unit eval]]
diff --git a/manual/Unit posix b/manual/Unit posix
index f15d3096..7d6b512f 100644
--- a/manual/Unit posix
+++ b/manual/Unit posix
@@ -1284,7 +1284,7 @@ Microsoft tools or with MinGW):
map/...
map-file-to-memory unmap-file-from-memory memory-mapped-file-pointer memory-mapped-file?
set-alarm!
- terminal-name
+ terminal-port? terminal-name
process-fork process-signal
parent-process-id
set-root-directory!
diff --git a/manual/Using the compiler b/manual/Using the compiler
index 7fac33a5..4e198eae 100644
--- a/manual/Using the compiler
+++ b/manual/Using the compiler
@@ -394,15 +394,25 @@ to procedures that are called to perform certain compilation passes
instead of the usual processing (for more information about parameters
see: [[Supported language]].
-; [parameter] user-options-pass : Holds a procedure that will be called with a list of command-line arguments and should return two values: the source filename and the actual list of options, where compiler switches have their leading {{-}} (hyphen) removed and are converted to symbols. Note that this parameter is invoked '''before''' processing of the {{-extend}} option, and so can only be changed in compiled user passes.
+<parameter>user-options-pass</parameter>
-; [parameter] user-read-pass : Holds a procedure of three arguments. The first argument is a list of strings with the code passed to the compiler via {{-prelude}} options. The second argument is a list of source files including any files specified by {{-prologue}} and {{-epilogue}}. The third argument is a list of strings specified using {{-postlude}} options. The procedure should return a list of toplevel Scheme expressions.
+Holds a procedure that will be called with a list of command-line arguments and should return two values: the source filename and the actual list of options, where compiler switches have their leading {{-}} (hyphen) removed and are converted to symbols. Note that this parameter is invoked '''before''' processing of the {{-extend}} option, and so can only be changed in compiled user passes.
-; [parameter] user-preprocessor-pass : Holds a procedure of one argument. This procedure is applied to each toplevel expression in the source file '''before''' macro-expansion. The result is macro-expanded and compiled in place of the original expression.
+<parameter>user-read-pass</parameter>
-; [parameter] user-pass : Holds a procedure of one argument. This procedure is applied to each toplevel expression '''after''' macro-expansion. The result of the procedure is then compiled in place of the original expression.
+Holds a procedure of three arguments. The first argument is a list of strings with the code passed to the compiler via {{-prelude}} options. The second argument is a list of source files including any files specified by {{-prologue}} and {{-epilogue}}. The third argument is a list of strings specified using {{-postlude}} options. The procedure should return a list of toplevel Scheme expressions.
-; [parameter] user-post-analysis-pass : Holds a procedure that will be called after every performed program analysis pass. The procedure (when defined) will be called with seven arguments: a symbol indicating the analysis pass, the program database, the current node graph, a getter and a setter-procedure which can be used to access and manipulate the program database, which holds various information about the compiled program, a pass iteration count, and an analysis continuation flag. The getter procedure should be called with two arguments: a symbol representing the binding for which information should be retrieved, and a symbol that specifies the database-entry. The current value of the database entry will be returned or {{#f}}, if no such entry is available. The setter procedure is called with three arguments: the symbol and key and the new value. The pass iteration count currently is meaningful only for the 'opt pass. The analysis continuation flag will be {{#f}} for the last 'opt pass. For information about the contents of the program database contact the author.
+<parameter>user-preprocessor-pass</parameter>
+
+Holds a procedure of one argument. This procedure is applied to each toplevel expression in the source file '''before''' macro-expansion. The result is macro-expanded and compiled in place of the original expression.
+
+<parameter>user-pass</parameter>
+
+Holds a procedure of one argument. This procedure is applied to each toplevel expression '''after''' macro-expansion. The result of the procedure is then compiled in place of the original expression.
+
+<parameter>user-post-analysis-pass</parameter>
+
+Holds a procedure that will be called after every performed program analysis pass. The procedure (when defined) will be called with seven arguments: a symbol indicating the analysis pass, the program database, the current node graph, a getter and a setter-procedure which can be used to access and manipulate the program database, which holds various information about the compiled program, a pass iteration count, and an analysis continuation flag. The getter procedure should be called with two arguments: a symbol representing the binding for which information should be retrieved, and a symbol that specifies the database-entry. The current value of the database entry will be returned or {{#f}}, if no such entry is available. The setter procedure is called with three arguments: the symbol and key and the new value. The pass iteration count currently is meaningful only for the 'opt pass. The analysis continuation flag will be {{#f}} for the last 'opt pass. For information about the contents of the program database contact the author.
Loaded code (via the {{-extend}} option) has access to the library
units {{extras, srfi-1, srfi-4, utils, regex}} and the pattern matching macros.
Trap