~ chicken-core (chicken-5) 889b7000401cdc37ad919a578e7caee9928a092f
commit 889b7000401cdc37ad919a578e7caee9928a092f
Author: felix <felix@call-with-current-continuation.org>
AuthorDate: Tue Feb 7 08:23:38 2012 +0100
Commit: felix <felix@call-with-current-continuation.org>
CommitDate: Tue Feb 7 08:23:38 2012 +0100
merged some changes from the wiki to the manual
diff --git a/manual/Accessing external objects b/manual/Accessing external objects
index 6a1323ee..e043e926 100644
--- a/manual/Accessing external objects
+++ b/manual/Accessing external objects
@@ -142,10 +142,9 @@ in {{STRING ...}}:
(my-strlen "one two three") ==> 13
</enscript>
-For obscure technical reasons you should use the {{C_return}} macro
-instead of the normal {{return}} statement to return a result from the
-foreign lambda body as some cleanup code has to be run before
-execution commences in the calling code.
+For obscure technical reasons you should use the {{C_return}} macro instead of the normal {{return}} statement
+to return a result from the foreign lambda body as some cleanup code has to be run before execution
+commences in the calling code.
=== foreign-safe-lambda
diff --git a/manual/Cross development b/manual/Cross development
index 9f8908b6..38a73154 100644
--- a/manual/Cross development
+++ b/manual/Cross development
@@ -33,7 +33,7 @@ repository, then build the libraries and necessary development files:
make ARCH= \
PREFIX=/usr \
- PLATFORM=linux
+ PLATFORM=linux \
HOSTSYSTEM=arm-none-linux-gnueabi \
DESTDIR=$HOME/target \
TARGET_FEATURES="-no-feature x86 -feature arm" \
diff --git a/manual/Deployment b/manual/Deployment
index 467ae801..61fd9321 100644
--- a/manual/Deployment
+++ b/manual/Deployment
@@ -14,7 +14,7 @@ system or if the application should be completely self-contained.
=== Simple executables
The simplest form of deployment is the single executable. The runtime
-libraries ({{libchicken.so}} or {{libchicken.dll}} is required for these
+library ({{libchicken.so}} or {{libchicken.dll}}) is required for these
programs to run, unless you link your application statically:
% csc myprogram.scm
@@ -107,12 +107,14 @@ extensions that the program will use at runtime:
[debug] loading compiled module `/home/felix/tmp/myprogram/defstruct.so' (handle is 0x886ce98)
...
-There is one restriction that you should be aware of, though: any extension that
-you install inside an application directory must first be installed system-wide
-(unless you use a custom repository with the {{CHICKEN_REPOSITORY}} environment variable),
-so that {{csc}}/{{chicken}} will find an import library for the extension. Just make
-sure you have all the extensions installed that you use in an application (something
-you will normally have anyway).
+There is one restriction that you should be aware of: you cannot
+{{chicken-install -deploy}} an uninstalled extension, e.g.
+directly from an SVN checkout. You must first install it on your
+build system normally with {{chicken-install}}, so that {{csc}} can
+find its import library in the system-wide repository (or in a custom
+one if you have set {{CHICKEN_REPOSITORY}}). This is only needed
+while you are deploying the extension into the application directory; once
+deployed, of course, it's totally self-contained.
You can execute the program from its location, or you can install a symbolic
link pointing to it - it will find the correct directory where the actual
diff --git a/manual/Deviations from the standard b/manual/Deviations from the standard
index 8bdd363e..19150aea 100644
--- a/manual/Deviations from the standard
+++ b/manual/Deviations from the standard
@@ -11,7 +11,8 @@ compiled procedure or macro is limited to 120 (1000 on some
common hardware platforms like x86).
Likewise, the maximum number of values that can be passed
to continuations captured using {{call-with-current-continuation}}
-is limited as well.
+is 120. This is an implementation restriction that is unlikely
+to be lifted.
=== {{numerator}}, {{denominator}} and {{rationalize}}
diff --git a/manual/Exceptions b/manual/Exceptions
index 9e75e0bd..14bdf436 100644
--- a/manual/Exceptions
+++ b/manual/Exceptions
@@ -132,6 +132,8 @@ formatted as follows:
There is no guaranteed order within the list.
+{{condition->list}} was introduced in CHICKEN 4.7.0.
+
== SRFI-12 specification
A Scheme implementation ("the system") raises an exception whenever an
diff --git a/manual/Extensions b/manual/Extensions
index 00481f61..6ecda63f 100644
--- a/manual/Extensions
+++ b/manual/Extensions
@@ -74,14 +74,18 @@ be passed using {{-I}} and {{-L}} to the C compiler.
=== Creating extensions
-Extensions can be created by creating an (optionally gzipped) {{tar}}
-archive named {{EXTENSION.egg}} containing all needed files plus a
-{{.setup}} script in the root directory. After {{chicken-install}} has
-extracted the files, the setup script will be invoked. There are no
-additional constraints on the structure of the archive, but the setup
-script has to be in the root path of the archive.
+An extension can be created by placing its code and some special
+files in a directory named after it. For example, if your
+extension is called {{foo}}, create a directory called {{foo}}
+and put the extension code in it.
-For more details on creating extensions, see the [[/eggs tutorial|eggs tutorial]].
+Extensions need two special files: an {{<extension name>.setup}}
+file and an {{<extension name>.meta}} file (where {{<extension
+name>}} is the name of your extension). The former indicates how
+the egg is to be copiled and the latter provides some information
+about the extension (author, license, dependencies etc). See the
+[[/eggs tutorial|eggs tutorial]] for further information about
+how to create extensions.
=== Procedures and macros available in setup scripts
@@ -524,10 +528,10 @@ Next, it should be possible to load the library:
$ csi -q
#;1> (use my-lib)
- ; loading /usr/local/lib/chicken/5/my-lib.import.so ...
- ; loading /usr/local/lib/chicken/5/scheme.import.so ...
- ; loading /usr/local/lib/chicken/5/chicken.import.so ...
- ; loading /usr/local/lib/chicken/5/my-lib.so ...
+ ; loading /usr/local/lib/chicken/6/my-lib.import.so ...
+ ; loading /usr/local/lib/chicken/6/scheme.import.so ...
+ ; loading /usr/local/lib/chicken/6/chicken.import.so ...
+ ; loading /usr/local/lib/chicken/6/my-lib.so ...
#;2> (my-sum '(10 20 30))
my-sum used one more time!
60
@@ -639,7 +643,7 @@ or by modifying {{config.make}}. Eggs will then be installed in
=== Changing repository location
When Chicken is installed a repository for eggs is created and initialized
-in a default location (usually something like {{/usr/local/lib/chicken/5/}}).
+in a default location (usually something like {{/usr/local/lib/chicken/6/}}).
It is possible to keep an eggs repository in another location. This can be
configured at build-time by passing {{VARDIR=<directory>}} to {{make(3)}}
or by modifying the {{config.make}} configuration file. If you want to
@@ -647,13 +651,18 @@ override this location after chicken is installed, you can create an
initial repository directory with some default extensions and set the
{{CHICKEN_REPOSITORY}} environment variable:
+Note that your binary version can differ from the examples here, if your
+chicken version is older or newer than the one used in these examples.
+Check your default location for the correct binary-version number.
+
First, initialize the new repository with
- chicken-install -init ~/myeggs/lib/chicken/5
+ mkdir -p ~/myeggs/lib/chicken/6 # to create directory structure
+ chicken-install -init ~/myeggs/lib/chicken/6
Then set this environment variable:
- export CHICKEN_REPOSITORY=~/myeggs/lib/chicken/5
+ export CHICKEN_REPOSITORY=~/myeggs/lib/chicken/6
{{CHICKEN_REPOSITORY}} is the place where extensions are to be
loaded from for all chicken-based programs (which includes all
@@ -671,13 +680,27 @@ When you load eggs from the interpreter, you will see messages showing
where libraries are being loaded from:
#;1> (use numbers)
- ; loading /home/jdoe/myeggs/lib/chicken/5/numbers.import.so ...
- ; loading /home/jdoe/myeggs/lib/chicken/5/scheme.import.so ...
- ; loading /home/jdoe/myeggs/lib/chicken/5/chicken.import.so ...
- ; loading /home/jdoe/myeggs/lib/chicken/5/foreign.import.so ...
- ; loading /home/jdoe/myeggs/lib/chicken/5/regex.import.so ...
- ; loading /home/jdoe/myeggs/lib/chicken/5/numbers.so ...
- #;2>
+ ; loading /home/jdoe/myeggs/lib/chicken/6/numbers.import.so ...
+ ; loading /home/jdoe/myeggs/lib/chicken/6/scheme.import.so ...
+ ; loading /home/jdoe/myeggs/lib/chicken/6/chicken.import.so ...
+ ; loading /home/jdoe/myeggs/lib/chicken/6/foreign.import.so ...
+ ; loading /home/jdoe/myeggs/lib/chicken/6/regex.import.so ...
+ ; loading /home/jdoe/myeggs/lib/chicken/6/numbers.so ...
+ #;2>
+
+==== Upgrading
+
+After a main upgrade, you need to reinstall all the eggs. First,
+reset the repository environment variable:
+
+ export CHICKEN_REPOSITORY=/usr/lib/chicken/6
+
+Then, make a new directory that reflects the systematic one:
+
+ mkdir ~/myeggs/lib/chicken/6
+
+After that, do the same steps above for the new directory (initialize, set repository environment variable)
+and reinstall all the eggs.
=== Other modes of installation
diff --git a/manual/Getting started b/manual/Getting started
index 0a1266f2..157ac01a 100644
--- a/manual/Getting started
+++ b/manual/Getting started
@@ -156,10 +156,10 @@ resources.
The CHICKEN wiki ([[http://wiki.call-cc.org]]) 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://wiki.call-cc.org/chicken-projects/egg-index-4.html#category-list]].
+[[http://wiki.call-cc.org/egg-index]].
A very useful search facility for questions about CHICKEN is found at
-[[http://chickadee.call-cc.org]]. The CHICKEN issue tracker is at
+[[http://api.call-cc.org]]. The CHICKEN issue tracker is at
[[http://bugs.call-cc.org]].
The CHICKEN community has two major mailing lists. If you are a
@@ -327,23 +327,8 @@ convenient.
The REPL also supports debugging commands:
input lines beginning with a {{,}} (comma) are treated as special
-commands. (See the [[Using the interpreter#Toplevel commands|full list]].) We can
-'''trace''' {{fact}} to see how it works.
-
- #;5> ,tr fact
- #;5> (fact 3)
- |(fact 3)
- | (fact 2)
- | (fact 1)
- | (fact 0)
- | fact -> 1
- | fact -> 1
- | fact -> 2
- |fact -> 6
- 6
+commands. (See the [[Using the interpreter#Toplevel commands|full list]].)
-The command number didn't increment, because the {{tr}} command isn't
-actually a Scheme ''form''.
==== Scripts
diff --git a/manual/Non-standard macros and special forms b/manual/Non-standard macros and special forms
index f14984d3..8a942647 100644
--- a/manual/Non-standard macros and special forms
+++ b/manual/Non-standard macros and special forms
@@ -50,7 +50,7 @@ See also: {{set-extension-specifier!}}
<macro>(require-extension ID ...)</macro>
This is equivalent to {{(require-library ID ...)}} but performs an implicit
-{{import}}, if necessary. {{ID}} may also be an import specification
+{{import}}, if necessary. Since version 4.4.0, {{ID}} may also be an import specification
(using {{rename}}, {{only}}, {{except}} or {{prefix}}).
This implementation of {{require-extension}} is compliant with [[http://srfi.schemers.org/srfi-55/srfi-55.html|SRFI-55]]
@@ -71,7 +71,8 @@ This implementation of {{require-extension}} is compliant with [[http://srfi.sch
Use this form for procedures that take a single optional argument. If
{{ARGS}} is the empty list {{DEFAULT}} is evaluated and
-returned, otherwise the first element of the list {{ARGS}}.
+returned, otherwise the first element of the list {{ARGS}}. It is
+an error if {{ARGS}} contains more than one value.
<enscript highlight=scheme>
(define (incr x . i) (+ x (optional i 1)))
@@ -111,7 +112,8 @@ be a rest-parameter taken from a lambda-list. {{let-optionals}}
binds {{VAR1 ...}} to available arguments in parallel, or
to {{DEFAULT1 ...}} if not enough arguments were provided.
{{let-optionals*}} binds {{VAR1 ...}} sequentially, so every
-variable sees the previous ones.
+variable sees the previous ones. it is an error if any excess
+arguments are provided.
<enscript highlight=scheme>
(let-optionals '(one two) ((a 1) (b 2) (c 3))
@@ -128,7 +130,8 @@ binds {{VAR1 ...}} to available arguments in parallel, or
to {{DEFAULT1 ...}} if not enough arguments were provided.
{{let-optionals*}} binds {{VAR1 ...}} sequentially, so every
variable sees the previous ones. If a single variable {{RESTVAR}}
-is given, then it is bound to any remaining arguments.
+is given, then it is bound to any remaining arguments, otherwise it is
+an error if any excess arguments are provided.
<enscript highlight=scheme>
(let-optionals* '(one two) ((a 1) (b 2) (c a))
@@ -297,6 +300,9 @@ Defines the toplevel variable {{NAME}} at macro-expansion time. This can
be helpful when you want to define support procedures for use in macro-transformers,
for example.
+Note that {{define-for-syntax}} definitions within a module are implicitly
+added to that module's import library. Refer to the documentation on
+[[/man/4/Modules#import-libraries|import libraries]] for more information.
==== define-compiler-syntax
diff --git a/manual/Parameters b/manual/Parameters
index e5b17421..738ef1d2 100644
--- a/manual/Parameters
+++ b/manual/Parameters
@@ -22,6 +22,7 @@ owns a local copy of a parameters' value.
CHICKEN implements [[http://srfi.schemers.org/srfi-39/srfi-39.html|SRFI-39]].
+
=== make-parameter
<procedure>(make-parameter VALUE [GUARD])</procedure>
diff --git a/manual/Unit files b/manual/Unit files
index 1c4c3d59..bdbc3e58 100644
--- a/manual/Unit files
+++ b/manual/Unit files
@@ -30,10 +30,14 @@ For any component that is not contained in {{PATHNAME}}, {{#f}} is returned.
<procedure>(make-pathname DIRECTORY FILENAME [EXTENSION])</procedure><br>
<procedure>(make-absolute-pathname DIRECTORY FILENAME [EXTENSION])</procedure>
-Returns a string that names the file with the components {{DIRECTORY,
-FILENAME}} and (optionally) {{EXTENSION}}. {{DIRECTORY}} can be
-{{#f}} (meaning no directory component), a string or a list of
-strings. {{FILENAME}} and {{EXTENSION}} should be strings or {{#f}}.
+Returns a string that names the file with the
+components {{DIRECTORY, FILENAME}} and (optionally)
+{{EXTENSION}} with {{SEPARATOR}} being the directory separation indicator
+(usually {{/}} on UNIX systems and {{\}} on Windows, defaulting to whatever
+platform this is running on).
+{{DIRECTORY}} can be {{#f}} (meaning no
+directory component), a string or a list of strings. {{FILENAME}}
+and {{EXTENSION}} should be strings or {{#f}}.
{{make-absolute-pathname}} returns always an absolute pathname.
==== pathname-directory
diff --git a/manual/Unit library b/manual/Unit library
index d8f641d9..1fed1282 100644
--- a/manual/Unit library
+++ b/manual/Unit library
@@ -420,8 +420,6 @@ Exit the running process and return exit-code, which defaults to 0
Note that pending {{dynamic-wind}} thunks are ''not'' invoked when exiting your program in this way.
-
-
==== build-platform
<procedure>(build-platform)</procedure>
@@ -455,12 +453,13 @@ Returns the error code of the last system call.
==== get-environment-variable
<procedure>(get-environment-variable STRING)</procedure><br>
-<procedure>(getenv STRING)</procedure>
Returns the value of the environment variable {{STRING}} or
{{#f}} if that variable is not defined. See also [[http://srfi.schemers.org/srfi-98/|SRFI-98]].
-{{getenv}} is an alias for {{get-environment-variable}}.
+<procedure>(getenv STRING)</procedure>
+
+{{getenv}} was removed in Chicken 4.6.4. Use {{get-environment-variable}} instead.
==== machine-byte-order
diff --git a/manual/Unit lolevel b/manual/Unit lolevel
index 82648d74..494feabe 100644
--- a/manual/Unit lolevel
+++ b/manual/Unit lolevel
@@ -304,7 +304,7 @@ the {{NULL}}-pointer.
<procedure>(make-pointer-vector LENGTH [INIT])</procedure>
Creates a pointer-vector of the given length and optionally initializes each
-element to {{INIT}}, which should be a pointer or {{#f}, which represents the
+element to {{INIT}}, which should be a pointer or {{#f}}, which represents the
{{NULL}} pointer.
==== pointer-vector?
diff --git a/manual/Unit ports b/manual/Unit ports
index 7285804b..b57bdcd4 100644
--- a/manual/Unit ports
+++ b/manual/Unit ports
@@ -102,23 +102,19 @@ bound to a string-output-port and return the accumulated output string.
<procedure>(port-for-each FN THUNK)</procedure>
-Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}}
-until it returns {{#!eof}}, discarding the results.
+Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}} (typically {{read}}) until it returns {{#!eof}}, discarding the results.
==== port-map
<procedure>(port-map FN THUNK)</procedure>
-Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}}
-until it returns {{#!eof}}, returning a list of the collected results.
+Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}} (typically {{read}}) until it returns {{#!eof}}, returning a list of the collected results.
==== port-fold
<procedure>(port-fold FN ACC THUNK)</procedure>
-Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}},
-passing the {{ACC}} value as the second argument. The {{FN}} result becomes the new
-{{ACC}} value. When {{THUNK}} returns {{#!eof}}, the last {{FN}} result is returned.
+Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}}, (typically {{read}}) passing the {{ACC}} value as the second argument. The {{FN}} result becomes the new {{ACC}} value. When {{THUNK}} returns {{#!eof}}, the last {{FN}} result is returned.
==== copy-port
@@ -126,13 +122,14 @@ passing the {{ACC}} value as the second argument. The {{FN}} result becomes the
Reads all remaining data from port {{FROM}} using the reader procedure
{{READ}} and writes it to port {{TO}} using the writer procedure
-{{WRITE}}. {{READ}} defaults to {{read-char}} and {{WRITE} to
+{{WRITE}}. {{READ}} defaults to {{read-char}} and {{WRITE}} to
{{write-char}}. Note that this procedure does not check {{FROM}} and
{{TO}} for being ports, so the reader and writer procedures may
perform arbitrary operations as long as they can be invoked
as {{(READ FROM)}} and {{(WRITE X TO)}}, respectively.
{{copy-port}} returns an undefined value.
+{{copy-port}} was introduced in Chicken 4.6.0.
=== Funky ports
diff --git a/manual/Unit posix b/manual/Unit posix
index 6eaba7bd..309f80bf 100644
--- a/manual/Unit posix
+++ b/manual/Unit posix
@@ -393,14 +393,68 @@ time of {{FILE}} to {{SECONDS}}.
<procedure>(file-stat FILE [LINK])</procedure>
-Returns a 13-element vector with the following contents: inode-number,
-mode (as with {{file-permissions}}), number of hard links, uid of
-owner (as with {{file-owner}}), gid of owner, size (as with
-{{file-size}}) and access-, change- and modification-time (as with
-{{file-access-time}}, {{file-change-time}} and
-{{file-modification-time}}, device id, device type (for special file
-inode, blocksize and blocks allocated. On Windows systems the last 4
-values are undefined.
+Returns a 13-element vector with the following contents:
+
+<table>
+<tr><th>index</th>
+ <th>value</th>
+ <th>field</th>
+ <th>notes</th></tr>
+<tr><td>0</td>
+ <td>inode number</td>
+ <td>{{st_ino}}</td>
+ <td></td></tr>
+<tr><td>1</td>
+ <td>mode</td>
+ <td>{{st_mode}}</td>
+ <td>bitfield combining file permissions and file type</td></tr>
+<tr><td>2</td>
+ <td>number of hard links</td>
+ <td>{{st_nlink}}</td>
+ <td></td></tr>
+<tr><td>3</td>
+ <td>UID of owner</td>
+ <td>{{st_uid}}</td>
+ <td>as with {{file-owner}}</td></tr>
+<tr><td>4</td>
+ <td>GID of owner</td>
+ <td>{{st_gid}}</td>
+ <td></td></tr>
+<tr><td>5</td>
+ <td>size</td>
+ <td>{{st_size}}</td>
+ <td>as with {{file-size}}</td></tr>
+<tr><td>6</td>
+ <td>access time</td>
+ <td>{{st_atime}}</td>
+ <td>as with {{file-access-time}}</td></tr>
+<tr><td>7</td>
+ <td>change time</td>
+ <td>{{st_ctime}}</td>
+ <td>as with {{file-change-time}}</td></tr>
+<tr><td>8</td>
+ <td>modification time</td>
+ <td>{{st_mtime}}</td>
+ <td>as with {{file-modification-time}}</td></tr>
+<tr><td>9</td>
+ <td>parent device ID </td>
+ <td>{{st_dev}}</td>
+ <td>ID of device on which this file resides</td></tr>
+<tr><td>10</td>
+ <td>device ID</td>
+ <td>{{st_rdev}}</td>
+ <td>device ID for special files (i.e. the raw major/minor number)</td></tr>
+<tr><td>11</td>
+ <td>block size</td>
+ <td>{{st_blksize}}</td>
+ <td></td></tr>
+<tr><td>12</td>
+ <td>number of blocks allocated</td>
+ <td>{{st_blocks}}</td>
+ <td></td></tr>
+</table>
+
+On Windows systems, the last 4 values are undefined.
By default, symbolic links are followed and
the status of the referenced file is returned;
@@ -723,7 +777,7 @@ Creates a hard link from {{OLDNAME}} to {{NEWNAME}} (both strings).
<procedure>(current-user-id)</procedure>
[setter] (set! (current-user-id) UID)
-Get or set the real user-id of the current process.
+Get or set the real user-id of the current process. The procedure corresponds to the getuid and setuid C functions.
==== current-effective-user-id
@@ -1199,8 +1253,13 @@ followed.
Note that {{action}} is called with the full pathname of each file,
including the directory prefix.
-The signature of this procedure changed in CHICKEN 4.7.4 from
-positional arguments to a keyword-driven style.
+This procedure's signature was changed in CHICKEN 4.6. In older versions, {{find-files}}
+has a different signature:
+
+ (find-files DIRECTORY [TEST [ACTION [SEED [LIMIT]]]])
+
+The old signature is still supported in CHICKEN 4.6 for compatibility reasons, but is
+deprecated.
=== Getting the hostname and system information
diff --git a/manual/Unit srfi-1 b/manual/Unit srfi-1
index 7a8eb917..f16fd62a 100644
--- a/manual/Unit srfi-1
+++ b/manual/Unit srfi-1
@@ -834,7 +834,7 @@ The dynamic order in which the various applications of F are made is not
specified. In the n-ary case, CLIST_2, CLIST_3, ... must have at least as
many elements as LIST_1.
-<procedure>(map-in-order f) clist_1 clist_2 ...) -> list</procedure><br>
+<procedure>(map-in-order f clist_1 clist_2 ...) -> list</procedure><br>
A variant of the {{map}} procedure that guarantees to apply F across the
elements of the LIST_I arguments in a left-to-right order. This is useful
diff --git a/manual/Unit tcp b/manual/Unit tcp
index bd20c855..abc8885c 100644
--- a/manual/Unit tcp
+++ b/manual/Unit tcp
@@ -10,7 +10,7 @@ PLT Scheme.
This unit uses the {{extras}} unit.
All errors related to failing network operations will raise a condition
-of kind {{(exn i/o network)}}.
+of kind {{(exn i/o net)}}.
=== tcp-listen
diff --git a/manual/Using the compiler b/manual/Using the compiler
index 0d4c09a3..924356e7 100644
--- a/manual/Using the compiler
+++ b/manual/Using the compiler
@@ -20,7 +20,7 @@ on the command line for a list of options.
be compiled. A filename argument of {{-}} specifies that
the source text should be read from standard input.
-==== Command-line options
+==== Basic command-line options
; -analyze-only : Stop compilation after first analysis pass.
Trap